# Broken, do not try
my class Rx is Regex {
    my $rx-body = ' foo \s bar ';

    has     @!input-chars;
    has Int $!pos = 0;

    method CALL-ME(Rx:U: Str() $input  - > Match) {
       my $rx = self.bless: :input-chars($input.comb);
       $rx!match
    }

    method !match {
        while 0 ≤ $!pos ≤ @!input-chars.elem {
            my $c := @!input-chars[$pos];
            if MATCHER($c, $rx-body) === PartMatch { $pos++ }
            #  ^^^ somehow handles backtracking?
            if MATCHER($c, $rx-body) === FullMatch {
                return Match(FullMatch) }
            else { $pos -  }
        }
        $pos < 0 { return Match('#<failed match>') }
    }
}

# Hypothetical useage:
Rx('foo bar');

grammar InnerLang {
    rule TOP { \s+ | ['(' ~ ')' .* ] }
}
grammar MainLang  {
    rule TOP       { [<.text-like> <lisp-like>*]* }
    rule text-like { [ <.alpha>+ ]+}

    rule lisp-like {
        :my $inner;
        <?{ $inner
              = InnerLang.subparse: $/.orig, :pos($/.to) }>
        .**{$inner.to - $/.pos}
    #   ^^^^^^^^^^^^^^^^^^^^^^^ I really dislike this part
    }
}

method lisp-like {
    InnerLang.subparse: $.orig, :pos($.to)
}

my regex Rx { . }
say Rx('some text');
# OUTPUT: «No such method '!cursor_start' for invocant of type 'Str'»

my rule word { <alpha>+ }
say &word.WHAT;            # OUTPUT: «(Regex)»
#   ^ & sigil required because it does Callable
try word('a');
#        ^^^ Regexes don't take Str arguments
say $!.^name;              # OUTPUT: «(X::Method::NotFound)»

my $match = Match.new: :orig('Raku is -Ofun');
# call with ^^^^^^ a Match:D with the Str in :orig
say word($match);          # OUTPUT: «｢Raku｣»

# We can build a non-zero match using :to and :from
my $m2 = Match.new: :orig('Raku is -Ofun'), :from(0) :to(8);
say $m2;                   # OUTPUT: «｢Raku is ｣»
# And we can use that Match normally:
say $m2.&(/'-' \w**4/);    # OUTPUT: «｢-Ofun｣»
#         ^^^^^^^^^^^ regex-literal syntax also works

# A Regex is a Method and a Routine
say &word.^mro[1..4];      # OUTPUT: «((Method) (Routine) (Block) (Code))»
say $match.&word;          # OUTPUT: «｢Raku｣»
# so using ^^^^^^ method syntax might be more fitting

# A regex also returns a Match:
my $res = word $match;
say $res.WHAT;             # OUTPUT: «(Match)

# But *not* the same Match it got:
say $match.WHICH;          # OUTPUT: «Match|94080907590240»
say $res.WHICH;            # OUTPUT: «Match|94080907590384»
say $match, $res;          # OUTPUT: «(｢｣ ｢Raku｣)»
#   ^^^^^^ the Match we started with is unchanged

# The returned Match records where we are in the input string:
say $res.raku; #`[ OUTPUT: «Match.new( :orig("Raku is -Ofun"),
                                       :from(0), :pos(5) )» ]
# Which lets us use it as input for a new match:
say my $r2 = $res.&word; # OUTPUT: «｢is ｣»
say $r2.raku;  #`[ OUTPUT: «Match.new( :orig("Raku is -Ofun"),
                                       :from(5), :pos(8) )» ]

