=head1 NAME

pir.pg - A PIR grammar for PGE.

TODO:

 1. fix Heredocs parsing
 2. Test and fix things

Some rules/tokens have names in capitals; these represent the C<pure> token.
Each such token has also a rule with the same name in lowercase, which does
reports a syntax error if the token was not read. For instance, <STRING_CONST>
will match a string constant, but <string_constant> will report an error if
there was no STRING_CONST token.

=cut


grammar PIR::Grammar;


token TOP {
    ^ <program> [ $ | <syntax_error: end of file expected> ]
   {*}
}

rule program {
    <.NL>*
    <compilation_unit>
    [ <.NL> <compilation_unit> ]*
    [ <.NL> | <warning: no newline at end of file> ]
    {*}
}

token compilation_unit {
    | <expansion>  {*} #= expansion
    | <sub_def>    {*} #= sub_def
    | <const_def>  {*} #= const_def
    | <pragma>     {*} #= pragma
}


=head2 Sub defs, sub pragmas, sub body and parameters

=cut

rule sub_def {
    '.sub' <sub_id> <sub_pragma>* <.nl>
    <param_decl>*
    <labeled_pir_instr>*
    [ '.end' | <syntax_error: '.end' expected to close method/sub body> ]
    {*}
}

rule sub_id {
    | <IDENT>            {*} #= IDENT
    | <STRING_CONST>     {*} #= STRING_CONST
    | <syntax_error: subroutine identifier expected>
}

=head3 sub_pragmas

=cut

rule sub_pragma {
    | ':load'
    | ':init'
    | ':immediate'
    | ':postcomp'
    | ':main'
    | ':anon'
    | ':lex'
    | <vtable_pragma>  {*} #= vtable_pragma
    | <multi_pragma>   {*} #= multi_pragma
    | <outer_pragma>   {*} #= outer_pragma
}

rule vtable_pragma {
    ':vtable' <parenthesized_string>?
    {*}
}

rule parenthesized_string {
    '('
    <string_constant>
    <.right_paren>
    {*}
}

rule multi_pragma {
    ':multi' <.left_paren> <multi_types>? <.right_paren>
    {*}
}

rule left_paren {
    '(' | <syntax_error: '(' expected>
}

rule right_paren {
    ')' | <syntax_error: ')' expected>
}

rule outer_pragma {
    ':outer'
    <.left_paren>
    <sub_id>
    <.right_paren>
    {*}
}

rule multi_types {
    <multi_type> [ ',' <multi_type> ]*
}

rule multi_type {
    | <pir_type>       {*} #= pir_type
    | '_'              {*} #= any_type
    | <keylist>        {*} #= keylist
    | <IDENT>          {*} #= ident
    | <STRING_CONST>   {*} #= string_constant
}

rule param_decl {
    '.param' <parameter> <parameter_flags> <.nl>
    {*}
}

rule parameter {
    | <pir_type> [ <STRING_CONST> '=>' ]? <IDENT>
    | <syntax_error: parameter type or register expected>
}

rule parameter_flags {
    [ <get_flags> | ':unique_reg' ]*
}



=head2 PIR instructions

=cut

rule labeled_pir_instr {
    [ <label> <instr>?
    | <instr>
    ]
    <.nl>
    {*}
}

rule labeled_pasm_instr {
    [ <label> <pasm_instr>?
    | <pasm_instr>
    ]
    <.nl>
    {*}
}

rule instr {
    | <pir_instr>    {*} #= pir_instr
    | <pasm_instr>   {*} #= pasm_instr
}

token pir_instr {
    | <local_decl>         {*} #= local_decl
    | <lexical_decl>       {*} #= lexical_decl
    | <const_def>          {*} #= const_def
    | <globalconst_def>    {*} #= globalconst_def
    | <conditional_stat>   {*} #= conditional_stat
    | <assignment_stat>    {*} #= assignment_stat
    | <return_stat>        {*} #= return_stat
    | <sub_invocation>     {*} #= sub_invocation
    | <macro_invocation>   {*} #= macro_invocation
    | <goto_stat>          {*} #= goto_stat
    | <source_info>        {*} #= source_info
}

