org.vishia.zbnf
Class ZbnfParser

java.lang.Object
  org.vishia.zbnf.ZbnfParser

public class ZbnfParser
extends java.lang.Object

An instance of ZbnfParser contains a syntax prescript inside and is able to parse a text, test the syntax and output a tree of information given in the input text.
The invocation is in followed manner:

 ZbnfParser parser = new ZbnfParser(reportConsole);
 try{ parser.setSyntax(syntaxString);}
 catch(ParseException exception)
 { writeError("parser reading syntax error: " + exception.getMessage();
   return;
 }
 if(!parser.parse(inputString))
 { writeError(parser.getSyntaxErrorReport());
 }
 else
 { ParseResultItem resultItem = parser.getFirstParseResult();
   while( resultItem != null)
   { evaluateResult(resultItem);
     resultItem = resultItem.next(null))
   }
 }

The syntax

 <?ZBNF-www.vishia.org version="1.0" encoding="iso-8859-1" ?>  ##this first line is not prescribed but possible.
 $setLinemode.                                 ##if set, than the newline char \n is not overwritten as whitespace
 $endlineComment=##.                           ##defines the string introducing a comment to eol, default is //
 $comment=[*...*].                             ##... between [* ... *] all chars are ignored, default is /*...* /
 $keywords=if|else.                            ##that identifiers are not accepted as identifiers parsing by <$?...>
 $inputEncodingKeyword="encoding".             ##it helps to define the encoding of the input file via a keyword input-file
 $inputEncoding="UTF-8".                       ##it helps to define the encoding of the input file (useable outside parser core)
 $xmlns:nskey="value".                         ##defines a namespace key for XML output (useable outside parser core)
 
 component::=<$?name>=<#?number> { <value> , }. ##The first syntax term is the toplevel syntax.
 value::= val = [ a | b | c].         ##another syntax term
 

White space and comment handling when parsing

• The comment start/end characters defined in the syntax prescript are valid, if a calling of setSkippingComment(String, String, boolean), setSkippingEndlineComment(String, boolean), setWhiteSpaces(String), setLinemode(boolean) is not occured after setSyntax(String).
• Whitespaces and comments are skipped before any matching test occurs, but only if the syntax term in the syntax prescript has at least one whitespace at this position.
• The consideration of whitespaces in syntax terms are switchable off by using the <$NoWhiteSpaces>-construct, see ZbnfSyntaxPrescript.
• But if constant symbols are tested, first a comment is not skipped but tested. If the comment start with this constants, it is recognized as content. So it is possible to include comments in the parsing process . If the constant are not matched to a start of comment, the comment is skipped over and the test is repeated.

Evaluate the parsers result

sEmpty

private static final java.lang.String sEmpty

Helpfull empty string to build some spaces in strings.

See Also:

Constant Field Values

report

protected final Report report

To Report something.

nReportLevel

protected int nReportLevel

The current report level. This value is used to compare wether the report arguments are prepared or not. The test of the level before calling report(...) saves calculation time. It is set on starting of parse().

nLevelReportParsing

protected int nLevelReportParsing

The used reportlevel for output the progress of parsing. It is set on starting of parse().

nLevelReportComponentParsing

protected int nLevelReportComponentParsing

The used reportlevel for output the progress of parsing. It is set on starting of parse().

nLevelReportInfo

protected int nLevelReportInfo

The used reportlevel for output the progress of parsing. It is set on starting of parse().

nLevelReportError

protected int nLevelReportError

The used reportlevel for output the progress of parsing. It is set on starting of parse().

idReportParsing

protected int idReportParsing

The ident to report the progress of parsing.

idReportComponentParsing

protected int idReportComponentParsing

idReportInfo

protected int idReportInfo

idReportError

protected int idReportError

listSubPrescript

protected final java.util.TreeMap<java.lang.String,ZbnfSyntaxPrescript> listSubPrescript

The list of some sub syntax definitons.

listKeywords

java.util.TreeMap<java.lang.String,java.lang.String> listKeywords

Keywords

xmlnsList

java.util.TreeMap<java.lang.String,java.lang.String> xmlnsList

xmlns

bConstantSyntaxAsParseResult

protected boolean bConstantSyntaxAsParseResult

Set if constant syntax (terminate morphems) also should stored. See setStoringConstantSyntax()

mainScript

private ZbnfSyntaxPrescript mainScript

The main syntaxprescript setted from setSyntax(StringPart).

prescriptParserTopLevel

protected ZbnfParser.PrescriptParser prescriptParserTopLevel

subParserTopLevel

protected ZbnfParser.PrescriptParser.SubParser subParserTopLevel

sRightestError

protected java.lang.String sRightestError

The string and position found on the rightest position of an parse fault. It is necessarry to report a parsing error.

