2

Implementing arara Dialog boxes

I've taken a number of steps to implement LaTeX arara Dialog boxes on a M2 Mac, as described on pages 80-85 in the arara-manual.pdf et al., but something is still missing.

The steps taken so far include:

  1. To make the Java Swing toolkit available, I installed (and confirmed via the Terminal command java version) that java version 1.8.0_371 is, in fact, installed.

  2. In Terminal, I set the appropriate environment variables to ensure Java runtime is accessible:

export JAVA_HOME =$(/usr/libexec/java_home)
export PATH=$JAVA_HOME/bin:$PATH
  1. I confirmed that the Swing toolkit is available and functioning properly via a simple Java Swing program SwingTest.java:
import javax.swing.*;

public class SwingTest {
    public static void main(String[] args) {
        SwingUtilities.invokeLater(() -> {
            JFrame frame = new JFrame("Swing Test");
            frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
            frame.setSize(300, 200);
            frame.setVisible(true);
        });
    }
}

that I ran in Terminal as:

javac SwingTest.java then java SwingTest

The test resulted in a small window titled "Swing Test" to appear on the screen, confirming that everything was setup correctly.

  1. In my HOME directory (cd ~), I created the hidden folder .arara (mkdir .arara) in which I created what would serve as the template, arara YAML configuration file araraconfig.yaml.

The YAML configuration file contains a custom arara rule called mydialog with the necessary logic to display the sought-after arara Dialog box, e.g:

!config
# Arara rule: mydialog
# Description: Example rule with a Dialog box
# Author: Your Name

# Declare the rule
identifier: mydialog
name: My Dialog Rule
command: >
  @{
    // Import the necessary Java classes
    import javax.swing.JOptionPane;

    // Display the Dialog box and capture the user's response
    int option = JOptionPane.showConfirmDialog(null, "Are you sure you want to proceed?", "Confirmation", JOptionPane.YES_NO_OPTION);

    // Process the user's response
    if (option == JOptionPane.YES_OPTION) {
      // Execute the necessary commands or actions here
      // For example, you can run a specific command using `runCommand`:
      // runCommand("pdflatex", "-interaction=nonstopmode", "%O", "--shell-escape", "%S");
      // Or execute a custom script:
      // run("myscript.sh");
    } else {
      // User chose not to proceed, so you can perform alternative actions if needed
      // For example, you can terminate the compilation process with an error message:
      // throwError("User cancelled the operation.");
    }
  }
  1. The above YAML directive was confirmed on the online YAML validator https://www.anyjson.in/yaml-validator as valid.

  2. I placed a copy of the araraconfig.yaml file in the same directory as my LuaLateX project file (with the .tex extension).

  3. On the very top line of my LuaLateX project file (with the .tex extension), I included the arara directive: % arara: mydialog to trigger the arara Dialog box to appear immediately prior to executing the remaining directives in the LuaLateX project file.

  4. I created a four line MWE LuaLateX project file for the sole purpose of testing the above arara configuration to demonstrate how the arara Dialog box should appear:

% arara: mydialog
\documentclass{book}
\begin{document}
\end{document}

Upon typesetting, I was hoping that an arara Dialog box with the question: "Are you sure you want to proceed?" (as spelled out in my araraconfig.yaml configuration file) would immediately appear, prior to executing the three subsequent lines of LuaLaTeX code.

Unfortunately, with the above arrangement, there are two issues.

First, when I use TeXShop to typeset the above LuaLateX MWE project file (with the .tex extension), the much sought-after arara Dialog box never appears, an indication that something is amiss.

Second, as a check that the arara package itself is correctly installed, running arara -v (in Terminal) results in the following error:

Usage: arara [OPTIONS] file...

Error: Missing argument "file"

Any thoughts as to what I can do to correct what is amiss, or to get closer to determining what is amiss, would be greatly appreciated.

Thanks for reading, Star Blooming


Update: In answer to the first comment posted from David Carlisle, if I run arara youfile.tex (e.g. myprojectfile.tex) in Terminal, the following response appears:

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

  ERROR

I could not parse the configuration file, something bad happened.
This part is quite tricky, since it involves aspects of the
underlying data serialization format. I will do my best to help
you in any way I can. There are more details available on this
exception:

