1 :Info: contents:  2020-05-09  contents
  2 
  3 Syntax as a command: contents PATH {-control_args}
  4 
  5 
  6 Syntax as an active function:  [contents PATH {-control_args}]
  7 
  8 
  9 Function: prints or returns the selected contents of a segment or
 10 archive component as a character string.
 11 
 12 
 13 Arguments:
 14 PATH
 15    is an absolute or relative pathname to the segment or archive
 16    component to be processed.
 17 
 18 
 19 Control arguments (line range):
 20    The range of lines eligible for output is given by zero or one
 21    -from control arguments; and zero or one -to or -for control
 22    arguments.
 23 
 24 
 25 -from N, -fm N
 26    line range begins with the Nth line.  (default: line range begins
 27    with line 1 of segment/component)
 28 -from -N, -fm -N
 29    range begins with the Nth line before end of segment/component.
 30 -from STRING, -fm STRING
 31    range begins with first line containing a string matching STRING.
 32 -from /REGEXP/, -fm /REGEXP/
 33    range begins with first line containing a string matching the
 34    regular expression REGEXP.  (See "Notes on regular expressions".)
 35 
 36 
 37 -for N
 38    line range includes (at most) N lines including first line of the
 39    range.
 40 -to N
 41    line range stops after line number N.  (default: line range
 42    continues through the last line of segment/component)
 43 -to +N
 44    range stops with the Nth line after the -from line (includes at
 45    most N+1 consecutive lines).  This is equivalent to:
 46       -for [plus N 1]
 47 -to -N
 48    range stops after the Nth line before end of the segment/component.
 49 
 50 
 51 -to STRING
 52    range stops after first line containing a string matching STRING,
 53    or continues to end of segment/component if such line is not found.
 54    The search for STRING begins with the first line of the range.
 55 -to /REGEXP/
 56    range stops after the first line containing a string matching the
 57    regular expression REGEXP, or continues to end of segment/component
 58    if such line is not found.  The search for REGEXP begins with the
 59    first line of the range.  (See "Notes on regular expressions".)
 60 
 61 
 62 Control arguments (content filters):
 63    Up to 30 controls select which lines in the line range are output,
 64    in any combination of -match and -exclude.  If -match controls are
 65    given, a line is output if it matches any of the -match controls,
 66    and does not match any of the -exclude controls.  If -match
 67    controls are not given, a line is output if it does not match any
 68    -exclude controls.
 69 
 70 -match STRING
 71    matches lines containing the characters in STRING.
 72 -match /REGEXP/
 73    matches lines containing a string matching the regular
 74    expression REGEXP.  (See "Notes on regular expressions".)
 75 
 76 
 77 -exclude STRING, -ex STRING
 78    excludes lines containing the characters in STRING.  Exclusion test
 79    is done after matching.  Thus, -match A -exclude B outputs all
 80    lines with an A except those containing a B.
 81 -exclude /REGEXP/, -ex /REGEXP/
 82    excludes lines containing a string matching the regular
 83    expression REGEXP.  (See "Notes on regular expressions".)
 84 
 85 
 86 Control arguments (output format):
 87 -newline, -nl
 88    leaves unchanged the newline character ending each selected line.
 89    It is printed with each selected line from the line range.
 90 -no_newline, -nnl
 91    changes the newline character ending each selected line to a space
 92    character. (default)
 93 -requote_line, -rql
 94    requotes each selected line, returning it as a unit without its
 95    ending newline.  Quoted lines are separated by a space character.
 96 
 97 
 98 Control arguments (errors):
 99 -errors, -err