sExpectedSyntax

protected java.lang.String sExpectedSyntax

Required syntax on rightest parsing error position

xxxsFoundedSyntax

protected java.lang.String xxxsFoundedSyntax

founded syntax on rightest parsing error position

maxParseResultEntriesOnError

private int maxParseResultEntriesOnError

Maximum number of shown parsing results on error.

listParseResultOnError

java.util.ArrayList<ZbnfParseResultItem> listParseResultOnError

founded content on rightest parsing error position. This list will be filled with current parse result if it is the rightest position.

posRightestError

protected long posRightestError

The string and position found on the rightest position of an parse fault. It is necessarry to report a parsing error.

sCommentStringStart

java.lang.String sCommentStringStart

The start of a comment string, if null than no comment is known. The default value is "/ *" like Java or C.

sCommentStringEnd

java.lang.String sCommentStringEnd

The end of a comment string, it shoult be set if sCommentStringStart is not null. The default value is "* /" like Java or C.

bStoreComment

boolean bStoreComment

If it is true, the comment is stored in the ParserStore and is supplied by calling getFirstParseResult() and from there calling next().

sEndlineCommentStringStart

java.lang.String sEndlineCommentStringStart

The start of a comment string, if null than no comment is known.

sInputEncodingKeyword

protected java.lang.String sInputEncodingKeyword

If the syntax prescript contains $inputEncodingKeyword="...". this variable is set. The content are not used inside the parser itself, but may be requested outside.

sInputEncoding

protected java.lang.String sInputEncoding

If the syntax prescript contains $inputEncoding="...". this variable is set. The content are not used inside the parser itself, but may be requested outside.

bStoreEndlineComment

boolean bStoreEndlineComment

If it is true, the end-line-comment is stored in the ParserStore and is supplied by calling getFirstParseResult() and from there calling next().

sWhiteSpaces

java.lang.String sWhiteSpaces

Chars there are detect as white spaces:

bStoreNewline

boolean bStoreNewline

If it is true, a newline is stored in the ParserStore and is supplied by calling getFirstParseResult() and from there calling next().

bStoreOneSpaceOnWhitespaces

boolean bStoreOneSpaceOnWhitespaces

If it is true, one space is stored on whitespaces in the ParserStore and is supplied by calling getFirstParseResult() and from there calling next().

bStoreWhiteSpaces

boolean bStoreWhiteSpaces

If it is true, the complete white spaces are stored in the ParserStore and is supplied by calling getFirstParseResult() and from there calling next().

charsetInput

private java.nio.charset.Charset charsetInput

parserStoreTopLevel

private ZbnfParserStore parserStoreTopLevel

The actual parse result buffer.

ZbnfParser

public ZbnfParser(Report report)

Creates a empty parser instance.

Parameters:

report - A report output

ZbnfParser

public ZbnfParser(Report report,
                  int maxParseResultEntriesOnError)

Creates a empty parser instance.

Parameters:

report - A report output

maxParseResultEntriesOnError - if 0 than no parse result is stored. If >0, than the last founded parse result is stored to support better analysis of syntax errors, but the parser is slower.

setSyntax

public void setSyntax(java.lang.String syntax)
               throws java.text.ParseException

Sets the syntax from given string. Further expanations, see setSyntax(vishia.StringScan.StringPart)

Parameters:

syntax - The ZBNF-Syntax.

Throws:

java.text.ParseException

setSyntax

protected void setSyntax(java.io.InputStream input)
                  throws java.text.ParseException

Throws:

java.text.ParseException

setSyntax

public void setSyntax(java.io.File fileSyntax)
               throws java.nio.charset.IllegalCharsetNameException,
                      java.nio.charset.UnsupportedCharsetException,
                      java.io.FileNotFoundException,
                      java.io.IOException,
                      java.text.ParseException

Throws:

java.nio.charset.IllegalCharsetNameException

java.nio.charset.UnsupportedCharsetException

java.io.FileNotFoundException

java.io.IOException

java.text.ParseException

setSyntax

public void setSyntax(StringPart syntax)
               throws java.text.ParseException

Sets the syntax from given String. The String should contain the syntax in ZBNF-Format. The string is parsed and converted into a tree of objects of class SyntaxPrescript. The class SyntaxPrescript is private inside the Parser, but its matter of principle may be explained here.
The class SyntaxPrescript contains a list of elements (listSyntaxElements) or a list of such listSyntaxElements. The list of listSyntaxElements is used if there are some alternatives.
The listSyntaxElements contains objects of type String, SyntaxPrescript, Component or Repetition. It is the sequence of syntax elements of one syntax-path in ZBNF. An object of type String represents a terminal symbol (constant string). An element of SyntaxPrescript is an option construction [...|..|..] or also a simple option [...]. The Repetition represents the {...?...}-construction. A Repetition contains one or two objects of type SyntaxPrescript for the forward and optional backward syntax. This syntax-prescripts may be build complexly in the same way.
An object of type Component in the listSyntaxElements represents a construction <...?...>. It may contained the semantic information, it may containded a reference to another SyntaxPrescript if there is required in the wise <syntax.... It is also built if a construction of kind <!regex..., <$..., <#... or such else is given.
The tree of SyntaxPrescript is passed by syntax test, the right way is searched, see method parse()

