☰

# std/cmdline

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

This module contains system facilities for reading command line parameters.See also:

- parseopt module for command-line parser beyond parseCmdLine proc

# Imports

widestrs, posix

# Procs

    proc commandLineParams(): seq[string] {....raises: [], tags: [ReadIOEffect],
                                            forbids: [].}

  Convenience proc which returns the command line parameters.

  This returns only the parameters. If you want to get the application executable filename, call getAppFilename().

  Availability: On Posix there is no portable way to get the command line from a DLL and thus the proc isn't defined in this environment. You can test for its availability with declared().

  See also:

  - parseopt module
  - parseCmdLine proc
  - paramCount proc
  - paramStr proc
  - getAppFilename proc

  Examples:

      when declared(commandLineParams):
        # Use commandLineParams() here
      else:
        # Do something else!

  Source Edit

    proc paramCount(): int {....tags: [ReadIOEffect], raises: [], forbids: [].}

  Returns the number of command line arguments given to the application.

  Unlike argc in C, if your binary was called without parameters this will return zero. You can query each individual parameter with paramStr proc or retrieve all of them in one go with commandLineParams proc.

  Availability: When generating a dynamic library (see `--app:lib`) on Posix this proc is not defined. Test for availability using declared().

  See also:

  - parseopt module
  - parseCmdLine proc
  - paramStr proc
  - commandLineParams proc

  Examples:

      when declared(paramCount):
        # Use paramCount() here
      else:
        # Do something else!

  Source Edit

    proc paramStr(i: int): string {....tags: [ReadIOEffect], raises: [], forbids: [].}

  Returns the `i`-th command line argument given to the application.

  `i` should be in the range `1..paramCount()`, the `IndexDefect` exception will be raised for invalid values. Instead of iterating over paramCount() with this proc you can call the convenience commandLineParams().

  Similarly to argv in C, it is possible to call `paramStr(0)` but this will return OS specific contents (usually the name of the invoked executable). You should avoid this and call getAppFilename() instead.

  Availability: When generating a dynamic library (see `--app:lib`) on Posix this proc is not defined. Test for availability using declared().

  See also:

  - parseopt module
  - parseCmdLine proc
  - paramCount proc
  - commandLineParams proc
  - getAppFilename proc

  Examples:

      when declared(paramStr):
        # Use paramStr() here
      else:
        # Do something else!

  Source Edit

    proc parseCmdLine(c: string): seq[string] {.noSideEffect, ...gcsafe,
        extern: "nos$1", raises: [], tags: [], forbids: [].}

  Splits a command line into several components.

  Note: This proc is only occasionally useful, better use the parseopt module.

  On Windows, it uses the following parsing rules:

  - Arguments are delimited by white space, which is either a space or a tab.
  - The caret character (^) is not recognized as an escape character or delimiter. The character is handled completely by the command-line parser in the operating system before being passed to the argv array in the program.
  - A string surrounded by double quotation marks ("string") is interpreted as a single argument, regardless of white space contained within. A quoted string can be embedded in an argument.
  - A double quotation mark preceded by a backslash (") is interpreted as a literal double quotation mark character (").
  - Backslashes are interpreted literally, unless they immediately precede a double quotation mark.
  - If an even number of backslashes is followed by a double quotation mark, one backslash is placed in the argv array for every pair of backslashes, and the double quotation mark is interpreted as a string delimiter.
  - If an odd number of backslashes is followed by a double quotation mark, one backslash is placed in the argv array for every pair of backslashes, and the double quotation mark is "escaped" by the remaining backslash, causing a literal double quotation mark (") to be placed in argv.

  On Posix systems, it uses the following parsing rules: Components are separated by whitespace unless the whitespace occurs within `"` or `'` quotes.

  See also:

  - parseopt module
  - paramCount proc
  - paramStr proc
  - commandLineParams proc
  Source Edit