nmcli: add -g[et-values] option as a '-m tab -t -f <arg>' shortcut

Quick and easy way to get clean and parsable field values.

3 files changed, 71 insertions, 16 deletions

diff --git a/clients/cli/nmcli.c b/clients/cli/nmcli.c
index 429acf9fbc..6f0edbf012 100644
--- a/clients/cli/nmcli.c
+++ b/clients/cli/nmcli.c
@@ -171,17 +171,18 @@ usage (void)
 	g_printerr (_("Usage: nmcli [OPTIONS] OBJECT { COMMAND | help }\n"
 	              "\n"
 	              "OPTIONS\n"
-	              "  -t[erse]                                   terse output\n"
-	              "  -p[retty]                                  pretty output\n"
-	              "  -m[ode] tabular|multiline                  output mode\n"
-	              "  -c[olors] auto|yes|no                      whether to use colors in output\n"
-	              "  -f[ields] <field1,field2,...>|all|common   specify fields to output\n"
-	              "  -e[scape] yes|no                           escape columns separators in values\n"
-	              "  -a[sk]                                     ask for missing parameters\n"
-	              "  -s[how-secrets]                            allow displaying passwords\n"
-	              "  -w[ait] <seconds>                          set timeout waiting for finishing operations\n"
-	              "  -v[ersion]                                 show program version\n"
-	              "  -h[elp]                                    print this help\n"
+	              "  -t[erse]                                       terse output\n"
+	              "  -p[retty]                                      pretty output\n"
+	              "  -m[ode] tabular|multiline                      output mode\n"
+	              "  -c[olors] auto|yes|no                          whether to use colors in output\n"
+	              "  -f[ields] <field1,field2,...>|all|common       specify fields to output\n"
+	              "  -g[et-values] <field1,field2,...>|all|common   shortcut for -m tabular -t -f\n"
+	              "  -e[scape] yes|no                               escape columns separators in values\n"
+	              "  -a[sk]                                         ask for missing parameters\n"
+	              "  -s[how-secrets]                                allow displaying passwords\n"
+	              "  -w[ait] <seconds>                              set timeout waiting for finishing operations\n"
+	              "  -v[ersion]                                     show program version\n"
+	              "  -h[elp]                                        print this help\n"
 	              "\n"
 	              "OBJECT\n"
 	              "  g[eneral]       NetworkManager's general status and operations\n"
@@ -231,7 +232,7 @@ process_command_line (NmCli *nmc, int argc, char **argv)
 		if (argc == 1 && nmc->complete) {
 			nmc_complete_strings (opt, "--terse", "--pretty", "--mode", "--colors", "--escape",
 			                           "--fields", "--nocheck", "--ask", "--show-secrets",
-			                           "--wait", "--version", "--help", NULL);
+			                           "--get-values", "--wait", "--version", "--help", NULL);
 		}
 
 		if (opt[1] == '-') {
@@ -332,6 +333,21 @@ process_command_line (NmCli *nmc, int argc, char **argv)
 			if (argc == 1 && nmc->complete)
 				complete_fields (argv[0]);
 			nmc->required_fields = g_strdup (argv[0]);
+		} else if (matches (opt, "-get-values")) {
+			if (next_arg (&argc, &argv) != 0) {
+				g_string_printf (nmc->return_text, _("Error: fields for '%s' options are missing."), opt);
+				nmc->return_value = NMC_RESULT_ERROR_USER_INPUT;
+				return FALSE;
+			}
+			if (argc == 1 && nmc->complete)
+				complete_fields (argv[0]);
+			nmc->required_fields = g_strdup (argv[0]);
+			nmc->print_output = NMC_PRINT_TERSE;
+			/* We want fixed tabular mode here, but just set the mode specified and rely on the initialization
+			 * in nmc_init: in this way we allow use of "-m multiline" to swap the output mode also if placed
+			 * before the "-g <field>" option (-g may be still more practical and easy to remember than -t -f).
+			*/
+			nmc->mode_specified = TRUE;
 		} else if (matches (opt, "-nocheck")) {
 			/* ignore for backward compatibility */
 		} else if (matches (opt, "-ask")) {
diff --git a/man/nmcli-examples.xml b/man/nmcli-examples.xml
index 864e650423..0b15f112d8 100644
--- a/man/nmcli-examples.xml
+++ b/man/nmcli-examples.xml
@@ -254,6 +254,25 @@ B,DISPATCH</screen>
       </para>
     </example>
 
+    <example><title>Convenient field values retrieval for scripting</title>
+<screen><prompt>$ </prompt><userinput>nmcli -g ip4.address connection show my-con-eth0</userinput>
+192.168.1.12/24</screen>
+<screen><prompt>$ </prompt><userinput>nmcli -g ip4.address,ip4.dns connection show my-con-eth0</userinput>
+192.168.1.12/24
+192.168.1.1</screen>
+<screen><prompt>$ </prompt><userinput>nmcli -g ip4 connection show my-con-eth0</userinput>
+IP4:192.168.1.12/24:192.168.1.1::192.168.1.1::</screen>
+      <para>
+        This example shows retrieval of ip4 connection field values via the --get-values
+        option. Multiple comma separated fields can be provided: they will be printed one
+        per line. If a whole section is provided instead of a single field, the name of the
+        section will be printed followed by all the related field values on the same line.
+        See also --terse, --mode, --fields and --escape options in <link linkend='nmcli'><citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>
+        manual page for more customized output.
+      </para>
+    </example>
+
+
     <example><title>Escaping colon characters in tabular mode</title>
 <screen><prompt>$ </prompt><userinput>nmcli -t -f general -e yes -m tab dev show eth0</userinput>
 GENERAL:eth0:ethernet:Intel Corporation:82567LM Gigabit Network Connection:
diff --git a/man/nmcli.xml b/man/nmcli.xml
index a2d9223c3f..8ee7914b15 100644
--- a/man/nmcli.xml
+++ b/man/nmcli.xml
@@ -205,10 +205,30 @@
           command. <literal>common</literal> is used to print common field values of
           the command.</para>
 
-          <para>If omitted, default is <literal>common</literal>. The option is
-          mandatory when <option>--terse</option> is used. In this case, generic values
-          <literal>all</literal> and <literal>common</literal> cannot be used. This
-          is to maintain compatibility when new fields are added in the future.</para>
+          <para>If omitted, default is <literal>common</literal>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><group choice='plain'>
+          <arg choice='plain'><option>-g</option></arg>
+          <arg choice='plain'><option>--get-values</option></arg>
+          <group choice='req'>
+            <arg choice='plain' rep='repeat'><replaceable>field1</replaceable>,<replaceable>field2</replaceable></arg>
+            <arg choice='plain'>all</arg>
+            <arg choice='plain'>common</arg>
+          </group>
+        </group></term>
+
+        <listitem>
+          <para>This option is used to print values from specific fields. It is basically
+          a shortcut for <literal>--mode tabular --terse --fields</literal> and is a convenient
+          way to retrieve values for particular fields. The values are printed one per line
+          without headers.</para>
+
+          <para>If a section is specified instead of a field, the section name will be printed
+          followed by colon separated values of the fields belonging to that section, all on
+          the same line.</para>
         </listitem>
       </varlistentry>