From e21ef6928fa32f8c21414f00ec4a6cae741dec7a Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Thu, 26 Sep 2019 16:23:33 -0600 Subject: [PATCH] regen/regcomp.pl, regcomp.sym: Comments I spent some time in this code trying to understand some things, and as a result I'm commenting previously undocumented features. The comments about what an entry in regcomp.sym should look like are moved to that file, rather than the file that reads it. The former is most often touched, and they had gotten out-of-sync in the latter. Things now make more sense to me, and hopefully anyone using this in the future. --- pod/perldebguts.pod | 2 +- regcomp.sym | 23 +++++++++++++++++++---- regen/regcomp.pl | 35 +++++++++++++++-------------------- 3 files changed, 35 insertions(+), 25 deletions(-) diff --git a/pod/perldebguts.pod b/pod/perldebguts.pod index b439380..002c73f 100644 --- a/pod/perldebguts.pod +++ b/pod/perldebguts.pod @@ -562,7 +562,7 @@ will be lost. =for regcomp.pl begin - # TYPE arg-description [num-args] [longjump-len] DESCRIPTION + # TYPE arg-description [regnode-struct-suffix] [longjump-len] DESCRIPTION # Exit points diff --git a/regcomp.sym b/regcomp.sym index c69e4c9..31beb19 100644 --- a/regcomp.sym +++ b/regcomp.sym @@ -11,14 +11,29 @@ # Note that the order in this file is important. # # Format for first section: -# NAME \s+ TYPE, arg-description [num-args] [flags] [longjump] ; DESCRIPTION +# NAME \s+ TYPE, arg-description [struct regnode suffix] [flags] [longjump] ; DESCRIPTION +# arg-description is currently unused +# suffix is appended to 'struct_regnode_' giving which one to use. If empty, +# it means plain 'struct regnode'. If the regnode is a string one, this +# should instead refer to the base regnode, without the char[1] element +# of the structure # flag means is REGNODE_SIMPLE; flag means is REGNODE_VARIES; <.> is -# a placeholder -# longjump is 1 if the (first) argument holds the next offset. -# +# a placeholder +# longjump is 1 if the (first) argument holds the next offset (instead of the +# usual 'next_offset' field # # run perl regen.pl after editing this file +# +- suffix of which struct regnode to use e.g., +# | +- flags (S or V) struct regnode_1 +# un- | | +- longjmp (0, blank, or 1) blank means 0 +# Name Type used | | | ; comment +# -------------------------------------------------------------------------- +# IFMATCH BRANCHJ, off 1 . 1 ; Succeeds if the following matches. +# UNLESSM BRANCHJ, off 1 . 1 ; Fails if the following matches. +# SUSPEND BRANCHJ, off 1 V 1 ; "Independent" sub-RE. +# IFTHEN BRANCHJ, off 1 V 1 ; Switch, should be preceded by switcher. +# GROUPP GROUPP, num 1 ; Whether the group matched. #* Exit points diff --git a/regen/regcomp.pl b/regen/regcomp.pl index cb98613..5397dc0 100644 --- a/regen/regcomp.pl +++ b/regen/regcomp.pl @@ -49,14 +49,17 @@ use strict; # name Both Name of op/state # id Both integer value for this opcode/state # optype Both Either 'op' or 'state' -# line_num Both line_num number of the input file for this item. +# line_num Both line_num number of the input file for this item. # type Op Type of node (aka regkind) -# code Op what code is associated with this node (???) -# args Op what type of args the node has (which regnode struct) -# flags Op (???) +# code Op Apparently not used +# suffix Op which regnode struct this uses, so if this is '1', it +# uses 'struct regnode_1' +# flags Op S for simple; V for varies # longj Op Boolean as to if this node is a longjump -# comment Both Comment about node, if any +# comment Both Comment about node, if any. Placed in perlredebguts +# as its description # pod_comment Both Special comments for pod output (preceding lines in def) +# Such lines begin with '#*' # Global State my @all; # all opcodes/state @@ -97,23 +100,15 @@ sub register_node { } # Parse and add an opcode definition to the global state. -# An opcode definition looks like this: +# What an opcode definition looks like is given in regcomp.sym. # -# +- args -# | +- flags -# | | +- longjmp -# Name Type code | | | ; comment -# -------------------------------------------------------------------------- -# IFMATCH BRANCHJ, off 1 . 2 ; Succeeds if the following matches. -# UNLESSM BRANCHJ, off 1 . 2 ; Fails if the following matches. -# SUSPEND BRANCHJ, off 1 V 1 ; "Independent" sub-RE. -# IFTHEN BRANCHJ, off 1 V 1 ; Switch, should be preceded by switcher. -# GROUPP GROUPP, num 1 ; Whether the group matched. -# -# Not every opcode definition has all of these. We should maybe make this -# nicer/easier to read in the future. Also note that the above is tab +# Not every opcode definition has all of the components. We should maybe make +# this nicer/easier to read in the future. Also note that the above is tab # sensitive. +# Special comments for an entry precede it, and begin with '#*' and are placed +# in the generated pod file just before the entry. + sub parse_opcode_def { my ( $text, $line_num, $pod_comment )= @_; my $node= { @@ -635,7 +630,7 @@ EOD print <<'END_OF_DESCR'; - # TYPE arg-description [num-args] [longjump-len] DESCRIPTION + # TYPE arg-description [regnode-struct-suffix] [longjump-len] DESCRIPTION END_OF_DESCR for my $n (@ops) { $node= $n; -- 1.8.3.1