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.
:)