Trying to convert my old custom arara rule

I have a rule which worked with the old version of arara:

!config
# Open the every <filename>.<format> that can be opened
# The default for <filename> is the current file.
# The default for <format> is pdf.
# Sample usage:
# - if myfile.tex is the current file, all these open myfile.pdf
# % arara: showfile
# % arara: showfile {format: pdf}
# % arara: showfile {filename: myfile, format: pdf}
# and both these open myfile.log:
# % arara: showfile {format: log}
# % arara: showfile {filename: myfile, format: log}
#
identifier: showfile
name: showfile
commands:
- <arara> @{ isWindows( "cmd /c start", "xdg-open" ) } "@{ getBasename(file) }.@{format}"
arguments:
- identifier: format
flag: <arara> @{parameters.format}
default: pdf


According to New version of arara broke my custom rule I have changed it into:

!config
identifier: showfile
name: showfile
commands:
- command: <arara> @{ isWindows( "cmd /c start", "xdg-open" ) } "@{ getBasename(file) }.@{format}"
arguments:
- identifier: format
flag: <arara> @{parameters.format}
default: pdf


But if I run

arara main.tex


on a simple main.tex:

% arara: pdflatex
% arara: showfile
\documentclass{article}

\begin{document}
Test
\end{document}


I only get:

and the main.pdf is not shown.

The task remains appended, and if I close the command prompt windows, I get:

Processing 'main.tex' (size: 98 bytes, last modified: 12/15/2018

(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS

Total: 339.97 seconds
<<< Process finished (PID=9956). (Exit code 0)


Could you try this new rule?

!config
identifier: showfile
name: Display
commands:
- name: Show file
command: >
@{
prefix = isWindows( [ 'cmd', '/c', 'start' ], [ 'xdg-open' ] );
view = getBasename(file) + '.' + format;
return getCommand(prefix, view);
}
arguments:
- identifier: format
flag: >
@{
return parameters.format;
}
default: pdf


Let me break the elements into sections:

!config
identifier: showfile
name: Display


Nothing new here, it's just the header: showfile is the identifier to be used as directive in the source code, and Display is the name to be printed as the main task in the terminal. :)

Moving on.

commands:
- name: Show file


Now, we have a list of subtasks associated with this rule. In our case, we just have one element in the list. Each element consists of a name and a proper command. Show file is the name of this subtask and it will be displayed right after Display (the task name) in the terminal.

  command: >


The > symbol denotes the folded style for scalars. I highly suggest taking a look at the arara manual for a complete description of what it is. In short, it is a way of having multiple lines in a field (there's actually way more to that, but let's keep concepts easy to grasp for the uninitiated).

    @{


I simply opened the orb tag (please refer to the manual for more details on this concept). The rule logic will be described inside this tag.

      prefix = isWindows( [ 'cmd', '/c', 'start' ], [ 'xdg-open' ] );


prefix is a variable that holds the result of the following evaluation: if arara is being executed under Windows, return a list of strings containing cmd, /c and start. Otherwise, return a list containing only xdg-open.

      view = getBasename(file) + '.' + format;


In a similar fashion, view is a variable that holds the basename of the file reference plus a literal . and the format, obtained from the rule argument of the same name.

      return getCommand(prefix, view);


We now return a command composed of the prefix variable (properly flattened during command construction, please refer to the manual for more details) and the view variable. Introduced in version 4.0, the Command type is a robust way of making the underlying system know what to do. It's way more reliable than raw strings (deprecated in this version and to be removed in later versions).

    }


Now the orb tag is properly closed. Please mind the spaces that compose the folded representation of the current scalar. Otherwise, the YAML parsing will fail.

arguments:


Now we have the list of rule arguments, as usual. In our case, we only have one element, defined as follows.

- identifier: format


The argument name, to be used in the directive in the source code.

  flag: >
@{
return parameters.format;
}


Again, I decided to use the folded style for scalar representation. In this case, the original representation in the OP's question is fine, it's just my personal preference. :)

  default: pdf


Then we have here the default value if this particular argument is not explicitly specified in the directive.

That's it. :)

• @CarLaTeX: done. :) – Paulo Cereda Dec 15 '18 at 19:30
• Very detailed explanation, thanks! – CarLaTeX Dec 15 '18 at 19:33
• Beautiful work :) – cmhughes Dec 15 '18 at 21:35