context-filter (14jan13)

git-svn-id: svn://tug.org/texlive/trunk@28835 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 129 insertions, 9 deletions

diff --git a/Master/texmf-dist/doc/context/third/filter/filter.txt b/Master/texmf-dist/doc/context/third/filter/filter.txt
index b98325b2fec..68deb3e2a34 100644
--- a/Master/texmf-dist/doc/context/third/filter/filter.txt
+++ b/Master/texmf-dist/doc/context/third/filter/filter.txt
@@ -683,6 +683,72 @@ Then you can use
 
 to get a chess board.
 
+Special use case:  `\write18` with caching
+------------------------------------------
+
+Although the raison d'être of the externalfilter module is to process the
+content of an evironment or a macro through an external program, it may also be
+used to simply exectute an external program without processing any content.
+
+For example, suppose we want to include an image with a swirl gradient in our
+document. ImageMagick can generate such an image using:
+
+     convert -size 100x100 gradient: -swirl 180 <output file>
+
+Notice that in this case, the external program does not need any input file. We
+just need to pass the size of the image to the external program. 
+
+In such cases, we still want to cache the result, i.e., rerun the external
+program only when the `size` of the image has changed. The `write=no` option
+covers this use case. The basic usage is:
+
+    \defineexternalfilter
+        [...]
+        [
+          ...
+          write=no,
+          cacheoption=....,
+          ...
+        ]
+
+Out of the four macros (see [Basic Usage]) created by `\defineexternalfilter`,
+only `\inline<externalfilter>` makes sense with `write=no`. The usage of this
+macro is
+
+    \inline<externalfilter>[....]
+
+Unlike the default case, this version does not take an argument! (That is
+because, it does not write anything to a file). 
+
+When `write=no` is set, `\externalfilterbasefile` is equal to
+`\jobname-temp-<filter>-<cacheoption>` where `<cacheoption>` is the value of the
+`cacheoption` key. 
+
+For example, to generate swirl backgrounds described above, define:
+
+    \defineexternalfilter
+        [swirl]
+        [
+          write=no,
+          cacheoptions={\externalfilterparameter{size}},
+          cache=yes,
+          size={1000x1000},
+          output=\externalfilterbasefile.png,
+          filtercommand={convert -size \externalfilterparameter{size} gradient: -swirl 180 \externalfilteroutputfile},
+          readcommand=\ReadFigure,
+        ]
+
+    \def\ReadFigure#1%
+        {\externalfigure[#1]}
+
+
+This creates a macro `\inlineswirl` that uses ImageMagick to generate a file
+`\jobname-temp-swirl-1000x1000.png`. 
+
+The result is cached and the external program is rerun only if the value of
+cacheoption changes, that is, only if the value of `size` key changes. 
+
+
 Dealing with expansion
 ----------------------
 
@@ -888,3 +954,5 @@ Version History
     - Added `align` key.
 - **2012.06.20**
     - Support for `\usepath`
+- **2012.01.13**
+    - Support for `write=no` and `cacheoption=...`.
diff --git a/Master/texmf-dist/tex/context/third/filter/t-filter.mkii b/Master/texmf-dist/tex/context/third/filter/t-filter.mkii
index 560f9003ffd..0f002b1e5ce 100644
--- a/Master/texmf-dist/tex/context/third/filter/t-filter.mkii
+++ b/Master/texmf-dist/tex/context/third/filter/t-filter.mkii
@@ -1,6 +1,6 @@
 %D \module
 %D   [     file=t-filter,
-%D      version=2012.06.20,
+%D      version=2013.01.13,
 %D        title=\CONTEXT\ User Module,
 %D     subtitle=Filter,
 %D       author=Aditya Mahajan,
@@ -9,7 +9,7 @@
 %D        email=adityam <at> ieee <dot> org,
 %D      license=Simplified BSD License]
 
-\writestatus{loading}{Filter (ver: 2012.06.20)}
+\writestatus{loading}{Filter (ver: 2013.01.13)}
 
 \ifx\undefined\normalexpanded \let\normalexpanded\expanded \fi
 
@@ -44,6 +44,7 @@
     \setinterfaceconstant {output}           {output}
     \setinterfaceconstant {purge}            {purge}
     \setinterfaceconstant {read}             {read}
+    \setinterfaceconstant {write}            {write}
     \setinterfaceconstant {readcommand}      {readcommand}
 \stopinterface
 
@@ -95,6 +96,7 @@
 \setinterfacemessage\m!externalfilter{forbidden}        {Fatal Error: Cannot use absolute path -- as directory}
 \setinterfacemessage\m!externalfilter{slash}            {Appending / to directory -- }
 \setinterfacemessage\m!externalfilter{reuse}            {\c!state=\v!stop : Not running filter on file --}
+\setinterfacemessage\m!externalfilter{writedisabled}    {\c!write=\v!no : Not writing output for filter --}
 
 
 %D \subject {Tracing Macros}
@@ -221,6 +223,25 @@
    \externalfilter@set_filenames
 
    \pushcatcodetable
+   \doifelse{\externalfilterparameter\c!write}\v!no
+       \externalfilter@inline_write_disabled
+       \externalfilter@inline_write_enabled
+\stoptexdefinition
+       
+\starttexdefinition externalfilter@inline_write_disabled
+   \iftraceexternalfilters \showmessage\m!externalfilter{writedisabled} \currentexternalfilter \fi 
+
+   \externalfilter@execute_filter
+   \endlinechar\minusone %to prevent line break after reading file
+   \externalfilter@read_processed_file
+
+   % Finalization
+   \doifinset{\externalfilterparameter\c!cache}{\v!yes,\v!force}
+        {\doglobal\incrementvalue\externalfilter@count}
+   \endgroup
+\stoptexdefinition
+
+\starttexdefinition externalfilter@inline_write_enabled
    \futurelet\next\externalfilter@inline_grabcontent
 \stoptexdefinition
 
@@ -335,6 +356,8 @@
         {\edef\externalfilter@buffer_name{\externalfilter@temp_prefix-\currentexternalfilter}}
    \doifsomething{\externalfilterparameter\c!name}
         {\edef\externalfilter@buffer_name{\externalfilter@temp_prefix-\currentexternalfilter-\externalfilterparameter\c!name}}
+   \doif{\externalfilterparameter\c!write}\v!no
+        {\edef\externalfilter@buffer_name{\externalfilter@temp_prefix-\currentexternalfilter-\externalfilterparameter{\c!cache\c!option}}}
 
    \externalfilter@set_filenames_extras
 
@@ -390,9 +413,10 @@
             {\showmessage\m!externalfilter{reuse}\externalfilter@input_file}
             {\doifmode{*first}
                  {\doiffileelse{\externalfilter@output_file}
-                     {\executesystemcommand
-                              {mtxrun --ifchanged=\externalfilter@input_file\space
-                                  --direct \externalfilterparameter\c!filtercommand}}}
+                     {\doifnot{\externalfilterparameter\c!write}\v!no
+                         {\executesystemcommand
+                                  {mtxrun --ifchanged=\externalfilter@input_file\space
+                                      --direct \externalfilterparameter\c!filtercommand}}}}
                      {\showmessage\m!externalfilter{missing_cache}\externalfilter@output_file
                          \executesystemcommand
                               {mtxrun --direct \externalfilterparameter\c!filtercommand}}}}