rule macro_invocation {
    <macro_id> <parenthesized_args>?
}


=head2 Local declarations

Local declarations can be done using C<.local> in normal context.
TODO: how to declare locals in a macro? this needs to be fixed.

=cut

rule local_decl {
    '.local'
    [ <pir_type> | <syntax_error: type for local symbol expected> ]
    <local_id> [ ',' <local_id> ]*
    {*}
}


rule local_id {
    <id> ':unique_reg'?
    {*}
}

rule lexical_decl {
    '.lex' <string_constant> <.comma>
    [ <target> | <syntax_error: register or identifier expected> ]
    {*}
}

rule comma {
    ',' | <syntax_error: ',' expected>
}



=head2 Const definition

Const definitions, a check is done for the constant type and the type of the constant value.

=cut

rule const_def {
    '.const' <const_def_tail>

}

rule globalconst_def {
    '.globalconst' <const_def_tail>

}

rule const_def_tail {
    | 'int'    <const_assign> <int_constant>     {*} #= int_const_def
    | 'num'    <const_assign> <float_constant>   {*} #= num_const_def
    | 'pmc'    <const_assign> <string_constant>  {*} #= pmc_const_def
    | 'string' <const_assign> <string_constant>  {*} #= string_const_def
    | <syntax_error: type expected for constant>
}

rule const_assign {
    <id> <.assign_token>
    {*}
}

rule assign_token {
    '=' | <syntax_error: '=' expected>
}

rule conditional_stat {
    $<sym>=[if|unless] <conditional_expr> <.goto> <label_identifier>
    {*}
}

rule goto {
    goto | <syntax_error: 'goto' expected>
}

token label_identifier {
    | <IDENT>          {*} #= IDENT
    | <pasm_instr>     {*} #= pasm_instr
    | <syntax_error: label identifier expected>
}

rule conditional_expr {
    | null <target>                                            {*} #= null_expr
    | <simple_expr> [ <relational_operator> <simple_expr> ]?   {*} #= rel_expr
}

rule goto_stat {
    goto <label_identifier>
    {*}
}


token relational_operator {
    || '=='
    || '!='
    || '<='
    || '<'
    || '>='
    || '>'
}

token binary_operator {
    | '+'  | '-'  | '/'  | '**' | '*' | '%' | '<<' | '>>>'
    | '>>' | '&&' | '||' | '~~' | '|' | '&' | '~'  | '.'
}

token assign_operator {
    | '+=' | '-=' | '/=' | '%='  | '*='  | '.='
    | '&=' | '|=' | '~=' | '<<=' | '>>=' | '>>>='
}

token unary_operator {
    '!' | '-' | '~'
}

rule expression {
    | <binary_expr>   #= binary_expr
    | <unary_expr>    #= unary_expr
    | <simple_expr>   #= simple_expr
}

rule binary_expr {
    <simple_expr> <binary_operator> <simple_expr>
    {*}
}

rule unary_expr {
    <unary_operator> <simple_expr>
    {*}
}

token simple_expr {
    | <constant>  {*} #= constant
    | <target>    {*} #= target
}


rule keylist {
    '['
    <key> [ <separator> <key> ]*
    <right_bracket>
}

token separator {
    | ','
    | ';'
}

rule key {
    <simple_expr>
    {*}
}


rule assignment_stat {
    | <target> '=' <rhs>                        {*} #= simple_assign
    | <target> <assign_operator> <simple_expr>  {*} #= augment_assign
    | <target> <keylist> '=' <simple_expr>      {*} #= key_assign
    | <result_var_list> '=' <short_sub_call>    {*} #= subcall_assign
}

rule rhs {
    | <short_sub_call>                        {*} #= short_sub_call
    | <target> <keylist>                      {*} #= target_keylist
    | <expression>                            {*} #= expression
    | <pasm_instruction> \N*                  {*} #= pasm_instr
    | <heredoc>                               {*} #= heredoc
    | 'new' [ <STRING_CONST> | <keylist> ]    {*} #= instantiation
}



