2.3.2 - Line Parser - JdlLineParser

John W. Campbell

2.3.2.1 Introduction

This class is used to parse fields or items from a line of text. The fields may be returned as strings or may be interpreted, for example as 'integer' or 'double' values. By default the items are assumed to be separated by spaces but any character or combination of characters may be specified as the required field separators.

Class, constructors and methods:

Class Details
Accessible Fields
Constructors
Returning fields
Some additional methods

2.3.2.2 Class Details

Package:
Jdl.JdlLib;
Class name:
JdlLineParser
Class definition:
public class JdlLineParser
Extends:
Object
Implements:
none
Actions:
none

2.3.2.3 Accessible Fields

No fields with public, package or protected access defined.

2.3.2.4 Constructors

2.3.2.4.1 Introduction

The following two constructors are available:

Constructors:

Standard constructor
Full constructor

2.3.2.4.2 Standard constructor

This constructs the JdlLineParser object from a given input string and sets spaces (one or more) as the field separators.

Constructor Definition:
public JdlLineParser (String str)
Parameters List:
str
The string to be parsed.

2.3.2.4.3 Full constructor

This constructs the JdlLineParser object from a given input string and sets the required field field separators.

Constructor Definition:
public JdlLineParser (String str, String seps)
Parameters List:
str
The string to be parsed.
sep
A string containing a list of the characters to be treated as field separators. If the first character is given as a space then any number of spaces or a set of spaces containing one of the other characters will be treated as a single separator. e.g. for sep = " ,;" and the string 
"Options one,two,  three;  Ignore"
The fields are "Options", "one", "two", "three" and "Ignore". If sep = ",; ", each character would be treated as an individual field separator and the fields would be "Options", "one", "two", null, null, "three", null, null, "Ignore".

2.3.2.5 Returning fields

2.3.2.5.1 Introduction

These methods are used to return the parsed fields in sequence from the input string based on the field separators defined when the JdlLineParser object was created. Some options enable the fields to be interpreted, for example, as 'integer' or 'double' values. Several variants exist for some of these methods, for example, in their error handling.

Methods:

Get next field - nextField
Get next field - nextField
Get next string field - nextStringField
Get remaining string - remainingString
Get fixed width field - nextFixedWidthField
Get next integer - nextInt
Get next integer - nextInt
Get fixed width integer - nextFixedWidthInt
Get next double - nextDouble
Get next double - nextDouble
Get next double - nextDouble
Get fixed width double - nextFixedWidthDouble

2.3.2.5.2 Get next field - nextField

This method returns the next field from the line as a string.

Method Definition:
public String nextField()
Parameters List:
none
Method Return:
Returns the field as a string; null if no more fields available; "" if a blank field.

2.3.2.5.3 Get next field - nextField

This method returns the next field from the line as a string. As well as returning the string, this version of the method returns the start and end chatacter offsets of the field within the original string.

Method Definition:
public String nextField(JdlInt idx1, JdlInt idx2)
Parameters List:
idx1
'idx1.value' returns the index within the line of the first character of the field; -1 if no string was returned.
idx2
'idx2.value' returns the index within the line of the final character of the field; -1 if no string was returned.
Method Return:
Returns the field as a string; null if no more fields available; "" if a blank field.

2.3.2.5.4 Get next string field - nextStringField

This method returns the next field from the line as a string. In contrast to the nextField(..) method, this method allows for the possibility of quoted fields (Such strings may contain separator characters). Single or double quotes may be used. The enclosing quotes are not returned as part of the string.

Method Definition:
public String nextStringField()
Parameters List:
none
Method Return:
Returns the field as a string; null if no more fields available; "" if blank field;

2.3.2.5.5 Get remaining string - remainingString

This method returns the remainder of line as a string.

Method Definition:
public String remainingString()
Parameters List:
none
Method Return:
The remainder of the string (untrimmed); null if end already reached.

2.3.2.5.6 Get fixed width field - nextFixedWidthField

This method enables a fixed width field to be returned from the line as a string.

Method Definition:
public String nextFixedWidthField(int w)
Parameters List:
w
The field width.
Method Return:
Returns the field as a string; null if no more fields available.

2.3.2.5.7 Get next integer - nextInt

This method gets the next field from the line and interprets it as an integer. The error return mechanism for this version of the method may be convenient when the required valid values of the integer are in a defined range e.g >0.

Method Definition:
public int nextInt(int blankval, int errval)
Parameters List:
blankval
The integer value to return if the end of the input line was reached or the string has no characters in it.
errval
The integer value to return if there is an error in the syntax of the integer value string.
Method Return:
Returns the field as an integer value; 'blankval' if no more fields available or no digits present; 'errval' if a syntax error was found.

2.3.2.5.8 Get next integer - nextInt

This method gets the next field from the line and interprets it as an integer. In this version of the method, error conditions are returned in a JdlError object.

Method Definition:
public int nextInt(JdlError err)
Parameters List:
err
JdlError object to return error status. If an error was found, 'err.err' will be returned as true, one or two error messages will be set and 'err.flag' may have the following values:
= 0, OK
= 1, Null/blank string (or + character only)
= 2, Invalid character in string
= 3, Java conversion exception
= -1, End of line reached
Method Return:
Returns the field as an integer value; 0 if an error etc. was found.

