NAME

MarpaX::ESLIF::Grammar - MarpaX::ESLIF's grammar

VERSION

version 3.0.17

SYNOPSIS

  use MarpaX::ESLIF;

  my $eslif = MarpaX::ESLIF->new();
  my $data = do { local $/; <DATA> };
  my $eslifGrammar = MarpaX::ESLIF::Grammar->new($eslif, $data);

  __DATA__
  #
  # This is an example of a calculator grammar
  #
  :start   ::= Expression
  :default ::=             action        => do_op
                           symbol-action => do_symbol
                           free-action   => do_free     # Supported but useless
  :desc    ::= 'Calculator'
  :discard ::= whitespaces event  => discard_whitespaces$
  :discard ::= comment     event  => discard_comment$

  event ^Number = predicted Number
  event Number$ = completed Number
  Number   ::= NUMBER   action => ::shift

  event Expression$ = completed Expression
  event ^Expression = predicted Expression
  Expression ::=
      Number                                           action => do_int
      | '(' Expression ')'              assoc => group action => ::copy[1]
     ||     Expression '**' Expression  assoc => right
     ||     Expression  '*' Expression
      |     Expression  '/' Expression
     ||     Expression  '+' Expression
      |     Expression  '-' Expression

  whitespaces ::= WHITESPACES
  comment ::= /(?:(?:(?:\/\/)(?:[^\n]*)(?:\n|\z))|(?:(?:\/\*)(?:(?:[^\*]+|\*(?!\/))*)(?:\*\/)))/u

  :lexeme ::= NUMBER pause => before event => ^NUMBER
  :lexeme ::= NUMBER pause => after  event => NUMBER$

  :desc      ~ 'Calculator Tokens'
  NUMBER     ~ /[\d]+/   name => 'NUMBER Lexeme'
  WHITESPACES ~ [\s]+    name => 'WHITESPACES Lexeme'

As many grammars as wanted can be created using the same MarpaX::ESLIF parent. After creating a MarpaX::ESLIF::Grammar instance, the user can use the parse() method to have an immediate parse value, or create a MarpaX::ESLIF::Recognizer instance to control the parse.

DESCRIPTION

MarpaX::ESLIF::Grammar is the second step after getting a MarpaX::ESLIF instance.

METHODS

MarpaX::ESLIF::Grammar->new($eslif, $grammar, $encoding)

   my $eslifGrammar = MarpaX::ESLIF::Grammar->new($eslif, $data);

Returns a grammar instance, noted $eslifGrammar later. Parameters are:

$eslif

MarpaX::ESLIF object instance. Required.

$grammar

A scalar containing the grammar. Required.

$encoding

A scalar containing the grammar encoding. Optional.

Encoding will always be guessed if not given.

$eslifGrammar->ngrammar()

  printf "Number of sub-grammars: %d\n", $eslifGrammar->ngrammar;

Returns the number of sub-grammars.

A grammar can have multiple sub-grammars, identified by a level. Internally this is a sparse array of grammars, and it is legal that a level is not defined.

$eslifGrammar->currentLevel()

  printf "Current indice: %d\n", $eslifGrammar->currentLevel;

Returns the current level, which is always the first indice that have a defined sub-grammar.

$eslifGrammar->currentDescription()

  printf "Current description: %s\n", $eslifGrammar->currentDescription;

Returns the description of the current level, with the same encoding as found in the grammar. This correspong to the :desc meta-symbol in a grammar.

$eslifGrammar->descriptionByLevel($level)

  printf "Level 1 description: %s\n", $eslifGrammar->descriptionByLevel(1);

Returns the description of the grammar at indice $level, with the same encoding as found in the grammar.

$eslifGrammar->currentRuleIds

  printf "Current Rule Ids: %s\n", join(' ', @{$eslifGrammar->currentRuleIds});

Returns the list of rule identifiers of the current grammar, as a reference to an array of integers.

Rule identifiers are integers that uniquely identify a rule.

$eslifGrammar->ruleIdsByLevel($level)

  printf "Level 1 Rule Ids: %s\n", join(' ', @{$eslifGrammar->ruleIdsByLevel(1)});

Returns the list of rule identifiers at indice $level, as a reference to an array of integers.

$eslifGrammar->currentSymbolIds

  printf "Current Symbol Ids: %s\n", join(' ', @{$eslifGrammar->currentSymbolIds});

Returns the list of symbol identifiers at current level, as a reference to an array of integers.

$eslifGrammar->symbolIdsByLevel($level)

  printf "Level 1 Symbol Ids: %s\n", join(' ', @{$eslifGrammar->symbolIdsByLevel(1)});

Returns the list of symbol identifiers at indice $level, as a reference to an array of integers.

$eslifGrammar->currentProperties

  use Data::Dumper; printf "Current Properties: %s\n", Dumper($eslifGrammar->currentProperties);

Returns the current grammar properties as an instance of <MarpaX::ESLIF::Grammar::Properties>.

$eslifGrammar->propertiesByLevel($level)

  use Data::Dumper; printf "Properties at level %d: %s\n", $level, Dumper($eslifGrammar->propertiesByLevel($level));

