NAME

       x2gooptionsstring - X2Go Agent Options String Manipulator and Extractor

SYNOPSIS

       x2gooptionsstring --help|-h|-?
       x2gooptionsstring --man
       x2gooptionsstring [<--mode|-m><=| >t[ransform]|-t] [--compact|-c] [--base64|-b]
       [--debug|-d] [--] options_string [+]|-key[=value] ...
       x2gooptionsstring <--mode|-m><=| >e[xtract]|-e [--base64|-b] [--debug|-d] [--]
       options_string key[=value] ...

DESCRIPTION

       x2gooptionsstring is a utility for manipulating and extracting data from options strings
       as passed to X2Go/NX Agent.  For more information about supported options strings, refer
       to the OPTIONS STRINGS section in the X2Go::Server::Agent::NX::Options documentation.

       For full support of options string, which are allowed (but not recommended) to include
       binary data, the special --base64|-b switch is supported.  If given, all arguments other
       than flags must be base64-encoded (making it possible to pass binary data via shells, for
       instance).  The program's output, minus potentially debugging messages, will also be
       base64-encoded.

       Currently, two modes are supported:

       Transform (default)
           Transformation mode is enabled by default if no mode has been explicitly selected.

           Call this program with optional flags, the options string as the first parameter and
           the transformations to be carried out as additional parameters.  At least one
           additional parameter (i.e., a transformation) must be provided.  Transformations are
           described here briefly, but also in the TRANSFORMATIONS section in the
           X2Go::Server::Agent::NX::Options documentation.

           It can either add, remove or replace components.

           To add or replace a component, pass key[=value] or +key[=value] as a parameter.  The
           latter syntax is useful if key starts with a dash and would therefore be interpreted
           as a removal operation.  If the options string does not include a key key, it will be
           appended to the end of the options string.  If it already exists, either with no value
           or a different value, the component will be replaced with the provided value.

           To fully remove a component, pass -key.  To only remove it if it is set to a specific
           value, pass -key=value.

           Use the --compact option to minimize the original options string, removing duplicated
           and empty entries.

           Assuming no error happened, the resulting options string is written to stdout.

       Extract
           Extraction mode must be explicitly requested using the -e or <--mode|-m><=| >e[xtract]
           flags.

           Call this program with optional flags, the options string as the first parameter and
           key-value pairs to be extracted as additional parameters.  At least one additional
           parameter (i.e., a key-value pair to extract) must be provided.

           A degenerated key-value pair without an explicit value can be used to test for the
           existence of a key and extract its value at the same time.

           A full, proper key-value pair can be used to test for the existence of a key-value
           pair exactly as provided.

           Assuming no error happened, the extracted key-value pairs will be written to stdout.
           Each pair will be base64-encoded and, if multiple key-value pairs to extract have been
           provided, delimited via pipe characters ("|").

           Key-value pairs which haven't been found in the original options string, as well as
           potentially an empty key-value pair, will be represented as empty fields.

       Refer to the OPTIONS PARSING section for a description of when and how to terminate
       options passed to this program.

OPTIONS

       --help|-?|-h
               Print a brief help message and exits.

       --man   Prints the manual page and exits.

       --debug|-d
               Enables noisy debug output.

       -t      Shorthand for --mode=transform.

       -e      Shorthand for --mode=extract.

       <--mode|-m><=| >mode string
               Selects a specific program mode.

               Currently, the following mode strings are supported:

               •   transform

               •   extract

               Mode strings can be abbreviated, as long as the abbreviation is uniquely selecting
               one mode exactly.

       --compact|-c
               Remove duplicate and empty entries after the initial parsing.  The order of
               arguments is preserved in a first-seen fashion.

               This option is only available in transformation mode.  It will be silently ignored
               in extraction mode, as compaction is a pre-requisite and done automatically during
               extraction.

       --base64|-b
               Enable a special full base64 mode.

               Any binary data can be given and output by this program in this mode, even when
               operating on a shell.

               Input parameters must always be provided encoded in base64 form.

               Likewise, the program will always output data encoded in a base64 form.  Since
               key-value pairs returned in extraction mode are already base64-encoded and
               delimited with a character that is not legal in the base64 encoding, this flag
               does not modify the extraction's mode output (i.e., you will not have to decode
               the output data twice).

   OPTIONS PARSING
       You can terminate program options parsing via a standard double-dash (--) pseudo-option.
       It is highly recommended to always do so.

       If you pass removal transformation operations or an extraction key-value pair starts with
       a dash (-), passing the options terminator is mandatory, even if no actual options are
       used.  Otherwise, transformation operations or extraction key-value pairs will be
       interpreted as options to the program, which will almost certainly lead to an error.

       For example, passing "-clipboard" as a transformation operation without a previous options
       terminator will be interpreted as the option "-c", with the rest of the string modified
       into "-lipboard".  Since this program does not accept an option called "-l", it will
       terminate with an error.  Even if the program does not terminate with an error due to an
       unknown option being supplied, a degradation into options is certainly not what the
       original transformation operation was supposed to represent.

EXAMPLES

   TRANSFORMATIONS
       For an options string such as

        nx/nx,clipboard=both,foo:50

         calling x2gooptionsstring '--' 'nx/nx,clipboard=both,foo:50' '-clipboard' shall return

          nx/nx,foo:50

         while calling x2gooptionsstring '--' 'nx/nx,clipboard=both,foo:50' '-clipboard=server'
         shall return

          nx/nx,clipboard=both,foo:50

         Calling "x2gooptionsstring '--' 'nx/nx,clipboard=both,foo:50' 'bar'" shall return

          nx/nx,clipboard=both,foo,bar:50

         and calling x2gooptionsstring '--' 'nx/nx,clipboard=both,foo:50' '+-bar' 'foo=gulp'
         '-clipboard=client' shall return

          nx/nx,clipboard=both,foo=gulp,-bar:50

       For an options string such as

        nx/nx,clipboard=both,foo=bar,bar=baz,foo=oof:50

         you can get a compacted version by cheating a bit and providing a transformation which
         will certainly be a no-operation using x2gooptionsstring '-c' '--'
         'nx/nx,clipboard=both,foo=bar,bar=baz,,foo=oof,:50' '-', which shall return

          nx/nx,clipboard=both,foo=oof,bar=baz:50

   EXTRACTIONS
       For an options string such as

        nx/nx,clipboard=both,foo=bar,-=-,,bar=baz,foo=oof:50

         Calling x2gooptionsstring '-e' '--'
         'nx/nx,clipboard=both,foo=bar,-=-,bar=baz,foo=oof,:50' 'foo' shall return

          Zm9vPW9vZg==

         while calling x2gooptionsstring '-e' '--'
         'nx/nx,clipboard=both,foo=bar,-=-,bar=baz,foo=oof,:50' 'bar' '' 'clipboard=none' '-'
         shall return

          YmFyPWJheg==|||LT0t

AUTHOR

       This manual has been written by Mihai Moldovan <ionic@ionic.de> <mailto:ionic@ionic.de>
       for the X2Go project (<https://www.x2go.org>).