18

Disclaimer: Since arara 4.0 is now live on TeX Live, I am antecipating the inevitable and asking the question myself. Hope it helps! :)

I updated my TeX Live distro today and found that arara got updated to the very much awaited version 4.0:

[paulo@cambridge ~] $ /opt/texbin/tlmgr info arara
package:     arara
...
installed:   Yes
revision:    48183
sizes:       src: 625k, doc: 2793k, run: 5177k, bin: 5k
relocatable: No
cat-version: 4.0
cat-date:    2018-07-10 16:34:23 +0200

This means good news, right? However, when I tried to run it with my custom rule, I got the following error:

  __ _ _ __ __ _ _ __ __ _ 
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Processing 'doc4.tex' (size: 31 bytes, last modified: 05/27/2018
21:05:57), please wait.

I have spotted an error in rule 'ls' located at '/home/paulo'. I
could not parse the rule, something bad happened. Apparently, the
provided YAML file is invalid. I will do my best to help you in
any way I can. There are more details available on this
exception:

DETAILS ---------------------------------------------------------
Cannot create property=command for
JavaBean=com.github.cereda.arara.model.Rule@29774679
 in
'reader', line 1, column 1:
    !config
    ^
Unable to find
property 'command' on class: com.github.cereda.arara.model.Rule

in 'reader', line 4, column 10:
    command: ls @{details}

      ^


Total: 0.03 seconds

The custom rule was working before, I swear! What did I do wrong? Why has arara broken my custom rule? Can I have some cake in the meantime?

This is the offending ls rule, working before and now broken with version 4.0:

!config
identifier: ls
name: LS
command: ls @{details}
arguments:
- identifier: details
  flag: '@{ isTrue(parameters.details, "-l", "") }'

Any help is truly appreciated! :)

  • 2
    You naughty duck, how dare you broke my rules?! – Paulo Cereda Jul 11 '18 at 9:50
  • 1
    @PauloCereda: Oh no! – Paulo Cereda Jul 11 '18 at 9:50
  • Now we need to find somewhere to file this in Often referenced questions :-) – Nicola Talbot Jul 11 '18 at 10:43
  • 1
    Last time I used LaTeX was 20 years ago for my PhD and I just joined here to thank you for such a question and answer. It would make people life easier if this was the norm in other SE sites. An author anticipating issues and posting to the place where people will be looking for them - bravo. – WoJ Jul 11 '18 at 14:29
  • @WoJ: thanks for the kind words, my friend! I am very happy this approach had a very positive impact. It is a nice way to acknowledge a potential issue and provide an authoritative answer at the same time. All the best! :) – Paulo Cereda Jul 11 '18 at 15:54
19

Disclaimer: We have a migration guide in the new manual which describes how to update custom rules to the new 4.0 format. It is surely worth a look. Thanks! :)

Actually, most of this text is extracted from my own user manual! Oopsie. :)

Indeed, rules from version 4.0 are incompatible with older versions of arara. The reason for such drastic decision was to standardise and unify command entries. So we opted for the general, broader approach: we need to use commands instead of command and provide a contextual element, described as follows.

The ls rule does nothing too important, it simply runs the system command ls which lists the contents of the current directory. However, when we try to run arara on a file which contains a directive referencing this rule, we get an error, as seen in the question. In order to fix the rule, we need to move the command key inside a commands context as a list element, as seen as follows:

!config
identifier: ls
name: LS
commands:
- command: ls @{details}
arguments:
- identifier: details
  flag: '@{ isTrue(parameters.details, "-l", "") }'

This fix is sufficient to make the rule valid in the new format. :)

Now, let us consider an example containing a list of commands, also based on the old format. The ls rule was updated to include two runs of the system command of the same name in the current directory:

!config
identifier: ls
name: LS
commands:
- ls @{details}
- ls @{details}
arguments:
- identifier: details
  flag: '@{ isTrue(parameters.details, "-l", "") }'

In order to fix the rule, we need to precede every list element in the commands context with the command key, as seen as follows:

!config
identifier: ls
name: LS
commands:
- command: ls @{details}
- command: ls @{details}
arguments:
- identifier: details
  flag: '@{ isTrue(parameters.details, "-l", "") }'

And that is it. :)

There is a helper tool available in the release section of our project repository that attempts to automatically convert rules in the old format to the new one. If you want to try it, download the rc.jar file from the repository and put it in the same directory where the old rules are located. You can also provide a full path instead.

It is important to note that, although the tool might indicate a successful conversion, there are no guarantees that the resulting rule is fully compliant with the new format, due to potential changes in the internal workings of arara, so your mileage may vary. In general, it should work.

The rule converter is written in Java and requires a virtual machine to run. The tool has a straightforward workflow and takes just one parameter referring to the rule to be converted. The entire process should happen without intervention:

$ java -jar rc.jar ls.yaml
         _                                _
 ___ _ _| |___    ___ ___ ___ _ _ ___ ___| |_ ___ ___
|  _| | | | -_|  |  _| . |   | | | -_|  _|  _| -_|  _|
|_| |___|_|___|  |___|___|_|_|\_/|___|_| |_| |___|_|

version 1.0 (rules < 4.0)

The provided YAML rule looks OK. I will try my best to
convert it to the new version 4.0 format adopted by arara.
The new rule name will be written in the same directory of
the original one and will have a '_v4' suffix to it. Keep in
mind that the base name must match the identifier!

YAY! -------------------------------------------------------
Good news, everybody! The provided YAML rule was updated
successfully to the new version 4.0 format of arara! Of
course, there are no guarantees this new rule will work out
of the box, so fingers crossed! Take a closer look at the
manual and update your rule to use the new enhancements of
arara. Have a great time!

The resulting rule is identical to the one manually converted in this section. Note that, when creating the file, the resulting YAML file might write the keys in alphabetical order. That means that, although both files semantically represent the same rule, the positions of the keys differ. However, that poses no issue at all, as long as the keys are correctly defined.

And we are good to go. :) Enjoy arara 4.0!

Final note: Since you are migrating from an old format to a new one, please consider replacing plain strings in command by proper Command objects. Refer to the user manual for more details on this feature.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.