[X2Go-Commits] [x2goserver] 84/99: x2goserver/bin/x2goupdateoptionsstring: document mode selection and extraction mode.

[git-admin at x2go.org]

This is an automated email from the git hooks/post-receive script.

x2go pushed a commit to branch master
in repository x2goserver.

commit 3b08baf4c3a7bf2fa3c2d8be2b73608a830c7b75
Author: Mihai Moldovan <ionic at ionic.de>
Date:   Wed Dec 9 02:16:57 2020 +0100

    x2goserver/bin/x2goupdateoptionsstring: document mode selection and extraction mode.
---
 debian/changelog                       |   2 +
 x2goserver/bin/x2goupdateoptionsstring | 118 ++++++++++++++++++++++++++++++---
 2 files changed, 110 insertions(+), 10 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 63931311..e7c9ca9c 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -358,6 +358,8 @@ x2goserver (4.1.0.4-0x2go1.2) UNRELEASED; urgency=medium
       package names all across the code for consistency.
     - x2goserver/bin/x2goupdateoptionsstring: fix typos in documentation and
       reword misinterpreted-as-options section.
+    - x2goserver/bin/x2goupdateoptionsstring: document mode selection and
+      extraction mode.
   * debian/control:
     + Build-depend upon lsb-release for distro version detection.
   * debian/x2goserver.manpages:
diff --git a/x2goserver/bin/x2goupdateoptionsstring b/x2goserver/bin/x2goupdateoptionsstring
index 68ad7a24..f7c4a2d7 100755
--- a/x2goserver/bin/x2goupdateoptionsstring
+++ b/x2goserver/bin/x2goupdateoptionsstring
@@ -715,7 +715,7 @@ __END__
 
 =head1 NAME
 
-x2goupdateoptionsstring - X2Go Agent Options String Manipulator
+x2goupdateoptionsstring - X2Go Agent Options String Manipulator and Extractor
 
 =head1 SYNOPSIS
 
@@ -725,7 +725,9 @@ x2goupdateoptionsstring - X2Go Agent Options String Manipulator
 
 =item B<x2goupdateoptionsstring> B<--man>
 
-=item B<x2goupdateoptionsstring> [B<--compact>|B<-c>] [B<--debug>|B<-d>] [B<-->] I<options_string> [B<+>]|B<->I<key>[B<=>I<value>] ...
+=item B<x2goupdateoptionsstring> [<B<--mode>|B<-m>>[B<=>| ]B<t>[B<ransform>]|B<-t>] [B<--compact>|B<-c>] [B<--debug>|B<-d>] [B<-->] I<options_string> [B<+>]|B<->I<key>[B<=>I<value>] ...
+
+=item B<x2goupdateoptionsstring> <B<--mode>|B<-m>>[B<=>| ]B<e>[B<xtract>]|B<-e> [B<--debug>|B<-d>] [B<-->] I<options_string> I<key>[B<=>I<value>] ...
 
 =back
 
@@ -739,14 +741,23 @@ characters.
 A workaround for this has been proposed in
 https://github.com/Perl/perl5/issues/18305 .
 
-B<x2goupdateoptionsstring> is a utility for manipulating options strings as
-passed to B<X2Go/NX Agent>.
+B<x2goupdateoptionsstring> is a utility for manipulating and extracting data
+from options strings as passed to B<X2Go/NX Agent>.
 For more information about supported options strings, refer to the L<OPTIONS
 STRINGS section in the X2Go::Server::Agent::NX::Options
 documentation|X2Go::Server::Agent::NX::Options/OPTIONS STRINGS>.
 
-Call it with optional flags, the options string as the first parameter and the
-transformations to be carried out as additional parameters.
+Currently, two modes are supported:
+
+=over
+
+=item 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 L<TRANSFORMATIONS
 section in the X2Go::Server::Agent::NX::Options
@@ -770,6 +781,36 @@ B<->I<key>B<=>I<value>.
 Use the B<--compact> option to minimize the original options string, removing
 duplicated and empty entries.
 
+Assuming no error happened, the resulting options string is written to
+C<stdout>.
+
+=item Extract
+
+Extraction mode must be explicitly requested using the B<-e> or
+<B<--mode>|B<-m>>[B<=>| ]B<e>[B<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
+C<stdout>.
+Each pair will be base64-encoded and, if multiple key-value pairs to extract
+have been provided, delimited via C<pipe> characters (C<|>).
+
+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.
+
+=back
+
 Refer to the L<OPTIONS PARSING section|/OPTIONS PARSING> for a description of
 when and how to terminate options passed to this program.
 
@@ -789,11 +830,44 @@ Prints the manual page and exits.
 
 Enables noisy debug output.
 
+=item B<-t>
+
+Shorthand for B<--mode=transform>.
+
+=item B<-e>
+
+Shorthand for B<--mode=extract>.
+
+=item <B<--mode>|B<-m>>[B<=>| ]I<mode string>
+
+Selects a specific program mode.
+
+Currently, the following mode strings are supported:
+
+=over
+
+=item *
+
+transform
+
+=item *
+
+extract
+
+=back
+
+Mode strings can be abbreviated, as long as the abbreviation is uniquely
+selecting one mode exactly.
+
 =item B<--compact>|B<-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 B<transformation mode>.
+It will be silently ignored in B<extraction mode>, as compaction is a
+pre-requisite and done automatically during extraction.
+
 =back
 
 =head2 OPTIONS PARSING
@@ -802,10 +876,12 @@ You can terminate program options parsing via a standard double-dash (B<-->)
 pseudo-option.
 It is B<highly recommended> to always do so.
 
-If you pass removal transformation operations, passing the options terminator
-is B<mandatory>, even if no actual options are used.
-Otherwise, transformation operations will be interpreted as options to the
-program, which will almost certainly lead to an error.
+If you pass removal transformation operations or an extraction key-value pair
+starts with a dash (B<->), passing the options terminator is B<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 C<-clipboard> as a transformation operation without a
 previous options terminator will be interpreted as the option C<-c>, with the
@@ -818,6 +894,8 @@ transformation operation was supposed to represent.
 
 =head1 EXAMPLES
 
+=head2 TRANSFORMATIONS
+
 For an options string such as
 
  nx/nx,clipboard=both,foo:50
@@ -861,6 +939,26 @@ C<x2goupdateoptionsstring '-c' '--'
 
 =back
 
+=head2 EXTRACTIONS
+
+For an options string such as
+
+ nx/nx,clipboard=both,foo=bar,-=-,,bar=baz,foo=oof:50
+
+=over 2
+
+Calling C<x2goupdateoptionsstring '-e' '--'
+'nx/nx,clipboard=both,foo=bar,-=-,bar=baz,foo=oof,:50' 'foo'> shall return
+
+ Zm9vPW9vZg==
+
+while calling C<x2goupdateoptionsstring '-e' '--'
+'nx/nx,clipboard=both,foo=bar,-=-,bar=baz,foo=oof,:50' 'bar' '' '-'> shall return
+
+ YmFyPWJheg==||LT0t
+
+=back
+
 =head1 AUTHOR
 
 This manual has been written by

--
Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/x2goserver.git