@@ -453,6 +477,7 @@
    \c!setups=,
    \c!continue=\v!no,
    \c!cache=\externalfilterparameter\c!continue, % for backward compatibility
+   \c!cache\c!option=,
    \c!read=\v!yes,
    \c!readcommand=\ReadFile,
    \c!directory=,
diff --git a/Master/texmf-dist/tex/context/third/filter/t-filter.mkiv b/Master/texmf-dist/tex/context/third/filter/t-filter.mkiv
index 87a5970a82a..50b7f1ecc0c 100644
--- a/Master/texmf-dist/tex/context/third/filter/t-filter.mkiv
+++ b/Master/texmf-dist/tex/context/third/filter/t-filter.mkiv
@@ -1,6 +1,6 @@
 %D \module
 %D   [     file=t-filter,
-%D      version=2012.07.24,
+%D      version=2013.01.13,
 %D        title=\CONTEXT\ User Module,
 %D     subtitle=Filter,
 %D       author=Aditya Mahajan,
@@ -9,7 +9,7 @@
 %D        email=adityam <at> ieee <dot> org,
 %D      license=Simplified BSD License]
 
-\writestatus{loading}{Filter (ver: 2012.07.24)}
+\writestatus{loading}{Filter (ver: 2013.01.13)}
 
 \startmodule [filter]
 \usemodule   [module-catcodes]
