[Nmh-commits] [SCM] The nmh Mail Handling System branch, master, updated. 93cf33c07eed0e56b4f3a0d1c07ff183ac1510ef

[Ken Hornstein]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "The nmh Mail Handling System".

The branch, master has been updated
       via  93cf33c07eed0e56b4f3a0d1c07ff183ac1510ef (commit)
       via  c3ed95b3c5530b84a73dbdd531cb9aca9ba8dea0 (commit)
       via  5ee3667d7daf6e7090e3de104c3679259eb26da5 (commit)
      from  3a84d814004fd4557bf4f44952648e9e69bd22a8 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
http://git.savannah.gnu.org/cgit/nmh.git/commit/?id=93cf33c07eed0e56b4f3a0d1c07ff183ac1510ef


commit 93cf33c07eed0e56b4f3a0d1c07ff183ac1510ef
Merge: c3ed95b 3a84d81
Author: Ken Hornstein <address@hidden>
Date:   Fri Jan 13 12:05:13 2012 -0500

    Merge branch 'master' of git.sv.nongnu.org:/srv/git/nmh


http://git.savannah.gnu.org/cgit/nmh.git/commit/?id=c3ed95b3c5530b84a73dbdd531cb9aca9ba8dea0


commit c3ed95b3c5530b84a73dbdd531cb9aca9ba8dea0
Author: Ken Hornstein <address@hidden>
Date:   Fri Jan 13 12:04:13 2012 -0500

    Add some comments to the format compiler and engine.

diff --git a/docs/pending-release-notes b/docs/pending-release-notes
index c73464c..f7e0ac7 100644
--- a/docs/pending-release-notes
+++ b/docs/pending-release-notes
@@ -14,3 +14,4 @@ Things to add to the release notes for the next full release:
   message parts in MIME messages) has been removed.
 - fileproc and mhlproc mh-profile entries will now be obeyed by
   send, rcvdist, and whatnow.
+- New format instructions %(putlit) and %(concataddr) have been implemented.
diff --git a/sbr/fmt_compile.c b/sbr/fmt_compile.c
index 8368728..f643421 100644
--- a/sbr/fmt_compile.c
+++ b/sbr/fmt_compile.c
@@ -5,6 +5,38 @@
  * This code is Copyright (c) 2002, by the authors of nmh.  See the
  * COPYRIGHT file in the root directory of the nmh distribution for
  * complete copyright information.
+ *
+ * This code compiles the format strings (documented in mh-format(5)) into
+ * an internal form to be later processed by fmt_scan.c.
+ *
+ * What happens here is that the format strings are parsed and an array
+ * of struct format structures are returned.  Each format structure is
+ * a single operation interpreted by the the routines in fmt_scan.c.
+ *
+ * There is a NOT a one-to-one correspondence between format strings and
+ * format instructions; some functions have side effects that can result
+ * in multiple instructions being generated.  The exact list of instructions
+ * generated by a format string can be seem with the nmh fmtdump utility.
+ *
+ * A list of format instructions can be found in fmt_compile.h.
+ *
+ * If you wish to add a new function, you will need to do the following
+ * things:
+ *
+ * - Add a new instruction to the list of instructions in fmt_compile.h.
+ *   Note that test instructions (starting with FT_IF_S_NULL) have special
+ *   handling, so if you are NOT writing a test function then you need
+ *   to insert it into the list before that _and_ bump all of the
+ *   following instruction numbers.
+ *
+ * - Add the function name to the functable[] array below, and write any
+ *   special code that your function may require in terms of parsing
+ *   (it very well may not need anything).
+ *
+ * - Add the code in fmt_scan.c to handle your new function.
+ *
+ * - Document the new function in the mh-format(5) man page.
+ *
  */
 
 #include <h/mh.h>
@@ -51,6 +83,31 @@ extern struct mailname fmt_mnull;
 #define        TFL_PUTS   1        /* implicit putstr if top level */
 #define        TFL_PUTN   2        /* implicit putnum if top level */
 
