.Dd 0.1.0
.Dt commandlinetester 1
.Sh NAME
.Nm commandlinetester
.Nd md2h: Converts markdown to HTML
.Sh SYNOPSIS
.Nm commandlinetester
.Op Fl b Ar base
.Op Fl t Ar file
.Op Fl h
.Op Fl e Ar foo
.Ar subcommand
.Sh DESCRIPTION
Convert Bit Powder Markdown to HTML. Overview of Bit Powder Markdown:
.Bl -bullet
.It
supports attributes with `{attr}` syntax, multiple attributes delimited with `;`. These attributes can be:
.Bl -bullet -compact
.It
CSS classes with: `.class`
.It
CSS properties with: `key: value`
.It
HTML tag attributes with: `key=value`
.It
HTML ids with: `#id`
.El
.It
spans with `[content]`, divs with `[[content]]`;
.It
marks with `==content==`, and abbrs with `=content=`;
.It
superscript with `x^^[2]`, and subscript with `CO~~[2]`;
.It
icons with `:fas-hexagon:`;
.It
as-is copy to output with `[[[ as-is-content ]]]`;
.It
reports errors when encountering syntax errors (so does not continue like regular Markdown);
.It
no tables as of yet.
.El
This utility also supports Bit Powder Mustache templates. Variables can be declared at top of an input file with `key: json-value` pairs. The templates supports:
.Bl -bullet
.It
values with `{{value}}`;
.It
iterators and conditional with `{{#value}}contents{{/}}`.
Contents is displayed (if this default form is used) if value is an object, array of objects, or true.
An iteration variable can be specified with `{{#name -> variable}}content{{/}}`, which can be used to iterate over (arrays of) any type.
Iterators can have optional default values (in `object`) with `{{#name <- object}}content{{/}}` (these object defaults are evaluated once during parsing of the file and can reference global variables);
.It
template definition with `{{=name}}content{{/}}`.
Templates can have optional default values (in `object`) with `{{=name <- object}}content{{/}}`;
.It
template instantation with `{{>name}}` or `{{name <- value}}`;
.It
Error handling is different from normal Mustache: missing fields is always considered an error. Errors can be suppressed with the `expr ??? alternative` try syntax (on error in `expr`, `alternative` will be executed). Shorthand for `expr ??? null` is `expr ???` (which can be used in loops with `{{#someField???}}` (which ignores errors if the field is not found).
.El
Binary Object expressions can be used instead of values as above (think of expressions, functional calls, selectors, etc). This utility supports also Lua in the templates. Prefix anywhere a value is accepted with `lua:` to run Lua code (with current value in `this`).
There are a couple of special functions added to the Binary Object expressions:
.Bl -tag -width Ds
.It Ft string Fn compile "string template, [any context]"
Compiles a string to a dynamic Mustache template that can be evaluated, and evaluates the defaults using the optional context
.Ar context
(otherwise empty context is used).
.It Ft string Fn eval "string compiled_template, any context"
Evaluates a dynamic Mustache template using the context
.Ar context .
.It Ft void Fn set "string key, any value"
.It Ft any Fn get "string key"
Sets/retrieves a global value (useful for figure numbers etc).
.It Ft string Fn filehash "string path"
.It Ft string Fn filewithhash "string path"
Calculates the xxhash32 for the contents of the file specified by path (relative to the --base flag). Useful to support caching with a long TTL: setting the hash as query makes the URL unique for the content (if the content changes). The function call
.Fn filewithhash "path"
prints `path?hash`.
.El
.Sh EXAMPLE
.Bd -literal
{{=cardfeature <- {fillHeight: true, dark: false, photoHideBreakpoint: "md"}}}
[[{.card{{#!dark}}; .light{{/}}}
[[{.card-header}
:fas-{{icon}}:{.mr-2}
{{title}}
]]
...
{{eval(body, this)}}
...
]
]]
{{/cardfeature}}
{{cardfeature <- {
dark: true,
icon: "calendar-star",
title: "Upcoming",
body: compile(|
On **Tuesday 1 December** from **16:00 - 17:30**, *X* will present her recently published book 'XYZ'.
),
buttonLeft: {icon: "sign-in", name: "join", href: "http://"},
buttonRight: {icon: "calendar", name: "calendar feed", href: "http://"}
}}}
.Ed
.Sh FLAGS
.Bl -tag -width Ds
.It Fl b,--base Ar base
base dir relative to which `filehash()` and `filewithhash()` works
.It Fl t,--template Ar file
load templates from specified files
.It Fl h,--header
number of header sections to skip
.It Fl e Ar foo
.El
.Sh SUBCOMMAND commandlinetester get
.Nm commandlinetester get
.Op Fl b Ar base
.Op Fl z Ar foo
.Ar markdown-file
get a specific path
.Sh FLAGS
.Bl -tag -width Ds
.It Fl b,--base Ar base
base dir relative to which `filehash()` and `filewithhash()` works
.It Fl z Ar foo
some flag
.El
.Sh SUBCOMMAND commandlinetester set
.Nm commandlinetester set
set a specific path
.Sh SEE ALSO
.Xr foo 2
.Xr ls 1
.Sh AUTHORS
Bernard van Gastel <bvgastel@bitpowder.com>