summaryrefslogtreecommitdiff
path: root/support/arara/doc/chapters/methods.tex
blob: dd6da67902d3affdb516a984214dd32b2da87ba9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
% !TeX root = ../arara-manual.tex
\chapter{Methods}
\label{chap:methods}

\arara\ features several helper methods available in directive conditional and rule contexts which provide interesting features for enhancing the user experience, as well as improving the automation itself. This chapter provides a list of such methods. It is important to observe that virtually all classes from the Java runtime environment can be used within MVEL expressions, so your mileage might vary.

\begin{messagebox}{A note on writing code}{araracolour}{\icok}{white}
As seen in Chapter~\ref{chap:mvel}, on page~\pageref{chap:mvel}, Java and MVEL code be used interchangeably within expressions and orb tags, including instantiation of classes into objects and invocation of methods. However, be mindful of explicitly importing Java packages and classes through the classic \rbox{import} statement, as MVEL does not automatically handle imports, or an exception will surely be raised. Alternatively, you can provide the full qualified name to classes as well.
\end{messagebox}

Methods are listed with their complete signatures, including potential  parameters and corresponding types. Also, the return type of a method is denoted by \rrbox{type} and refers to a typical Java data type (either class or primitive). Do not worry too much, as there are illustrative examples. A method available in the directive conditional context will be marked by \ctbox{C} next to the corresponding signature. Similarly, an entry marked by \ctbox{R} denotes that the corresponding method is available in the rule context.

\section{Files}
\label{sec:files}

This section introduces methods related to file handling, searching and hashing. It is important to observe that no exception is thrown in case of an anomalous method call. In this particular scenario, the methods return empty references, when applied.

\begin{description}
\item[\mdbox{R}{getOriginalFile()}{String}] This method returns the original file name, as plain string, regardless of a potential override through the special \abox{files} parameter in the directive mapping, as seen in Section~\ref{sec:directives}, on page~\pageref{sec:directives}.

