Comment Handling   (Free Comments)

 

   

(From Flags Pane)

 

 

 

 

(From Input Pane)

 

 

 

 

(See also Formatting)

 

Free Comments can lose their alignment and meaning when

the relative structure of the regular expression might  be

altered during a Formatting process.

 

Because of this, heuristic assumptions are used such that

Free Comments reasonably integrate into the Formatted

regular expression output in a meaningful way.

This option is selected by enabling Advanced Comment

handling option.

 

Below are descriptions of options that enable you to select

the handling type and control the shaping of the comments

output.

 

 

Turning On/Off Comment Printing

          Check or un-check the ‘Cmt Print’ box (above ‘Free Comments’ section).

          This does not alter comment handling, it just prints or doesn’t

          print the comment. Not printing comments does Not remove newlines.

 

 

Selecting Handling Type

          Three handling types are available, only one is selectable

          at a time via the radio buttons (see image above).

 

Select this to enable Advanced Comment handling

(see below for options that can be used with this type).

 

Selecting raw type injects comments in-line as encountered

to the formatted regular expression.

 

Same as raw except stand-alone comments are shifted to the

current formatting indent at that location.

 

 

Advanced Handling Options

 

By default, comments try to retain their original column position they

had before formatting. If the current position in the formatted line is

greater than that column position, the comment is moved out.

This could make some comments not line up as in the original.

Comment Shift adds Virtual padding to All comments by the amount

specified. As the shift is increased, comments tend to line up as was

found in the original input.

           

   Note - The shift amount can be entered manually in the

   Flags Pane by right clicking on the value past the ‘= 0’ <-here.

   For quick access, enabling/disabling and the shift amount can be

   set from the Input Pane using the check box and value-spinner

   labeled ‘Cmt Shift’ (see image above).

 

By default, comments that are on a line by themselves, are located

so they align with the formatting indent.

Set this option to allow lone comments to retain their original alignment.

There is a threshold override that can be set, below which the comment

Snaps back to the formatting indent. This allows farther out comments

to float and closer in comments (below this threshold) to snap to the indent.

If you wish to have All lone-comments free floating, turn floating On and

set the float threshold to 0.

 

   Note - The Float Snap threshold amount can be entered manually in the

   Flags Pane by right clicking on the value past the ‘=  10’ <-here.

   For quick access, enabling/disabling and the threshold amount can be

   set from the Input Pane using the check box and value-spinner

   labeled ‘Float Snap’ (see image above).

 

Comments try to retain their original column positions (as stated above).

Sometimes, formatting will move regex constructs to a new line.

In the case of a comment being at the end of a very long line, the end

result will be the comment way out to the right.

This option removes all the original column position information

for All comments and puts comments at the ends of formatted lines.

 

Auto-generated group comments can be stripped out if needed.

For example, when the input regex group number structure has changed,

or when just wanting to strip them out.

This is particularly usefull when dynamically formatting from the Output

window. (see also Dynamic Formatting)

 

Setting this, causes All comments to have a horizontal shape that exactly

matches the formatting indent of the line it is on. The original column positions

are not used. It will use the additive Virtual Comment Shift if it is set.

Increase the comment shift to get the indent shape farther out.

 

This is identical to Indent Shaping Comments except comments on lines

with just an Alternation will have their comments (if any) recessed to match

the alternation recess. This could help visualization of alternating subexpressions.

 

Setting this, causes All comments to line up vertically.

The original column positions are not used.

This uses Virtual Comment Shift value and shifting must be enabled.

Increase the comment shift to get the vertical shape farther out.

 

(see also Group Counting)

Capture Group numbers can be automatically generated in comments.

If no comment is on the line of the capture group, a comment is generated

for that line. If a comment exists on that line, the group number is incorporated

into it. This will use the additive Virtual Comment Shift if it is set.

 

Group Start

     Requires  ‘Enable group number comment’  to be set.

 

o        If the group starts and ends on the same line,

or the group ends on a different line and Group End option is not set,

just the group number will be printed.

 

o         If the group ends on a different line and Group End option Is set,

               Group number and “Start” are printed.

 

 Group End

     Requires  ‘Enable group number comment’  to be set.

     Requires  ‘Enable end group number comment’  to be set.

 

o         If the group ends on a different line and Group End option Is set,

                             Group number and “End” are printed.

 

 

Comments Presets

 

          For convience, usefull Comments flags presets can be selected from the

Flags Pane context menu.

Selecting an item here will turn on/off a group of flags that control how the

Comments are handled. Below are a sampling of possible (not all) configurations.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

RegexFormat Help - © 2014 RDNC Software