From 731d2e1f005464742c691c3f6b554214beb19e05 Mon Sep 17 00:00:00 2001 From: Joan Josep Ordinas Rosa Date: Tue, 16 Aug 2016 08:52:51 +0200 Subject: [PATCH] Modularized options --- bin/jqt | 57 ++++++++------ docs/Makefile | 22 +++++- docs/content/document.md | 8 ++ docs/content/engine.md | 163 +++++++++++++++------------------------ docs/content/help.txt | 41 ++++++++++ docs/content/metadata.md | 8 ++ docs/content/opt/4.md | 6 ++ docs/content/opt/C.md | 6 ++ docs/content/opt/D.md | 6 ++ docs/content/opt/E.md | 7 ++ docs/content/opt/H.md | 6 ++ docs/content/opt/I.md | 7 ++ docs/content/opt/L.md | 7 ++ docs/content/opt/M.md | 7 ++ docs/content/opt/P.md | 7 ++ docs/content/opt/S.md | 6 ++ docs/content/opt/V.md | 6 ++ docs/content/opt/d.md | 6 ++ docs/content/opt/e.md | 6 ++ docs/content/opt/f.md | 6 ++ docs/content/opt/h.md | 6 ++ docs/content/opt/i.md | 6 ++ docs/content/opt/j.md | 6 ++ docs/content/opt/m.md | 6 ++ docs/content/opt/n.md | 6 ++ docs/content/opt/p.md | 6 ++ docs/content/opt/r.md | 6 ++ docs/content/opt/t.md | 6 ++ docs/content/template.md | 25 ++---- 29 files changed, 320 insertions(+), 141 deletions(-) create mode 100644 docs/content/help.txt create mode 100644 docs/content/opt/4.md create mode 100644 docs/content/opt/C.md create mode 100644 docs/content/opt/D.md create mode 100644 docs/content/opt/E.md create mode 100644 docs/content/opt/H.md create mode 100644 docs/content/opt/I.md create mode 100644 docs/content/opt/L.md create mode 100644 docs/content/opt/M.md create mode 100644 docs/content/opt/P.md create mode 100644 docs/content/opt/S.md create mode 100644 docs/content/opt/V.md create mode 100644 docs/content/opt/d.md create mode 100644 docs/content/opt/e.md create mode 100644 docs/content/opt/f.md create mode 100644 docs/content/opt/h.md create mode 100644 docs/content/opt/i.md create mode 100644 docs/content/opt/j.md create mode 100644 docs/content/opt/m.md create mode 100644 docs/content/opt/n.md create mode 100644 docs/content/opt/p.md create mode 100644 docs/content/opt/r.md create mode 100644 docs/content/opt/t.md diff --git a/bin/jqt b/bin/jqt index 109c5ae..457c893 100755 --- a/bin/jqt +++ b/bin/jqt @@ -437,20 +437,23 @@ function die function help { - cat < result + jqt [options] infile > result + jqt [options] infile result Preprocessor options: -D NAME=VAL Define the user macro NAME as equal to VAL. -I DIRECTORY - Append DIRECTORY to the end of the preprocessor list of directories to be - searched for include files. + Append DIRECTORY to the end of the preprocessor list of + directories to be searched for include files. Template options: -L DIRECTORY - Append DIRECTORY to the end of the jq list of directories to be searched for - included and imported modules. + Append DIRECTORY to the end of the jq list of directories to be + searched for included and imported modules. -i MODULE Include the jq MODULE in the render stage. -j MODULE:NAME @@ -460,25 +463,36 @@ Document options: Set output HTML version (HTML4 / HTML5). -d FILE Read content document from FILE. - -p Print list of Pandoc accepted options. Metadata options: -M NAME:FILE - Add a FILE in JSON or YAML format to the input metadata at the top level (NAME is - ignored but must be present and unique). + Add a FILE in YAML or JSON format to the input metadata at the top + level (NAME is ignored but must be present and unique). -m NAME:FILE - Add a FILE in JSON or YAML format to the input metadata as a value of object NAME. + Add a FILE in YAML or JSON format to the input metadata as a value + of object NAME. Debugging options: - -C Stops processing before the render stage (outputs full JSON data model). - -E Stops template processing after the preprocessing stage (outputs the expanded - template). - -H Stops MarkDown processing after generating HTML (outputs several HTML fragments). - -P Stops MarkDown processing after preprocessing stage (outputs the expanded - MarkDown). - -S Stops template processing before the render stage (outputs the jq script). + -C + Stops processing before the render stage (outputs full JSON data + model). + -E + Stops template processing after the preprocessing stage (outputs the + expanded template). + -H + Stops MarkDown processing after generating HTML (outputs several + HTML fragments). + -P + Stops MarkDown processing after preprocessing stage (outputs the + expanded MarkDown). + -S + Stops template processing before the render stage (outputs the jq + script). Information options: -h, --help Display this message. - -V Display version information. + -p + Print list of Pandoc accepted options. + -V + Display version information. EOF exit 0 } @@ -487,16 +501,11 @@ EOF # #?Document options: #? -e -#? Extract YAML front matter to stdout. #? -r -#? Remove front matter from MarkDown. #? -t -#? Test presence of front matter in MarkDown. #?Metadata options: #? -f NAME -#? Set name for YAML document metadata (defaults to 'front'). #? -n NAME -#? Set name for converted document (defaults to 'body'). function pandoc_options { diff --git a/docs/Makefile b/docs/Makefile index a80978d..6caecf0 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -68,6 +68,19 @@ JQT := jqt \ -msnippets:$(CACHE)/snippets.json \ --toc-depth=3 \ +# Macro process MarkDown +MPMD := gpp --nostdinc \ + +sccc '&\n' '' '' \ + +sccc '<\#' '\#>\n' '' \ + +siqi "'" "'" '' \ + +siQi '"' '"' '' \ + +ssss '' '' \ + +ssss '`' '`' '' \ + +ssss '\n```' '\n```' '' \ + +ssss '\n~~~' '\n~~~' '' \ + -U '<%' '>' '\B' '\B' '\W>' '<' '>' '$$' '' \ + -M '<%' '>' '\B' '\B' '\W>' '<' '>' \ + # Macro process CSS MPCSS := gpp --nostdinc \ +c '/*' '*/' \ @@ -76,7 +89,7 @@ MPCSS := gpp --nostdinc \ -M '&' ';' '(' ',' ');' '(' ')' \ # Minify CSS -CSSMIN := sed 's/^[ \t]\+//;s/[ \t]\$$//;/^$$/d;s/[\t ]*\([{}:,;>+~]\)[\t ]*/\1/g' +CSSMIN := sed 's/^[ \t]\+//;s/[ \t]\$$//;/^$$/d;s/[\t ]*\([{}:,;>+~]\)[\t ]*/\1/g' # Common sources for all targets COMMON := \ @@ -152,6 +165,13 @@ $(DESTINATION)/jqt.css: $(PRESENTATION)/jqt.css $(PRESENTATION)/github.css $(info ==> $@) $(MPCSS) $< | $(CSSMIN) > $@ +# Help text +/tmp/help: $(CONTENT)/help.txt + $(MPMD) -I. -I$(CONTENT) $< \ + | pandoc --from markdown --to plain - \ + | sed '1,7b;/^$$/d;s/_\([A-Z]\+\)_/\1/g;/^[^A-Z]/s/^/ /' \ + > $@ + ######################################################################## # Utilities ######################################################################## diff --git a/docs/content/document.md b/docs/content/document.md index 7a2262c..4372742 100644 --- a/docs/content/document.md +++ b/docs/content/document.md @@ -16,6 +16,14 @@ This is described on the middle of this diagram: <%include "FLOW.md"> +You can pass the following options to `jqt` to modify document evaluation: + +<%include "opt/4.md"> +<%include "opt/D.md"> +<%include "opt/I.md"> +<%include "opt/d.md"> +<%include "opt/n.md"> + ## Document structure Documents contains MarkDown text with an optional YAML front matter. diff --git a/docs/content/engine.md b/docs/content/engine.md index 793695c..6c001b6 100644 --- a/docs/content/engine.md +++ b/docs/content/engine.md @@ -33,130 +33,95 @@ Usage: jqt [options] < infile > result #### Preprocessor options --D NAME=VAL - -: Define the user macro *NAME* as equal to *VAL*. - --I DIRECTORY - -: Append *DIRECTORY* to the end of the preprocessor list of directories to be -searched for include files. - +<%include "opt/D.md"> +<%include "opt/I.md"> #### Template options --L DIRECTORY - -: Append *DIRECTORY* to the end of the jq list of directories to be searched -for included and imported modules. - --i MODULE - -: Include the jq *MODULE* in the render stage. - --j MODULE:NAME - -: Import the jq *MODULE* in the render stage. +<%include "opt/L.md"> +<%include "opt/i.md"> +<%include "opt/j.md"> #### Document options --4, -5 - -: Set output HTML version (HTML4 / HTML5). - --d FILE - -: Read content document from *FILE*. - --p - -: Print list of Pandoc accepted options. +<%include "opt/4.md"> +<%include "opt/d.md"> +<%include "opt/n.md"> #### Metadata options --M NAME:FILE - -: Add a *FILE* in YAML or JSON format to the input metadata at the top level -(*NAME* is ignored but must be present and unique). - --m NAME:FILE - -: Add a *FILE* in YAML or JSON format to the input metadata as a value of object *NAME*. +<%include "opt/M.md"> +<%include "opt/f.md"> +<%include "opt/m.md"> #### Debugging options --E +<%include "opt/E.md"> -: Stops template processing after the preprocessing stage (outputs the -expanded template). - - ``` - $ jqt -E layouts/footer.html -
- {{.snippets.footer}} -
- ... - ``` - --S - -: Stops template processing before the render stage (outputs the jq script). +``` +$ jqt -E layouts/footer.html +
+{{.snippets.footer}} +
+... +``` - ``` - $ jqt -S docs/layouts/footer.html - import "libjqt" as jqt; - . as $M | - "
", - " \(.snippets.footer)", - "
", - ... - ``` +<%include "opt/S.md"> --P +``` +$ jqt -S docs/layouts/footer.html +import "libjqt" as jqt; +. as $M | +"
", +" \(.snippets.footer)", +"
", +... +``` -: Stops MarkDown processing after preprocessing stage (outputs the expanded -MarkDown). +<%include "opt/P.md"> - ``` - $ jqt -P content/engine.md - --- - title: jqt · the jq template engine - baseURL: https://fadado.github.com/jqt/ - lang: en - --- +``` +$ jqt -P content/engine.md +--- +title: jqt · the jq template engine +baseURL: https://fadado.github.com/jqt/ +lang: en +--- - ## jq templates +## jq templates - The jq template language will be called jqt. - The tools used in the implementation of jqt are: - ``` +The jq template language will be called jqt. +The tools used in the implementation of jqt are: +``` --H +<%include "opt/H.md"> -: Stops MarkDown processing after generating HTML (outputs several HTML fragments). +``` +$ jqt -Icontent -H content/engine.md +

