summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-01-14 23:33:25 +0000
committerKarl Berry <karl@freefriends.org>2013-01-14 23:33:25 +0000
commitbc35a860149a92327228f57c0234021fc32fad06 (patch)
treef4fae10971d5c963c4c6a16ff8f48b7643fd0f55
parent3e6b25207e86f8109b30b08f8b7498e932832ca7 (diff)
context-filter (14jan13)
git-svn-id: svn://tug.org/texlive/trunk@28835 c570f23f-e606-0410-a88d-b1316a301751
-rw-r--r--Master/texmf-dist/doc/context/third/filter/filter.txt68
-rw-r--r--Master/texmf-dist/tex/context/third/filter/t-filter.mkii35
-rw-r--r--Master/texmf-dist/tex/context/third/filter/t-filter.mkiv35
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=,