Skip to content

Latest commit

 

History

History
111 lines (72 loc) · 5.08 KB

README.adoc

File metadata and controls

111 lines (72 loc) · 5.08 KB
Raw

Jamal Command Line

With the command line version of Jamal you can convert files processing the Jamal meta-markup. You can process a single file or multiple files traversing in a directory structure.

To convert a single file, you simply have to specify the input and the output file:

Jamal source
jamal input output

This is the simplest use of Jamal. When you want to convert multiple files from a single command need to specify options controlling the directory traversal.

The options can be given in upper or lower case letters and have a - or -- prefix. Options can be abbreviated to their shortest form, which is still unambiguous.

When an option has a value, it has to follow the option name with =. For example

jamal -jamalize version=2.8.2
jamal -jamalize -version=2.8.2
jamal -jamalize --version=2.8.2

These command lines do the same: install Jamal version 2.8.2 into the .asciidoctor/lib directory. When the option has a value the prefix - or -- is optional.

The options are the followings:

  • -help displays a help text and then the application quits.

  • -shcnf prints out the configuration values, which are in the file ~/.jamal/settings.(properties|xml) file.

  • -version displays the version of Jamal currently running and then the application quits. If this option is used together with the option -jamalize` it must have a value, which is the version of Jamal to be installed.

  • -verbose instructs the application to print out the individual file conversions. This is useful when the application is started to convert multiple files in a directory structure.

  • -open=<macroOpen> can specify the macro opening string. The default string is {.

  • -close=<macroClose> can specify the macro closing string. The default string is }.

    Note that the different operating systems may interpret the characters you specify as a value. You should use the operating system specific escape sequences when needed.

  • -T7 sets the open and close strings to {% and %}. This is the usual setting when you want to use Jamal in a Markdown or AsciiDoc files.

  • -depth=<depth> can specify the maximum traversal depth while scanning the directories for files to convert. The default value is Integer.MAX_VALUE, which is practically infinite.

  • -debug=<debug> using this option you can specify the debugger connection string. It usually should be http:8080. Specifying the debugger connection string to start Jamal in debug mode may not be enough. A debugger implementation capable interpreting the connection string has to be on the classpath. The command line version does not do that by default. The recommended mode is to use jbang to start the application, which puts the debugger on the classpath.

  • -dry-run run dry, do not write the result to output file. Using this option you will see all the error messages that may be printed, but the output files will not be created or overwritten.

  • -dry-dry-run run dry, do not execute Jamal. Using this option you may see what commands would be executed, but the commands will not be executed. Use this option together with the option -verbose.

The following options control the directory parsing. If any of the following options are used, Jamal will collect the files from the source directory and process them. In this case any command line parameter, like input and output file names are ignored.

  • -include=<include> this option can define a regular expression for the file name to include into the processing. The default value is \\.jam$, wich means every file that has a .jam extension. A file is processed if the name of the file matches the 'include' regular expression and does not match the 'exclude' regular expression.

  • -exclude=<exclude> file name regex pattern to exclude from the processing. A file will not be processed if the name of the file matches the 'exclude' regular expression, even if the 'include' regular expression matches. If the option is not used, no files will be explicitly excluded.

  • -source=<sourceDirectory> source directory to start the processing. The default value is the current working directory.

  • -target=<targetDirectory> target directory to create the output. The default value is the current working directory.

  • -from=<regex> pattern for the file name transformation. When a file is processed, the output file name is calculated using a replaceAll operation. The regex is used as the pattern and the replacement is the value of the option to.

  • -to=<replacement> replacement for the file name transformation. See also the option -from.

  • -docx process the input as a DOCX, Microsoft Word file and also generate a Microsoft Word document on the output.

  • -shcnf show the configuration values from the ~/.jamal/settings.properties, or from the ~/.jamal/settings.xml file, whichever exists.

  • -jamalize will install Jamal in the .asciidoctor/lib directory. It version of the installed Jamal is the same as the one installing it. It can also install a different version if the option -version=xxx is specifying a specific versions.