# Sub-commands

#### Zuguang Gu (z.gu@dkfz.de)

#### 2025-11-28

## A quick example

The following code gives you a quick example of how the sub commands are set. In the function `subCommands()`, the input is in form of a vector, where the elements are grouped by every three. The three elements in every group are

1. name of the sub command,
2. path of the corresponding R script,
3. description of the corresponding sub command.

The following code is in the script called `main.R` which contains dispatch of the sub commands.

    library(GetoptLong)

    subCommands(
        "sub1", "sub1.R",
                "This is the description of sub command 1, which will be a long long long text.",
        "sub2", "sub2.R",
                "This is the description of sub command 2, which will be a long long long text."
    )

Code in `sub1.R`:

    library(GetoptLong)

    GetoptLong("foo=i", "Set value for foo.")

    qqcat("foo is @{foo}\n")

And code in `sub2.R`:

    library(GetoptLong)

    GetoptLong("bar=i", "Set value for bar")

    qqcat("bar is @{bar}\n")

Calling `main.R` with no argument prints the list of sub commands it supports:

    Rscript main.R

    Usage: Rscript main.R [command] [options]

    Commands:
      sub1    This is the description of sub command 1, which will be a long long
              long text.
      sub2    This is the description of sub command 2, which will be a long long
              long text.

When sub command is called, the corresponding R script is invoked. Here all command-line arguments after the sub command `sub1` go to the correspond R script `sub1.R`.

    Rscript main.R sub1 --help

    Usage: Rscript main.R sub1 [options]

    Options:
      --foo, -f integer
        Set value for foo.

      --help, -h
        Print help message and exit.

      --version, -v
        Print version information and exit.

Internally, it actually executes `Rscript sub1.R --help`.

Options in `sub1.R` can be directly set after the sub command:

    Rscript main.R sub1 --foo 10

    foo is 10

## The specification

The specification for sub commands can be set as a vector. The length should be multiples of either 2 or 3.

In the following code, the input of `subCommands()` will be internally put into a three-column matrix filled by rows, where the first column contains sub commands, the second column contains paths of corresponding R scripts, and the third column contains descriptions for sub commands.

    subCommands(
        "sub1", "path/sub1.R", "description 1",
        "sub2", "path/sub2.R", "description 2"
    )

Or in another way:

    subCommands(
        "path/sub1.R", "description 1",
        "path/sub2.R", "description 2"
    )

In this case, the sub commands are taken from the basename of the R script, also removing the suffix names (`.R`).

Whether the arguments are grouped by every 2 elements or 3 elements is automatically detected in `subCommands()`.

## Commands in sections

Sometimes we want to group commands and put them into sections. This can be done by adding a section tag `"-----"` as shown in the following example.

    subCommands(
        "----", "----", "This is section1",
        "sub1", "sub1.R",
              "This is the description of sub command 1, which will be a long long long text.",

        "----", "----", "This is section2",
        "sub2", "sub2.R",
              "This is the description of sub command 2, which will be a long long long text."
    )

    Usage: Rscript main.R [command] [options]

    This is section1
      sub1    This is the description of sub command 1, which will be a long long
              long text.

    This is section2
      sub2    This is the description of sub command 2, which will be a long long
              long text.

## Setting help head and foot

`help_head` adds text before the help message and `help_foot` adds text after the help message.

    subCommands(
        help_head = "This is the head of the help message.",

        "sub1", "sub1.R",
                "This is the description of sub command 1, which will be a long long long text.",
        "sub2", "sub2.R",
                "This is the description of sub command 2, which will be a long long long text.",

        help_foot = "This is the foot of the help message."
    )

    This is the head of the help message.

    Usage: Rscript main.R [command] [options]

    Commands:
      sub1    This is the description of sub command 1, which will be a long long
              long text.
      sub2    This is the description of sub command 2, which will be a long long
              long text.

    This is the foot of the help message.

## Setting with a template

`subCommands()` can be set as a single long text which is a template of the help message. Commands are wrapped in `<>`. The value can be a pair of `<command=script>` or just `<script>`. If it is in a form of `<script>`, the basename without the file suffix is used as the command.

    subCommands(
    "This is the head of the help message.

    Usage: Rscript main.R [command] [options]

    Commands:
      <sub1=sub1.R> This is the description of sub command 1, which will be a long long
              long text.
      <longlonglong=sub2.R> This is the description of sub command 2, which will be a long long
              long text.

    This is the foot of the help message.
    "
    )

    This is the head of the help message.

    Usage: Rscript main.R [command] [options]

    Commands:
      sub1            sub1 This is the description of sub command 1, which will be a
                      long long long text.
      longlonglong    longlonglong This is the description of sub command 2, which
                      will be a long long long text.

    This is the foot of the help message.