DETAILS ---------------------------------------------------------
com.charleskorn.kaml.UnknownPropertyException at identifier on
line 7, column 1: Unknown property 'identifier'. Known properties
are: dbname, defaultPreamble, filetypes, header, laf, language,
logging, logname, loops, paths, preambles,
prependPreambleIfDirectivesGiven, verbose

Total: 0.53 seconds

At first glance, it would appear that the above DETAILS may be pointing to line 7 in my araraconfig.yaml file, e.g.:

identifier: mydialog

Despite my having verified the araraconfig.yaml YAML file at the online YAML validator https://www.anyjson.in/yaml-validator, there may in fact be something amiss with configuration file.

If that is the case, it would also appear that the arara directive (% arara: mydialog) at least recognizes the existence of the araraconfig.yaml YAML configuration file.

As a complete novice in YAML, and in particular with respect to the interface between Java and the arara Dialog box, I am clueless as to the YAML error, and what I need to do to properly access the arara Dialog box via Java.

I don't see anything in arara-manual.pdf that would provide a clue to correct what is amiss.

Any suggestions as to what I might do to correct the error would be greatly appreciated.


Update 2: Before I begin, to @TeXnician, a hundred-thousand Thank You's. What you've provided is extraordinary!. (My hope is you've had some sleep b4 you read this!)

It took me a while (early stage dimentia?) to parse through your answer. We're making progress. If you don't mind, before I accept your answer, I'd like to resolve what I hope is one remaining error.

Apologies if this is redundant, but after incorporating your answer & suggestions, I'd like to spell out the steps for myself and others who may follow and also wish to utilize arara Dialog boxes.

One correction ... the Terminal command to check whether arara is properly installed is arara --version, NOT arara -v as I stated earlier. The response I received when I ran arara --version in Terminal was:

% arara --version
  __ _ _ __ __ _ _ __ __ _
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

arara 7.1.0
Copyright (c) 2023, Island of TeX
arara is released under the New BSD license.

New features in version 7.1.0:
* Add (Lua) project support to arara.
* Use a defined domain-specific file system API instead of `java.io.File`.
* Use header mode by default (`-w` restores the old behavior).

See the full changelog of this release at
https://gitlab.com/islandoftex/arara/-/blob/development/CHANGELOG.md

It appears that arara is correctly installed, after all.

The first 3 steps remain the same as before; the remaining steps follow along with @TeXnician's answer & suggestions.

  1. To make the Java Swing toolkit available, I installed (and confirmed via the Terminal command java version) that java version 1.8.0_371 is, in fact, installed.

  2. In Terminal, I set the appropriate environment variables to ensure Java runtime is accessible:

export JAVA_HOME =$(/usr/libexec/java_home)
export PATH=$JAVA_HOME/bin:$PATH
  1. I confirmed that the Swing toolkit is available and functioning properly via a simple Java Swing program SwingTest.java:
import javax.swing.*;

public class SwingTest {
    public static void main(String[] args) {
        SwingUtilities.invokeLater(() -> {
            JFrame frame = new JFrame("Swing Test");
            frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
            frame.setSize(300, 200);
            frame.setVisible(true);
        });
    }
}

that I ran in Terminal as:

javac SwingTest.java then java SwingTest

The test resulted in a small window titled "Swing Test" to appear on the screen, confirming that everything was setup correctly.

  1. I created the following hidden CONFIGURATION file: ./.araraconfig.yaml and placed the file in the <project> directory where my lualatex .tex file resides:
!config
paths:
- 'rules/'

This tells arara to look for custom RULES in my <project>/rules/ subdirectory.

  1. Within the <project>/rules/ subdirectory, I placed the mydialog.yaml RULES file with the following YAML directives:
!config
# Arara rule: mydialog
# Declare the rule
identifier: mydialog
name: My Dialog Rule
authors:
- Star Blooming
commands:
- name: Show confirmation dialog
  command: >
  @{
    // Import the necessary Java classes
    import javax.swing.JOptionPane;

    // Display the Dialog box and capture the user's response
    int option = JOptionPane.showConfirmDialog(null, "Are you sure you want to proceed?", "Confirmation", JOptionPane.YES_NO_OPTION);

    // Process the user's response
    if (option == JOptionPane.YES_OPTION) {
      // Execute the necessary commands or actions here
      // For example, you can run a specific command using `runCommand`:
      // runCommand("pdflatex", "-interaction=nonstopmode", "%O", "--shell-escape", "%S");
      // Or execute a custom script:
      // run("myscript.sh");
    } else {
      // User chose not to proceed, so you can perform alternative actions if needed
      // For example, you can terminate the compilation process with an error message:
      // throwError("User cancelled the operation.");
    }

    return true;
  }

(Note: The above directives reflect the fact that command needs to be enclosed in the commands section.)

  1. With the setup detailed above, my project structure looks like:
. (<--the <project directory>)
|- rules/  (<--the <project>/rules/ subdirectory)
|  |- mydialog.yaml  (<--arara RULES file in <project>/rules/ subdirectory)
|- .araraconfig.yaml  (<--arara CONFIGURATION file in <project directory>)
|- <lualatex project>.tex  (<--my lualatex `.tex` file in <project directory>)
  1. The four line MWE LuaLateX project file, araratesting.tex (for the sole purpose of testing the above arara configuration and demonstrate how the arara Dialog box should appear) remains the same as before:
% arara: mydialog
\documentclass{book}
\begin{document}
\end{document}
  1. Now, with the appropriate content in both the hidden CONFIGURATION file and the RULE file, I ran the following code in Terminal:
% arara araratesting.tex

with the following results:

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

Processing "araratesting.tex" (size: 70 B, last modified:
2023-06-04 05:52:42), please wait.

  ERROR

I have spotted an error in rule "mydialog" located at
"/<project directory>/rules/mydialog.yaml".
I could not parse the rule, something bad happened. This part is
quite tricky, since it involves aspects of the underlying data
serialization format. I will do my best to help you in any way I
can. There are more details available on this exception:

DETAILS ---------------------------------------------------------
java.util.NoSuchElementException: No value present

Total: 0.55 seconds

My guess is the above ERROR is due to an error in the mydialog.yaml RULE file (but that's just a guess).

I can of course also provide the araratesting.log file if need be.

Thanks again for reading, and for ALL your assistance and suggestions. Time to sleep.


Update 3: Based on a suggestion by @TeXnician in another post regarding running arara with the -l flag, the following is the arara.log after executing the following command in Terminal:

arara -l araratesting.tex

05 Jun 2023 11:51:24.883 INFO  - 
Welcome to arara 7.1.0!
-----------------------------------------------------------------
05 Jun 2023 11:51:24.885 DEBUG - 
::: arara @ /usr/local/texlive/2023/texmf-dist/scripts/arara
::: Java 20.0.1, Oracle Corporation
::: /Library/Java/JavaVirtualMachines/jdk-20.jdk/Contents/Home
::: Mac OS X, aarch64, 13.4
::: user.home @ /Users/<USER_ROOT>
::: CF @ /Users/<USER_ROOT>/Scrivener/Differ2Latex/Differ2Latex-v29b1/.araraconfig.yaml
-----------------------------------------------------------------
05 Jun 2023 11:51:24.888 INFO  - Processing "araratesting.tex" (size: 70 B, last modified: 2023-06-04 05:52:42), please wait.
05 Jun 2023 11:51:24.889 INFO  - I found a potential pattern in line 1: mydialog
05 Jun 2023 11:51:24.890 INFO  - All directives were validated. We are good to go.
-------------------------- DIRECTIVES ---------------------------
Directive(identifier='mydialog', parameters={reference=/Users/<USER_ROOT>/Scrivener/Differ2Latex/Differ2Latex-v29b1/araratesting.tex},conditional={ NONE }, lineNumbers=[1])
-----------------------------------------------------------------
05 Jun 2023 11:51:24.891 INFO  - I am ready to interpret rule "mydialog".
05 Jun 2023 11:51:24.892 INFO  - Rule location: "/Users/<USER_ROOT>/Scrivener/Differ2Latex/Differ2Latex-v29b1/rules"
05 Jun 2023 11:51:24.894 ERROR - I have spotted an error in rule "mydialog" located at "/Users/<USER_ROOT>/Scrivener/Differ2Latex/Differ2Latex-v29b1/rules/mydialog.yaml". I could not parse the rule, something bad happened. This part is quite tricky, since it involves aspects of the underlying data serialization format. I will do my best to help you in any way I can. There are more details available on this exception:
05 Jun 2023 11:51:24.894 ERROR - java.util.NoSuchElementException: No value present
05 Jun 2023 11:51:24.895 INFO  - Total: 0.102 seconds

From the above arara.log file, it is clear now that the error lies within the mydialog.yaml file.


10
  • you said you changed the path in the terminal but is it changed in the shell used by the editor? what happens if you run arara youfile.tex in the terminal in the directory with yourfile.tex ? Jun 3, 2023 at 9:09
  • @David Carlisle - It would appear that there may be an error in my araraconfig.yaml file, despite my having verified the file online. Any suggestions? Jun 3, 2023 at 9:57
  • You are using a rule as configuration file. This cannot work. Put the rule into a different YAML file and provide a valid configuration in the configuration file.
    – TeXnician
    Jun 3, 2023 at 18:19
  • Btw: The clue you are looking for is the chapter titled “configuration file” containing all valid keys for configuration files which do not correspond to the keys of a rule. And it lists the need for a configuration file with the paths variable set to have a custom rule set. Other than that, your rule is ill-formed (a YAML validator only checks syntax not semantics). You need to wrap the command in a commands block. Have a look at a basic rule like this for inspiration.
    – TeXnician
    Jun 3, 2023 at 18:25
  • 3
    @StarBlooming By coincidence, I stumbled upon your edited question (answerers do not get pings for edits to the question). Please do not make extensive edits that invalidate answers (now my answer reads like nonsense because it does not relate to your post anymore). Instead, please roll back this question and ask an updated question. Where your first question was basically “why does arara not find my rule”, your new question can focus on the “what is wrong in my rule” part, i.e. about the dialog boxes itself.
    – TeXnician
    Jun 5, 2023 at 17:00

1 Answer 1

4

First of all, thank you for your very elaborate question. That makes it easy to find the places where you have taken the wrong turn. Steps 1 to 4 are fine, so let's look into the remaining ones.

Step 4: In my HOME directory (cd ~), I created the hidden folder .arara (mkdir .arara) in which I created what would serve as the template, arara YAML configuration file araraconfig.yaml.

This is misleading on multiple accounts:

  1. What you are providing is not actually a configuration file (see the chapter “configuration file” in the manual for what is a configuration file). The YAML code you show here, is a rule. I'll explain how those interact down below.
  2. ~/.arara/araraconfig.yaml is not a recognized location. In terms of shell expressions, arara looks at ~/{.araraconfig.yaml,araraconfig.yaml,.arararc.yaml,arararc.yaml} (in this order) for a global configuration file. Or if you do it locally (e.g. in your project), then ./{.araraconfig.yaml,araraconfig.yaml,.arararc.yaml,arararc.yaml}. But you seem to have recognized that as you are mentioning it as a template location and you copying it somewhere.

Step 5 is all fine but irrelevant, so I will ignore it.

Step 6: I placed a copy of the araraconfig.yaml file in the same directory as my LuaLateX project file (with the .tex extension).

This is the point where you trip over the problem of mixing rules and configuration files. Because with that location (./araraconfig.yaml) you have told arara that the file you present there is a configuration file that instructs arara how to execute its run. For instance, whether it should log its output, whether it should print verbose output etc.

A valid configuration file would be something like this:

!config
verbose: true

Note that this is also hinted at by the error message you provided:

I could not parse the configuration file, something bad happened.
This part is quite tricky, since it involves aspects of the
underlying data serialization format. I will do my best to help
you in any way I can. There are more details available on this
exception:

DETAILS ---------------------------------------------------------
com.charleskorn.kaml.UnknownPropertyException at identifier on
line 7, column 1: Unknown property 'identifier'. Known properties
are: dbname, defaultPreamble, filetypes, header, laf, language,
logging, logname, loops, paths, preambles,
prependPreambleIfDirectivesGiven, verbose

See, the error message lists which options you actually can provide in a configuration file. In your case, you want to provide a custom rule, so let us try with the following ./araraconfig.yaml:

!config
paths:
- 'rules/'

which tells arara to look for custom rules in a directory called rules. I'll refer to that in a moment.

Step 7: On the very top line of my LuaLateX project file (with the .tex extension), I included the arara directive: % arara: mydialog to trigger the arara Dialog box to appear immediately prior to executing the remaining directives in the LuaLateX project file.

This directive % arara: mydialog will cause arara to look for a rule named mydialog in its rule paths. Without a configuration file, arara will only look into the TeX distributions default rules. It will not find a rule mydialog there.

And that's the point where the configuration file comes into play. The configuration file above tells arara to look into the rules/ directory as well. So now it will check if there is a rules/mydialog.yaml file in your project directory.

And this is where you want to put your rule content:

!config
# Arara rule: mydialog
# Description: Example rule with a Dialog box
# Author: Your Name

# Declare the rule
identifier: mydialog
name: My Dialog Rule
command: >
  @{
    // Import the necessary Java classes
    import javax.swing.JOptionPane;

    // Display the Dialog box and capture the user's response
    int option = JOptionPane.showConfirmDialog(null, "Are you sure you want to proceed?", "Confirmation", JOptionPane.YES_NO_OPTION);

    // Process the user's response
    if (option == JOptionPane.YES_OPTION) {
      // Execute the necessary commands or actions here
      // For example, you can run a specific command using `runCommand`:
      // runCommand("pdflatex", "-interaction=nonstopmode", "%O", "--shell-escape", "%S");
      // Or execute a custom script:
      // run("myscript.sh");
    } else {
      // User chose not to proceed, so you can perform alternative actions if needed
      // For example, you can terminate the compilation process with an error message:
      // throwError("User cancelled the operation.");
    }
  }

But wait, this looks like a rule, to a human it is clear that it is meant as a rule. But it does not conform to the rule syntax as required by arara. If you would run it like this, you will get an error message because you use command outside commands (the documentation is quite clear on the part that command needs to be enclosed in the commands section). So let us fix that part (actually, it is still untested but definitely more correct than the OP):

!config
# Arara rule: mydialog
# Declare the rule
identifier: mydialog
name: My Dialog Rule
authors:
- Star Blooming
commands:
- name: Show confirmation dialog
  command: >
  @{
    // Import the necessary Java classes
    import javax.swing.JOptionPane;

    // Display the Dialog box and capture the user's response
    int option = JOptionPane.showConfirmDialog(null, "Are you sure you want to proceed?", "Confirmation", JOptionPane.YES_NO_OPTION);

    // Process the user's response
    if (option == JOptionPane.YES_OPTION) {
      // Execute the necessary commands or actions here
      // For example, you can run a specific command using `runCommand`:
      // runCommand("pdflatex", "-interaction=nonstopmode", "%O", "--shell-escape", "%S");
      // Or execute a custom script:
      // run("myscript.sh");
    } else {
      // User chose not to proceed, so you can perform alternative actions if needed
      // For example, you can terminate the compilation process with an error message:
      // throwError("User cancelled the operation.");
    }

    return true;
  }

In the above rule, you will still have to do some adjustments. For instance (as in the OP), all your actual tasks to execute are commented out. And there is no runCommand in arara. Instead, you want to return all those commands it should run (where return true is above you should say something like return [getCommand(…)]; you can build the list you want to return in any way, e.g. using the conditional).

NB: You do not actually use any arara dialog boxes in your example, you use plain Swing. arara's way of dealing with yes/no dialogs would be showOptions(250, 4, 'Important!', 'Do you like ice cream?', 'Yes!', 'No!') == 1 (documentation example checking if you like ice cream). From the top of my head, I do not remember how well that does work in rules, though (all examples I remember use these dialog boxes in directives).

Step 8: I created a four line MWE LuaLateX project file for the sole purpose of testing the above arara configuration to demonstrate how the arara Dialog box should appear:

The MWE is flawless ;)


To reiterate: You have mixed up rules and configuration files as well as syntactical correctness of the format (YAML) and syntactical correctness of the metalanguage (arara rules).

With the setup detailed above, your project would look like

.
|- rules/
|  |- mydialog.yaml
|- .araraconfig.yaml
|- myfile.tex

with the appropriate content in the configuration file and rule file.

And please note that you still have to fix that rule to actually return useful commands and do something useful.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .