txt: ## grammar.md
  class Grammar
  
  Formal grammar made up of named regexes
  
  ```raku
  class Grammar is Match {}
  ```
  
  Every type declared with `grammar`, and not explicitly stating its superclass, becomes a subclass of `Grammar`.
  
  ```raku
  grammar Identifier {
      token TOP       { <initial> <rest>* }
      token initial   { <+myletter +[_]> }
      token rest      { <+myletter +mynumber +[_]> }
      token myletter  { <[A..Za..z]> }
      token mynumber  { <[0..9]> }
  }
  
  say Identifier.isa(Grammar);                # OUTPUT: «True␤»
  my $match = Identifier.parse('W4anD0eR96');
  say ~$match;                                # OUTPUT: «W4anD0eR96␤»
  ```
  
  More [documentation on grammars](/language/grammars) is available.
  
  # [Methods](#class_Grammar "go to top of document")[§](#Methods "direct link")
  
  ## [method parse](#class_Grammar "go to top of document")[§](#method_parse "direct link")
  
  ```raku
  method parse($target, :$rule = 'TOP',  Capture() :$args = \(), Mu :$actions = Mu, *%opt)
  ```
  
  Parses the `$target`, which will be coerced to [`Str`](/type/Str) if it isn't one, using `$rule` as the starting rule. Additional `$args` will be passed to the starting rule if provided.
  
  ```raku
  grammar RepeatChar {
      token start($character) { $character+ }
  }
  
  say RepeatChar.parse('aaaaaa', :rule('start'), :args(\('a')));
  say RepeatChar.parse('bbbbbb', :rule('start'), :args(\('b')));
  
  # OUTPUT:
  # ｢aaaaaa｣
  # ｢bbbbbb｣
  ```
  
  If the `actions` named argument is provided, it will be used as an actions object, that is, for each successful regex match, a method of the same name, if it exists, is called on the actions object, passing the match object as the sole positional argument.
  
  ```raku
  my $actions = class { method TOP($/) { say "7" } };
  grammar { token TOP { a { say "42" } b } }.parse('ab', :$actions);
  # OUTPUT: «42␤7␤»
  ```
  
  Additional named arguments are used as options for matching, so you can for example specify things like `:pos(4)` to start parsing from the fifth (:pos is zero-based) character. All [matching adverbs](/language/regexes#Adverbs) are allowed, but not all of them take effect. There are several types of adverbs that a regex can have, some of which apply at compile time, like `:s` and `:i`. You cannot pass those to `.parse`, because the regexes have already been compiled. But, you can pass those adverbs that affect the runtime behavior, such as `:pos` and `:continue`.
  
  ```raku
  say RepeatChar.parse('bbbbbb', :rule('start'), :args(\('b')), :pos(4)).Str;
  # OUTPUT: «bb␤»
  
  ```
  
  Method `parse` only succeeds if the cursor has arrived at the end of the target string when the match is over. Use [method subparse](/routine/subparse) if you want to be able to stop in the middle.
  
  The top regex in the grammar will be allowed to backtrack.
  
  Returns a [`Match`](/type/Match) on success, and [`Nil`](/type/Nil) on failure.
  
  ## [method subparse](#class_Grammar "go to top of document")[§](#method_subparse "direct link")
  
  ```raku
  method subparse($target, :$rule = 'TOP', Capture() :$args = \(),  Mu :$actions = Mu, *%opt)
  ```
  
  Does exactly the same as [method parse](/routine/parse), except that cursor doesn't have to reach the end of the string to succeed. That is, it doesn't have to match the whole string.
  
  Note that unlike [method parse](/routine/parse), `subparse` *always* returns a [`Match`](/type/Match), which will be a failed match (and thus falsy), if the grammar failed to match.
  
  ```raku
  grammar RepeatChar {
      token start($character) { $character+ }
  }
  
  say RepeatChar.subparse('bbbabb', :rule('start'), :args(\('b')));
  say RepeatChar.parse(   'bbbabb', :rule('start'), :args(\('b')));
  say RepeatChar.subparse('bbbabb', :rule('start'), :args(\('a')));
  say RepeatChar.subparse('bbbabb', :rule('start'), :args(\('a')), :pos(3));
  
  
  # OUTPUT:
  # ｢bbb｣
  # Nil
  # #<failed match>
  # ｢a｣
  ```
  
  ## [method parsefile](#class_Grammar "go to top of document")[§](#method_parsefile "direct link")
  
  ```raku
  method parsefile(Str(Cool) $filename, :$enc, *%opts)
  ```
  
  Reads file `$filename` encoding by `$enc`, and parses it. All named arguments are passed on to [method parse](/routine/parse).
  
  ```raku
  grammar Identifiers {
      token TOP        { [<identifier><.ws>]+ }
      token identifier { <initial> <rest>* }
      token initial    { <+myletter +[_]> }
      token rest       { <+myletter +mynumber +[_]> }
      token myletter   { <[A..Za..z]> }
      token mynumber   { <[0..9]> }
  }
  
  say Identifiers.parsefile('users.txt', :enc('UTF-8'))
      .Str.trim.subst(/\n/, ',', :g);
  
  # users.txt :
  # TimToady
  # lizmat
  # jnthn
  # moritz
  # zoffixznet
  # MasterDuke17
  
  # OUTPUT: «TimToady,lizmat,jnthn,moritz,zoffixznet,MasterDuke17␤»
  ```
  
  # [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")
  
  Type relations for `Grammar`
  
  
  
  raku-type-graph
  
  
  
  Grammar
  Grammar
  
  
  Match
  Match
  
  
  Grammar->Match
  
  
  
  Mu
  Mu
  
  
  Any
  Any
  
  
  Any->Mu
  
  
  
  Capture
  Capture
  
  
  Capture->Any
  
  
  
  Cool
  Cool
  
  
  Cool->Any
  
  
  
  Match->Capture
  
  
  
  Match->Cool
  
  [Expand chart above](/assets/typegraphs/Grammar.svg)
  