Parameters:

syntax - The syntax in ZBNF-Format.

Throws:

java.text.ParseException - If any wrong syntax is containing in the ZBNF-string. A string-wise information of the error location is given.

setSyntax

private void setSyntax(StringPart syntax,
                       java.lang.String sDirParent)
                throws java.text.ParseException,
                       java.nio.charset.IllegalCharsetNameException,
                       java.nio.charset.UnsupportedCharsetException,
                       java.io.FileNotFoundException,
                       java.io.IOException

Throws:

java.text.ParseException

java.nio.charset.IllegalCharsetNameException

java.nio.charset.UnsupportedCharsetException

java.io.FileNotFoundException

java.io.IOException

importScript

private void importScript(java.lang.String sFile,
                          java.lang.String sDirParent)
                   throws java.nio.charset.IllegalCharsetNameException,
                          java.nio.charset.UnsupportedCharsetException,
                          java.io.FileNotFoundException,
                          java.io.IOException,
                          java.text.ParseException

Throws:

java.nio.charset.IllegalCharsetNameException

java.nio.charset.UnsupportedCharsetException

java.io.FileNotFoundException

java.io.IOException

java.text.ParseException

setSkippingComment

public void setSkippingComment(java.lang.String sCommentStringStart,
                               java.lang.String sCommentStringEnd,
                               boolean bStoreComment)

Set the mode of skipping comments. It it is set, comments are always skipped on every parse operation. This mode may or should be combinded with setIgnoreWhitespace.

Parameters:

sCommentStringStart - The start chars of comment string, at example '/ *'

sCommentStringEnd - The end chars of comment string, at example '* /'

bStoreComment - If it is true, the comment string will be stored in the ParserStrore and can be evaluated from the user.

setSkippingEndlineComment

public void setSkippingEndlineComment(java.lang.String sCommentStringStart,
                                      boolean bStoreComment)

Set the mode of skipping comments to end of line. It it is set, comments to end of line are always skipped on every parse operation. This mode may or should be combinded with setIgnoreWhitespace.

Parameters:

sCommentStringStart - The start chars of comment string to end of line, at example '/ /'

bStoreComment - If it is true, the comment string will be stored in the ParserStrore and can be evaluated from the user.

setWhiteSpaces

public void setWhiteSpaces(java.lang.String sWhiteSpaces)

Sets the chars which are recognized as white spaces. The default without calling this method is " \t\r\n\f", that is: space, tab, carrige return, new line, form feed. This mehtod is equal to the using of the syntaxprescript variable $Whitespaces,

Parameters:

sWhiteSpaces - Chars there are recognize as white space.

See Also:

setSyntax(String).

setLinemode

public void setLinemode(boolean bTrue)

Sets the line mode or not. The line mode means, a new line character is not recognize as whitespace, it must considered in syntax prescript as a signifying element. This mehtod is equal to the using of the syntaxprescript variable $setLinemode,

See Also:

setSyntax(String).

setReportIdents

public void setReportIdents(int identError,
                            int identInfo,
                            int identComponent,
                            int identFine)

sets the ident number for report of the progress of parsing. If the idents are >0 and < Report.fineDebug, theay are used directly as report level.

Parameters:

identError - ident for error and warning outputs.

identInfo - ident for progress information output.

identComponent - ident for output if a component is parsing

identFine - ident for fine parsing outputs.

parse

public boolean parse(java.lang.String input)

Parsed a given Input and produces a parse result. See parse(StringPart).

Parameters:

input -

Returns:

parse

public boolean parse(StringPart input)

parses a given Input and produces a parse result. The method setSyntax(vishia.StringScan.StringPart) should be called before. While parsing the pathes in the tree of SyntaxPrescript are tested. If a matching path is found, the method returns true, otherwise false. The result of parsing is stored inside the parser (private internal class ParserStore). To evaluate the parse result see getFirstParseResult().

Parameters:

input - The source to be parsed.

Returns:

true if the input is matched to the syntax, otherwise false.

parse

public boolean parse(StringPart input,
                     java.util.List<java.lang.String> additionalInfo)

