Modularizing pdoc, pinclude and pproto

+ pgetopt documentation & example
+ regenerated docs

Version

@@ -1,4 +1,3 @@
 #!/bin/sh
-echo "0.24.0"
-
-# When changing version number, remove src/version.h to regenerate it!
+. ./run/.phorward
+echo $VERSION

configure.ac

@@ -1,5 +1,5 @@
 AC_PREREQ([2.68])
-AC_INIT([Phorward C/C++ Library], [0.24.0])
+AC_INIT([Phorward C/C++ Library], [0.25.0])
 AC_PREFIX_DEFAULT([/usr])
 
 AC_CONFIG_SRCDIR([src/phorward.tpl.h])

doc/phorward.html

@@ -14,7 +14,7 @@
 <div class="header" id="header">
 <h1>The Phorward C/C++ Library</h1>
 <h2>libphorward 0.24.0</h2>
-<h3>Dec 2018</h3>
+<h3>Jan 2019</h3>
 </div>
 
 <div class="body" id="body">
@@ -2120,6 +2120,8 @@ <h2 id="plex">Lexical analysis using regular expressions (plex)</h2>
 </li>
 <li><a href="#fn_plex_free">plex_free()</a> - destructs the <a href="#plex">plex</a>-object after its usage,
 </li>