rule heredoc {
    '<<' <string_constant> <.nl>
    <heredoc_string>
    [ <heredoc_label> | <syntax_error: heredoc label expected> ]
}

token heredoc_label {
    [ ^^ | <syntax_error: no whitespace allowed in front of a heredoc label> ]
    <IDENT>
    [ $$ | <syntax_error: no whitespace allowed after a heredoc> ]
}

# fix this:
rule heredoc_string {
    [ \N | \n ]*
}

rule long_sub_call {
    '.begin_call' <.nl>
    <arguments>
    <long_call_invocation> <.nl>
    [ <local_decl> <.nl> ]*
    <result_values>
    [ '.end_call'  | <syntax_error: '.end_call' expected> ]
    {*}
}

rule long_call_invocation {
    | <method_invocation>        {*} #= method_invocation
    | <non_method_invocation>    {*} #= non_method_invocation
}

rule non_method_invocation {
    [ '.call' | '.nci_call' ]
    [ <target> | <syntax_error: variable or register expected that holds the sub object> ]
    {*}
}

rule method_invocation {
    '.invocant' <target> <.nl>
    '.meth_call' <method>
    {*}
}

#
# in case of a method call, these options are allowed:
# - foo.bar()
# - foo. bar()
# - foo .bar()
#
# where the method ('bar') can also be a quoted string.
# it's important to recognize that the dot can NOT be written as
# a separate token, it must be glued to either the invocant or the method.
# otherwise it's recognized as a concatentation.
#

rule short_sub_call {
    <short_call_invocant>
    <parenthesized_args>             # sub args
    <process_heredocs>               # process the list of heredoc labels, if any
    <clear_heredocs>
    {*}
}

rule short_call_invocant {
    | <target> [ \.<method> ]
    | [ <target>\. ]? <method>
    {*}
}

rule method {
    | <target>        {*} #= target
    | <STRING_CONST>  {*} #= string_constant
}

rule sub_invocation {
    | <long_sub_call>    {*} #= long_sub_call
    | <short_sub_call>   {*} #= short_sub_call
}

rule result_var_list {
    '('
    [
      <result_var>
      [ ','
        [ <result_var> | <syntax_error: target to store result expected after ','> ]
      ]*
    ]?
    <right_paren>
    {*}
}

rule result_var {
    <target> <get_flags>*
    {*}
}

rule parenthesized_args {
    '('
    [
      <arg>
      [ ','
        [ <arg> | <syntax_error: argument expected after ','> ]
      ]*
    ]?
    <right_paren>
    {*}
}

rule arg {
    [ <FLOAT_CONST>   {*} #= float_constant
    | <INT_CONST>     {*} #= int_constant
    | <STRING_CONST>  {*} #= string_constant
      [ '=>'
        [ <target> | <syntax_error: target for named argument expected> ]
      ]?
    | <target>        {*} #= target
    | <heredoc_id>    {*} #= heredoc_id
    ] <set_flags>*
    {*}
}

token heredoc_id {
    '<<' <string_constant> <store_heredoc_label: $1>
}

#rule heredoc_label {
#    .* ^^ <ident> $$
#}

rule arguments {
    [ '.arg'
      [ <simple_expr> | <syntax_error: argument expression expected> ]
      <set_flags>*
      <.nl>
    ]*
    {*}
}

rule result_values {
    [ '.result'
      [ <target> | <syntax_error: target expected to hold the result> ]
      <get_flags>*
      <.nl>
    ]*
    {*}
}

rule set_flags {
    | ':flat'
    | <named_flag>
}

rule get_flags {
    | ':slurpy'
    | ':optional'
    | ':opt_flag'
    | <named_flag>
}

rule named_flag {
    ':named' <parenthesized_string>?
    {*}
}

