%job, %j

Using a Job File with CSVfox Commands

Description

A %job command denotes a file which in turn contains some CSVfox command line parameters.

A job file is a plain text file. Each line contains exactly one CSVfox command. So the commands will be read from the job file line by line.
They will be processed in order, as if they were placed in the command line at the position the %job command was called.

Indentation, empty lines and comments

Prepending one or more whitespaces are removed from each line of the job file. Trailing spaces are part of the command.
Empty lines are ignored and skipped.
Comment lines start with a hash, followed by a whitespace: "# ". They are also being ignored and skipped.

Advantages over directly use on command line

Moving commands into a file allows better clarity, reuse in different constellations, and it saves the quoting of spaces embedded in the parameter.
Especially for a very long sequence of command line parameters, or a complex ±regex or ±if command, which may contain many brackets and special characters that may become also interpreted and obfuscated by the batch command processor, storing the commands neatly in a parameter file can be helpful.
In every shell there are also various control characters and wildcard mechanism, as well as forwarding and redirection signs, that may interfere with CSVfox commands; these effects can also completely avoided by using a job file.

Pattern

%j=filename
%job=filename
%job/encoding=filename

The %job command can be specified alone or between other csvfox commands.
Multiple %job commands are possible on the same command line. %job files can even be nested.
The character set used in the parameter file can be optionally specified using the "/" option.

In the %job file, each line contains one argument that otherwise would have been a program parameter. Every blank space is part of the expression, so included and trailing whitespaces must be carefully avoided, if they are not intended part of the command expression.
Preceding whitespaces are ignored and can be used for better visual structuring of the file.

On the other hand, any enclosing of commands, expressions, field names containing blank spaces, is not necessary, because they are not splitted automatically at whitespace.

A %job file can have any supported encoding, so it overcomes any restricting or command line character sets. This is especially important for Windows, as in Linux or MacOS an UTF-8 shell is standard which implies only few character restrictions.

Imagine the command line sequence:

csvfox infile.csv +delim=, -delim=; -set[a]=([*]+20%) "my output file.csv"

You can put all of the command line parameters into one file "changedelimiters.txt":

changedelimiters.txt

# the input csv file infile.csv # change csv delimiters from comma to semicolon +delim=, -delim=; # increase field [a] by 20 percent -set[a]=([*]+20%) # the output csv file my output file.csv

And from now on, you can simply call:

csvfox %job=changedelimiters.txt

See how using quote signs for enclosing whitespace characters is not necessary anymore, like it was before on the command line.

You can place all or only some of the required parameters into a %job file. This way it is possible to prepare some building blocks that can be used frequently.

Usage Examples

csvfox infile.csv %job=us_to_german.txt outfile.csv: us_to_german.txt
# reformat from ASCII to windows +delim=, +encoding=ASCII -delim=; -encoding=Windows-1252 -regex[Price]=\d\.\d/\1,\2
The %job file us_to_german.txt contains a set of conversions that can be made to better fit a CSV file that follows US customs to the German locale (on a legacy Windows PC). It changes the CSV delimiter from comma to semicolon, the encoding from ASCII to Windows-1252, and replaces the decimal dot in the field "Price" with a decimal comma.
The file is here being used for modifying infile.csv to outfile.csv.
csvfox infile.csv %job/UTF-8=us_to_german.txt outfile.csv: Reads the commands from us_to_german.txt explicitly in UTF-8 format instead of the platform-specific default format, and uses them for modifying infile.csv to outfile.csv.
csvfox infile.csv %job=us_to_german.txt -rename[Price]=[Amount] -columns=[3]-[6] outfile.csv: Reads the commands from us_to_german.txt again, and uses them for modification from infile.csv to outfile.csv.
And there additional commands to execute, as the field "Price" will have to be renamed to "Amount" in outfile.csv, and the output file shall only contain the fields with numbers 3 to 6.