Could be jq the +basis for a web template engine? Let's explore…

+

jq

+... +``` - ``` - $ jqt -Icontent -H content/engine.md -

Could be jq the - basis for a web template engine? Let's explore…

-

jq

- ... - ``` +<%include "opt/C.md"> --C +``` +$ jqt -I layouts -C -d content/home.md layouts/default.html +{ + "body": " +<%include "opt/p.md"> +<%include "opt/V.md"> ## Implementation diff --git a/docs/content/help.txt b/docs/content/help.txt new file mode 100644 index 0000000..3a88756 --- /dev/null +++ b/docs/content/help.txt @@ -0,0 +1,41 @@ +jqt - jq based web template engine [version <%include "../VERSION">] + +Usage: jqt [options] < infile > result\ + jqt [options] infile > result\ + jqt [options] infile result + +Preprocessor options: + +<%include "opt/D.md"> +<%include "opt/I.md"> + +Template options: + +<%include "opt/L.md"> +<%include "opt/i.md"> +<%include "opt/j.md"> + +Document options: + +<%include "opt/4.md"> +<%include "opt/d.md"> + +Metadata options: + +<%include "opt/M.md"> +<%include "opt/m.md"> + +Debugging options: + +<%include "opt/C.md"> +<%include "opt/E.md"> +<%include "opt/H.md"> +<%include "opt/P.md"> +<%include "opt/S.md"> + +Information options: + +<%include "opt/h.md"> +<%include "opt/p.md"> +<%include "opt/V.md"> + diff --git a/docs/content/metadata.md b/docs/content/metadata.md index e7c6328..ed44249 100644 --- a/docs/content/metadata.md +++ b/docs/content/metadata.md @@ -16,6 +16,14 @@ This is described on the bottom of this diagram: <%include "FLOW.md"> +You can pass the following options to `jqt` to modify metadata evaluation: + +<%include "opt/D.md"> +<%include "opt/I.md"> +<%include "opt/M.md"> +<%include "opt/f.md"> +<%include "opt/m.md"> + ## Data XXXXXX ### Preprocessing diff --git a/docs/content/opt/4.md b/docs/content/opt/4.md new file mode 100644 index 0000000..481f54e --- /dev/null +++ b/docs/content/opt/4.md @@ -0,0 +1,6 @@ +-4, -5 +: Set output HTML version (HTML4 / HTML5). + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/C.md b/docs/content/opt/C.md new file mode 100644 index 0000000..16830a2 --- /dev/null +++ b/docs/content/opt/C.md @@ -0,0 +1,6 @@ +-C +: Stops processing before the render stage (outputs full JSON data model). + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/D.md b/docs/content/opt/D.md new file mode 100644 index 0000000..7d01cd0 --- /dev/null +++ b/docs/content/opt/D.md @@ -0,0 +1,6 @@ +-D NAME=VAL +: Define the user macro *NAME* as equal to *VAL*. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/E.md b/docs/content/opt/E.md new file mode 100644 index 0000000..c230bfe --- /dev/null +++ b/docs/content/opt/E.md @@ -0,0 +1,7 @@ +-E +: Stops template processing after the preprocessing stage (outputs the +expanded template). + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/H.md b/docs/content/opt/H.md new file mode 100644 index 0000000..f5befad --- /dev/null +++ b/docs/content/opt/H.md @@ -0,0 +1,6 @@ +-H +: Stops MarkDown processing after generating HTML (outputs several HTML fragments). + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/I.md b/docs/content/opt/I.md new file mode 100644 index 0000000..a794825 --- /dev/null +++ b/docs/content/opt/I.md @@ -0,0 +1,7 @@ +-I DIRECTORY +: Append *DIRECTORY* to the end of the preprocessor list of directories to be +searched for include files. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/L.md b/docs/content/opt/L.md new file mode 100644 index 0000000..4d3bdac --- /dev/null +++ b/docs/content/opt/L.md @@ -0,0 +1,7 @@ +-L DIRECTORY +: Append *DIRECTORY* to the end of the jq list of directories to be searched +for included and imported modules. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/M.md b/docs/content/opt/M.md new file mode 100644 index 0000000..e560464 --- /dev/null +++ b/docs/content/opt/M.md @@ -0,0 +1,7 @@ +-M NAME:FILE +: Add a *FILE* in YAML or JSON format to the input metadata at the top level +(*NAME* is ignored but must be present and unique). + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/P.md b/docs/content/opt/P.md new file mode 100644 index 0000000..ff63f53 --- /dev/null +++ b/docs/content/opt/P.md @@ -0,0 +1,7 @@ +-P +: Stops MarkDown processing after preprocessing stage (outputs the expanded +MarkDown). + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/S.md b/docs/content/opt/S.md new file mode 100644 index 0000000..7fb5a24 --- /dev/null +++ b/docs/content/opt/S.md @@ -0,0 +1,6 @@ +-S +: Stops template processing before the render stage (outputs the jq script). + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/V.md b/docs/content/opt/V.md new file mode 100644 index 0000000..f062df0 --- /dev/null +++ b/docs/content/opt/V.md @@ -0,0 +1,6 @@ +-V +: Display version information. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/d.md b/docs/content/opt/d.md new file mode 100644 index 0000000..212203d --- /dev/null +++ b/docs/content/opt/d.md @@ -0,0 +1,6 @@ +-d FILE +: Read content document from *FILE*. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/e.md b/docs/content/opt/e.md new file mode 100644 index 0000000..c2aebb0 --- /dev/null +++ b/docs/content/opt/e.md @@ -0,0 +1,6 @@ +-e +: Extract YAML front matter to stdout. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/f.md b/docs/content/opt/f.md new file mode 100644 index 0000000..7145fa2 --- /dev/null +++ b/docs/content/opt/f.md @@ -0,0 +1,6 @@ +-f NAME +: Set name for YAML document metadata (defaults to 'front'). + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/h.md b/docs/content/opt/h.md new file mode 100644 index 0000000..32c071b --- /dev/null +++ b/docs/content/opt/h.md @@ -0,0 +1,6 @@ +-h, --help +: Display this message. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/i.md b/docs/content/opt/i.md new file mode 100644 index 0000000..ee4cc36 --- /dev/null +++ b/docs/content/opt/i.md @@ -0,0 +1,6 @@ +-i MODULE +: Include the jq *MODULE* in the render stage. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/j.md b/docs/content/opt/j.md new file mode 100644 index 0000000..721c98d --- /dev/null +++ b/docs/content/opt/j.md @@ -0,0 +1,6 @@ +-j MODULE:NAME +: Import the jq *MODULE* in the render stage. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/m.md b/docs/content/opt/m.md new file mode 100644 index 0000000..00eb379 --- /dev/null +++ b/docs/content/opt/m.md @@ -0,0 +1,6 @@ +-m NAME:FILE +: Add a *FILE* in YAML or JSON format to the input metadata as a value of object *NAME*. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/n.md b/docs/content/opt/n.md new file mode 100644 index 0000000..7c20245 --- /dev/null +++ b/docs/content/opt/n.md @@ -0,0 +1,6 @@ +-n NAME +: Set name for converted document (defaults to 'body'). + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/p.md b/docs/content/opt/p.md new file mode 100644 index 0000000..addcc1a --- /dev/null +++ b/docs/content/opt/p.md @@ -0,0 +1,6 @@ +-p +: Print list of Pandoc accepted options. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/r.md b/docs/content/opt/r.md new file mode 100644 index 0000000..26fdf85 --- /dev/null +++ b/docs/content/opt/r.md @@ -0,0 +1,6 @@ +-r +: Remove front matter from MarkDown. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/opt/t.md b/docs/content/opt/t.md new file mode 100644 index 0000000..4a34a98 --- /dev/null +++ b/docs/content/opt/t.md @@ -0,0 +1,6 @@ +-t +: Test presence of front matter in MarkDown. + +<# +vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown +#> diff --git a/docs/content/template.md b/docs/content/template.md index 88fd455..f00cdff 100644 --- a/docs/content/template.md +++ b/docs/content/template.md @@ -16,6 +16,14 @@ This is described on the top of this diagram: <%include "FLOW.md"> +You can pass the following options to `jqt` to modify template evaluation: + +<%include "opt/D.md"> +<%include "opt/I.md"> +<%include "opt/L.md"> +<%include "opt/i.md"> +<%include "opt/j.md"> + ## Syntax A template is a file with UTF-8-encoded text, with a few kinds of delimited @@ -118,23 +126,6 @@ The text inside the expressions and control delimiters is normal _jq_ code, when a bonus, the `M$` global variable point to `jq` JSON input (the initial `.` –dot–). -## Template evaluation - -You can pass to `jqt` the following template options to include or import external _jq_ modules: - --L DIRECTORY - -: Append *DIRECTORY* to the end of the jq list of directories to be searched -for included and imported modules. - --i MODULE - -: Include the jq *MODULE* in the render stage. - --j MODULE:NAME - -: Import the jq *MODULE* in the render stage. - <# vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown #>