# ubelt.util_arg module

Simple ways to interact with the commandline without defining a full blown CLI. These are usually used for developer hacks. Any real interface should probably be defined using `argparse`, `click`, or `scriptconfig`. Be sure to ignore unknown arguments if you use them in conjunction with these functions.

The `argflag()` function checks if a boolean `--flag` style CLI argument exists on the command line.

The `argval()` function returns the value of a `--key=value` style CLI argument.

ubelt.util_arg.argval(key, default=NoParam, argv=None)

  Get the value of a keyword argument specified on the command line.

  Values can be specified as `<key> <value>` or `<key>=<value>`

  The use-case for this function is to add hidden command line feature where a developer can pass in a special value. This can be used to prototype a command line interface, provide an easter egg, or add some other command line parsing that wont be exposed in CLI help docs.

  Parameters:

    - key (str | Tuple[str, …]) – string or tuple of strings. Each key should be prefixed with two hyphens (i.e. `--`)

    - default (Any | NoParamType) – a value to return if not specified.

    - argv (List[str] | None) – The command line arguments to parse. If unspecified, uses `sys.argv` directly.

  Returns:

    value - the value specified after the key. It they key is specified multiple times, then the first value is returned.

  Return type:

    str | Any

  Todo

  - [x] Can we handle the case where the value is a list of long paths? - No

  - [ ] Should we default the first or last specified instance of the flag.

  CommandLine

      xdoctest -m ubelt.util_arg argval:0
      xdoctest -m ubelt.util_arg argval:0 --devval
      xdoctest -m ubelt.util_arg argval:0 --devval=1
      xdoctest -m ubelt.util_arg argval:0 --devval=2
      xdoctest -m ubelt.util_arg argval:0 --devval 3
      xdoctest -m ubelt.util_arg argval:0 --devval "4 5 6"

  Example

      >>> # Everyday usage of this function might look like this where
      >>> import ubelt as ub
      >>> # grab a key/value pair if is given on the command line
      >>> value = ub.argval('--devval', default='1')
      >>> print('Checking if the hidden CLI key/value pair is given')
      >>> if value != '1':
      >>>     print(ub.color_text(
      >>>         'A hidden developer secret: {!r}'.format(value), 'yellow'))
      >>> print('Pass the hidden CLI key/value pair to see a secret message')

  Example

      >>> import ubelt as ub
      >>> argv = ['--ans', '42', '--quest=the grail', '--ans=6', '--bad']
      >>> assert ub.argval('--spam', argv=argv) == ub.NoParam
      >>> assert ub.argval('--quest', argv=argv) == 'the grail'
      >>> assert ub.argval('--ans', argv=argv) == '42'
      >>> assert ub.argval('--bad', argv=argv) == ub.NoParam
      >>> assert ub.argval(('--bad', '--bar'), argv=argv) == ub.NoParam

  Example

      >>> # Test fix for GH Issue #41
      >>> import ubelt as ub
      >>> argv = ['--path=/path/with/k=3']
      >>> ub.argval('--path', argv=argv) == '/path/with/k=3'

ubelt.util_arg.argflag(key, argv=None)

  Determines if a key is specified on the command line.

  This is a functional alternative to `key in sys.argv`, but it also allows for multiple aliases of the same flag to be specified.

  Parameters:

    - key (str | Tuple[str, …]) – string or tuple of strings. Each key should be prefixed with two hyphens (i.e. `--`).

    - argv (List[str] | None) – The command line arguments to parse. If unspecified, uses `sys.argv` directly.

  Returns:

    flag - True if the key (or any of the keys) was specified

  Return type:

    bool

  CommandLine

      xdoctest -m ubelt.util_arg argflag:0
      xdoctest -m ubelt.util_arg argflag:0 --devflag
      xdoctest -m ubelt.util_arg argflag:0 -df
      xdoctest -m ubelt.util_arg argflag:0 --devflag2
      xdoctest -m ubelt.util_arg argflag:0 -df2

  Example

      >>> # Everyday usage of this function might look like this
      >>> import ubelt as ub
      >>> # Check if either of these strings are in sys.argv
      >>> flag = ub.argflag(('-df', '--devflag'))
      >>> if flag:
      >>>     print(ub.color_text(
      >>>         'A hidden developer flag was given!', 'blue'))
      >>> print('Pass the hidden CLI flag to see a secret message')

  Example

      >>> import ubelt as ub
      >>> argv = ['--spam', '--eggs', 'foo']
      >>> assert ub.argflag('--eggs', argv=argv) is True
      >>> assert ub.argflag('--ans', argv=argv) is False
      >>> assert ub.argflag('foo', argv=argv) is True
      >>> assert ub.argflag(('bar', '--spam'), argv=argv) is True