Error in arara: unresolvable property or identifier: file

Question

^{Disclaimer: Since arara 5.1 is now live on TeX Live and we have some significant changes in the rule format, I am antecipating the inevitable and asking the question myself. Hope it helps! :)}

So I recently updated my TeX distro and noticed arara has been updated from version 4 to 5. At the time of my writing, the aforementioned software is in version 5.1 in CTAN.

I have a custom rule named foo with the following content:

!config
identifier: foo
name: Foo
commands:
- name: The Foo program
  command: >
    @{
        return getCommand('foo', file);
    }
arguments: []

Pretty straightforward, it simply runs foo on my current file. This rule was working in arara 4.0, but now the new version raises the following error:

DETAILS ---------------------------------------------------------
[Error: unresolvable property or identifier: file]
[Near : {...
return getCommand('foo', file); ....}]

           ^
[Line: 2, Column: 30]

It was working before, I know it! What happened? Can you help me?

Answer 1

This behaviour is now expected, as described in the project CHANGELOG and the current user manual (try texdoc arara in your terminal to open the corresponding PDF file). According to the latter:

arara previously had the file name string as the file variable in the rule context. As of version 5.0, support for this variable has been dropped. Users should favour the reference variable instead, since it holds the absolute, canonical representation of the file name as a proper File object.

So, file is no more. Simply replace the file occurrences in your rule by reference and you should be good to go:

!config
identifier: foo
name: Foo
commands:
- name: The Foo program
  command: >
    @{
        return getCommand('foo', reference);
    }
arguments: []

A simple test:

Processing 'mydoc.tex' (size: 23 B, last modified: 04/11/2020
12:44:24), please wait.

[DR] (Foo) The Foo program
-----------------------------------------------------------------
Authors: No authors provided
About to run: [ foo, /home/paulo/mydoc.tex ] @ 

Total: 0.25 seconds

That's it! Hope it helps! :)