NAME

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

VERSION

version 2.0.11

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;

Return 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;

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

$eslifGrammar->currentDescription()

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

Return 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);

Return 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});

Return 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)});

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

$eslifGrammar->ruleDisplay($ruleId)

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

Return 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});

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

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

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

Return 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->ruleShowByLevel($level, $ruleId)

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

Return 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();

Return the description of current grammar.

$eslifGrammar->showByLevel($level)

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

Return 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

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.

cpanm MarpaX::ESLIF

perl -MCPAN -e shell
install MarpaX::ESLIF