token return_stat {
    | <long_return_stat>   {*} #= long_return_stat
    | <short_return_stat>  {*} #= short_return_stat
    | <long_yield_stat>    {*} #= long_yield_stat
    | <short_yield_stat>   {*} #= short_yield_stat
    | <tail_call>          {*} #= tail_call
}

rule long_return_stat {
    '.begin_return' <.nl>
    [ '.return' <return_value> ]*
    [ '.end_return' | <syntax_error: '.end_return' expected> ]
    {*}
}

rule short_return_stat {
    '.return' <parenthesized_args>
    {*}
}

rule long_yield_stat {
    '.begin_yield' <.nl>
    [ '.yield' <return_value> ]*
    [ '.end_yield' | <syntax_error: '.end_yield' expected> ]
    {*}
}


rule return_value {
    [ <simple_expr> | <syntax_error: simple expression expected> ]
    <set_flags>*
    <.nl>
}

rule short_yield_stat {
    '.yield' <parenthesized_args>
    {*}
}

rule tail_call {
    '.return' <short_sub_call>
    {*}
}

rule macro_def {
    '.macro' <id> <macro_parameters>? <.nl>
    <macro_body>
    {*}
}

rule macro_parameters {
    '(' <id_list>? ')'
    {*}
}

=head2 Macro body

In order to be able to parse macro identifiers, before
the macro body is parsed, some rules are redefined.
After parsing the macro body, they are restored.

=cut

regex macro_body {
    <init_macro_rules>
    <labeled_pir_instr>*
    '.endm'
    <close_macro_rules>
    {*}
}

token expansion {
    | <macro_def>     {*} #= macro_def
    | <include>       {*} #= include
    | <pasm_constant> {*} #= pasm_constant
}

rule pasm_constant {
    '.constant' <IDENT>
    [ <pasm_register> | <constant> ]
    {*}
}

token constant {
    | <FLOAT_CONST>  {*} #= FLOAT_CONST
    | <INT_CONST>    {*} #= INT_CONST
    | <STRING_CONST> {*} #= STRING_CONST
}


# only a PASM register is allowed for pasm_constant
#
token pasm_register {
    [P|I|N|S]\d\d?
}

=head2 Pragmas

=cut

token pragma {
    | <new_operators>   {*} #= new_operators
    | <loadlib>         {*} #= loadlib
    | <namespace>       {*} #= namespace
    | <hll_mapping>     {*} #= hll_mapping
    | <hll_specifier>   {*} #= hll_specifier
    | <source_info>     {*} #= source_info
}

rule include {
    '.include' <string_constant>
    {*}
}

rule new_operators {
    '.pragma' 'n_operators' <int_constant>
    {*}
}

rule loadlib {
    '.loadlib' <string_constant>
    {*}
}

rule namespace {
    '.namespace'
    [ '['
      [ <namespace_id> | <syntax_error: namespace identifier expected> ]
      <.right_bracket>
    ]?
    {*}
}

rule right_bracket {
    ']' | <syntax_error: ']' expected>
}

rule hll_specifier {
    '.HLL' <string_constant> <.comma> <string_constant>
    {*}
}

rule hll_mapping {
    '.HLL_map' <string_constant> <.comma> <string_constant>
    {*}
}

rule namespace_id {
    <STRING_CONST>
    [ ';' <string_constant> ]*
}

rule source_info {
    '.line' <int_constant> [ ',' <string_constant> ]?
    {*}
}

rule id_list {
    <IDENT> [ ',' <id> ]*
}



=head2 Tokens

=head3 normal_label

this is a token, because no spaces are allowed between the IDENT and the colon.

=cut

token normal_label {
    <IDENT> ':'
}

rule macro_label {
    <MACRO_LABEL> | <syntax_error: $LABEL: expected>
}

token MACRO_LABEL {
    '$' <IDENT> ':'
}

rule macro_label_decl {
    | '.label' <macro_label>
    | <normal_label>
}

rule int_constant {
    <INT_CONST> | <syntax_error: int constant expected>
}

token INT_CONST {
    | '0b' \d+
    | '0x' \d+
    | ['-']? \d+
    {*}
}