Returns the grammar properties at level $level as an instance of <MarpaX::ESLIF::Grammar::Properties>.

$eslifGrammar->currentRuleProperties($ruleId)

  use Data::Dumper; printf "Current Rule Properties: %s\n", Dumper($eslifGrammar->currentRuleProperties($ruleId));

Returns the rule number $ruleId properties as an instance of MarpaX::ESLIF::Grammar::Rule::Properties.

$eslifGrammar->rulePropertiesByLevel($level, $ruleId)

  use Data::Dumper; printf "Rule Properties at level %d: %s\n", $level, Dumper($eslifGrammar->currentRuleProperties($ruleId));

Returns the rule number $ruleId properties at grammar level $level as an instance of MarpaX::ESLIF::Grammar::Rule::Properties.

$eslifGrammar->currentSymbolProperties($symbolId)

  use Data::Dumper; printf "Current Symbol Properties: %s\n", Dumper($eslifGrammar->currentSymbolProperties($symbolId));

Returns the symbol number $symbolId properties as an instance of MarpaX::ESLIF::Grammar::Symbol::Properties.

$eslifGrammar->symbolPropertiesByLevel($level, $symbolId)

  use Data::Dumper; printf "Symbol Properties at level %d: %s\n", $level, Dumper($eslifGrammar->currentSymbolProperties($symbolId));

Returns the symbol number $symbolId properties at grammar level $level as an instance of MarpaX::ESLIF::Grammar::Symbol::Properties.

$eslifGrammar->ruleDisplay($ruleId)

  printf "Rules display:\n\t%s\n", join("\n\t", map { $eslifGrammar->ruleDisplay($_) } @{$eslifGrammar->currentRuleIds});

Returns the name of a rule identified by its rule ID $ruleId.

$eslifGrammar->symbolDisplay($symbolId)

  printf "Symbols display:\n\t%s\n", join("\n\t", map { $eslifGrammar->symbolDisplay($_) } @{$eslifGrammar->currentSymbolIds});

Returns the name of a rule identified by its rule ID $ruleId.

$eslifGrammar->ruleShow($ruleId)

  printf "Rules shows:\n\t%s\n", join("\n\t", map { $eslifGrammar->ruleShow($_) } @{$eslifGrammar->currentRuleIds});

Returns the description of a rule identified by its rule ID $ruleId.

$eslifGrammar->ruleDisplayByLevel($level, $ruleId)

  printf "Level 1 Rule display:\n\t%s\n", join("\n\t", map { $eslifGrammar->ruleDisplayByLevel(1, $_) } @{$eslifGrammar->ruleIdsByLevel(1)});

Returns the name of a rule at a specificed indice $level identified by its rule ID $ruleId. This correspond to the name adverb, if present, else a default naming applies.

$eslifGrammar->symbolDisplayByLevel($level, $symbolId)

  printf "Level 1 Symbol display:\n\t%s\n", join("\n\t", map { $eslifGrammar->symbolDisplayByLevel(1, $_) } @{$eslifGrammar->symbolIdsByLevel(1)});

Returns the name of a symbol at a specificed indice $level identified by its symbol ID $symbolId. This correspond to the name adverb, if present, else a default naming applies.

$eslifGrammar->ruleShowByLevel($level, $ruleId)

  printf "Level 1 Rules shows:\n\t%s\n", join("\n\t", map { $eslifGrammar->ruleShowByLevel(1, $_) } @{$eslifGrammar->ruleIdsByLevel(1)});

Returns the description of a rule at a specified indice $level, identified by its rule ID $ruleId.

$eslifGrammar->show()

  printf "Description of current grammar: %s\n", $eslifGrammar->show();

Returns the description of current grammar.

$eslifGrammar->showByLevel($level)

  printf "Level 1 grammar description: %s\n", $eslifGrammar->showByLevel(1);

Returns the description of the grammar at indice $level.

$eslifGrammar->parse($recognizerInterface, $valueInterface)

  my $recognizerInterface = MyRecognizer->new();
  my $valueInterface      = MyValue->new();
  if ($eslifGrammar->parse($recognizerInterface, $valueInterface)) {
    printf "Parse result: %s\n", $valueInterface->getResult;
  }

Short version of input validation and valuation, that will never give back control to the user until the end or a failure. No event is possible when using this method. If this method returns true, then it is guaranteed that the result is in $valueInterface-getResult()>.

Please refer to MarpaX::ESLIF::Recognizer::Interface and MarpaX::ESLIF::Value::Interface for the $recognizerInterface and $valueInterface required parameters.

SEE ALSO

MarpaX::ESLIF::Recognizer::Interface, MarpaX::ESLIF::Recognizer::Interface, MarpaX::ESLIF::Value::Interface, MarpaX::ESLIF::Grammar::Properties, MarpaX::ESLIF::Grammar::Rule::Properties, MarpaX::ESLIF::Grammar::Symbol::Properties

AUTHOR

Jean-Damien Durand <jeandamiendurand@free.fr>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Jean-Damien Durand.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.