\begin{codebox}{Example}{teal}{\icnote}{white}
if (file == getOriginalFile()) {
    System.out.println("The 'file' variable
       was not overridden.");
}
\end{codebox}

\item[\mdbox{R}{getOriginalReference()}{File}] This method returns the original file reference, as a \rbox{File} object, regardless of a potential reference override indirectly through the special \abox{files} parameter in the directive mapping, as seen in Section~\ref{sec:directives}, on page~\pageref{sec:directives}.

\begin{codebox}{Example}{teal}{\icnote}{white}
if (reference.equals(getOriginalFile())) {
    System.out.println("The 'reference' variable
       was not overridden.");
}
\end{codebox}

\item[\mddbox{C}{R}{currentFile()}{File}] This method returns the file reference, as a \rbox{File} object, for the current directive. It is important to observe that \arara\ replicates the directive when the special \abox{files} parameter is detected amongst the parameters, so each instance will have a different reference.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex if currentFile().getName() == 'thesis.tex'
\end{codebox}

\item[\mddbox{C}{R}{toFile(String reference)}{File}] This method returns a file (or directory) reference, as a \rbox{File} object, based on the provided string. Note that the string can refer to either a relative entry or a complete, absolute path. It is worth mentioning that, in Java, despite the curious name, a \rbox{File} object can be assigned to either a file or a directory.

\begin{codebox}{Example}{teal}{\icnote}{white}
f = toFile('thesis.tex');
\end{codebox}

\item[\mdbox{R}{getBasename(File file)}{String}] This method returns the base name (i.e, the name without the associated extension) of the provided \rbox{File} reference, as a string. Observe that this method ignores a potential path reference when extracting the base name. Also, this method will throw an exception if the provided reference is not a proper file.

\begin{codebox}{Example}{teal}{\icnote}{white}
basename = getBasename(toFile('thesis.tex'));
\end{codebox}

\item[\mdbox{R}{getBasename(String reference)}{String}] This method returns the base name (i.e, the name without the associated extension) of the provided \rbox{String} reference, as a string. Observe that this method ignores a potential path reference when extracting the base name.

\begin{codebox}{Example}{teal}{\icnote}{white}
basename = getBasename('thesis.tex');
\end{codebox}

\item[\mdbox{R}{getFiletype(File file)}{String}] This method returns the file type (i.e, the associated extension specified as a suffix to the name, typically delimited with a full stop) of the provided \rbox{File} reference, as a string. This method will throw an exception if the provided reference is not a proper file. An empty string is returned if, and only if, the provided file name has no associated extension.

\begin{codebox}{Example}{teal}{\icnote}{white}
extension = getFiletype(toFile('thesis.pdf'));
\end{codebox}

\item[\mdbox{R}{getFiletype(String reference)}{String}] This method returns the file type (i.e, the associated extension specified as a suffix to the name, typically delimited with a full stop) of the provided \rbox{String} reference, as a string. An empty string is returned if, and only if, the provided file name has no associated extension.

\begin{codebox}{Example}{teal}{\icnote}{white}
extension = getFiletype('thesis.pdf');
\end{codebox}

\item[\mddbox{C}{R}{exists(File file)}{boolean}] This method, as the name implies, returns a boolean value according to whether the provided \rbox{File} reference exists. Observe that the provided reference can be either a file or a directory.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: bibtex if exists(toFile('references.bib'))
\end{codebox}

\item[\mddbox{C}{R}{exists(String extension)}{boolean}] This method returns a boolean value according to whether the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the provided \rbox{String} extension exists. This method eases the checking of files which share the current file name modulo extension (e.g, log and auxiliary files). Note that the provided string refers to the extension, not the file name.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdftex if exists('tex')
\end{codebox}

\item[\mddbox{C}{R}{missing(File file)}{boolean}] This method, as the name implies, returns a boolean value according to whether the provided \rbox{File} reference does not exist. It is important to observe that the provided reference can be either a file or a directory.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdftex if missing(toFile('thesis.pdf'))
\end{codebox}

\item[\mddbox{C}{R}{missing(String extension)}{boolean}] This method returns a boolean value according to whether the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the provided \rbox{String} extension does not exist. This method eases the checking of files which share the current file name modulo extension (e.g, log and auxiliary files). Note that the provided string refers to the extension, not the file name.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdftex if missing('pdf')
\end{codebox}

\item[\mddbox{C}{R}{changed(File file)}{boolean}] This method returns a boolean value according to whether the provided \rbox{File} reference has changed since last verification, based on a traditional cyclic redundancy check. The file reference, as well as the associated hash, is stored in a YAML database file named \rbox{arara.yaml} located in the same directory as the current file (the database name can be overridden in the configuration file, as discussed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). The method semantics (including the return values) is presented as follows.

\vspace{1em}

{\centering\small
\setlength\tabcolsep{0.8em}
\begin{tabular}{@{}ccccc@{}}
\toprule
\emph{file exists?} & \emph{entry exists?} &
\emph{has changed?} & \emph{DB action} &
\emph{result} \\
\midrule
\cbyes{-2} & \cbyes{-2} & \cbyes{-2} & update & \cbyes{-2} \\
\cbyes{-2} & \cbyes{-2} & \cbno{-2} & --- & \cbno{-2} \\
\cbyes{-2} & \cbno{-2} & --- & insert & \cbyes{-2} \\
\cbno{-2} & \cbno{-2} & --- & --- & \cbno{-2} \\
\cbno{-2} & \cbyes{-2} & --- & remove & \cbyes{-2} \\
\bottomrule
\end{tabular}\par}

\vspace{1.4em}

It is important to observe that this method \emph{always} performs a database operation, either an insertion, removal or update on the corresponding entry. When using \mtbox{changed} within a logical expression, make sure the evaluation order is correct, specially regarding the use of short-circuiting operations. In some scenarios, order does matter.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex if changed(toFile('thesis.tex'))
\end{codebox}

\begin{messagebox}{Short-circuit evaluation}{araracolour}{\icok}{white}
According to the \href{https://en.wikipedia.org/wiki/Short-circuit_evaluation}{Wikipedia entry}, a \emph{short-circuit evaluation} is the semantics of some boolean operators in some programming languages in which the second argument is executed or evaluated only if the first argument does not suffice to determine the value of the expression. In Java (and consequently MVEL), both short-circuit and standard boolean operators are available.
\end{messagebox}

\begin{messagebox}{CRC as a hashing algorithm}{attentioncolour}{\icattention}{black}
\arara\ internally relies on a CRC32 implementation for file hashing. This particular choice, although not designed for hashing, offers an interesting trade-off between speed and quality. Besides, since it is not computationally expensive as strong algorithms such as MD5 and SHA1, CRC32 can be used for hashing typical \TeX\ documents and plain text files with little to no collisions.
\end{messagebox}

\item[\mddbox{C}{R}{changed(String extension)}{boolean}] This method returns a boolean value according to whether the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the provided \rbox{String} extension has changed since last verification, based on a traditional cyclic redundancy check. The file reference, as well as the associated hash, is stored in a YAML database file named \rbox{arara.yaml} located in the same directory as the current file (the database name can be overridden in the configuration file, as discussed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). The method semantics (including the return values) is presented as follows.

\vspace{1em}

{\centering\small
\setlength\tabcolsep{0.8em}
\begin{tabular}{@{}ccccc@{}}
\toprule
\emph{file exists?} & \emph{entry exists?} &
\emph{has changed?} & \emph{DB action} &
\emph{result} \\
\midrule
\cbyes{-2} & \cbyes{-2} & \cbyes{-2} & update & \cbyes{-2} \\
\cbyes{-2} & \cbyes{-2} & \cbno{-2} & --- & \cbno{-2} \\
\cbyes{-2} & \cbno{-2} & --- & insert & \cbyes{-2} \\
\cbno{-2} & \cbno{-2} & --- & --- & \cbno{-2} \\
\cbno{-2} & \cbyes{-2} & --- & remove & \cbyes{-2} \\
\bottomrule
\end{tabular}\par}

\vspace{1.4em}

It is important to observe that this method \emph{always} performs a database operation, either an insertion, removal or update on the corresponding entry. When using \mtbox{changed} within a logical expression, make sure the evaluation order is correct, specially regarding the use of short-circuiting operations. In some scenarios, order does matter.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex if changed('tex')
\end{codebox}

\item[\mddbox{C}{R}{unchanged(File file)}{boolean}] This method returns a boolean value according to whether the provided \rbox{File} reference has not changed since last verification, based on a traditional cyclic redundancy check. The file reference, as well as the associated hash, is stored in a YAML database file named \rbox{arara.yaml} located in the same directory as the current file (the database name can be overridden in the configuration file, as discussed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). The method semantics (including the return values) is presented as follows.

\vspace{1em}

{\centering\small
\setlength\tabcolsep{0.8em}
\begin{tabular}{@{}ccccc@{}}
\toprule
\emph{file exists?} & \emph{entry exists?} &
\emph{has changed?} & \emph{DB action} &
\emph{result} \\
\midrule
\cbyes{-2} & \cbyes{-2} & \cbyes{-2} & update & \cbno{-2} \\
\cbyes{-2} & \cbyes{-2} & \cbno{-2} & --- & \cbyes{-2} \\
\cbyes{-2} & \cbno{-2} & --- & insert & \cbno{-2} \\
\cbno{-2} & \cbno{-2} & --- & --- & \cbyes{-2} \\
\cbno{-2} & \cbyes{-2} & --- & remove & \cbno{-2} \\
\bottomrule
\end{tabular}\par}

\vspace{1.4em}

It is important to observe that this method \emph{always} performs a database operation, either an insertion, removal or update on the corresponding entry. When using \mtbox{unchanged} within a logical expression, make sure the evaluation order is correct, specially regarding the use of short-circuiting operations. In some scenarios, order does matter.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex if !unchanged(toFile('thesis.tex'))
\end{codebox}

\item[\mddbox{C}{R}{unchanged(String extension)}{boolean}] This method returns a boolean value according to whether the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the provided \rbox{String} extension has not changed since last verification, based on a traditional cyclic redundancy check. The file reference, as well as the associated hash, is stored in a YAML database file named \rbox{arara.yaml} located in the same directory as the current file (the database name can be overridden in the configuration file, as discussed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). The method semantics (including the return values) is presented as follows.

\vspace{1em}

{\centering\small
\setlength\tabcolsep{0.8em}
\begin{tabular}{@{}ccccc@{}}
\toprule
\emph{file exists?} & \emph{entry exists?} &
\emph{has changed?} & \emph{DB action} &
\emph{result} \\
\midrule
\cbyes{-2} & \cbyes{-2} & \cbyes{-2} & update & \cbno{-2} \\
\cbyes{-2} & \cbyes{-2} & \cbno{-2} & --- & \cbyes{-2} \\
\cbyes{-2} & \cbno{-2} & --- & insert & \cbno{-2} \\
\cbno{-2} & \cbno{-2} & --- & --- & \cbyes{-2} \\
\cbno{-2} & \cbyes{-2} & --- & remove & \cbno{-2} \\
\bottomrule
\end{tabular}\par}

\vspace{1.4em}

It is important to observe that this method \emph{always} performs a database operation, either an insertion, removal or update on the corresponding entry. When using \mtbox{unchanged} within a logical expression, make sure the evaluation order is correct, specially regarding the use of short-circuiting operations. In some scenarios, order does matter.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex if !unchanged('tex')
\end{codebox}

\item[\mdbox{R}{writeToFile(File file, String text, boolean append)}{boolean}] This method performs a write operation based on the provided parameters. In this case, the method writes the \rbox{String} text to the \rbox{File} reference and returns a boolean value according to whether the operation was successful. The third parameter holds a \rbox{boolean} value and acts as a switch indicating whether the text should be appended to the existing content of the provided file. Keep in mind that the existing content of a file is always overwritten if this switch is disabled. Also, note that the switch has no effect if the file is being created at that moment. It is important to observe that this method does not raise any exception.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = writeToFile(toFile('foo.txt'), 'hello world', false);
\end{codebox}

\begin{messagebox}{Read and write operations in Unicode}{attentioncolour}{\icattention}{black}
\arara\ \emph{always} uses Unicode as the encoding format for read and write operations. This decision is deliberate as a means to offer a consistent representation and handling of text. Unicode can be implemented by different character encodings. In our case, the tool relies on UTF-8, which uses one byte for the first 128 code points, and up to 4 bytes for other characters. The first 128 Unicode code points are the ASCII characters, which means that any ASCII text is also UTF-8 text.
\end{messagebox}

\begin{messagebox}{File system permissions}{attentioncolour}{\icattention}{black}
Most file systems have methods to assign permissions or access rights to specific users and groups of users. These permissions control the ability of the users to view, change, navigate, and execute the contents of the file system. Keep in mind that read and write operations depend on such permissions.
\end{messagebox}

\item[\mdbox{R}{writeToFile(String reference, String text, boolean append)}{boolean}] This method performs a write operation based on the provided parameters. In this case, the method writes the \rbox{String} text to the \rbox{String} reference and returns a boolean value according to whether the operation was successful. The third parameter holds a \rbox{boolean} value and acts as a switch indicating whether the text should be appended to the existing content of the provided file. Keep in mind that the existing content of a file is always overwritten if this switch is disabled. Also, note that the switch has no effect if the file is being created at that moment. It is important to observe that this method does not raise any exception.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = writeToFile('foo.txt', 'hello world', false);
\end{codebox}

\item[\mdbox{R}{writeToFile(File file, List<String> lines, boolean append)}{boolean}] This method performs a write operation based on the provided parameters. In this case, the method writes the \rbox{List<String>} lines to the \rbox{File} reference and returns a boolean value according to whether the operation was successful. The third parameter holds a \rbox{boolean} value and acts as a switch indicating whether the text should be appended to the existing content of the provided file. Keep in mind that the existing content of a file is always overwritten if this switch is disabled. Also, note that the switch has no effect if the file is being created at that moment. It is important to observe that this method does not raise any exception.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = writeToFile(toFile('foo.txt'),
         [ 'hello world', 'how are you?' ], false);
\end{codebox}

\item[\mdbox{R}{\parbox{0.51\textwidth}{writeToFile(String reference,\\\hspace*{1em} List<String> lines, boolean append)}}{boolean}] This method performs a write operation based on the provided parameters. In this case, the method writes the \rbox{List<String>} lines to the \rbox{String} reference and returns a boolean value according to whether the operation was successful. The third parameter holds a \rbox{boolean} value and acts as a switch indicating whether the text should be appended to the existing content of the provided file. Keep in mind that the existing content of a file is always overwritten if this switch is disabled. Also, note that the switch has no effect if the file is being created at that moment. It is important to observe that this method does not raise any exception.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = writeToFile('foo.txt', [ 'hello world',
         'how are you?' ], false);
\end{codebox}

\item[\mdbox{R}{readFromFile(File file)}{List<String>}] This method performs a read operation based on the provided parameter. In this case, the method reads the content from the \rbox{File} reference and returns a \rbox{List<String>} object representing the lines as a list of strings. If the reference does not exist or an exception is raised due to access permission constraints, the \mtbox{readFromFile} method returns an empty list. Keep in mind that, as a design decision, UTF-8 is \emph{always} used as character encoding for read operations.

\begin{codebox}{Example}{teal}{\icnote}{white}
lines = readFromFile(toFile('foo.txt'));
\end{codebox}

\item[\mdbox{R}{readFromFile(String reference)}{List<String>}] This method performs a read operation based on the provided parameter. In this case, the method reads the content from the \rbox{String} reference and returns a \rbox{List<String>} object representing the lines as a list of strings. If the reference does not exist or an exception is raised due to access permission constraints, the \mtbox{readFromFile} method returns an empty list. Keep in mind that, as a design decision, UTF-8 is \emph{always} used as character encoding for read operations.

\begin{codebox}{Example}{teal}{\icnote}{white}
lines = readFromFile('foo.txt');
\end{codebox}

\item[\mdbox{R}{\parbox{0.61\textwidth}{listFilesByExtensions(File file,\\\hspace*{1em} List<String> extensions, boolean recursive)}}{List<File>}] This method performs a file search operation based on the provided parameters. In this case, the method list all files from the provided \rbox{File} reference according to the \rbox{List<String>} extensions as a list of strings, and returns a \rbox{List<File>} object representing all matching files. The leading full stop in each extension must be omitted, unless it is part of the search pattern. The third parameter holds a \rbox{boolean} value and acts as a switch indicating whether the search must be recursive, i.e, whether all subdirectories must be searched as well. If the reference is not a proper directory or an exception is raised due to access permission constraints, the \mtbox{listFilesByExtensions} method returns an empty list.

\begin{codebox}{Example}{teal}{\icnote}{white}
files = listFilesByExtensions(toFile('/home/paulo/Documents'),
        [ 'aux', 'log' ], false);
\end{codebox}

\item[\mdbox{R}{\parbox{0.61\textwidth}{listFilesByExtensions(String reference,\\\hspace*{1em} List<String> extensions, boolean recursive)}}{List<File>}] This method performs a file search operation based on the provided parameters. In this case, the method list all files from the provided \rbox{String} reference according to the \rbox{List<String>} extensions as a list of strings, and returns a \rbox{List<File>} object representing all matching files. The leading full stop in each extension must be omitted, unless it is part of the search pattern. The third parameter holds a \rbox{boolean} value and acts as a switch indicating whether the search must be recursive, i.e, whether all subdirectories must be searched as well. If the reference is not a proper directory or an exception is raised due to access permission constraints, the \mtbox{listFilesByExtensions} method returns an empty list.

\begin{codebox}{Example}{teal}{\icnote}{white}
files = listFilesByExtensions('/home/paulo/Documents',
        [ 'aux', 'log' ], false);
\end{codebox}

\item[\mdbox{R}{\parbox{0.59\textwidth}{listFilesByPatterns(File file,\\\hspace*{1em} List<String> patterns, boolean recursive)}}{List<File>}] This method performs a file search operation based on the provided parameters. In this case, the method lists all files from the provided \rbox{File} reference according to the \rbox{List<String>} patterns as a list of strings, and returns a \rbox{List<File>} object representing all matching files. The pattern specification is described below. The third parameter holds a \rbox{boolean} value and acts as a switch indicating whether the search must be recursive, i.e, whether all subdirectories must be searched as well. If the reference is not a proper directory or an exception is raised due to access permission constraints, the \mtbox{listFilesByPatterns} method returns an empty list. It is very important to observe that this file search operation might be slow depending on the provided directory. It is highly advisable to not rely on recursive searches whenever possible.

\begin{messagebox}{Patterns for file search operations}{araracolour}{\icattention}{white}
\arara\ employs wildcard filters as patterns for file search operations. Testing is case sensitive by default. The wildcard matcher uses the characters \rbox[araracolour]{?} and \rbox[araracolour]{*} to represent a single or multiple wildcard characters. This is the same as often found on typical terminals.
\end{messagebox}

\begin{codebox}{Example}{teal}{\icnote}{white}
files = listFilesByPatterns(toFile('/home/paulo/Documents'),
        [ '*.tex', 'foo?.txt' ], false);
\end{codebox}


\item[\mdbox{R}{\parbox{0.59\textwidth}{listFilesByPatterns(String reference,\\\hspace*{1em} List<String> patterns, boolean recursive)}}{List<File>}] This method performs a file search operation based on the provided parameters. In this case, the method lists all files from the provided \rbox{String} reference according to the \rbox{List<String>} patterns as a list of strings, and returns a \rbox{List<File>} object representing all matching files. The pattern specification follows a wildcard filter. The third parameter holds a \rbox{boolean} value and acts as a switch indicating whether the search must be recursive, i.e, whether all subdirectories must be searched as well. If the reference is not a proper directory or an exception is raised due to access permission constraints, the \mtbox{listFilesByPatterns} method returns an empty list. It is very important to observe that this file search operation might be slow depending on the provided directory. It is highly advisable to not rely on recursive searches whenever possible.

\begin{codebox}{Example}{teal}{\icnote}{white}
files = listFilesByPatterns('/home/paulo/Documents',
        [ '*.tex', 'foo?.txt' ], false);
\end{codebox}
\end{description}

As the methods presented in this section have transparent error handling, the writing of rules and conditionals becomes more fluent and not too complex for the typical user.

\section{Conditional flow}
\label{sec:conditionalflow}

This section introduces methods related to conditional flow based on \emph{natural boolean values}, i.e, words that semantically represent truth and falsehood signs. Such concept provides a friendly representation of boolean values and eases the use of switches in directive parameters. The tool relies on the following set of natural boolean values:

\vspace{1em}

{\centering
\setlength\tabcolsep{0.2em}
\begin{tabular}{ccccccccccc}
\cbyes{-2} &
\rbox[araracolour]{\hphantom{w}yes\hphantom{w}} &
\rbox[araracolour]{\hphantom{w}true\hphantom{w}} &
\rbox[araracolour]{\hphantom{w}1\hphantom{w}} &
\rbox[araracolour]{\hphantom{w}on\hphantom{w}} &
\hspace{2em} &
\cbno{-2} &
\rbox[warningcolour]{\hphantom{w}no\hphantom{w}} &
\rbox[warningcolour]{\hphantom{w}false\hphantom{w}} &
\rbox[warningcolour]{\hphantom{w}0\hphantom{w}} &
\rbox[warningcolour]{\hphantom{w}off\hphantom{w}}
\end{tabular}\par}

\vspace{1.4em}

All elements from the provided set of natural boolean values can be used interchangeably in directive parameters. It is important to observe that \arara\ throws an exception if a value absent from the set is provided to the methods described in this section.

\begin{description}
\item[\mdbox{R}{isTrue(String string)}{boolean}] This method returns a boolean value according to whether the provided \rbox{String} value is contained in the sub-set of natural true boolean values. It is worth mentioning that the verification is case insensitive, i.e, upper case and lower case symbols are treated as equivalent. If the provided value is an empty string, the method returns false.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isTrue('yes');
\end{codebox}

\item[\mdbox{R}{isFalse(String string)}{boolean}] This method returns a boolean value according to whether the provided \rbox{String} value is contained in the sub-set of natural false boolean values. It is worth mentioning that the verification is case insensitive, i.e, upper case and lower case symbols are treated as equivalent. If the provided value is an empty string, the method returns false.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isFalse('off');
\end{codebox}

\item[\mdbox{R}{isTrue(String string, Object yes)}{Object}] This method checks if the first parameter is contained in the sub-set of natural true boolean values. If the result holds true, the second parameter is returned. Otherwise, an empty string is returned. It is worth mentioning that the verification is case insensitive, i.e, upper case and lower case symbols are treated as equivalent. If the first parameter is an empty string, the method returns an empty string.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isTrue('on', [ 'ls', '-la' ]);
\end{codebox}

\item[\mdbox{R}{isFalse(String string, Object yes)}{Object}] This method checks if the first parameter is contained in the sub-set of natural false boolean values. If the result holds true, the second parameter is returned. Otherwise, an empty string is returned. It is worth mentioning that the verification is case insensitive, i.e, upper case and lower case symbols are treated as equivalent. If the first parameter is an empty string, the method returns an empty string.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isFalse('0', 'pwd');
\end{codebox}

\item[\mdbox{R}{isTrue(String string, Object yes, Object no)}{Object}] This method checks if the first parameter is contained in the sub-set of natural true boolean values. If the result holds true, the second parameter is returned. Otherwise, the third parameter is returned. It is worth mentioning that the verification is case insensitive, i.e, upper case and lower case symbols are treated as equivalent. If the first parameter is an empty string, the method returns the third parameter.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isTrue('on', [ 'ls', '-la' ], 'pwd');
\end{codebox}

\item[\mdbox{R}{isFalse(String string, Object yes, Object no)}{Object}] This method checks if the first parameter is contained in the sub-set of natural false boolean values. If the result holds true, the second parameter is returned. Otherwise, the third parameter is returned. It is worth mentioning that the verification is case insensitive, i.e, upper case and lower case symbols are treated as equivalent. If the first parameter is an empty string, the method returns the third parameter.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isFalse('0', 'pwd', 'ps');
\end{codebox}

\item[\mdbox{R}{\parbox{0.45\textwidth}{isTrue(String string, Object yes,\\\hspace*{1em} Object no, Object fallback)}}{Object}] This method checks if the first parameter is contained in the sub-set of natural true boolean values. If the result holds true, the second parameter is returned. Otherwise, the third parameter is returned. It is worth mentioning that the verification is case insensitive, i.e, upper case and lower case symbols are treated as equivalent. If the first parameter is an empty string, the method returns the fourth parameter as default value.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isTrue('on', 'ls', 'pwd', 'who');
\end{codebox}

\item[\mdbox{R}{\parbox{0.46\textwidth}{isFalse(String string, Object yes,\\\hspace*{1em} Object no, Object fallback)}}{Object}] This method checks if the first parameter is contained in the sub-set of natural false boolean values. If the result holds true, the second parameter is returned. Otherwise, the third parameter is returned. It is worth mentioning that the verification is case insensitive, i.e, upper case and lower case symbols are treated as equivalent. If the first parameter is an empty string, the method returns the fourth parameter as default value.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isFalse('0', 'pwd', 'ps', 'ls');
\end{codebox}

\item[\mdbox{R}{isTrue(boolean value, Object yes)}{Object}] This method evaluates the first parameter as a boolean expression. If the result holds true, the second parameter is returned. Otherwise, an empty string is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isTrue(1 == 1, 'yes');
\end{codebox}

\item[\mdbox{R}{isFalse(boolean value, Object yes)}{Object}] This method evaluates the first parameter as a boolean expression. If the result holds false, the second parameter is returned. Otherwise, an empty string is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isFalse(1 != 1, 'yes');
\end{codebox}

\item[\mdbox{R}{isTrue(boolean value, Object yes, Object no)}{Object}] This method evaluates the first parameter as a boolean expression. If the result holds true, the second parameter is returned. Otherwise, the third parameter is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isTrue(1 == 1, 'yes', 'no');
\end{codebox}

\item[\mdbox{R}{isFalse(boolean value, Object yes, Object no)}{Object}] This method evaluates the first parameter as a boolean expression. If the result holds false, the second parameter is returned. Otherwise, the third parameter is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isFalse(1 != 1, 'yes', 'no');
\end{codebox}
\end{description}

Supported by the concept of natural boolean values, the methods presented in this section ease the use of switches in directive parameters and can be adopted as valid alternatives for traditional conditional flows, when applied.

\section{Strings}
\label{sec:strings}

String manipulation constitutes one of the foundations of rule interpretation in our tool. This section introduces methods for handling such types, as a means to offer high level constructs for users.

\begin{description}
\item[\mdbox{R}{isEmpty(String string)}{boolean}] This method returns a boolean value according to whether the provided \rbox{String} value is empty, i.e, the string length is equal to zero.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isEmpty('not empty');
\end{codebox}

\item[\mdbox{R}{isNotEmpty(String string)}{boolean}] This method returns a boolean value according to whether the provided \rbox{String} value is not empty, i.e, the string length is greater than zero.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isNotEmpty('not empty');
\end{codebox}

\item[\mdbox{R}{isEmpty(String string, Object yes)}{boolean}] This method checks if the first parameter is empty, i.e, if the string length is equal to zero. If the result holds true, the second parameter is returned. Otherwise, an empty string is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isEmpty('not empty', 'ps');
\end{codebox}

\item[\mdbox{R}{isNotEmpty(String string, Object yes)}{boolean}] This method checks if the first parameter is not empty, i.e, if the string length is greater than zero. If the result holds true, the second parameter is returned. Otherwise, an empty string is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isNotEmpty('not empty', 'ls');
\end{codebox}

\item[\mdbox{R}{isEmpty(String string, Object yes, Object no)}{boolean}] This method checks if the first parameter is empty, i.e, if the string length is equal to zero. If the result holds true, the second parameter is returned. Otherwise, the third parameter is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isEmpty('not empty', 'ps', 'ls');
\end{codebox}

\item[\mdbox{R}{isNotEmpty(String string, Object yes, Object no)}{boolean}] This method checks if the first parameter is not empty, i.e, if the string length is greater than zero. If the result holds true, the second parameter is returned. Otherwise, the third parameter is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isNotEmpty('not empty', 'ls', 'ps');
\end{codebox}

\item[\mdbox{R}{buildString(Object... objects)}{String}] This method returns a string based on the provided array of objects, separating each element by one blank space. It is important to observe that empty values are not considered. Also, note that the object array is denoted by a  comma-separated sequence of elements in the actual method call, resulting in a variable number of parameters.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = buildString('a', 'b', 'c', 'd');
\end{codebox}

\item[\mdbox{R}{trimSpaces(String string)}{String}] This method trims spaces from the provided parameter, i.e, leading and trailing spaces in the \rbox{String} reference are removed, and returns the resulting string. It is important to observe that non-boundary spaces inside the string are not removed at all.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = trimSpaces('   hello world   ');
\end{codebox}

\item[\mdbox{R}{replicatePattern(String pattern, List<Object> values)}{List<Object>}] This method replicates the provided pattern to each element of the second parameter and returns the resulting list. The pattern must contain exactly one placeholder. For instance, \rbox{\%s} denotes a string representation of the provided argument. Please refer to the \rbox{Formatter} class reference in the \href{https://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html}{Java documentation} for more information on placeholders. This method raises an exception if an invalid pattern is applied.

\begin{codebox}{Example}{teal}{\icnote}{white}
names = replicatePattern('My name is %s', [ 'Brent', 'Nicola' ]);
\end{codebox}

\item[\mddbox{C}{R}{found(File file, String regex)}{boolean}] This method returns a boolean value according to whether the content of the provided \rbox{File} reference contains at least one match of the provided \rbox{String} regular expression. It is important to observe that this method raises an exception if an invalid regular expression is provided as the parameter or if the provided file reference does not exist.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex while found(toFile('article.log'),
% arara: --> 'undefined references')
\end{codebox}

\item[\mddbox{C}{R}{found(String extension, String regex)}{boolean}] This method returns a boolean value according to whether the content of the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the provided \rbox{String} extension contains at least one match of the provided \rbox{String} regular expression. It is important to observe that this method raises an exception if an invalid regular expression is provided as the parameter or if the provided file reference does not exist.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex while found('log', 'undefined references')
\end{codebox}
\end{description}

The string manipulation methods presented in this section constitute an interesting and straightforward approach to handling directive parameters without the usual verbosity in writing typical Java constructs.

\section{Operating systems}
\label{sec:operatingsystems}

This section introduces methods related to the underlying operating system detection, as a means of providing a straightforward approach to writing cross-platform rules.

\begin{description}
\item[\mdbox{R}{isWindows()}{boolean}] This method returns a boolean value according to whether the underlying operating system vendor is Microsoft Windows.

\begin{codebox}{Example}{teal}{\icnote}{white}
if (isWindows()) { System.out.println('Running Windows.'); }
\end{codebox}

\item[\mdbox{R}{isLinux()}{boolean}] This method returns a boolean value according to whether the underlying operating system vendor is a Linux instance.

\begin{codebox}{Example}{teal}{\icnote}{white}
if (isLinux()) { System.out.println('Running Linux.'); }
\end{codebox}

\item[\mdbox{R}{isMac()}{boolean}] This method returns a boolean value according to whether the underlying operating system vendor is Apple Mac OS.

\begin{codebox}{Example}{teal}{\icnote}{white}
if (isMac()) { System.out.println('Running Mac OS.'); }
\end{codebox}

\item[\mdbox{R}{isUnix()}{boolean}] This method returns a boolean value according to whether the underlying operating system vendor is any Unix variation.

\begin{codebox}{Example}{teal}{\icnote}{white}
if (isUnix()) { System.out.println('Running Unix.'); }
\end{codebox}

\item[\mdbox{R}{isCygwin()}{boolean}] This method returns a boolean value according to whether the underlying operating system vendor is Microsoft Windows and \arara\ is being executed inside a Cygwin environment.

\begin{codebox}{Example}{teal}{\icnote}{white}
if (isCygwin()) { System.out.println('Running Cygwin.'); }
\end{codebox}

\item[\mdbox{R}{isWindows(Object yes, Object no)}{Object}] This method checks if the underlying operating system vendor is Microsoft Windows. If the result holds true, the first parameter is returned. Otherwise, the second parameter is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
command = isWindows('del', 'rm');
\end{codebox}

\item[\mdbox{R}{isLinux(Object yes, Object no)}{Object}] This method checks if the underlying operating system vendor is a Linux instance. If the result holds true, the first parameter is returned. Otherwise, the second parameter is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
command = isLinux('rm', 'del');
\end{codebox}

\item[\mdbox{R}{isMac(Object yes, Object no)}{Object}] This method checks if the underlying operating system vendor is Apple Mac OS. If the result holds true, the first parameter is returned. Otherwise, the second parameter is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
command = isMac('ls', 'dir');
\end{codebox}

\item[\mdbox{R}{isUnix(Object yes, Object no)}{Object}] This method checks if the underlying operating system vendor is any Unix variation. If the result holds true, the first parameter is returned. Otherwise, the second parameter is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
command = isUnix('tree', 'dir');
\end{codebox}

\item[\mdbox{R}{isCygwin(Object yes, Object no)}{Object}] This method checks if the underlying operating system vendor is Microsoft Windows and if \arara\ is being executed inside a Cygwin environment. If the result holds true, the first parameter is returned. Otherwise, the second parameter is returned.

\begin{codebox}{Example}{teal}{\icnote}{white}
command = isCygwin('ls', 'dir');
\end{codebox}
\end{description}

The methods presented in the section provide useful information to help users write cross-platform rules and thus enhance the automation experience based on specific features of the underlying operating system.

\section{Type checking}
\label{sec:typechecking}

In certain scenarios, a plain string representation of directive parameters might be inadequate or insufficient given the rule requirements. To this end, this section introduces methods related to type checking as a means to provide support and verification for common data types.

\begin{description}
\item[\mdbox{R}{isString(Object object)}{boolean}] This method returns a boolean value according to whether the provided \rbox{Object} object is a string or any extended type.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isString('foo');
\end{codebox}

\item[\mdbox{R}{isList(Object object)}{boolean}] This method returns a boolean value according to whether the provided \rbox{Object} object is a list or any extended type.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isList([ 1, 2, 3 ]);
\end{codebox}

\item[\mdbox{R}{isMap(Object object)}{boolean}] This method returns a boolean value according to whether the provided \rbox{Object} object is a map or any extended type.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isMap([ 'Paulo' : 'Palmeiras', 'Carla' : 'Inter' ]);
\end{codebox}

\item[\mdbox{R}{isBoolean(Object object)}{boolean}] This method returns a boolean value according to whether the provided \rbox{Object} object is a boolean or any extended type.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isBoolean(false);
\end{codebox}

\item[\mdbox{R}{checkClass(Class clazz, Object object)}{boolean}] This method returns a boolean value according to whether the provided \rbox{Object} object is an instance or a subtype of the provided \rbox{Class} class. It is interesting to note that all methods presented in this section internally rely on \mtbox{checkClass} for type checking.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = checkClass(List.class, [ 'a', 'b' ]);
\end{codebox}
\end{description}

The methods presented in this section cover the most common types used in directive parameters and should suffice for expressing the rule requirements. If a general approach is needed, please refer to the \mtbox{checkClass} method for checking virtually any type available in the Java environment.

\section{Classes and objects}
\label{sec:classesandobjects}

\arara\ can be extended at runtime with code from JVM languages, such as Groovy, Scala, Clojure and Kotlin. The tool can load classes from \rbox{class} and \rbox{jar} files and even instantiate them. This section introduces methods related to class loading and object instantiation.

\begin{messagebox}{Ordered pairs}{araracolour}{\icok}{white}
According to the \href{https://en.wikipedia.org/wiki/Ordered_pair}{Wikipedia entry}, in mathematics, an \emph{ordered pair} $(a, b)$ is a pair of objects. The order in which the objects appear in the pair is significant: the ordered pair $(a, b)$ is different from the ordered pair $(b, a)$ unless $a = b$. In the ordered pair $(a, b)$, the object $a$ is called the \emph{first} entry, and the object $b$ the \emph{second} entry of the pair. \arara\ relies on this concept with the helper \rbox{Pair<A, B>} class, in which \rbox{A} and \rbox{B} denote the component classes, i.e, the types associated to the pair elements. In order to access the pair entries, the class provides two methods:

\begin{description}
\item[\mtbox{first()}\hfill\rrbox{A}] This method, as the name implies, returns the first entry of the ordered pair, as an \rbox{A} object. It is important to observe that, from the MVEL context, as the method constitutes a property accessor (namely, a getter), the parentheses can be safely omitted.

\item[\mtbox{second()}\hfill\rrbox{B}] This method, as the name implies, returns the second entry of the ordered pair, as a \rbox{B} object. It is important to observe that, from the MVEL context, as the method constitutes a property accessor (namely, a getter), the parentheses can be safely omitted.
\end{description}

Keep in mind that the entries in the \rbox{Pair} class, once defined, cannot be modified to other values. The initial values are set during instantiation and, therefore, only entry getters are available to the user during the object life cycle. 
\end{messagebox}

\begin{messagebox}{Status for class loading and instantiation}{araracolour}{\icok}{white}
The class loading and instantiation methods provided by \arara\ typically return a pair composed of an integer value and a class or object reference. This integer value acts as a status of the underlying operation itself and might indicate potential issues. The possible values are:

\vspace{1em}

{\centering
\def\arraystretch{1.5}
\begin{tabular}{lllll}
\rbox[araracolour]{\hphantom{x}0\hphantom{x}} & Successful execution & \hspace{1.5em} &
\rbox[araracolour]{\hphantom{x}3\hphantom{x}} & Class was not found \\
\rbox[araracolour]{\hphantom{x}1\hphantom{x}} & File does not exist & &
\rbox[araracolour]{\hphantom{x}4\hphantom{x}} & Access policy violation \\
\rbox[araracolour]{\hphantom{x}2\hphantom{x}} & File URL is incorrect & &
\rbox[araracolour]{\hphantom{x}5\hphantom{x}} & Instantiation exception
\end{tabular}\par}

\vspace{1.4em}

Please make sure to \emph{always} check the returned integer status when using class loading and instantiation methods in directive and rule contexts. This feature is quite powerful yet tricky and subtle! 
\end{messagebox}

\begin{description}
\item[\mddbox{C}{R}{loadClass(File file, String name)}{Pair<Integer, Class>}] This method loads a class based on the canonical name from the provided \rbox{File} reference and returns an ordered pair containing the status and the class reference itself. The file must contain the Java bytecode, either directly accessible from a \rbox{class} file or packaged inside a \rbox{jar} file. If an exception is raised, this method returns the \rbox{Object} class reference as second entry of the pair.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = loadClass(toFile('mymath.jar'),
         'com.github.cereda.mymath.Arithmetic');
\end{codebox}

\item[\mddbox{C}{R}{loadClass(String reference, String name)}{Pair<Integer, Class>}] This method loads a class based on the canonical name from the provided \rbox{String} reference and returns an ordered pair containing the status and the class reference itself. The file must contain the Java bytecode, either directly accessible from a \rbox{class} file or packaged inside a \rbox{jar} file.  If an exception is raised, this method returns the \rbox{Object} class reference as second entry of the pair.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = loadClass('mymath.jar',
         'com.github.cereda.mymath.Arithmetic');
\end{codebox}

\item[\mddbox{C}{R}{loadObject(File file, String name)}{Pair<Integer, Object>}] This method loads a class based on the canonical name from the provided \rbox{File} reference and returns an ordered pair containing the status and a proper corresponding object instantiation. The file must contain the Java bytecode, either directly accessible from a \rbox{class} file or packaged inside a \rbox{jar} file. If an exception is raised, this method returns an \rbox{Object} object as second entry of the pair.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = loadObject(toFile('mymath.jar'),
         'com.github.cereda.mymath.Trigonometric');
\end{codebox}

\item[\mddbox{C}{R}{loadObject(String reference, String name)}{Pair<Integer, Object>}] This method loads a class based on the canonical name from the provided \rbox{String} reference and returns an ordered pair containing the status and a proper corresponding object instantiation. The file must contain the Java bytecode, either directly accessible from a \rbox{class} file or packaged inside a \rbox{jar} file. If an exception is raised, this method returns an \rbox{Object} object as second entry of the pair.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = loadObject('mymath.jar',
         'com.github.cereda.mymath.Trigonometric');
\end{codebox}
\end{description}

This section presented class loading and instantiation methods which may significantly enhance the expressiveness of rules and directives. However, make sure to use such feature with great care and attention.

\section{Dialog boxes}
\label{sec:dialogboxes}

A \emph{dialog box} is a graphical control element, typically a small window, that communicates information to the user and prompts them for a response. This section introduces UI methods related to such interactions.

\begin{messagebox}{UI elements}{araracolour}{\icok}{white}
The graphical elements are provided by the Swing toolkit from the Java runtime environment. Note that the default look and feel class reference can be modified through a key in the configuration file, as seen in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}. It is important to observe that the methods presented in this section require a graphical interface. If \arara\ is being executed in a headless environment (i.e, an environment with no graphical display available), an exception will be thrown when trying to use such UI methods in either directive or rule contexts.
\end{messagebox}

Each dialog box provided by the UI methods of \arara\ requires the specification of an associated icon. An \emph{icon} is a pictogram displayed on a computer screen in order to help the user quickly identify the message by conveying its meaning through a visual resemblance to a physical object. Our tool features five icons, illustrated below, to be used with dialog boxes. Observe that each icon is associated with a unique integer value which is provided later on to the actual method call. Also, it is worth mentioning that the visual appearance of such icons is based on the underlying Java virtual machine and the current look and feel, so your mileage might vary.

\vspace{1em}

{\centering
\begin{tabularx}{0.8\textwidth}{YYYYY}
\uierror{cyan} &
\uiinfo{cyan} &
\uiwarning{cyan} &
\uiquestion{cyan} &
\uiplain{cyan} \\
{\footnotesize\emph{error}} &
{\footnotesize\emph{information}} &
{\footnotesize\emph{attention}} &
{\footnotesize\emph{question}} &
{\footnotesize\emph{plain}} \\
\rbox[cyan]{\hphantom{ww}1\hphantom{ww}} &
\rbox[cyan]{\hphantom{ww}2\hphantom{ww}} &
\rbox[cyan]{\hphantom{ww}3\hphantom{ww}} &
\rbox[cyan]{\hphantom{ww}4\hphantom{ww}} &
\rbox[cyan]{\hphantom{ww}5\hphantom{ww}}
\end{tabularx}\par}

\vspace{1.4em}

As good practice, make sure to provide descriptive messages to be placed in dialog boxes in order to ease and enhance the user experience. It is also highly advisable to always provide an associated icon, so avoid the plain option whenever possible.

\begin{messagebox}{Message text width}{araracolour}{\icok}{white}
\arara\ sets the default message text width to 250 pixels. Feel free to override this value according to your needs. Please refer to the appropriate method signatures for specifying a new width.
\end{messagebox}

The UI method signatures are followed by a visual representation of the provided dialog box. For the sake of simplicity, each parameter index refers to the associated number in the figure.

\begin{description}
\item[\mdbox{R}{showMessage(int width, int icon, String title, String text)}{void}]\uimethod{messagebox1}

This method shows a message box according to the provided parameters. The dialog box is disposed when the user either presses the confirmation button or closes the window. It is important to observe that \arara\ temporarily interrupts the execution and waits for the dialog box disposal. Also note that the total time includes the idle period as well.

\begin{codebox}{Example}{teal}{\icnote}{white}
showMessage(250, 2, 'My title', 'My message');
\end{codebox}

\item[\mdbox{R}{showMessage(int icon, String title, String text)}{void}]\uimethod{messagebox2}

This method shows a message box according to the provided parameters. The dialog box is disposed when the user either presses the confirmation button or closes the window. It is important to observe that \arara\ temporarily interrupts the execution and waits for the dialog box disposal. Also note that the total time includes the idle period as well.

\begin{codebox}{Example}{teal}{\icnote}{white}
showMessage(2, 'My title', 'My message');
\end{codebox}

\item[\mddbox{C}{R}{\parbox{0.62\textwidth}{showOptions(int width, int icon, String title,\\\hspace*{1em} String text, Object... options)}}{int}]\uimethod{optionbox1}

This method shows a message box according to the provided parameters, including options represented as an array of \rbox{Object} objects. This array is portrayed in the dialog box as a list of buttons. The dialog box is disposed when the user either presses one of the buttons or closes the window. The method returns the natural index of the selected button, starting from \rbox{1}. If no button is pressed (e.g, the window is closed), \rbox{0} is returned. Note that the object array is denoted by a  comma-separated sequence of elements in the actual method call, resulting in a variable number of parameters. It is important to observe that \arara\ temporarily interrupts the execution and waits for the dialog box disposal. Also note that the total time includes the idle period as well.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex if showOptions(250, 4, 'Important!',
% arara: --> 'Do you like ice cream?', 'Yes!', 'No!') == 1
\end{codebox}

\begin{messagebox}{Button orientation}{attentioncolour}{\icattention}{black}
Keep in mind that your window manager might render the button orientation differently than the original arrangement specified in your array of objects. For instance, I had a window manager that rendered the buttons in the reverse order. However, note that the visual appearance should not interfere with the programming logic! The indices shall remain the same, pristine as ever, regardless of the actual rendering. Trust your code, not your eyes.
\end{messagebox}

\item[\mddbox{C}{R}{\parbox{0.49\textwidth}{showOptions(int icon, String title,\\\hspace*{1em} String text, Object... options)}}{int}]\uimethod{optionbox2}

This method shows a message box according to the provided parameters, including options represented as an array of \rbox{Object} objects. This array is portrayed in the dialog box as a list of buttons. The dialog box is disposed when the user either presses one of the buttons or closes the window. The method returns the natural index of the selected button, starting from \rbox{1}. If no button is pressed (e.g, the window is closed), \rbox{0} is returned. Note that the object array is denoted by a  comma-separated sequence of elements in the actual method call, resulting in a variable number of parameters. It is important to observe that \arara\ temporarily interrupts the execution and waits for the dialog box disposal. Also note that the total time includes the idle period as well.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex if showOptions(4, 'Important!',
% arara: --> 'Do you like ice cream?', 'Yes!', 'No!') == 1
\end{codebox}

\item[\mddbox{C}{R}{\parbox{0.62\textwidth}{showDropdown(int width, int icon, String title,\\\hspace*{1em} String text, Object... options)}}{int}]\uimethod{dropdown1}

This method shows a dialog box according to the provided parameters, including options represented as an array of \rbox{Object} objects. This array is portrayed in the dialog box as a dropdown list. The first element from the array is automatically selected. The dialog box is disposed when the user either presses one of the buttons or closes the window. The method returns the natural index of the selected item, starting from \rbox{1}. If the user cancels the dialog or closes the window, \rbox{0} is returned.  Note that the object array is denoted by a comma-separated sequence of elements in the actual method call, resulting in a variable number of parameters. It is important to observe that \arara\ temporarily interrupts the execution and waits for the dialog box disposal. Also note that the total time includes the idle period as well.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex if showDropdown(250, 4, 'Important!',
% arara: --> 'Who deserves the tick?', 'David Carlisle',
% arara: --> 'Enrico Gregorio', 'Joseph Wright',
% arara: --> 'Heiko Oberdiek') == 2
\end{codebox}

\begin{messagebox}{Combo boxes and dropdown lists}{attentioncolour}{\icattention}{black}
According to the \href{https://en.wikipedia.org/wiki/Combo_box}{Wikipedia entry}, a \emph{combo box} is a combination of a dropdown list or list box and a single line editable textbox, allowing the user to either type a value directly or select a value from the list. The term is sometimes used to mean a dropdown list, but in Java, the term is definitely not a synonym! A dropdown list is sometimes clarified with terms such as non-editable combo box to distinguish it from the original definition of a combo box.
\end{messagebox}

\item[\mddbox{C}{R}{\parbox{0.49\textwidth}{showDropdown(int icon, String title,\\\hspace*{1em} String text, Object... options)}}{int}]\uimethod{dropdown2}

This method shows a dialog box according to the provided parameters, including options represented as an array of \rbox{Object} objects. This array is portrayed in the dialog box as a dropdown list. The first element from the array is automatically selected. The dialog box is disposed when the user either presses one of the buttons or closes the window. The method returns the natural index of the selected item, starting from \rbox{1}. If the user cancels the dialog or closes the window, \rbox{0} is returned.  Note that the object array is denoted by a comma-separated sequence of elements in the actual method call, resulting in a variable number of parameters. It is important to observe that \arara\ temporarily interrupts the execution and waits for the dialog box disposal. Also note that the total time includes the idle period as well.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex if showDropdown(4, 'Important!',
% arara: --> 'Who deserves the tick?', 'David Carlisle',
% arara: --> 'Enrico Gregorio', 'Joseph Wright',
% arara: --> 'Heiko Oberdiek') == 2
\end{codebox}

\begin{messagebox}{Swing toolkit}{araracolour}{\icok}{white}
According to the \href{https://en.wikipedia.org/wiki/Swing_(Java)}{Wikipedia entry}, the Swing toolkit was developed to provide a more sophisticated set of GUI components than the earlier  AWT widget system. Swing provides a look and feel that emulates the look and feel of several platforms, and also supports a pluggable look and feel that allows applications to have a look and feel unrelated to the underlying platform. It has more powerful and flexible components than AWT. In addition to familiar components such as buttons, check boxes and labels, Swing provides several advanced components, such as scroll panes, trees, tables, and lists.
\end{messagebox}

\item[\mddbox{C}{R}{showInput(int width, int icon, String title, String text)}{String}]\uimethod{inputbox1}

This method shows an input dialog box according to the provided parameters. The dialog box is disposed when the user either presses one of the buttons or closes the window. The method returns the content of the input text field, as a trimmed \rbox{String} object. If the user cancels the dialog or closes the window, an empty string is returned. It is important to observe that \arara\ temporarily interrupts the execution and waits for the dialog box disposal. Also note that the total time includes the idle period as well.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex if showInput(250, 4, 'Important!',
% arara: --> 'Who wrote arara?') == 'Paulo'
\end{codebox}

\item[\mddbox{C}{R}{showInput(int icon, String title, String text)}{String}]\uimethod{inputbox2}

This method shows an input dialog box according to the provided parameters. The dialog box is disposed when the user either presses one of the buttons or closes the window. The method returns the content of the input text field, as a trimmed \rbox{String} object. If the user cancels the dialog or closes the window, an empty string is returned. It is important to observe that \arara\ temporarily interrupts the execution and waits for the dialog box disposal. Also note that the total time includes the idle period as well.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex if showInput(4, 'Important!',
% arara: --> 'Who wrote arara?') == 'Paulo'
\end{codebox}
\end{description}

The UI methods presented in this section can be used for writing \TeX\ tutorials and assisted compilation workflows based on user interactions, including visual input and feedback through dialog boxes.

\section{Commands}
\label{sec:commands}

\arara\ features the \rbox{Command} object, a new approach for handling system commands based on a high level structure with explicit argument parsing.

\begin{messagebox}{The anatomy of a command}{araracolour}{\icok}{white}
\setlength{\parskip}{1em}
From the user perspective, a \rbox{Command} object is simply a good old list of \rbox{Object} objects, in which the list head (i.e, the first element) is the underlying system command, and the list tail (i.e, the remaining elements), if any, contains the associated command line arguments. For instance:

{\centering
\setlength\tabcolsep{0.2em}
\begin{tabular}{cccc}
{\footnotesize\em head} &
\multicolumn{3}{c}{\footnotesize\em tail (associated command line arguments)} \\
\rbox[cyan]{pdflatex} &
\rbox[araracolour]{{-}-shell-escape} &
\rbox[araracolour]{{-}-synctex=1} &
\rbox[araracolour]{thesis.tex}
\end{tabular}\par}

\vspace{0.4em}

From the previous example, it is important to observe that a potential file name quoting is not necessary. The underlying system command execution library handles the provided arguments accordingly. 

Behind the scenes, however, \arara\ employs a different workflow when constructing a \rbox{Command} object. The tool sets the working directory path for the current command to \abox[araracolour]{USER\_DIR} which is based on the current execution. The working directory path can be explicitly set through specific method calls, described later on in this section.

The list of objects is then completely flattened and all elements are mapped to their string representations through corresponding \mtbox{toString} calls. Finally, the proper \rbox{Command} object is constructed. Keep in mind that, although a command takes a list (or even an array) of objects, which can be of any type, the internal representation is \emph{always} a list of strings.
\end{messagebox}

A list of objects might contain nested lists, i.e, a list within another list. As previously mentioned, \arara\ employs \emph{list flattening} when handling a list of objects during a \rbox{Command} object instantiation. As a means to illustrate this handy feature, consider the following list of integers:

\begin{codebox}{A list with nested lists}{teal}{\icnote}{white}
[ 1, 2, [ 3, 4 ], 5, [ [ 6, 7 ], 8 ], 9, [ [ 10 ] ]
\end{codebox}

Note that the above list of integers contains nested lists. When applying list flattening, \arara\ recursively adds the elements of nested lists to the original list and then removes the nested occurrences. Please refer to the source code for implementation details. The new flattened list is presented as follows.

\begin{codebox}{A flattened list}{teal}{\icnote}{white}
[ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
\end{codebox}

List flattening and string mapping confer expressiveness and flexibility to the \rbox{Command} object construction, as users can virtually use any data type to describe the underlying rule logic and yet obtain a consistent representation.

\begin{description}
\item[\mdbox{R}{getCommand(List<String> elements)}{Command}] This method, as the name implies, returns a \rbox{Command} object according to the provided list of \rbox{String} elements. If the list is empty, the tool will ignore the execution.

\begin{codebox}{Example}{teal}{\icnote}{white}
return getCommand([ 'ls', '-l' ]);
\end{codebox}

\item[\mdbox{R}{getCommand(Object... elements)}{Command}] This method, as the name implies, returns a \rbox{Command} object according to the provided array of \rbox{Object} elements. If the array is empty, the tool will ignore the execution. Note that the object array is denoted by a comma-separated sequence of elements in the actual method call, resulting in a variable number of parameters.

\begin{codebox}{Example}{teal}{\icnote}{white}
return getCommand('pdflatex', '--shell-escape', 'thesis.tex');
\end{codebox}

\item[\mdbox{R}{\parbox{0.62\textwidth}{getCommandWithWorkingDirectory(File directory,\\\hspace*{1em} List<String> elements)}}{Command}] This method, as the name implies, sets the working directory based on the provided \rbox{File} reference and returns a proper \rbox{Command} object according to the provided list of \rbox{String} elements. If the list is empty, the tool will ignore the execution.

\begin{codebox}{Example}{teal}{\icnote}{white}
return getCommandWithWorkingDirectory(toFile('/home/paulo'),
       [ 'ls', '-l' ]);
\end{codebox}

\item[\mdbox{R}{\parbox{0.58\textwidth}{getCommandWithWorkingDirectory(String path,\\\hspace*{1em} List<String> elements)}}{Command}] This method, as the name implies, sets the working directory based on the provided \rbox{String} reference and returns a proper \rbox{Command} object according to the provided list of \rbox{String} elements. If the list is empty, the tool will ignore the execution.

\begin{codebox}{Example}{teal}{\icnote}{white}
return getCommandWithWorkingDirectory('/home/paulo',
       [ 'ls', '-l' ]);
\end{codebox}

\item[\mdbox{R}{\parbox{0.62\textwidth}{getCommandWithWorkingDirectory(File directory,\\\hspace*{1em} Object... elements)}}{Command}] This method, as the name implies, sets the working directory based on the provided \rbox{File} reference and returns a proper \rbox{Command} object according to the provided array of \rbox{Object} elements. If the array is empty, the tool will ignore the execution. Note that the object array is denoted by a comma-separated sequence of elements in the actual method call, resulting in a variable number of parameters.

\begin{codebox}{Example}{teal}{\icnote}{white}
return getCommandWithWorkingDirectory(toFile('/home/paulo'),
       'pdflatex', '--shell-escape', 'thesis.tex');
\end{codebox}

\item[\mdbox{R}{\parbox{0.58\textwidth}{getCommandWithWorkingDirectory(String path,\\\hspace*{1em} Object... elements)}}{Command}] This method, as the name implies, sets the working directory based on the provided \rbox{String} reference and returns a proper \rbox{Command} object according to the provided array of \rbox{Object} elements. If the array is empty, the tool will ignore the execution. Note that the object array is denoted by a comma-separated sequence of elements in the actual method call, resulting in a variable number of parameters.

\begin{codebox}{Example}{teal}{\icnote}{white}
return getCommandWithWorkingDirectory('/home/paulo',
       'pdflatex', '--shell-escape', 'thesis.tex');
\end{codebox}
\end{description}

The methods presented in this section constitute the foundations of underlying system command execution. In particular, whenever possible, it is highly advisable to use \rbox{Command} objects through proper \mtbox{getCommand} method calls, as the plain string approach used in previous versions of our tool is marked as deprecated and will be removed in future versions. 

\section{Others}
\label{sec:others}

This section introduces assorted methods provided by \arara\ as a means to improve the automation itself with expressive rules and enhance the user experience. Such methods are properly described as follows.

\begin{messagebox}{Session}{araracolour}{\icok}{white}
Rules are designed under the \emph{encapsulation} notion, such that the direct access to internal workings of such structures is restricted. However, as a means to support framework awareness, \arara\ provides a mechanism for data sharing across rule contexts, implemented as a \rbox{Session} object. In practical terms, this particular object is a global, persistent map composed of \rbox{String} keys and \rbox{Object} values available throughout the entire execution. The public methods of a session are described as follows:

\begin{description}
\item[\mtbox{put(String key, Object value)}\hfill\rrbox{void}] This method, as the name implies, inserts an object into the session, indexed by the provided key. Observe that, if the session previously contained a mapping for the provided key, the old value is replaced by the specified value.

\item[\mtbox{remove(String key)}\hfill\rrbox{void}] This method, as the name implies, removes  the mapping for the provided key from the session. Be mindful that an attempt to remove a mapping for a nonexistent key will raise an exception.

\item[\mtbox{contains(String key)}\hfill\rrbox{boolean}] This method, as the name implies, returns a boolean value according to whether the session contains a mapping for the provided key. It is highly advisable to use this method before attempting to remove a mapping from the session.

\item[\mtbox{get(String key)}\hfill\rrbox{Object}] This method, as the name implies, returns the object value to which the specified key is mapped. Be mindful that an attempt to return a value for a nonexistent key will raise an exception.

\item[\mtbox{forget()}\hfill\rrbox{void}] This method, as the name implies, removes all of the existing mappings from the session. The session object will be effectively empty after this call returns.
\end{description}

It is important to observe that the \rbox{Session} object provided by our tool follows the \emph{singleton} pattern, i.e, a software design pattern that restricts the instantiation of a class to one object. Therefore, the same session is consistently shared across rule contexts.
\end{messagebox}

\begin{description}
\item[\mdbox{R}{getSession()}{Session}] This method, as the name implies, returns the \rbox{Session} object for data sharing across rule contexts. Keep in mind that a session cannot contain duplicate keys. Each key can map to at most one value.

\begin{codebox}{Example}{teal}{\icnote}{white}
name = getSession().get('name');
\end{codebox}

\item[\mdbox{R}{throwError(String message)}{void}] This method deliberately throws an error to be intercepted later on during execution. Consider using such method for an explicit notification about unexpected or unsought scenarios, e.g, wrong parameter types or values. The raised error has an associated message which is displayed in the terminal and added to the log file.

\begin{codebox}{Example}{teal}{\icnote}{white}
options = 'not a list';
if (!isList(options)) {
    throwError('I was expecting a list.');
}
\end{codebox}

\item[\mdbox{R}{isVerboseMode()}{boolean}] This method, as the name implies, returns a boolean value according to whether \arara\ is being executed in verbose mode, enabled through either the \opbox{{-}verbose} command line option or the corresponding key in the configuration file (detailed in Sections~\ref{sec:options} and~\ref{sec:basicstructure}, respectively). Note that the logical negation of such method indicates whether the tool is being executed in silent mode.

\begin{codebox}{Example}{teal}{\icnote}{white}
verbose = isVerboseMode();
\end{codebox}

\item[\mdbox{R}{isOnPath(String name)}{boolean}] This method, as the name implies, returns a boolean value according to whether the provided \rbox{String} reference representing a command name is reachable from the system path.  For portability reasons, there is no need to provide extensions to Microsoft Windows command names, as \arara\ will look for common patterns. This behaviour is expected and by design. However, be mindful that the search is case sensitive.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = isOnPath('pdftex');
\end{codebox}

\begin{messagebox}{Path inspection}{araracolour}{\icok}{white}
According to the \href{https://en.wikipedia.org/wiki/PATH_(variable)}{Wikipedia entry}, \abox[araracolour]{PATH} is an environment variable on Unix-like operating systems and Microsoft Windows, specifying a set of directories where executable programs are located. \arara\ performs a file search operation based on all directories specified in the system path, filtering files by name (and extensions, when in Microsoft Windows). When an exact match is found, the search is concluded. Notwithstanding the great effort, it is very important to note that there is no guarantee that our tool will be able to correctly reach the command in all scenarios.
\end{messagebox}

\item[\mdbox{R}{unsafelyExecuteSystemCommand(Command command)}{Pair<Integer, String>}] This method, which has a very spooky name, unsafely executes the provided \rbox{Command} reference and returns an ordered pair containing the exit status and the command output. Note that, if an exception is raised during the command execution, \rbox{-99} is assigned as exit status and an empty string is defined as command output. Please make sure to always check the returned integer status when using this method.

\begin{codebox}{Example}{teal}{\icnote}{white}
result = unsafelyExecuteSystemCommand(getCommand('ls'));
\end{codebox}

\begin{messagebox}{Important change in version 5.0}{araracolour}{\icattention}{white}
\textbf{Working directory support} -- \arara\ now executes commands obtained from \rbox{getCommandWithWorkingDirectory} correctly. Previously, the working directory got silently ignored. This makes \arara\ even more powerful but we decided to change this for the sake of consistency.
\end{messagebox}

\begin{messagebox}{Hic sunt leones}{attentioncolour}{\icattention}{black}
Please \emph{do not abuse} this method! Keep in mind that this particular feature is included for very specific scenarios in which the command streams are needed ahead of time for proper decision making.
\end{messagebox}

\item[\mdbox{R}{isSubdirectory(File directory)}{boolean}] This method checks whether the provided \rbox{File} reference is a valid subdirectory under the project hierarchy, return a corresponding boolean value. This is a check to impose a possible restriction in the rule scope, so that users can change down to subdirectories in their projects but not up, outside of the root directory.

\begin{codebox}{Example}{teal}{\icnote}{white}
valid = isSubdirectory(toFile('chapters/'));
\end{codebox}
\end{description}

\begin{messagebox}{Flags and reserved storage in a session}{araracolour}{\icok}{white}
Within a session there are two ``reserved'' namespaces: \verb|arara| and \verb|environment|. The latter is quite intuitive: \arara\ will store the current state of the systems environment variables in its session. You may alter these values in the session storage but they will not be written back to the system configuration. To access an environment variable, you can use its usual name prefixed by \verb|environment:|.

\begin{codebox}{Example}{teal}{\icnote}{white}
path = getSession().get('environment:PATH');
\end{codebox}

The \verb|arara| namespace is a bit different. It provides flags that control \arara s behaviour. Flags are used in rules and may be manipulated by the user. Be aware, that every change in this namespace will result in \arara\ acting like you know what you did. Use this power with care. Currently, there is only one relevant flag: \verb|arara:FILENAME:halt|. This will stop the currently run command execution on the file with the specified file name. The value of this map entry is the exit status you want \arara\ to have. 

\begin{codebox}{Example}{teal}{\icnote}{white}
path = getSession().put('arara:myfile.tex:halt', 42);
\end{codebox}
\end{messagebox}

The methods presented in this section provide interesting features for persistent data sharing, error handling, early command execution, and templating. It is important to note that more classes, objects and methods can be incorporated into \arara\ through class loading and object instantiation, extending the features and enhancing the overall user experience.