condor.classad
Class ClassAdParser

Object
  extended bycondor.classad.ClassAdParser

public class ClassAdParser
extends Object

A factory for creating classad expressions (instances of Expr), by parsing a textual or XML representation. Input can come from a String, a Reader, or an InputStream.

Version:
2.1
Author:
Marvin Solomon
See Also:
ClassAd, Expr

Field Summary
 int format
          Input format.
static int TEXT
          Flag indicating that input format is "text".
static int XML
          Flag indicating that input format is xml.
 
Constructor Summary
ClassAdParser()
          Create a parser to parse text input.
ClassAdParser(InputStream str)
          Create a parser to parse an InputStream in default (text) format.
ClassAdParser(InputStream str, int format)
          Create a parser to parse an InputStream.
ClassAdParser(int format)
          Create a parser to parse input.
ClassAdParser(Reader rdr)
          Create a parser to parse characters in default (text) format.
ClassAdParser(Reader rdr, int format)
          Create a parser to parse characters.
ClassAdParser(String s)
          Create a parser to parse a string in default (text) format.
ClassAdParser(String s, int format)
          Create a parser to parse a string.
 
Method Summary
 boolean enableTracing(boolean on)
          Control whether the actions of the parser are traced.
 int getNextToken()
          Get and remove the "lookahead" token: the first token not yet consumed by the parser.
 int nextToken()
          Get the "lookahead" token: the first token not yet consumed by the parser.
 Object nextValue()
          The the "value" of the lookahead token.
 Expr parse()
          Parse a classsad Expr from the current input stream.
 Expr parse(boolean acceptPrefix)
          Parse a classsad Expr from the current input stream.
 void printMessage(String msg)
          Print a message, decorated with the current line and column number.
 void reset(InputStream str)
          Reset this parser to parse input from an InputStream.
 void reset(Reader rdr)
          Reset this parser to parse input from a Reader.
 void reset(String s)
          Reset this parser to parse input from a String.
 PrintStream setErrorStream(PrintStream dest)
          Set the destination for error messages.
 int setVerbosity(int level)
          Set verbosity of error messages.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TEXT

public static final int TEXT
Flag indicating that input format is "text".

See Also:
XML, Constant Field Values

XML

public static final int XML
Flag indicating that input format is xml.

See Also:
TEXT, Constant Field Values

format

public final int format
Input format. Either TEXT or XML.

Constructor Detail

ClassAdParser

public ClassAdParser()
Create a parser to parse text input. An input source needs to be supplied by one of the reset methods before it can be used for parsing.


ClassAdParser

public ClassAdParser(int format)
Create a parser to parse input. An input source needs to be supplied by one of the reset methods before it can be used for parsing.

Parameters:
format - either TEXT or XML.

ClassAdParser

public ClassAdParser(String s)
Create a parser to parse a string in default (text) format.

Parameters:
s - the string to be parsed.

ClassAdParser

public ClassAdParser(String s,
                     int format)
Create a parser to parse a string.

Parameters:
s - the string to be parsed.
format - either TEXT or XML.

ClassAdParser

public ClassAdParser(InputStream str)
Create a parser to parse an InputStream in default (text) format.

Parameters:
str - the string to be parsed.

ClassAdParser

public ClassAdParser(InputStream str,
                     int format)
Create a parser to parse an InputStream.

Parameters:
str - the string to be parsed.
format - either TEXT or XML.

ClassAdParser

public ClassAdParser(Reader rdr)
Create a parser to parse characters in default (text) format.

Parameters:
rdr - the string to be parsed.

ClassAdParser

public ClassAdParser(Reader rdr,
                     int format)
Create a parser to parse characters.

Parameters:
rdr - the string to be parsed.
format - either TEXT or XML.
Method Detail

reset

public void reset(String s)
Reset this parser to parse input from a String.

Parameters:
s - the string to parse.

reset

