txt: ## parse.md
  parse
  
  Combined from primary sources listed below.
  
  # [In Grammar](#___top "go to top of document")[§](#(Grammar)_method_parse "direct link")
  
  See primary documentation
  [in context](/type/Grammar#method_parse)
  for **method parse**.
  
  ```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.
  