NAME

MarpaX::ESLIF::Symbol - MarpaX::ESLIF's symbol

VERSION

version 6.0.23

SYNOPSIS

use MarpaX::ESLIF;

my $eslif = MarpaX::ESLIF->new();

my $stringSymbol = MarpaX::ESLIF::Symbol->new($eslif, type => 'string', pattern => '"String Pattern"');
#
# In ESLIF, a regex is anchored by default
#
my $regexSymbol = MarpaX::ESLIF::Symbol->new($eslif, type => 'regex', pattern => 'Regex.*Pattern', modifiers => 'A');
my $metaSymbol = MarpaX::ESLIF::Symbol->new($eslif, type => 'meta',
                                                    grammar => MarpaX::ESLIF::Grammar->new(
                                                                 $eslif,
                                                                 "<something> ::= <SOMETHING>\n<SOMETHING> ~ 'that'")
                                                    symbol => 'SOMETHING');
#
# For regex, a substitution pattern is supported
#
my $substitutionSymbol = MarpaX::ESLIF::Symbol->new($eslif, type => 'regex', pattern => 'Regex(.*)Pattern', modifiers => 'A', substitutionPattern => '$1', substitutionModifiers => 'g');

if (defined(my $match = $stringSymbol->try('String Pattern here'))) {
    print "==> String match: $match\n";
}

if (defined(my $match = $regexSymbol->try('Should match Regex etc Pattern in there'))) {
    print "==> Regex match: $match\n";
}

if (defined(my $match = $metaSymbol->try('something'))) {
    print "==> Meta match: $match\n";
}

if (defined(my $match = $substitutionSymbol->try('Should match Regex etc Pattern in there'))) {
    print "==> Meta match: $match\n";
}

External symbols can be of type string, regex or meta. They can be used agains a MarpaX::ESLIF::Recognizer or any external input.

A string pattern must follow ESLIF)s BNF, i.e. start and ends with:

' (single quote) character

" (double quote) character

“ (LEFT DOUBLE QUOTATION MARK) and ” characters (RIGHT DOUBLE QUOTATION MARK), respectively

A meta symbol must be a lexeme in the given external grammar.

DESCRIPTION

MarpaX::ESLIF::Symbol allows to create external symbols on demand

METHODS

MarpaX::ESLIF::Symbol->new($eslif, %options)

Returns a symbol instance, noted $symbol later. %options is a hash that contains:

type

Value must be "string", "regex" or "meta". Required.

pattern

Value is the pattern content. Required for "string" and "regex" types.

encoding

Value is the pattern encoding. Optional for "string" and "regex" types.

modifiers

Value is a string containing modifiers. Optional for "string" and "regex" types.

It must follow the specification of the Terminals section of MarpaX::ESLIF::BNF:

----------------------------------------------------------------
Modifiers   Explanation
----------------------------------------------------------------
e           Unset back-references in the pattern will match to empty strings
i           Case-insensitive
j           \u, \U and \x and unset back-references will act as JavaScript standard
m           Multi-line regex
n           Enable Unicode properties and extend meaning of meta-characters
s           A dot meta-character in the pattern matches all characters, including newlines
x           Enable comments. This has some limitation due marpaESLIF semantics
D           A dollar meta-character matches only at the end of the subject string
J           Allow duplicate names for sub-patterns
U           Inverts the "greediness" of the quantifiers
a           Meta-characters will be limited to their ASCII equivalent
u           Forces support of large codepoints
b           Could mean "forced binary" mode
c           Could mean "forced unicode character" mode
A           Remove the systematic anchoring
----------------------------------------------------------------

Note that a string pattern accepts only the i and c modifiers.

substitutionPattern

Value is the substitution content, writen as if this was an ESLIF string. Optional and supported only for "regex" type. If set, it is assumed that it is in the same encoding as pattern.

substitutionModifiers

Value is a string containing substitution modifiers. Optional and supported only for "regex" type.

It must follow the substitution specification of the Terminals section of MarpaX::ESLIF::BNF:

----------------------------------------------------------------
Modifiers         PCRE2 flag unset   PCR2 flag set
----------------------------------------------------------------
x                                    PCRE2_SUBSTITUTE_EXTENDED
g                                    PCRE2_SUBSTITUTE_GLOBAL
l                                    PCRE2_SUBSTITUTE_LITERAL
!                                    PCRE2_SUBSTITUTE_UNKNOWN_UNSET
f                                    PCRE2_SUBSTITUTE_UNSET_EMPTY
----------------------------------------------------------------

grammar

Value is an external grammar. Required for "meta" type.

symbol

Value is a lexeme in the external grammar. Required for "meta" type.

$symbol->try($eslif, $scalar)

Try to match the external symbol $symbol on $scalar, that can be anything. Return undef if failure, the matched string if success.

SEE ALSO

MarpaX::ESLIF, MarpaX::ESLIF::Recognizer

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.