Skip to content

Commit

Permalink
Merge pull request #487 from katef/kate/man-flags
Browse files Browse the repository at this point in the history 
Document -F <flags> and -k <io>
  • Loading branch information
@katef
katef authored Aug 17, 2024
2 parents 0a36f1b + c26c5fd commit 64f26cc
Show file tree
Hide file tree
Showing 3 changed files with 106 additions and 29 deletions.
13 changes: 13 additions & 0 deletions man/lx.1/lx.1.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,14 @@

<!ENTITY api_tokbuf.arg "<replaceable>tokbuf</replaceable>">
<!ENTITY api_getc.arg "<replaceable>getc</replaceable>">
<!ENTITY api_io.arg "<replaceable>io</replaceable>">

<!ENTITY n.opt "<option>-n</option>">
<!ENTITY Q.opt "<option>-Q</option>">
<!ENTITY X.opt "<option>-X</option>">
<!ENTITY b.opt "<option>-b</option>&nbsp;&api_tokbuf.arg;">
<!ENTITY g.opt "<option>-g</option>&nbsp;&api_getc.arg;">
<!ENTITY k.opt "<option>-k</option>&nbsp;&api_io.arg;">
<!ENTITY l.opt "<option>-l</option>&nbsp;&lang.arg;">
<!ENTITY e.opt "<option>-e</option>&nbsp;&prefix.arg;">
<!ENTITY t.opt "<option>-t</option>&nbsp;&prefix.arg;">
Expand Down Expand Up @@ -62,6 +64,7 @@
<arg choice="opt">&X.opt;</arg>
<arg choice="opt">&b.opt;</arg>
<arg choice="opt">&g.opt;</arg>
<arg choice="opt">&k.opt;</arg>
<arg choice="opt">&l.opt;</arg>
<arg choice="opt">&e.opt;</arg>
<arg choice="opt">&t.opt;</arg>
Expand Down Expand Up @@ -223,6 +226,16 @@ Dot output is not subject to checks for semantic errors
</listitem>
</varlistentry>

<varlistentry>
<term>&k.opt;</term>

<listitem>
<para>Set the IO &api; for output,
per the <code>io</code> option for &fsm_print.3;.
The default is <literal>getc</literal>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>&e.opt;</term>

Expand Down
118 changes: 89 additions & 29 deletions man/re.1/re.1.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,10 @@
<!ENTITY stdout.lit "<literal>stdout</literal>">

<!-- TODO: centralise to mdb -->
<!ENTITY io.arg "<replaceable>io</replaceable>">
<!ENTITY re.arg "<replaceable>re</replaceable>">
<!ENTITY file.arg "<replaceable>file</replaceable>">
<!ENTITY flags.arg "<replaceable>flags</replaceable>">
<!ENTITY dialect.arg "<replaceable>dialect</replaceable>">
<!ENTITY prefix.arg "<replaceable>prefix</replaceable>">
<!ENTITY length.arg "<replaceable>length</replaceable>">
Expand All @@ -33,7 +35,9 @@
<!ENTITY X.opt "<option>-X</option>">
<!ENTITY e.opt "<option>-e</option>&nbsp;&prefix.arg;">
<!ENTITY E.opt "<option>-E</option>&nbsp;&prefix.arg;">
<!ENTITY F.opt "<option>-F</option>&nbsp;&flags.arg;">
<!ENTITY G.opt "<option>-G</option>&nbsp;&length.arg;">
<!ENTITY k.opt "<option>-k</option>&nbsp;&io.arg;">

<!ENTITY a.opt "<option>-a</option>">
<!ENTITY d.opt "<option>-d</option>">
Expand All @@ -49,7 +53,6 @@
<!ENTITY x.opt "<option>-x</option>">

<!ENTITY h.opt "<option>-h</option>">
<!ENTITY v.opt "<option>-v</option>">
]>

<refentry>
Expand Down Expand Up @@ -97,6 +100,7 @@ query

<arg choice="opt">&a.opt;</arg>
<arg choice="opt">&c.opt;</arg>
<arg choice="opt">&k.opt;</arg>
<arg choice="opt">&w.opt;</arg>
<arg choice="opt">&X.opt;</arg>
<arg choice="opt">&e.opt;</arg>
Expand Down Expand Up @@ -169,9 +173,6 @@ query

<group choice="req">
<arg choice="plain">&h.opt;</arg>
<!-- TODO: does re(1) have -v?
<arg choice="plain">&v.opt;</arg>
-->
</group>
</cmdsynopsis>
</refsynopsisdiv>
Expand All @@ -184,6 +185,8 @@ query
which are &ldquo;executed&rdquo; to match against input strings,
or used to provide example strings which would match when given as input.</para>

<para>This tool provides an interface to the &re.3; &api;.</para>