2.3.2.5.9 Get fixed width integer - nextFixedWidthInt

Gets the next fixed width field from the line and interprets it as an integer.

Method Definition:
public int nextFixedWidthInt(int w, JdlError err)
Parameters List:
w
The field width.
err
JdlError object to return error status. If an error was found, 'err.err' will be returned as true, one or two error messages will be set and 'err.flag' may have the following values:
= 0, OK
= 1, Null/blank string (or + character only)
= 2, Invalid character in string
= 3, Java conversion exception
= -1, End of line reached
Method Return:
Returns the field as an integer value; 0 if an error etc. was found.

2.3.2.5.10 Get next double - nextDouble

This method gets the next field from the line and interprets it a 'double' value. The error return mechanism for this version of the method may be convenient when the required valid values are in a defined range e.g >0.0

Method Definition:
public double nextDouble(double d_blankval, double d_errval)
Parameters List:
d_blankval
The double value to return if the end of the input line was reached or if the string has no characters in it.
d_errval
The double value to return if there is an error in the double value string.
Method Return:
Returns the field as a double value; 'd_blankval' if no more fields available or no digits present; 'd_errval' if a syntax error was found.

2.3.2.5.11 Get next double - nextDouble

This method gets the next field from the line and interprets it a 'double' value. In this version of the method, error conditions are returned in a JdlError object.

Method Definition:
public double nextDouble(JdlError err)
Parameters List:
err
JdlError object to return error status. If an error was found, 'err.err' will be returned as true, one or two error messages will be set and 'err.flag' may have the following values:
= 0, OK
= 1, Null/blank string (or + character only)
= 2, Invalid character in string
= 3, Java conversion exception
= -1, End of line reached
Method Return:
Returns the field as a double value; 0.0 if an error etc. found.

2.3.2.5.12 Get next double - nextDouble

This method gets the next field from the line and interprets it a 'double' value. In this version of the method, the number of decimal places given is also returned and an indicator if the number was specified in 'E' format.

Method Definition:
public double nextDouble(JdlInt nd, JdlError err)
Parameters List:
nd
Returns a flag giving the number of decimal places given in the input value or minus this number if it is in E format.
err
JdlError object to return error status. If an error was found, 'err.err' will be returned as true, one or two error messages will be set and 'err.flag' may have the following values:
= 0, OK
= 1, Null/blank string (or + character only)
= 2, Invalid character in string
= 3, Java conversion exception
= -1, End of line reached
Method Return:
Returns the field as a double value; 0.0 if error etc. found.

2.3.2.5.13 Get fixed width double - nextFixedWidthDouble

This method gets the next fixed width field from the line and interprets it as a 'double' value.

Method Definition:
public double nextFixedWidthDouble(int w, JdlError err)
Parameters List:
w
The field width.
err
JdlError object to return error status. If an error was found, 'err.err' will be returned as true, one or two error messages will be set and 'err.flag' may have the following values:
= 0, OK
= 1, Null/blank string (or + character only)
= 2, Invalid character in string
= 3, Java conversion exception
= -1, End of line reached
Method Return:
Returns the field as a double value; 0.0 if error etc. found.

2.3.2.6 Some additional methods

2.3.2.6.1 Introduction

This section includes some extra methods which may be useful when parsing a line with some specialised needs.

Methods:

Set to start - setStart
Number of fields - numberOfFields
Get separator characters - latestSeparator
Replace last field - replaceLastField
Get next XML field - nextXMLField

2.3.2.6.2 Set to start - setStart

This method starts the parsing again from the start of the string.

Method Definition:
public void setStart()
Parameters List:
none

2.3.2.6.3 Number of fields - numberOfFields

This method gets the number of fields present in the line.

Method Definition:
public int numberOfFields()
Parameters List:
none
Method Return:
The number of fields.

2.3.2.6.4 Get separator characters - latestSeparator

This method gets the separator characters following the latest field returned.

Method Definition:
public String latestSeparator()
Parameters List:
none
Method Return:
The character string (null if end of line or following a fixed width field)

2.3.2.6.5 Replace last field - replaceLastField

This method moves the current position back so that the last field currently returned can be accessed again by another call to one of the next field or remaining string methods. Note that the method cannot be used to go back more than one field.

Method Definition:
public void replaceLastField()
Parameters List:
none

2.3.2.6.6 Get next XML field - nextXMLField

This as a special purpose method to return the next 'XML' type field from a line. Such a field may either be a String or an XML type token. Note that this method does not make use of any separator characters except for those which surround the token ('<' and '>'). Returned strings may thus contain spaces etc. The moveBack(..) method may not be used in conjunction with this method.

Method Definition:
public String nextXMLField()
Parameters List:
none
Method Return:
The returned string or token field. If the field is a token, it starts with the character '<'. The XML element name may be derived from such a field using the method JdlUtils.getElementName(..). Returns null if no more fields are available.
⇑ Up 2   ⇑ Up 1   ⇑ Top of this