my $match = Match.new: :orig('The language Raku is -Ofun');
my $res = $match.&(/:s[\w+ ]**2<($<name>=[\w+] is (.*)/);
say $res;       # OUTPUT: «｢The language Raku is -Ofun｣»
# No capture groups, etc   ^^^^^^^^^^^^^^^^^^^^^^^^^^^

#    vvvvv the `MATCH` method `is implementation-detail`
$res.MATCH;
#    ^^^^^ $res is modified in place
say $res;       # OUTPUT: «｢Raku is -Ofun｣
                #           name => ｢Raku｣
                #           0 => ｢-Ofun｣»

grammar G {
    token TOP { <word>   }
    rule word { <alpha>+ }
}

grammar G {
    token TOP { <word>   }
    method word( --> Match:D) {
        my Match $new := regex {:r:s <alpha>+ }(self);
        $.actions.?word($new) if $new;
        $new
    #   ^^^^ NOTE: returns $new, **not** self. Here, $new is
    # a Grammar (which isa Match), but could be any Match:D
    }
}

method lisp-like {
    my Match $new := my regex {:r:s
        :my $inner;
        <?{ $inner
            = InnerLang.subparse: $/.orig, :pos($/.to) }>
        .**{$inner.to - $/.pos}
    }
    $.actions.?word($new) if $new;
    $new
}

method lisp-like {
    InnerLang.subparse: $.orig, :pos($.to)
}

grammar InnerLang {
    rule TOP { \s+ | ['(' ~ ')' .* ] }
}

grammar MainLang  {
    rule TOP { [<.text-like> <lisp-like>*]* }
    rule text-like { [<.alpha>+ ]+ }

    method lisp-like {
        InnerLang.subparse: $.orig, :pos($.to)
    }
}

say MainLang.parse($input);

grammar MainLang  {
    rule TOP(:$lisp-like-actions)  {
        [<.text-like> <lisp-like(:$lisp-like-actions)>*]* }

    rule text-like {  [<.alpha>+ ]+ }

    method lisp-like(:lisp-like-actions($actions)) {
        InnerLang.subparse: $.orig, :pos($.to), :$actions
    }
}

MainLang.parse: $input,
            :args(\(:lisp-like-actions(CheckLispSyntax)));

grammar MainLang  {
    method parse(:$lisp-like-actions, |) {
        my $*lisp-like-actions = $lisp-like-actions;
        nextsame
    }

    rule TOP       { [<.text-like> <lisp-like>*]* }
    rule text-like {  [<.alpha>+ ]+ }

    method lisp-like {
        InnerLang.subparse: $.orig, :pos($.to),
                    :actions($*lisp-like-actions)
    }
}

grammar MainLang  {
    method parse(:%nested-lang, |) {
        my %*nested-lang = (:grammar(InnerLang),
                            :actions(InnerLangActions),
                            |%nested-lang);
        nextsame
    }
    method subparse(:%nested-lang, |) {
        my %*nested-lang = (:grammar(InnerLang),
                            :actions(InnerLangActions),
                            |%nested-lang);
        nextsame
    }
    method parsefile(:%nested-lang, |) {
        my %*nested-lang = (:grammar(InnerLang),
                            :actions(InnerLangActions),
                            |%nested-lang);
        nextsame
    }

    rule TOP       { [<text-like> <nested-lang>*]* }
    rule text-like { [<.alpha>+ ]+ }

    method nested-lang {
        %*nested-lang<grammar>
            .subparse: $.orig, :pos($.to),
                       :actions(%*nested-lang<actions>)
    }
}

say MainLang.parse: $input,
                    :nested-lang{ :grammar(OtherLang),
                                  :actions(OtherLangActions)};

grammar MainLang handles(OtherLang) {...}

42 < 2 ?? (my $a = 2) !! 1; say $a # OUTPUT: «(Any)»`
#          ^^^^^^^^^  THUNK!

multi trait_mod:<handles>(Mu:U $grammar, &thunk) {
    import Grammar::Handles::Helpers;
    # Ensure we don't mess w/ non-grammar &handles candidates
    when $grammar.HOW
           .get_default_parent_type !=:= Grammar { nextsame }

                     # vvv The name for our new token
    my Grammar %tokens{Str} = build-token-hash &thunk;
    #  ^^^^^^^ the Grammar the token delegates to

    my %delegee-args;
    #  ^^^^^^^^^^^^^ where [sub]?parse[file]? methods save
    #  args for the delegee Grammar (keyed by token name)
    $grammar.&wrap-parse-methods: :%delegee-args,
                                  :token-names(%tokens.keys);
    $grammar.&install-tokens:     :%tokens, :%delegee-args;
}

#| Transforms the &thunk passed to `handles` into a hash
#| where the keys provide token names to install and the
#| values are the delegee Grammars
sub build-token-hash(&thunk  - > Map()) {
    proto thunk-mapper(|  - > Pair)   {*}
    multi thunk-mapper(Grammar $g)   {
        $g.^name => $g }
    multi thunk-mapper(Pair $renamed (Grammar :$value, |)) {
        $renamed }
    multi thunk-mapper(Str $name) {
        my Grammar $gram = try ::($name);
        $! ?? pick-err($!, :$name) !! $name => $gram }
    multi thunk-mapper(Mu $type) {
        pick-err (try my Grammar $ = $type) // $!}

    thunk().map: &thunk-mapper
}

#| Overrides the &parse, &subparse, and &parsefile methods with
#| a method that loads %delegee-args with named arguments whose
#| name matches a known $token-name
my method wrap-parse-methods(Mu: :@token-names,
                             :%delegee-args) is export {
    # despite the |, without vv, this sig rejects positionals
    my multi method wrapper ($?, *%args, |)
                             is hidden-from-backtrace {
        for @token-names -> $name {
            next unless %args{$name}:exists;
            if %args{$name}.first({$_ !~~ Map|Pair}, :p) {
                die X::TypeCheck::Binding::Parameter.new:
                        :symbol($name), :expected(Hash()),
                        got => %args{$name} }
            %delegee-args{$name}
              = %args{$name}.Hash;
        }
        nextsame }

    for |<parse subparse parsefile> -> $meth-name {
        self.^add_multi_method: $meth-name, &wrapper }
}

#| Install a method for each known token-name that delegates
#| to the correct Grammar delegee and passes the arguments
#| that the user supplied in their .parse call
my method install-tokens(Mu: :%tokens,
                   :%delegee-args) is export {
    for %tokens.kv -> $name, Grammar $delegee {
        my method TOKEN(:$actions, :$rule='TOP',
                        :$args) is hidden-from-backtrace {
            given %delegee-args{$name} {
                .<actions> = $actions unless .<actions>:exists;
                .<args>    = $args    unless .<args>:exists;
                .<rule>    = $rule    unless .<rule>:exists }
            $delegee.subparse: $.orig, :pos($.to),
                         :from($.from), |%delegee-args{$name}
        }
        self.^add_method: $name, &TOKEN }
}

grammar MainLang  {
    method parse(:%nested-lang, |) {
        my %*nested-lang = (:grammar(InnerLang),
                            :actions(InnerLangActions),
                            |%nested-lang);
        nextsame
    }
    method subparse(:%nested-lang, |) {
        my %*nested-lang = (:grammar(InnerLang),
                            :actions(InnerLangActions),
                            |%nested-lang);
        nextsame
    }
    method parsefile(:%nested-lang, |) {
        my %*nested-lang = (:grammar(InnerLang),
                            :actions(InnerLangActions),
                            |%nested-lang);
        nextsame
    }

    rule TOP       { [<text-like> <nested-lang>*]* }
    rule text-like { [<.alpha>+ ]+ }

    method nested-lang {
        %*nested-lang<grammar>
            .subparse: $.orig, :pos($.to),
                       :actions(%*nested-lang<actions>)
    }
}

say MainLang.parse: $input,
                    :nested-lang{ :grammar(OtherLang),
                                  :actions(OtherLangActions)};

grammar MainLang handles(:nested-lang(OtherLang))  {
    rule TOP       { [<text-like> <nested-lang>*]* }
    rule text-like { [<.alpha>+ ]+ }
}

say MainLang.parse: $input,
                    :nested-lang{:actions(OtherLangActions)};

# Grammar::Handles
my module Grammar::Handles::Helpers {

class X::Grammar::Can'tHandle is Exception {
    # extra ' to fix my blog’s syntax highlighter (aka hlfix)
    has $.type is required;
    multi method CALL-ME(|c) { die self.new(|c)}
    method message { q:to/§err/.trim.indent(2);
      The `handles` grammar trait expects a Grammar, the name
      of a Grammar, a Pair with a Grammar value, or a list of
      any of those types.  But `handles` was called with:
          \qq[{$!type.raku} of type ({$!type.WHAT.raku})]
      §err
}}

class X::Grammar::NotFound is Exception {
    has $.name;
    multi method CALL-ME(|c) { die self.new(|c)}
    method message { qq:to/§err/.trim.indent(2);
      The `handles` grammar trait tried to handle a grammar
      named '$!name' but couldn't find a grammar by that name
      §err
}}

#| A helper select the right error more concisely on the happy path
sub pick-err($_, :$name, |c) {
    when X::TypeCheck::Assignment { X::Grammar::Can'tHandle(:type(.got))  } # hlfix '
    when X::NoSuchSymbol          { X::Grammar::NotFound(:$name) }}

#| Install a method for each known token-name that delegates
#| to the correct Grammar delegee and passes the arguments
#| that the user supplied in their .parse call
my method install-tokens(Mu: :%tokens,
                   :%delegee-args) is export {
    for %tokens.kv -> $name, Grammar $delegee {
        my method TOKEN(:$actions, :$rule='TOP',
                        :$args) is hidden-from-backtrace {
            given %delegee-args{$name} {
                .<actions> = $actions unless .<actions>:exists;
                .<args>    = $args    unless .<args>:exists;
                .<rule>    = $rule    unless .<rule>:exists }
            $delegee.subparse: $.orig, :pos($.to),
                         :from($.from), |%delegee-args{$name}
        }
        self.^add_method: $name, &TOKEN }
}

#| Transforms the &thunk passed to `handles` into a hash
#| where the keys provide token names to install and the
#| values are the delegee Grammars
sub build-token-hash(&thunk  - > Map()) is export {
    proto thunk-mapper(|  - > Pair)   {*}
    multi thunk-mapper(Grammar $g)   { $g.^name => $g }
    multi thunk-mapper(Str $name) {
        my Grammar $gram = try ::($name);
        $! ?? pick-err($!, :$name)
           !! $name => $gram }
    multi thunk-mapper(Pair (:key($name), :value($_), |)) {
        when Grammar { $name => $_ }
        when Str     { $name => thunk-mapper($_).value }
        default      { #`[type err] thunk-mapper $_ }}
    multi thunk-mapper(Mu $invalid-type) {
        pick-err (try my Grammar $ = $invalid-type) // $! }

    thunk().map: &thunk-mapper
}

#| Overrides the &parse, &subparse, and &parsefile methods with
#| a method that loads %delegee-args with named arguments whose
#| name matches a known $token-name
my method wrap-parse-methods(Mu: :@token-names,
                             :%delegee-args) is export {
    # despite the |, without vv, this sig rejects positionals
    my multi method wrapper ($?, *%args, |)
                             is hidden-from-backtrace {
        for @token-names -> $name {
            next unless %args{$name}:exists;
            if %args{$name}.first({$_ !~~ Map|Pair}, :p) {
                die X::TypeCheck::Binding::Parameter.new:
                        :symbol($name), :expected(Hash()),
                        got => %args{$name} }
            %delegee-args{$name}
              = %args{$name}.Hash;
        }
        nextsame }

    for |<parse subparse parsefile> -> $meth-name {
        self.^add_multi_method: $meth-name, &wrapper 
    }
}

#`[end module Grammar::Handles::Helpers] }

multi trait_mod:<handles>(Mu:U $grammar, &thunk) {
    import Grammar::Handles::Helpers;
    # Ensure we don't mess w/ non-grammar &handles candidates
    when $grammar.HOW
           .get_default_parent_type !=:= Grammar { nextsame }

                     # vvv The name for our new token
    my Grammar %tokens{Str} = build-token-hash &thunk;
    #  ^^^^^^^ the Grammar the token delegates to

    my %delegee-args;
    #  ^^^^^^^^^^^^^ where [sub]?parse[file]? methods save
    #  args for the delegee Grammar (keyed by token name)
    $grammar.&wrap-parse-methods: :%delegee-args,
                                  :token-names(%tokens.keys);
    $grammar.&install-tokens:     :%tokens, :%delegee-args;
}