apg_py.api.api.Api Class Reference

The API class. More...

Classes
class	NameList
	A helper class to keep track of rule and UDT names. More...

Public Member Functions
def	__init__ (self)
	API constructor. More...
def	generate (self, source, strict=False, phase='all')
	Generate a grammar object from an SABNF grammar syntax. More...
def	write_grammar (self, fname)
	Write the APG grammar to a file in format for later use by a parser. More...
def	display_rule_attributes (self, sort='index')
	Display the rule attributes. More...
def	display_rule_dependencies (self, sort='index')
	Display the rule dependencies. More...
def	find_line (self, index)
	Find the line number of the line in which the given character occurs. More...
def	display_errors (self)
	Display the list of SABNF errors, if any. More...
def	display_grammar (self)
	Displays an annotated version of the SABNF grammar syntax. More...
def	display_line (self, line_no)
	Displays a line with special characters accounted for. More...
def	display_underline (self, line_no, index)
	Displays a syntax line, underlined with carrets highlightling error locations. More...
def	display_rules (self, sort='index')
	Display the syntax rules and UDTs, if available. More...

Public Attributes
	parser
	ast
	errors
	lines
	grammar
	source
	input
	rules
	udts
	rule_names
	udt_names
	rule_deps
	attributes

Detailed Description

The API class.

Houses all of the facilities needed to process an SABNF grammar syntax into a grammar object that can be used by an APG parser.

Definition at line 61 of file api.py.

Constructor & Destructor Documentation

__init__()

def apg_py.api.api.Api.__init__

(

self

)

API constructor.

self.errors is a list of errors. Each item, error, contains:

• error['line'] - The line number(zero-based) where the error occurred.
• error['index'] - The character index where the error occurred.
• error['msg'] - A text message describing the error.

self.lines is a list of the text lines in the input grammar. Each item, line, contains:

• line['line_no'] - The zero-based line number.
• line['index'] - The offset to the first character of the line.
• line['length'] - The number of characters in the line, including the line end characters, if any.
• line['text_length'] - the number of characters in the line, not including the line end characters.
• line['end'] - Designates the line end characters.
  • 'CRLF' - Carriage return, line feed pair (\r\n or 0x0D0A)
  • 'CR' - Carriage return only (\r or 0x0D)
  • 'LF' - Line feed only (\n or 0x0A)
  • '' - Empty string means no line end at all (possible for last line.)

Definition at line 109 of file api.py.

Member Function Documentation

display_errors()

def apg_py.api.api.Api.display_errors

(

self

)

Display the list of SABNF errors, if any.

For each error, lists the line number and relative character offset where the error occurred and a descriptive message.

Returns

Returns a string of the displayed error messages.

Definition at line 427 of file api.py.

display_grammar()

def apg_py.api.api.Api.display_grammar

(

self

)

Displays an annotated version of the SABNF grammar syntax.

Each line is preceeded by the line number and character offset of the line.

Returns

Returns a string of the display text.

Definition at line 446 of file api.py.

display_line()

def apg_py.api.api.Api.display_line	(		self,
			line_no
	)

Displays a line with special characters accounted for.

Parameters

line_no

The line number to display

Returns

Returns a string of the displayed line.

Definition at line 462 of file api.py.

display_rule_attributes()

def apg_py.api.api.Api.display_rule_attributes	(		self,
			sort = 'index'
	)

Display the rule attributes.

Parameters

sort	Determines the order of rule display. 'index' (default) rules are listed in the order they appear in the grammar 'type' rules are listed by recursive type

Returns

Returns a string with the displayed rule attributes.

Definition at line 372 of file api.py.

display_rule_dependencies()

def apg_py.api.api.Api.display_rule_dependencies	(		self,
			sort = 'index'
	)

Display the rule dependencies.

For each rule R, list both the list of rules that R refers to (both directly and indirectly) and the list of rules that refer to R (both directly and indirectly).