public void reset(InputStream str)
Reset this parser to parse input from an InputStream.

Parameters:
str - the stream that supplies the input.

reset

public void reset(Reader rdr)
Reset this parser to parse input from a Reader.

Parameters:
rdr - the reader that supplies the input.

parse

public Expr parse(boolean acceptPrefix)
Parse a classsad Expr from the current input stream. If "acceptPrefix" is true, the parser attempt to find a maximal prefix of the input that is a valid Expr. More precisely, it stops at the first token than cannot be part of an Expr, and the stream is left positioned so that the next token to be read is the first token (if any) not part of the expression parsed. For example, if the input stream contains
    a + b c
 
The first call to parse() will return "a+b" and a subsequent call will return "c". Note that this "greedy" algorithm may fail to break the input into a sequence of valid expressions if it is possible. For example, the input
   a - - b
 
can be parsed as the two expressions a and --b, but the first call will stop at the second minus sign and fail, because a - is not a valid expression.

If "acceptPrefix" is false, the parse will fail unless all the remaining input, up to end-of-stream, forms a valid expression.

If an error is detected, the return value is null and one or more error messages will be printed to the current error stream, provided the verbosity level is non-zero. See setVerbosity(int) and setErrorStream(PrintStream).

If format is XML, the entire stream will be parsed as a single Expr as if "acceptPrefix" were false. In this case, subsequent calls will always return null.

Parameters:
acceptPrefix - if true, parse a maximal valid prefix of the input.
Returns:
the parsed Expr or null on EOF or error.
Throws:
IllegalStateException - if no input source has been specified by a constructor or a call to a reset method.
See Also:
nextToken()

parse

public Expr parse()
Parse a classsad Expr from the current input stream. This method is equivalent to parse(true).

Returns:
the parsed Expr or null on EOF or error.
Throws:
IllegalStateException - if no input source has been specified by a constructor or a call to a reset method.
See Also:
parse(boolean)

nextToken

public int nextToken()
Get the "lookahead" token: the first token not yet consumed by the parser. The result is an internal code. In the case of one-charcter tokens, the code is the same as the integer value of the character. The code 0 means end-of-file. The token is not removed from the input stream. For XML parsers, always returns 0;

Returns:
the code for the next token.
See Also:
getNextToken()

nextValue

public Object nextValue()
The the "value" of the lookahead token. For XML parsers, always returns null;

Returns:
the value
See Also:
nextToken()

getNextToken

public int getNextToken()
Get and remove the "lookahead" token: the first token not yet consumed by the parser. The result is an internal code. In the case of one-charcter tokens, the code is the same as the integer value of the character. The code 0 means end-of-file. The token is removed from the input stream. For XML parsers, always returns 0;

Returns:
the code for the next token.
See Also:
getNextToken()

enableTracing

public boolean enableTracing(boolean on)
Control whether the actions of the parser are traced. The default is not to trace. For XML parsers, has no effect.

Parameters:
on - if true, turn on tracing; if false, turn it off.
Returns:
the previous value of the tracing flag.

setVerbosity

public int setVerbosity(int level)
Set verbosity of error messages.
0
no messages
1
only show message and line number
2
also echo line in question (TEXT) or document info (XML)
3
also list tokens expected (TEXT only)
The default is maximally verbose.

Parameters:
level - desired level.
Returns:
the old verbosity level.
Throws:
IllegalArgumentException - if level < 0 or level > 0 and setErrorStream(PrintStream) has been called with a null argument.
See Also:
setErrorStream(PrintStream)

setErrorStream

public PrintStream setErrorStream(PrintStream dest)
Set the destination for error messages. By default, errors go to System.err.

Parameters:
dest - destination of error messages. A null value is equivalent to setVerbosity(0).
Returns:
the previous error stream.
See Also:
setVerbosity(int)

printMessage

public void printMessage(String msg)
Print a message, decorated with the current line and column number.

Parameters:
msg - the message to print.