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.

diff --git a/pod/perldebguts.pod b/pod/perldebguts.pod
index b439380..002c73f 100644 (file)
--- 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 (file)
--- 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 <S> means is REGNODE_SIMPLE; flag <V> 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 (file)
--- 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;