+<li><a href="#fn_plex_dump_dot">plex_dump_dot()</a> - generates a dot-file Graphviz (<a href="http://www.graphviz.org/">http://www.graphviz.org/</a>) to visualize the constructed lexer.
+</li>
 </ul>
 
 <p>
@@ -5426,7 +5428,7 @@ <h3 id="fn_pgetline">pgetline</h3>
 <p>
 This function serves as a platform-independent implementation for POSIX <a href="#fn_getline">getline()</a>, which is wrapped in case of POSIX.
 </div>
-<!-- NEED 37 -->
+<!-- NEED 74 -->
 <div class='function'>
 </p>
 
@@ -5444,17 +5446,14 @@ <h3 id="fn_pgetopt">pgetopt</h3>
 <b>Usage:</b>
 </p>
 <p>
-Implementation of a command-line option interpreter.
+Command-line option interpreter.
 </p>
 <p>
 This function works similar to the <a href="#fn_getopt">getopt()</a> functions of the GNU Standard
 Library, but uses a different style of parameter submit.
 </p>
 <p>
 It supports both short- and long- option-style parameters.
-This function is currently under recent development relating to the issues it
-is used for. It can't be seen as compatible or feature-proven, and does not
-follow a clear concept right now.
 </p>
 
 <ul>
@@ -5477,17 +5476,61 @@ <h3 id="fn_pgetopt">pgetopt</h3>
 </li>
 </ul>
 
+<p>
+The function must be called multiple times to read all command-line parameters
+and to react on the parameters.
+</p>
 <p>
 The function returns 0, if the parameter with the given index was
 successfully evaluated. It returns 1, if there are still command-line
 parameters, but not as part of options. The parameter <i>param</i> will receive
 the given pointer. It returns -1 if no more options could be read, or if an
 option could not be evaluated (unknown option). In such case, <i>param</i> will
 hold a string to the option that is unknown to <a href="#fn_pgetopt">pgetopt()</a>.
+</p>
+<p>
+<b>Example:</b>
+</p>
+<p>
+This is a minimal example showing the usage of <a href="#fn_pgetopt">pgetopt()</a> in a real program:
+</p>
+
+<pre><code class="language-c">
+#include &lt;phorward.h&gt;
+
+int main( int argc, char** argv )
+{
+    int			i;
+    int			rc;
+    int			next;
+    char		opt			[ 10 + 1 ];
+    char*		param;
+
+    for( i = 0; ( rc = pgetopt( opt, &amp;param, &amp;next, argc, argv,
+                                "ho:", "help output:", i ) ) == 0; i++ )
+    {
+        if( !strcmp( opt, "help" ) || !strcmp( opt, "h" ) )
+            printf( "Help\n" );
+        else if( !strcmp( opt, "output" ) || !strcmp( opt, "o" ) )
+            printf( "Output = &gt;%s&lt;\n", param );
+    }
+
+    if( rc &lt; 0 &amp;&amp; param )
+    {
+        fprintf( stderr, "Unknown option '%s'\n", param );
+        return 1;
+    }
+
+    for( i = 0; next &lt; argc; next++, i++ )
+        printf( "Parameter %d = &gt;%s&lt;\n", i, argv[ next ] );
+
+    return 0;
+}
+</code></pre>
+
 </div>
 <!-- NEED 32 -->
 <div class='function'>
-</p>
 
 <h3 id="fn_plex_create">plex_create</h3>
 

doc/ref.t2t

@@ -2241,7 +2241,7 @@ includes the newline character, if one was found.
 
 This function serves as a platform-independent implementation for POSIX [getline() #fn_getline], which is wrapped in case of POSIX.
 %FUNCTION:END
-%NEED:37
+%NEED:74
 %FUNCTION:BEGIN
 === pgetopt ===[fn_pgetopt]
 
@@ -2253,15 +2253,12 @@ int pgetopt( char* opt, char** param, int* next, int argc, char** argv, char* op
 
 **Usage:**
 
-Implementation of a command-line option interpreter.
+Command-line option interpreter.
 
 This function works similar to the [getopt() #fn_getopt] functions of the GNU Standard
 Library, but uses a different style of parameter submit.
 
 It supports both short- and long- option-style parameters.
-This function is currently under recent development relating to the issues it
-is used for. It can't be seen as compatible or feature-proven, and does not
-follow a clear concept right now.
 
 - //opt// is a pointer to a buffer with enough space to store the requested parameter to. For short parameters, this is only one char, for long-parameters the full name. The string will be zero-terminated.
 - //param// is a pointer to store a possible parameter value to, if the detected option allows for parameters.
@@ -2274,12 +2271,52 @@ returned to param. This parameter can be (char*)NULL.
 - //idx// is the index of the requested option, 0 for the first option behind argv[0].
 -
 
+The function must be called multiple times to read all command-line parameters
+and to react on the parameters.
+
 The function returns 0, if the parameter with the given index was
 successfully evaluated. It returns 1, if there are still command-line
 parameters, but not as part of options. The parameter //param// will receive
 the given pointer. It returns -1 if no more options could be read, or if an
 option could not be evaluated (unknown option). In such case, //param// will
 hold a string to the option that is unknown to [pgetopt() #fn_pgetopt].
+
+**Example:**
+
+This is a minimal example showing the usage of [pgetopt() #fn_pgetopt] in a real program:
+
+```
+#include <phorward.h>
+
+int main( int argc, char** argv )
+{
+    int			i;
+    int			rc;
+    int			next;
+    char		opt			[ 10 + 1 ];
+    char*		param;
+
+    for( i = 0; ( rc = pgetopt( opt, &param, &next, argc, argv,
+                                "ho:", "help output:", i ) ) == 0; i++ )
+    {
+        if( !strcmp( opt, "help" ) || !strcmp( opt, "h" ) )
+            printf( "Help\n" );
+        else if( !strcmp( opt, "output" ) || !strcmp( opt, "o" ) )
+            printf( "Output = >%s<\n", param );
+    }
+
+    if( rc < 0 && param )
+    {
+        fprintf( stderr, "Unknown option '%s'\n", param );
+        return 1;
+    }
+
+    for( i = 0; next < argc; next++, i++ )
+        printf( "Parameter %d = >%s<\n", i, argv[ next ] );
+
+    return 0;
+}
+```
 %FUNCTION:END
 %NEED:32
 %FUNCTION:BEGIN

doc/regex.t2t

@@ -279,6 +279,7 @@ A plex-object can be seen as a container, which merges multiple regular expressi
 - @plex_next() - finds the next match within a string, where unrecognized characters are ignored,
 - @plex_tokenize() - generates an array of all tokens from a string,
 - @plex_free() - destructs the plex-object after its usage,
+- @plex_dump_dot() - generates a dot-file Graphviz (http://www.graphviz.org/) to visualize the constructed lexer.
 -
 
 To tokenize a C-styled variable assignment, one could write a simple lexical analyzer, like this:

run/.phorward

@@ -0,0 +1,58 @@
+#!/bin/sh
+#-------------------------------------------------------------------------------
+# Phorward C/C++ Library
+# Copyright (C) 2006-2019 by Phorward Software Technologies, Jan Max Meyer
+# https://phorward.info ++ contact<at>phorward<dash>software<dot>com
+# All rights reserved. See LICENSE for more information.
+#
+# Script:		.phorward
+# Author:		Jan Max Meyer
+# Usage:		Phorward Shell Script Tools
+#-------------------------------------------------------------------------------
+
+# This is the official place where the version number is provided:
+VERSION="0.25.0"
+
+# ------------------------------------------------------------------------------
+version()
+{
+    if [ -z "$1" ]
+    then
+        prog="Phorward C/C++ Library"
+    else
+        prog="$1"
+    fi
+
+    echo "$prog v$VERSION"
+
+    if [ -n "$2" ]
+    then
+        echo "$2. Part of the Phorward C/C++ Library."
+    fi
+
+    cat <<ENDL
+
+Copyright (C) 2006-2019 by Phorward Software Technologies, Jan Max Meyer
+All rights reserved. See LICENSE for more information.
+ENDL
+}
+
+# ------------------------------------------------------------------------------
+remove_c_comments()
+{
+    sed "/\/\*/!bc
+:a
+/\*\//!{
+N
+ba
+}
+:c
+s:/\*.*\*/::
+s://.*$::g" $1
+}
+
+# ------------------------------------------------------------------------------
+dos2unix()
+{
+    tr -d '\r' <$1
+}

run/Makefile.am

@@ -1,2 +1,2 @@
 
-bin_SCRIPTS = pdoc pinclude pproto
+bin_SCRIPTS = .phorward pdoc pinclude pproto