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@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