100    report an error if the -from line is not found; or if the active
101    function return string maxlength is exceeded.  (default)
102 -no_errors, -nerr
103    skip reporting of the above errors about the -from line or
104    maxlength of the active function return string.  No content is
105    examined if the -from line is not found.  Content that fits in the
106    active function string is returned without error.
107 
108 
109 Notes on regular expressions:
110 A regular expression /REGEXP/ is the character string between slash
111 delimiters in a line range or content selection search string.  It
112 follows the regular expression rules implemented by the qedx command.
113 
114 The regular expression characters are matched against characters
115 in each line of the segment/component.
116 
117 
118 List of specialized REGEXP characters:
119    The following characters have specialized meanings when used in a
120    regular expression.
121 
122 *
123    signifies any number (or none) of the preceding character.
124 ^
125    when used as the first character of a regular expression, signifies
126    the (imaginary) character preceding the first character on a line.
127 $
128    when used as the last character of a regular expression, signifies
129    the newline character at the end of each line.  If the segment ends
130    with a partial line (not ending in newline), that line does not
131    match an expression ending with a $ character.
132 
133 
134 .
135    matches any character on a line.
136 \c
137    suppresses the special meaning of the character following it.  For
138    example, /\c^switch/ matches the string "^switch" appearing
139    anywhere in the line.
140 
141 
142 :Info: contains:  2020-05-09  contains
143 
144 Syntax as a command: contains PATH -control_args
145 
146 
147 Syntax as an active function:  [contains PATH -control_args]
148 
149 
150 Function: returns "true" if any line of a segment/component
151 in a given a line range matches the requirements given in
152 -match and/or -exclude constraints; returns "false" if no lines
153 match those requirements.
154 
155 
156 Arguments:
157 PATH
158    is an absolute or relative pathname to the segment or archive
159    component whose contents is examined.
160 
161 
162 Control arguments (line range):
163    The range of lines to be examined may be limited by zero or one
164    -from control arguments; and zero or one -to or -for control
165    arguments.
166 
167 -from N, -fm N
168    line range begins with the Nth line.  (default: line range begins
169    with line 1 of segment/component)
170 -from -N, -fm -N
171    range begins with the Nth line before end of segment/component.
172 -from STRING, -fm STRING
173    range begins with first line containing a string matching STRING.
174 -from /REGEXP/, -fm /REGEXP/
175    range begins with first line containing a string matching the
176    regular expression REGEXP.  (See "Notes on regular expressions".)
177 
178 
179 -for N
180    line range includes (at most) N lines including first line of the
181    range.
182 -to N
183    line range stops after line number N.  (default: line range
184    continues through the last line of segment/component)
185 -to +N
186    range stops with the Nth line after the -from line (includes at
187    most N+1 consecutive lines).  This is equivalent to:
188       -for [plus N 1]
189 -to -N
190    range stops after the Nth line before end of the segment/component.
191 
192 
193 -to STRING
194    range stops after first line containing a string matching STRING,
195    or continues to end of segment/component if such line is not found.
196    The search for STRING begins with the first line of the range.
197 -to /REGEXP/
198    range stops after the first line containing a string matching the
199    regular expression REGEXP, or continues to end of segment/component
200    if such line is not found.  The search for REGEXP begins after the
201    first line of the range.  (See "Notes on regular expressions".)
202 
203 
204 Control arguments (content requirements):
205    Up to 30 controls define requirements for lines in the line range
206    in any combination of -match and -exclude.  One or more -match
207    and/or -exclude controls must be given.  If -match controls are
208    given, a line meets requirements if it matches any of the -match
209    controls, and does not match any of the -exclude controls.  If
210    -match controls are not given, a line meets requirements if it
211    does not match any -exclude controls.
212 
213 -match STRING
214    matches lines containing the character string STRING.
215 -match /REGEXP/
216    matches lines containing a string matching the regular
217    expression REGEXP.  (See "Notes on regular expressions".)
218 
219 
220 -exclude STRING, -ex STRING
221    excludes lines containing the characters in STRING.  Exclusion test
222    is done after matching.  Thus, -match A -exclude B selects all
223    lines with an A except those containing a B.
224 -exclude /REGEXP/, -ex /REGEXP/
225    excludes lines containing a string matching the regular
226    expression REGEXP.  (See "Notes on regular expressions".)
227 
228 
229 Control arguments (errors):
230 -errors, -err
231    report an error if the -from line is not found.  (default)
232 -no_errors, -nerr
233    skip reporting of the above error about the -from line.  No content
234    is examined if the -from line is not found.
235 
236 
237 Notes on regular expressions:
238 A regular expression /REGEXP/ is the character string between slash
239 delimiters in a line range or content selection search string.  It
240 follows the regular expression rules implemented by the qedx command.
241 
242 The regular expression characters are matched against characters
243 in each line of the segment/component.
244 
245 
246 List of specialized REGEXP characters:
247    The following characters have specialized meanings when used in a
248    regular expression.
249 
250 *
251    signifies any number (or none) of the preceding character.
252 ^
253    when used as the first character of a regular expression, signifies
254    the (imaginary) character preceding the first character on a line.
255 $
256    when used as the last character of a regular expression, signifies
257    the newline character at the end of each line.  If the segment ends
258    with a partial line (not ending in newline), that line does not
259    match an expression ending with a $ character.
260 
261 
262 .
263    matches any character on a line.
264 \c
265    suppresses the meaning of the special character following it.  For
266    example, /\c^switch/ matches the string "^switch" appearing
267    anywhere in the line.
268 
269 
270 :Internal: history_comment.gi:  2020-05-09  history_comment
271 
272 
273 /****^  HISTORY COMMENTS:
274   1) change(2020-05-09,GDixon), approve(2020-05-13,MCR10081),
275      audit(2020-06-08,Swenson):
276      Add modernized replacement for the contents command/AF which:
277       A) Uses ssu_ interface to permit easy integration with ssu_ subsystems,
278          and to simplify the code.
279       B) Adds support for signed numeric values in -from and -to bounds.
280       C) Adds -for and -no_error control arguments.
281       D) Adds a contains command/AF entrypoint which returns true if
282          contents would have printed any output; and false otherwise.
283       E) Adds ssu_contents_request and ssu_contains_request entrypoints
284          for possible use in future ssu_ subsystems.
285                                                    END HISTORY COMMENTS */
286