class TaskJuggler::TextParser
The TextParser
implements a somewhat modified LL(1) parser. It uses a dynamically compiled state machine. Dynamically means, that the syntax can be extended during the parse process. This allows support for languages that can extend their syntax during the parse process. The TaskJuggler
syntax is such an beast.
This class is just a base class. A complete parser would derive from this class and implement the rule set and the functions _nextToken()_ and _returnToken()_. It also needs to set the array variables to declare all variables ($SOMENAME) that the scanner may deliver.
To describe the syntax the functions TextParser#pattern
, TextParser#optional
and TextParser#repeatable
can be used. When the rule set is changed during parsing, TextParser#updateParserTables
must be called to make the changes effective. The parser can also document the syntax automatically. To document a pattern, the functions TextParser#doc, TextParser#descr, TextParser#also and TextParser#arg can be used.
In contrast to conventional LL grammars, we use a slightly improved syntax descriptions. Repeated patterns are not described by recursive call but we use a repeat flag for syntax rules that consists of repeatable patterns. This removes the need for recursion elimination when compiling the state machine and makes the syntax a lot more readable. However, it adds a bit more complexity to the state machine. Optional patterns are described by a rule flag, not by adding an empty pattern.
To start parsing the input the function TextParser#parse
needs to be called with the name of the start rule.
MacroTable.rb – The TaskJuggler
III Project Management Software¶ ↑
Copyright © 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014
by Chris Schlaeger <cs@taskjuggler.org>
This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation.
StackElement.rb – The TaskJuggler
III Project Management Software¶ ↑
Copyright © 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014
by Chris Schlaeger <cs@taskjuggler.org>
This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation.
State.rb – The TaskJuggler
III Project Management Software¶ ↑
Copyright © 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014
by Chris Schlaeger <cs@taskjuggler.org>
This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation.
TokenDoc.rb – The TaskJuggler
III Project Management Software¶ ↑
Copyright © 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014
by Chris Schlaeger <cs@taskjuggler.org>
This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation.
Attributes
Public Class Methods
Create a new TextParser
object.
# File lib/taskjuggler/TextParser.rb, line 80 def initialize # This Hash will store the ruleset that the parser is operating on. @rules = { } # Array to hold the token types that the scanner can return. @variables = [] # An list of token types that are not allowed in the current context. # For performance reasons we use a hash with the token as key. The value # is irrelevant. @blockedVariables = {} # The currently processed rule. @cr = nil @states = {} # The stack used by the FSM. @stack = nil end
Public Instance Methods
# File lib/taskjuggler/TextParser.rb, line 220 def error(id, text, sfi = nil, data = nil) sfi ||= sourceFileInfo if @scanner # The scanner has some more context information, so we pass the error # on to the TextScanner. @scanner.error(id, text, sfi, data) else error(id, text, sfi, data) end end
Call all methods that start with ‘rule_’ to initialize the rules.
# File lib/taskjuggler/TextParser.rb, line 112 def initRules methods.each do |m| if m[0, 5] == 'rule_' # Create a new rule with the suffix of the function name as name. newRule(m[5..-1]) # Call the function. send(m) end end end
Limit the allowed tokens of the scanner to the subset passed by the tokenSet Array.
# File lib/taskjuggler/TextParser.rb, line 99 def limitTokenSet(tokenSet) return unless tokenSet # Create a copy of all supported variables. blockedVariables = @variables.dup # Then delete all that are in the limited set. blockedVariables.delete_if { |v| tokenSet.include?(v) } # And convert the list into a Hash for faster lookups. @blockedVariables = {} blockedVariables.each { |v| @blockedVariables[v] = true } end
Add a new rule to the rule set. name must be a unique identifier. The function also sets the class variable @cr to the new rule. Subsequent calls to TextParser#pattern
, TextParser#optional
or TextParser#repeatable
will then implicitly operate on the most recently added rule.
# File lib/taskjuggler/TextParser.rb, line 128 def newRule(name) # Use a symbol instead of a String. name = name.intern raise "Fatal Error: Rule #{name} already exists" if @rules.has_key?(name) if block_given? saveCr = @cr @rules[name] = @cr = TextParser::Rule.new(name) yield @cr = saveCr else @rules[name] = @cr = TextParser::Rule.new(name) end end
Identify the patterns of the most recently added rule as optional syntax elements.
# File lib/taskjuggler/TextParser.rb, line 160 def optional @cr.setOptional end
To parse the input this function needs to be called with the name of the rule to start with. It returns the result of the processing function of the top-level parser rule that was specified by ruleName. In case of an error, the result is false.
# File lib/taskjuggler/TextParser.rb, line 197 def parse(ruleName) @stack = [] @@expectedTokens = [] begin result = parseFSM(@rules[ruleName]) rescue TjException => msg if msg.message && !msg.message.empty? critical('parse', msg.message) end return false end result end
Add a new pattern to the most recently added rule. tokens is an array of strings that specify the syntax elements of the pattern. Each token must start with an character that identifies the type of the token. The following types are supported.
-
! a reference to another rule
-
$ a variable token as delivered by the scanner
-
_ a literal token.
func is a Proc object that is called whenever the parser has completed the processing of this rule.
# File lib/taskjuggler/TextParser.rb, line 154 def pattern(tokens, func = nil) @cr.addPattern(TextParser::Pattern.new(tokens, func)) end
Identify the patterns of the most recently added rule as repeatable syntax elements.
# File lib/taskjuggler/TextParser.rb, line 166 def repeatable @cr.setRepeatable end
Return the SourceFileInfo
of the TextScanner at the beginning of the currently processed TextParser::Rule
. Or return nil if we don’t have a current position.
# File lib/taskjuggler/TextParser.rb, line 215 def sourceFileInfo return @scanner.sourceFileInfo if @stack.nil? || @stack.length <= 1 @stack.last.firstSourceFileInfo end
This function needs to be called whenever new rules or patterns have been added and before the next call to TextParser#parse
. It’s perfectly ok to call this function from within a parse() call as long as the states that are currently on the stack have not been modified.
# File lib/taskjuggler/TextParser.rb, line 174 def updateParserTables saveFsmStack # Invalidate some cached data. @rules.each_value { |rule| rule.flushCache } @states = {} # Generate the parser states for all patterns of all rules. @rules.each_value do |rule| rule.generateStates(@rules).each do |s| @states[[ s.rule, s.pattern, s.index ]] = s end checkRule(rule) end # Compute the transitions between the generated states. @states.each_value do |state| state.addTransitions(@states, @rules) end restoreFsmStack end
# File lib/taskjuggler/TextParser.rb, line 231 def warning(id, text, sfi = nil, data = nil) sfi ||= sourceFileInfo if @scanner # The scanner has some more context information, so we pass the # warning on to the TextScanner. @scanner.warning(id, text, sfi, data) else warning(id, text, sfi, data) end end