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

rules[R]

Public Class Methods

new() click to toggle source

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

error(id, text, sfi = nil, data = nil) click to toggle source
# 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
initRules() click to toggle source

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
limitTokenSet(tokenSet) click to toggle source

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
newRule(name) { || ... } click to toggle source

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
optional() click to toggle source

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
parse(ruleName) click to toggle source

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
pattern(tokens, func = nil) click to toggle source

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
repeatable() click to toggle source

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
sourceFileInfo() click to toggle source

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
updateParserTables() click to toggle source

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
warning(id, text, sfi = nil, data = nil) click to toggle source
# 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