<para>The &re.1; tool constructs a Finite State Machine
from Regular Expression syntax.
<!--
Expand All @@ -194,34 +197,38 @@ query
and minimised to its canonical &dfa; by default.
The &nfa; may be preserved by the &n.opt; option.</para>

<para>multiple regexps may be given; these are unioned by default,
<para>Multiple regexps may be given; these are unioned by default,
or concatenated when the &s.opt; option is given.</para>

<para>&re.1; is invoked in one of four modes of operation:
<para>&re.1; is invoked in one of several distinct modes:
&p.opt; to print the constructed &fsm;,
&q.opt; to query each pattern's &fsm;,
&m.opt; to print example strings,
&G.opt; to print example matching inputs,
and the default is to execute regular expressions.
These modes are mutually exclusive.</para>
<!--
-i for files rather than patterns
regexp dialect specified by &r.opt;
-->

<para>
XXX: when executing,
strings are single or multiple with --.
can't we feed a string to stdin, too?
XXX: now with -x instead: Unlike &grep.1;, strings are matched from
command line arguments rather than &stdin.lit;.
TODO: with no strings to match, will just validate fsm instead.
validate is the wrong word
</para>

<para>When executing, text to match is given either as strings
from command line arguments, or is given as filenames with &x.opt;.
Multiple arguments may be given using <literal>--</literal>.
Unlike &grep.1;, &re.1; does not read text from &stdin.lit;.
<!-- TODO: why not?
can't we feed a string to stdin, too?
maybe better after moving execution to fsm(1) only -->
With no text to match, &re.1; will just validate
<!-- validate is the wrong word -->
the pattern syntax instead.</para>

<!-- TODO: groups don't exist as a UI feature yet,
not sure what to say here that doesn't belong to the libre api instead
<para>XXX: Groups
group (for dialects which have them) (rather than a "whole" regexp)
</para>

<para>This tool provides an interface to the &re.3; &api;.</para>
-->
</refsection>

<refsection>
Expand Down Expand Up @@ -299,6 +306,60 @@ group (for dialects which have them) (rather than a "whole" regexp)
</listitem>
</varlistentry>

<varlistentry>
<term>&F.opt;</term>

<listitem>
<para>Set <literal>RE_*</literal> flags per &re.3;.
Note not all <code>enum re_flags</code> constants are meaningful
to expose to the &cli;.
The default is no flags set.
The available flags are:</para>

<table>
<col align="left"/>
<col align="left"/>
<col align="left"/>

<thead>
<tr>
<th>Flag</th>
<th>Value</th>
<th>Meaning</th>
</tr>
</thead>

<tbody>
<tr>
<td><literal>b</literal> (&b.opt;)</td>
<td><code>RE_ANCHORED</code></td>
<td>Anchor patterns at both start and end,
as if by <code>^</code> and <code>$</code>
(<code>\Z</code> for PCRE).</td>
</tr>
<tr>
<td><literal>i</literal> (&i.opt;)</td>
<td><code>RE_ICASE</code></td>
<td>Patterns are case insensitive.</td>
</tr>
<tr>
<td><literal>s</literal></td>
<td><code>RE_SINGLE</code></td>
<td>Single-line mode.
Equivalent to <code>PCRE_DOTALL</code>.</td>
</tr>
<tr>
<td><literal>x</literal></td>
<td><code>RE_EXTENDED</code></td>
<td>
Eextended mode.
Equivalent to <code>PCRE_EXTENDED</code>.</td>
</tr>
</tbody>
</table>
</listitem>
</varlistentry>

<varlistentry>
<term>&G.opt;</term>

Expand All @@ -307,6 +368,16 @@ group (for dialects which have them) (rather than a "whole" regexp)
</listitem>
</varlistentry>

<varlistentry>
<term>&k.opt;</term>

<listitem>
<para>Set the IO &api; for output,
per the <code>io</code> option for &fsm_print.3;.
The default is <literal>getc</literal>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>&q.opt;</term>

Expand Down Expand Up @@ -467,17 +538,6 @@ group (for dialects which have them) (rather than a "whole" regexp)
</listitem>
</varlistentry>

<!-- TODO:
<varlistentry>
<term>&v.opt;</term>
<listitem>
<para>Causes &re.1; to print its version number.</para>
</listitem>
</varlistentry>
-->

<varlistentry>
<term>&h.opt;</term>

Expand Down
4 changes: 4 additions & 0 deletions src/re/main.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -465,6 +465,10 @@ parse_flags(const char *arg, enum re_flags *flags)
{
for (; *arg; arg++) {
switch (*arg) {
case 'b':
*flags = *flags | RE_ANCHORED;
break;

case 'i':
*flags = *flags | RE_ICASE;
break;
Expand Down

0 comments on commit 64f26cc

Please sign in to comment.