Parameters

sort	Determines the order of display of the rules, R. 'index' (default) rules are listed in the order they appear in the grammar 'alpha' (actually anything but 'index') rules are listed alphabetically

Returns

Returns a string with the displayed rule dependencies.

Definition at line 386 of file api.py.

display_rules()

def apg_py.api.api.Api.display_rules	(		self,
			sort = 'index'
	)

Display the syntax rules and UDTs, if available.

Parameters

sort	'index'(default) - display rules in the order in which they are defined 'alpha' - display rules alphabetically

Definition at line 490 of file api.py.

display_underline()

def apg_py.api.api.Api.display_underline	(		self,
			line_no,
			index
	)

Displays a syntax line, underlined with carrets highlightling error locations.

Parameters

line_no	The line number to display
index	The index of the character to highlight

Returns

Returns a string of the displayed line.

Definition at line 472 of file api.py.

find_line()

def apg_py.api.api.Api.find_line	(		self,
			index
	)

Find the line number of the line in which the given character occurs.

Parameters

index

The (zero-based) index of the character in the source.

Returns

Returns the line number of the specified character. If index is out of range, returns the last line.

Definition at line 406 of file api.py.

generate()

def apg_py.api.api.Api.generate	(		self,
			source,
			strict = False,
			phase = 'all'
	)

Generate a grammar object from an SABNF grammar syntax.

Works its way through multiple steps.

• scan source for invalid characters, catalog lines
• parse the source, syntax check
• translate the parsed AST, semantic check
• attributes (left recursion, etc.) and rule dependencies
• construct the grammar object

  Parameters

  source	An SABNF grammar syntax as a Python string.
  strict	If True, source must be constrained to strictly follow the ABNF conventions of RFCs 5234 & 7405. If False, SABNF operators and line ending conventions are followed.
  phase	Used primarily for debugging.

• 'scanner' - generation halts after the scanner phase
• 'syntax' - generation halts after the syntax phase
• 'semantic' - generation halts after the semantic phase
• 'attributes' - generation halts after the attributes phase
• 'all' - (default) a grammar object is generated if no errors in any phases

  Returns

  If successful, returns the grammar object. Otherwise, returns None. Use, for example
  

          grammar = api.generator(...)
          if(not grammar):
              if(api.errors):
                  print(api.display_errors())
              raise Exception('api.generate() failed')
          # use the generated grammar
          

Definition at line 148 of file api.py.

write_grammar()

def apg_py.api.api.Api.write_grammar	(		self,
			fname
	)

Write the APG grammar to a file in format for later use by a parser.

Parameters

fname

the file name to write the grammar to

Definition at line 250 of file api.py.

Member Data Documentation

ast

apg_py.api.api.Api.ast

Definition at line 133 of file api.py.

attributes

apg_py.api.api.Api.attributes

Definition at line 240 of file api.py.

errors

apg_py.api.api.Api.errors

Definition at line 137 of file api.py.

grammar

apg_py.api.api.Api.grammar

Definition at line 139 of file api.py.

input

apg_py.api.api.Api.input

Definition at line 141 of file api.py.

lines

apg_py.api.api.Api.lines

Definition at line 138 of file api.py.

parser

apg_py.api.api.Api.parser

Definition at line 132 of file api.py.

rule_deps

apg_py.api.api.Api.rule_deps

Definition at line 146 of file api.py.

rule_names

apg_py.api.api.Api.rule_names

Definition at line 144 of file api.py.

rules

apg_py.api.api.Api.rules

Definition at line 142 of file api.py.

source

apg_py.api.api.Api.source

Definition at line 140 of file api.py.

udt_names

apg_py.api.api.Api.udt_names

Definition at line 145 of file api.py.

udts

apg_py.api.api.Api.udts

Definition at line 143 of file api.py.

---

The documentation for this class was generated from the following file:

• apg_py/api/api.py