File

A file type argument has a string value that points to a file or folder path.

Example:

arguments:
  - name: --input_csv
    type: file
    must_exist: true
    description: CSV file to read contents from
    alternatives: ["-i"]

alternatives

Type: String / List of String

Default: Empty

List of alternative format variations for this argument.

create_parent

Type: Boolean

Default: True

If the output filename is a path and it does not exist, create it before executing the script (only for direction: output).

Example:

- name: --my_file
  type: file
  direction: output
  create_parent: true

default

Type: Path / List of Path

Default: Empty

The default value when no argument value is provided. This will not work if the required property is enabled.

Example:

- name: --my_file
  type: file
  default: data.csv

description

Type: String

Default: Empty

A description of the argument. This is only used for documentation. Multiline descriptions are supported.

Example:

description: |
  A (multiline) description of the purpose of
  this argument.

direction

Type: Direction

Default: Input

Makes this argument an input or an output, as in does the file/folder needs to be read or written. input by default.

Example:

- name: --my_output_file
  type: file
  direction: output

example

Type: Path / List of Path

Default: Empty

An example value for this argument. If no default property was specified, this will be used for that purpose.

Example:

- name: --my_file
  type: file
  example: data.csv

info

Type: Json

Default: Empty

Structured information. Can be any shape: a string, vector, map or even nested map.

Example:

info:
  category: cat1
  labels: [one, two, three]

label

Type: String

Default: Empty

A clean version of the argument’s name. This is only used for documentation.

Example:

label: "My argument"

multiple

Type: Boolean

Default: False

Allow for multiple values (false by default).

For input arguments, this will be treated as a list of values. For example, values can be passed using the delimiter --foo=1:2:3 or by providing the same argument multiple times --foo 1 --foo 2. You can use a custom delimiter by using the multiple_sep property.

For output file arguments, the passed value needs to contain a wildcard. For example, --foo 'foo_*.txt' will be treated as a list of files that match the pattern. Note that in Bash, the wildcard will need to be in quotes ("foo_*.txt" or 'foo_*.txt') or else Bash will automatically attempt to expand the expression.

Other output arguments (e.g. integer, double, …) are not supported yet.

Examples:

- name: --my_files
  type: file
  multiple: true

Here’s an example of how to use this:

my_component --my_files=firstFile.csv:anotherFile.csv:yetAnother.csv

multiple_sep

Type: String

Default: ;

The delimiter character for providing multiple values. : by default.

Examples:

- name: --my_files
  type: file
  multiple: true
  multiple_sep: ";"

Here’s an example of how to use this:

my_component --my_files=firstFile.csv,anotherFile.csv,yetAnother.csv

must_exist

Type: Boolean

Default: True

Checks whether the file or folder exists. For input files, this check will happen before the execution of the script, while for output files the check will happen afterwards.

Example:

- name: --my_file
  type: file
  must_exist: true

name

Type: String

The name of the argument. Can be in the formats --foo, -f or foo. The number of dashes determines how values can be passed:

• --foo is a long option, which can be passed with executable_name --foo=value or executable_name --foo value
• -f is a short option, which can be passed with executable_name -f value
• foo is an argument, which can be passed with executable_name value

required

Type: Boolean

Default: False

Make the value for this argument required. If set to true, an error will be produced if no value was provided. false by default.

Example:

- name: --my_file
  type: file
  required: true

summary

Type: String

Default: Empty

A one-sentence summary of the argument. This is only used for documentation.

Example:

summary: "This argument sets XYZ."

type

Type: String

Specifies the type of the argument.