@@ -35,6 +35,7 @@
     \setinterfaceconstant {output}           {output}
     \setinterfaceconstant {purge}            {purge}
     \setinterfaceconstant {read}             {read}
+    \setinterfaceconstant {write}            {write}
     \setinterfaceconstant {readcommand}      {readcommand}
     \setinterfaceconstant {taglabel}         {taglabel}
 \stopinterface
@@ -85,6 +86,7 @@
 \setinterfacemessage\m!externalfilter{unwriteable}      {Fatal Error: Cannot write to file --}
 \setinterfacemessage\m!externalfilter{slash}            {Appending / to directory -- }
 \setinterfacemessage\m!externalfilter{reuse}            {\c!state=\v!stop : Not running filter on file --}
+\setinterfacemessage\m!externalfilter{writedisabled}    {\c!write=\v!no : Not writing output for filter --}
 
 
 %D \subject {Tracing Macros}
@@ -204,7 +206,25 @@
    \setupexternalfilter[#1][\c!numbering=,\c!name=,\c!location=\v!text,#2]
 
    \externalfilter@set_filenames
+   \doifelse{\externalfilterparameter\c!write}\v!no
+       \externalfilter@inline_write_disabled
+       \externalfilter@inline_write_enabled
+\stoptexdefinition
+       
+\starttexdefinition externalfilter@inline_write_disabled
+   \iftraceexternalfilters \showmessage\m!externalfilter{writedisabled} \currentexternalfilter \fi 
+
+   \externalfilter@execute_filter
+   \endlinechar\minusone %to prevent line break after reading file
+   \externalfilter@read_processed_file
+
+   % Finalization
+   \doifinset{\externalfilterparameter\c!cache}{\v!yes,\v!force}
+        {\doglobal\incrementvalue\externalfilter@count}
+   \endgroup
+\stoptexdefinition
 
+\starttexdefinition externalfilter@inline_write_enabled
    \pushcatcodetable
    \futurelet\next\externalfilter@inline_grabcontent
 \stoptexdefinition
@@ -337,6 +357,8 @@
         {\edef\externalfilter@buffer_name{\externalfilter@temp_prefix-\currentexternalfilter}}
    \doifsomething{\externalfilterparameter\c!name}
         {\edef\externalfilter@buffer_name{\externalfilter@temp_prefix-\currentexternalfilter-\externalfilterparameter\c!name}}
+   \doif{\externalfilterparameter\c!write}\v!no
+        {\edef\externalfilter@buffer_name{\externalfilter@temp_prefix-\currentexternalfilter-\externalfilterparameter{\c!cache\c!option}}}
 
    \externalfilter@set_filenames_extras
 
@@ -422,8 +444,12 @@
              {\doifelse{\externalfilterparameter\c!state}\v!stop
                   {\showmessage\m!externalfilter{reuse}\externalfilter@input_file}
                   {\doiffileelse{\externalfilter@output_file}
-                      {\ctxlua{job.files.run(\!!bs\externalfilter@input_file\!!es,
-                                    \!!bs\externalfilterparameter\c!filtercommand\!!es)}}
+                      {\doifnot{\externalfilterparameter\c!write}\v!no
+                       % When write=no is selected, % base_name=....-cacheoption...
+                       % Since there is no input, caching is simply achieved
+                       % using the filename.
+                           {\ctxlua{job.files.run(\!!bs\externalfilter@input_file\!!es,
+                                        \!!bs\externalfilterparameter\c!filtercommand\!!es)}}}
                       {\showmessage\m!externalfilter{missing_cache}\externalfilter@output_file
                        \executesystemcommand
                          {\externalfilterparameter\c!filtercommand}}}}
@@ -479,6 +505,7 @@
    \c!setups=,
    \c!continue=\v!no,
    \c!cache=\externalfilterparameter\c!continue, % for backward compatibility
+   \c!cache\c!option=,
    \c!read=\v!yes,
    \c!readcommand=\ReadFile,
    \c!directory=,