+/*
+ * The functable array maps between the text names of format functions and
+ * the format instructions interpreted by the engine in fmt_scan.c.
+ *
+ * The elements of this structure are as follows:
+ *
+ * name -   The name of the function as seen in the format string.  This is
+ *         what maps a particular function name into a format instruction.
+ * type -   The type of argument this function expects.  Those types are
+ *         listed above (with the TF_ prefix).  This affects what gets
+ *         placed in the format instruction (the f_un union).
+ * f_type - The instruction corresponding to this function (from the list
+ *         in fmt_compile.h).
+ * extra  - Used by some functions to provide extra data to the compiler.
+ *         Uses include:
+ *             - Providing an alternate instruction to combine a load
+ *               and test operation (see do_if()).
+ *             - Passed in f_value in the format instruction to provide
+ *               extra information for the engine (see FT_LV_DAT handling
+ *               in fmt_scan.c).
+ *             - Provide a hint as to preprocessing that is required for
+ *               this instruction (see do_name()).
+ * flags  - See the definitions for TFL_PUTS & TFL_PUTN above.
+ */
+
 struct ftable {
     char *name;                /* function name                  */
     char type;         /* argument type                  */
@@ -206,6 +263,9 @@ static char *do_loop(char *);
 static char *do_if(char *);
 
 
+/*
+ * Lookup a function name in the functable
+ */
 static struct ftable *
 lookup(char *name)
 {
@@ -353,6 +413,9 @@ compile (char *sp)
 }
 
 
+/*
+ * Process functions & components (handle field width here as well
+ */
 static char *
 do_spec(char *sp)
 {
@@ -404,6 +467,11 @@ do_spec(char *sp)
     return (cp);
 }
 
+/*
+ * Process a component name.  Normally this involves generating an FT_COMP
+ * instruction for the specified component.  If preprocess is set, then we
+ * do some extra processing.
+ */
 static char *
 do_name(char *sp, int preprocess)
 {
@@ -458,6 +526,10 @@ do_name(char *sp, int preprocess)
     return (cp);
 }
 
+/*
+ * Generate one or more instructions corresponding to the named function.
+ * The different type of function arguments are handled here.
+ */
 static char *
 do_func(char *sp)
 {
@@ -550,6 +622,10 @@ do_func(char *sp)
     return (cp);
 }
 
+/*
+ * Handle an expression as an argument.  Basically we call one of do_name(),
+ * do_func(), or do_if()
+ */
 static char *
 do_expr (char *sp, int preprocess)
 {
@@ -571,6 +647,15 @@ do_expr (char *sp, int preprocess)
     return (cp);
 }
 
+/*
+ * I am guessing this was for some kind of loop statement, which would have
+ * looked like %[ .... %].  It looks like the way this would have worked
+ * is that the format engine would have seen that FT_DONE had a 1 in the
+ * f_un.f_un_value and then decided whether or not to continue the loop.
+ * There is no support for this in the format engine, so right now if
+ * you try using it you will reach the FT_DONE and simply stop.  I'm leaving
+ * this here in case someone wants to continue the work.
+ */
 static char *
 do_loop(char *sp)
 {
@@ -589,6 +674,12 @@ do_loop(char *sp)
     return cp;
 }
 
+/*
+ * Handle an if-elsif-endif statement.  Note here that the branching
+ * is handled by the f_skip member of the struct format (which is really
+ * just f_width overloaded).  This number controls how far to move forward
+ * (or back) in the format instruction array.
+ */
 static char *
 do_if(char *sp)
 {
diff --git a/sbr/fmt_scan.c b/sbr/fmt_scan.c
index 5240781..574eeb3 100644
--- a/sbr/fmt_scan.c
+++ b/sbr/fmt_scan.c
@@ -5,6 +5,9 @@
  * This code is Copyright (c) 2002, by the authors of nmh.  See the
  * COPYRIGHT file in the root directory of the nmh distribution for
  * complete copyright information.
+ *
+ * This is the engine that processes the format instructions created by
+ * fmt_compile (found in fmt_compile.c).
  */
 
 #include <h/mh.h>

http://git.savannah.gnu.org/cgit/nmh.git/commit/?id=5ee3667d7daf6e7090e3de104c3679259eb26da5


commit 5ee3667d7daf6e7090e3de104c3679259eb26da5
Author: Ken Hornstein <address@hidden>
Date:   Fri Jan 13 09:30:03 2012 -0500

    Update README.developers with the correct version of autoconf we need.

diff --git a/docs/README.developers b/docs/README.developers
index 4381a2a..af38412 100644
--- a/docs/README.developers
+++ b/docs/README.developers
@@ -16,7 +16,7 @@ autoconf files
 If you wish to change the `configure' script or its related files, you'll need
 to first install GNU m4, available from <ftp://ftp.gnu.org/pub/gnu/m4/> and 
then
 GNU autoconf (<ftp://ftp.gnu.org/pub/gnu/autoconf/>).  Nmh is currently using
-a minimum of autoconf 2.54.
+a minimum of autoconf 2.61.
 
 Most of the configure-related files are automatically generated.  The only 
files
 you should need to manually edit are acconfig.h and configure.in.  Don't, for

-----------------------------------------------------------------------

Summary of changes:
 docs/README.developers     |    2 +-
 docs/pending-release-notes |    1 +
 sbr/fmt_compile.c          |   91 ++++++++++++++++++++++++++++++++++++++++++++
 sbr/fmt_scan.c             |    3 +
 4 files changed, 96 insertions(+), 1 deletions(-)


hooks/post-receive
-- 
The nmh Mail Handling System