document and clean

README

@@ -20,6 +20,8 @@ It expands some macros,
   @SHORT:N              - removes N suffixes, so (a.b.c 2 -> a)
   @ARGS                 - other arguments to the program
   @ARGS:N               - Provides the Nth argument, starting from 0
+  @ARGS:N+              - All arguments at and after Nth
+  @RECURS               - the full path name to the executable
   @LINE                 - line number at the selected @BAKE
 
 All macros can be exempted by prefixing them with a backslash,

bake.1

@@ -11,25 +11,25 @@ bake is a simple tool meant to execute embedded shell commands within
 any file.  It executes with /bin/sh the command after a "\fB@BAKE\fP " to
 the end of the line (a UNIX newline: '\fB\\n\fP').
 
-This format may be embedded within \fBbinary files\fP, or any file where no unwanted preceding
+This format may be embedded within \fBany file\fP.
-instance of \fB@BAKE\fP appears.
 
 It roots the shell execution in the directory of the given file.
 
-Options must always be put first, and short options may be merged together, numerical options must be trailing.
+Options must always be put before the filename, and short options may be merged together, numerical options must be trailing.
 
 .HP
  \-h \-\-help, Help message
-\fB\-n \-\-dry\-run\fP, don't execute anything
+ \fB\-n \-\-dry\-run\fP, don't execute anything
-\fB\-l \-\-list\fP, lists available shell commands
+ \fB\-c \-\-color\fP, disables color
-\fB\-s \-\-select\fP <\FBn\fP>, selects Nth shell command
+ \fB\-l \-\-list\fP, lists available shell commands
-\fB\-x \-\-expunge\fP, Removes what's specified in the expunge block <disabled for this build>
+ \fB\-s \-\-select\fP \<n\>, selects Nth shell command
+ \fB\-x \-\-expunge\fP, Removes what's specified in the expunge block
 .PP
 Macros
 
 All macros can be exempted by prefixing them with a backslash,
-which'll be subtracted in the expansion. multi-line commands may be
+which'll be subtracted in the expansion. backslashes may be used to
-done by a leading backslash, which are NOT subtracted.
+extend a command over several lines.
 
 These macros will expand to their counterpart before execution.
 .TP
@@ -41,20 +41,24 @@ returns target\-file without suffix (abc.x.txt \-> abc.x)
 supports choice syntax, @SHORT:N removes N suffixes, so (a.b.c 2 -> a)
 .TP
 .B @ARGS, $+
-returns
+returns \fBarguments\fP, supports choice syntax: @ARGS:N prints the
-.B arguments
+Nth argument starting from 0, leading plus prints inclusive remaining
-, supports choice syntax, @ARGS:0 returns the first argument, @ARGS:N so on.
+arguments (@ARGS:N+)
 .TP
 .B @LINE
 returns the line number
+.TP
+.B @RECURS
+returns full executable name (e.g. /usr/local/bin/bake)
 
 .PP
 Additional Features And Notes
 
 Shell execution may be disabled with the \fB-n\fP or \fB--dry-run\fP option.
 
-Expunge removes exactly one file specified in the @{...} format. You may use
+Expunge removes exactly one file specified in the @{TEXT} format, and
-backslashes to remove
+is not recursive. Expunge simply outputs rm 'TEXT...', where text
+expands any instance of ' to \\'.
 
 .SH EXAMPLE
 .\" SRC BEGIN (example.c)

bake.l

@@ -27,16 +27,19 @@ extern void pipeopen(char * filename, char * mode);
 %}
 
 SPACE [ \t\r\v\f]
-MACROS (@BAKE|@FILENAME|@FILE|@NAME|@SHORT|@ARGS|@LINE|@STOP|$@|$*|$+)
+                        /* Everything that can be backslashed */
+FILENAME (@FILENAME|@FILE|@NAME)
+CMD       @BAKE[[:space:]]
+MACROS   ({CMD}|@STOP|{FILENAME}|@SHORT|@ARGS|@LINE|@RECURS|$@|$*|$+|@\{)
 
 %x FOUND PADDING STOP
 %option nodefault noinput nounput noyywrap
 %%
 
 \n                    { ++line; }
-.  { ; }
+.|\\@BAKE[[:space:]]  {       ; }
 
-@BAKE[[:space:]] { bake:
+{CMD} { bake:
   static int nth = 0;
   first_nl = 1;
   if (yytext[yyleng-1] == '\n') { ++line;                                                      }
@@ -62,9 +65,9 @@ MACROS (@BAKE|@FILENAME|@FILE|@NAME|@SHORT|@ARGS|@LINE|@STOP|$@|$*|$+)
  }
 
  '                    { if (g_rm) { STRING("\\'"); } else { ECHO; }                                          }
- @BAKE[[:space:]]|@STOP   { BEGIN INITIAL; yyless(0); if (first_nl) { CHAR('\n'); } if (!g_select) { return 0; } }
+ {CMD}|@STOP          { BEGIN INITIAL; yyless(0); if (first_nl) { CHAR('\n'); } if (!g_select) { return 0; } }
  \\\n                 { BEGIN PADDING; ++line; CHAR(' ');                                                    }
- @FILENAME|@FILE|@NAME|$@ { STRING(g_filename);                                                                  }
+ {FILENAME}|$@        { STRING(g_filename);                                                                  }
  @SHORT:[[:digit:]]+  { shorten(g_filename, atoi(strrchr(yytext, ':')+1));                                   }
  @SHORT|$\*           { shorten(g_filename, 1);                                                              }
  @ARGS:[[:digit:]]+   { args(atoi(strrchr(yytext, ':')+1), 0);                                               }
@@ -84,7 +87,7 @@ MACROS (@BAKE|@FILENAME|@FILE|@NAME|@SHORT|@ARGS|@LINE|@STOP|$@|$*|$+)
 }
 
 <STOP>{
- @BAKE[[:space:]] { line += tmpline; goto bake; }
+ {CMD} { line += tmpline; goto bake; }
  @STOP { BEGIN FOUND; yyless(0);     }
  \n    { ++tmpline;   yymore();      }
  .|\\@ {              yymore();      }