rule float_constant {
    <FLOAT_CONST> | <syntax_error: float constant expected>

}

token FLOAT_CONST {
    ['-']? \d+\.\d+
    {*}
}

rule string_constant {
    <STRING_CONST> | <syntax_error: string constant expected>
}

rule STRING_CONST {
    [ <encoding_specifier>? <charset_specifier> ]?
    [ <stringdouble> | <stringsingle> ]
}

token encoding_specifier {
    'utf8:'
}

token charset_specifier {
    | 'ascii:'
    | 'binary:'
    | 'unicode:'
    | 'iso-8859-1:'
}

token stringsingle {
    \' <string_literal: '> \'
}

token stringdouble {
    '"' <string_literal: "> '"'
}

token aType {
    | <pir_type>
    | <macro_id>
}

token pir_type {
    | 'int'
    | 'num'
    | 'pmc'
    | 'string'
}

token normal_target {
    | <IDENT>      {*} #= id
    | <REGISTER>   {*} #= register
}

=head2 Macro_target

In a macro, a target can also be a macro_id

=cut

token macro_target {
    | <IDENT>
    | <REGISTER>
    | <macro_id>
}

token id {
    <IDENT> | <syntax_error: identifier expected>
}

token IDENT {
    <!keyword> \w+
}

token macro_id {
    <!pir_directive> \.\w+
}


rule register {
    <REGISTER> | <syntax_error: register expected>
}

token REGISTER {
    | <INT_REG>
    | <NUM_REG>
    | <PMC_REG>
    | <STRING_REG>
}

token INT_REG {
    | I\d<[\d]>?  # match I0 to I99
    | \$I\d+      # match $I0 to infinity
}

token STRING_REG {
    | S\d<[\d]>?
    | \$S\d+
}

token PMC_REG {
    | P\d<[\d]>?
    | \$P\d+
}

token NUM_REG {
    | N\d<[\d]>?
    | \$N\d+
}

token ws {
    [ [ \s & \N ]+
    | \# \N*
    | ^^ <.pod_comment>
    ]*
}


=head2 Newlines

match the set of a newline and possible indention space 1 or more times
this is necessary to be able to skip fully white lines (with some spaces/tabs in it).
However, therefore it is also necessary to put the comments skipping here as well.

=cut



token NL {
    [ \n <.ws> ]+
}

token nl {
    <NL> | <syntax_error: new line expected>
}

regex pod_comment {
    ^^ '=' [ [ cut \h*: | end [\h\N*]? ]
         | for [ \h\N+: ] \n [ \N+\n ]*:
         | \w\N*: \n .*? \n '=' [ cut \h*: | end [\h\N*:]? ]
         ]
         [\n|$]
}

=head2 Keywords

PIR directives, PASM instructions and
the Parrot datatypes (int, string, num, pmc)
are keywords, and must not be used as
identifiers.

=cut

token keyword {
    [ <pir_type>
    | <pir_keyword>
    | <pir_directive>
    | <pasm_instruction> # pasm instructions may be identifiers in IMCC
    ]
}


# TODO: find out if we need to do this: I think so..
token pir_keyword {
    'goto'
}

=head2 PIR directives

TODO: put this in <%pir_directive> PIR directives

=cut

token pir_directive {
    [ '.arg'
    | '.const'
    | '.constant'
    | '.endm'
    | '.end'
    | '.get_results'
    | '.globalconst'
    | '.HLL_map'
    | '.HLL'
    | '.include'
    | '.invocant'
    | '.label'
    | '.lex'
    | '.line'
    | '.loadlib'
    | '.local'
    | '.meth_call'
    | '.namespace'
    | '.nci_call'
    | '.param'
    | '.begin_return'
    | '.begin_yield'
    | '.begin_call'
    | '.call'
    | '.end_return'
    | '.end_yield'
    | '.end_call'
    | '.pcc_sub'
    | '.pragma'
    | '.return'
    | '.sub'
    | '.result'
    | '.yield'
    ] >>
}