parses a given Input, see [parse(StringPart), but write additional semantic informations into the first parse result (into the top level component).

Parameters:

input - The text to parse

additionalInfo - Pairs of semantic idents and approriate information content. The elements [0], [2] etc. contains the semantic identifier whereas the elements [1], [3] etc. contains the information content.

Returns:

true if the input is matched to the syntax, otherwise false.

searchSyntaxPrescript

private ZbnfSyntaxPrescript searchSyntaxPrescript(java.lang.String sSyntax)

reportSyntax

public void reportSyntax(Report report,
                         int reportLevel)

Reports the syntax.

reportStore

public void reportStore(Report report,
                        int reportLevel,
                        java.lang.String sTitle)

Reports the whole content of the parse result. The report is grouped into components. A component is represented by an own syntax presript, written in the current syntax prescript via <ident...>. A new nested component forces a deeper level.
The output is written in the form:

 parseResult:  <?semanticIdent> Component
 parseResult:   <?semanticIdent> ident="foundedString"
 parseResult:   <?semanticIdent> number=foundedNumber
 parseResult:  </?semanticIdent> Component
 

Every line is exactly one entry in the parsers store.

Parameters:

report - The report output instance

reportLevel - level of report. This level is shown in output. If the current valid reportLevel of report is less than this parameter, no action is done.

reportStore

public void reportStore(Report report,
                        int reportLevel)

reportStore

public void reportStore(Report report)

Reports the whole content of the parse result in the Report.fineInfo-level.

Parameters:

report - The report output instance.

See Also:

reportStore(Report report, int reportLevel)}.

reportStoreComponent

private int reportStoreComponent(ZbnfParseResultItem parseResultItem,
                                 Report report,
                                 int level,
                                 ZbnfParseResultItem parent,
                                 int reportLevel)

Inner method to report the content of the parse result

Parameters:

parseResultItem - The first item to report, it is the next item behind componentes first (head-) item, if it is a component.

report - The report system.

level - Level of nested componentes

parent - If not null, the inner items of parent component are reported.

Returns:

The number of written lines.

getInputEncodingKeyword

public java.lang.String getInputEncodingKeyword()

Returns the setting of $inputEncodingKeyword="...". in the syntax prescript or null it no such entry is given.

Returns:

getInputEncoding

public java.nio.charset.Charset getInputEncoding()

Returns the setting of $inputEncoding="...". in the syntax prescript or null it no such entry is given.

Returns:

getExpectedSyntaxOnError

public java.lang.String getExpectedSyntaxOnError()

Returns the expected syntax on error position. This position is matched to the report of getFoundenInputOnError(). Because the syntax may be differently, much more as a deterministic string is possible, the returned syntax are only one possibility and don't may be non-ambiguous. It may be only a help to detect the error. It is the same problem as error messages by compilers.

Returns:

A possible expected syntax.

getLastFoundedResultOnError

public java.lang.String getLastFoundedResultOnError()

Returns the up to now founded result on error position. This position is matched to the report of getFoundenInputOnError() and getExpectedSyntaxOnError().

Returns:

A possible founded result or null if this feature is not switched on.

getFoundedInputOnError

public java.lang.String getFoundedInputOnError()

Returns about 50 chars of the input string founded at the parsing error position. If the error position is the end of file or near them, this string ends with the chars "<<

Returns:

The part of input on error position.

getInputPositionOnError

public long getInputPositionOnError()

Returns the position of error in input string. It is the same number as in report.

throwSyntaxErrorException

protected void throwSyntaxErrorException(java.lang.String text)
                                  throws java.text.ParseException

throws a ParseException with the infos of syntax error from last parsing. This method is simple callable if a routine should be aborted on syntax error. Inside a string via @see getSyntaxErrorReport() is build.

Parameters:

text - leading text

Throws:

java.text.ParseException - immediate.

getSyntaxErrorReport

public java.lang.String getSyntaxErrorReport()

assembles a string with a user readable syntax error message. This method is useable if the user should be inform about the error and the application should be controlled by the users directives.

Returns:

String with syntax error message.

getFirstParseResult

public ZbnfParseResultItem getFirstParseResult()

Returns the first parse result item to start stepping to the results. See samples at interface ParseResultItem.

Returns:

The first parse result item.

getXmlnsFromSyntaxPrescript

public java.util.TreeMap<java.lang.String,java.lang.String> getXmlnsFromSyntaxPrescript()

Returns a TreeMap of all xmlns keys and strings. This is the result of detecting $xmlns:ns="string". -expressions in the syntax prescript.

setStoringConstantSyntax

public boolean setStoringConstantSyntax(boolean bStore)

Determines wether or not constant syntax (teminal syntax items or terminal morphes) should also strored in the result buffer.

Parameters:

bStore - true if they should strored, false if not.

Returns:

The old value of this setting.

stop

private void stop()

It's a debug helper. The method is empty, but it is a mark to set a breakpoint.