Sub-commands

Zuguang Gu ()

2022-08-01

Source: vignettes/sub_commands.Rmd

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.