/ 
perl-5.45.2
⭐ Starred 2013 / regen/regcomp.pl

NAME

regen/regcomp.pl - generate regex node metadata from regcomp.sym

DESCRIPTION

This file is the canonical Perl-data source consumed by regen/regcomp.pl. It defines the regex opcodes and regmatch states used to generate regnodes.h and the regnode table in pod/perlreguts.pod.

Order is significant. Preserve the existing order of groups and the order of entries within each group unless you are intentionally changing regex opcode or state numbering semantics.

TOP-LEVEL STRUCTURE

The file returns a single hashref with these keys:

  • ops_groups

    An ordered arrayref of opcode groups.

  • state_groups

    An ordered arrayref of state groups.

OPCODE GROUPS

Each entry in ops_groups is a hashref with:

  • GROUP

    The logical group/block name. Groups are emitted as blocks, so relative ordering within a group is preserved.

  • TYPE

    The regnode type shared by the group. This may be a string type name, an arrayref of types, or a special value "__MIXED__", which allows the type to contain ops of any type without validation.

  • pod

    Optional text emitted into the generated regnode table in pod/perlreguts.pod. A scalar is one paragraph. An arrayref of strings is one paragraph which will be reflowed. A nested arrayref starts a new paragraph; only two levels are supported.

  • comment

    Optional maintainer-facing notes about ordering, invariants, or implementation constraints.

  • ops

    An ordered arrayref of opcode definitions.

Each regop definition may contain:

  • NAME

    The opcode name.

  • TYPE

    Optional unless the containing group's TYPE is __MIXED__. If the group is not mixed, the containing group's TYPE is the default and any provided opcode TYPE must match it. If the group is mixed, each opcode must provide its own TYPE.

  • desc

    Description of what the regop does. It follows the same scalar/arrayref paragraph rules as pod.

  • struct

    Optional regnode structure name such as regnode_1 or regnode_charclass. Omit it for plain regnode.

  • pod

    Optional per-op text which is intended to be emitted into the generated regnode table in perlreguts.pod. It follows the same scalar/arrayref paragraph rules as group-level pod.

  • comment

    Optional maintainer-facing notes for this op.

  • attr

    Optional hashref of non-default attributes. Recognized keys currently include arg_spec, simple, varies, off_by_arg, and str_arg.

STATE GROUPS

Each entry in state_groups is a hashref with:

  • TYPE

    The base opcode/state name used to form the generated state names.

  • transitions

    The compact transition specification used to expand regmatch states.

  • pod

    Optional text emitted into the generated regnode table. It follows the same scalar/arrayref paragraph rules as opcode-group pod.

  • comment

    Optional maintainer-facing notes.

NOTES

The pod and comment fields serve different purposes. pod is for generated documentation output; comment is for source-maintainer guidance, we put the latter in the data structure so it can be regenerated via code if necessary.