Synchronize struct regexp information in perlreapi.pod and regexp.h #21241
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
demerphq
force-pushed
the
yves/fixup_perlreapi_pod
branch
from
de7c27d to
c129863
Compare
tonycoz
reviewed
Jul 16, 2023
tonycoz
reviewed
Jul 16, 2023
tonycoz
reviewed
Jul 17, 2023
So we should check if it is still in sync with the source, and ignore any line length issues as the source needs to be changed, not the copy. To enable this simply put "file source: FILENAME" or "copied from: FILENAME" in the first line of the verbatim text.
… source and update the individual struct members documentation accordingly, some time ago this structure was synchonize with the SV structure, so some members that used to be documented are now actually macros. This also includes a couple of field reordering to make the struct easier to understand and also to cluster the 32 bit fields together so that the structure is a minimal size. Thanks to Tony C for noticing this and calling it to my attention.
demerphq
force-pushed
the
yves/fixup_perlreapi_pod
branch
from
c129863 to
cf5c279
Compare
tonycoz
approved these changes
Jul 18, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
perlreapi.pod has a copy of the struct regexp from regexp.h, but over time the two copies have fallen out of sync with each other. When @nwc10 converted regexps to be first order SV types there were many changes that invalidated old structure members (typically replaced with RX_ macros), and there have been various other changes to the structure which were not captured in the docs.
This PR includes two commits. The first modifies t/porting/podcheck.t to support validating that a verbatim block can be found in the file it was copied from. This can be enabled by including the text "copied from: FILENAME" or "source file: FILENAME" on the first line of the verbatim text where the FILENAME actually exists on disk. This text can be commented however you like, or uncommented, whatever works for you, but must be on one line. If this special annotation is found then the podcheck logic will convert the verbatim block into a pattern (whitespace insensitve) and check to see if the named file contains the pattern. If it does not then it will throw an error. Thus we should notice if the docs and source get out of sync with each other. In this mode the normal verbatim text line length checks are disabled, as we want to be able to take the original source, copy it and then indent it into the pod file.
The second commit makes some minor changes to the structure in regexp.h, and copies the result into perlreapi.pod, following the convention established above. It also includes additional documentation on a few of the columns that were missing previously, and I also fixed some of the docs that were out of date, and added some that are new as of 5.38. For instance the old "precomp" value is now actually the pv value of the regexp, so the documentation for "precomp" is not documented as the macro RX_PRECOMP.
Thanks to @tonycoz for noticing this issue and calling my attention to it.