From c004840d5bbb5b5196a68b67f709008d055d496a Mon Sep 17 00:00:00 2001
From: Sebastian Thiel <byronimo@gmail.com>
Date: Sun, 12 Apr 2015 18:46:04 +0200
Subject: [PATCH] docs(CLI): inforamtion about setting structs

For now we just have a 'dum' example, but once we are there, we shall
make the example and documentation based on the actual request value.

This requires some additional work, which fortunately has to be done
in python only.
---
 src/mako/cli/docs/commands.md.mako | 32 +++++++++++++++++++++++++++++-
 src/mako/cli/lib/cli.py            |  2 ++
 src/mako/cli/lib/docopt.mako       |  6 +++---
 3 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/src/mako/cli/docs/commands.md.mako b/src/mako/cli/docs/commands.md.mako
index d02b1f23c7..70974585dc 100644
--- a/src/mako/cli/docs/commands.md.mako
+++ b/src/mako/cli/docs/commands.md.mako
@@ -2,7 +2,7 @@
 <%
     from util import (hash_comment, new_context, method_default_scope, indent_all_but_first_by)
     from cli import (subcommand_md_filename, new_method_context, SPLIT_START, SPLIT_END, pretty, SCOPE_FLAG,
-                     mangle_subcommand, is_request_value_property)
+                     mangle_subcommand, is_request_value_property, FIELD_SEP)
 
     c = new_context(schemas, resources, context.get('methods'))
 %>\
@@ -42,6 +42,36 @@ You can set the scope for this method like this: `${util.program_name()} --${SCO
     - ${p.get('description') or 'No description provided' | indent_all_but_first_by(2)}
 % endfor  # each required property (which is not the request value)
 % endif # have required properties
+% if mc.request_value:
+# Required Request Value
+
+The request value is a data-structure with various fields. Each field may be a simple scalar or another data-structure.
+In the latter case it is advised to set the field-cursor to the data-structure's field to specify values more concisely.
+
+For example, a structure like this:
+```
+"scalar_int": 5,
+"struct": {
+    "scalar_float": 2.4
+    "sub_struct": {
+        "strings": ["baz", "bar"],
+        "mapping": HashMap,
+    }
+}
+"scalar_str": "foo",
+```
+
+can be set completely with the following arguments. Note how the cursor position is adjusted the respective fields:
+```
+-r scalar_int=2 -r struct -r scalar_float=4.2 -r sub_struct -r strings=first -r strings=second -r mapping=key=value -r ${FIELD_SEP} -r scalar_str=other
+```
+
+* The cursor position is always set relative to the current one, unless the field name starts with the '${FIELD_SEP}' character. Fields can be nested such as in `-r f${FIELD_SEP}s${FIELD_SEP}o` .
+* **Lists** are always appended to, in the example, the list at `struct${FIELD_SEP}sub_struct${FIELD_SEP}strings` will have the value `["first", "second"]`.
+* **Mappings** are set using the `key=value` form.
+* You can also set nested fields without setting the cursor explicitly. For example, to set the mapping from the root, you would specify `-r struct${FIELD_SEP}sub_struct${FIELD_SEP}mapping=foo=bar`. In case the cursor is not at the root, you may explicitly drill down from the root using a leading '${FIELD_SEP}' character.
+
+% endif # have request value
 ${SPLIT_END}
 % endfor # each method
 % endfor # each resource
diff --git a/src/mako/cli/lib/cli.py b/src/mako/cli/lib/cli.py
index 42ad102d2d..92a0f0115f 100644
--- a/src/mako/cli/lib/cli.py
+++ b/src/mako/cli/lib/cli.py
@@ -14,6 +14,8 @@ OUTPUT_FLAG = 'o'
 VALUE_ARG = 'v'
 SCOPE_FLAG = 'scope'
 
+FIELD_SEP = '.'
+
 CONFIG_DIR = '~/.google-service-cli'
 
 re_splitters = re.compile(r"%s ([\w\-\.]+)\n(.*?)\n%s" % (SPLIT_START, SPLIT_END), re.MULTILINE|re.DOTALL)
diff --git a/src/mako/cli/lib/docopt.mako b/src/mako/cli/lib/docopt.mako
index cfef9b250c..e68e3e62a1 100644
--- a/src/mako/cli/lib/docopt.mako
+++ b/src/mako/cli/lib/docopt.mako
@@ -2,7 +2,7 @@
 <%!
     from util import (put_and, supports_scopes)
     from cli import (mangle_subcommand, new_method_context, PARAM_FLAG, STRUCT_FLAG, UPLOAD_FLAG, OUTPUT_FLAG, VALUE_ARG,
-                     CONFIG_DIR, SCOPE_FLAG, is_request_value_property)
+                     CONFIG_DIR, SCOPE_FLAG, is_request_value_property, FIELD_SEP)
 
     v_arg = '<%s>' % VALUE_ARG
     file_arg = '<file>'
@@ -63,9 +63,9 @@ Usage:
 Options:
 % if struct_used:
     -${STRUCT_FLAG} ${v_arg}  set request structure field;
-            ${v_arg} supports cursor form 'field[:subfield]...' to 
+            ${v_arg} supports cursor form 'field[${FIELD_SEP}subfield]...' to 
             set the curor for upcoming values and supports the value form
-            'field[:subfield]...=value' to set an actual field.
+            'field[${FIELD_SEP}subfield]...=value' to set an actual field.
 % endif
 % if upload_protocols_used:
     -${UPLOAD_FLAG}  <mode> ${file_arg} ${mime_arg}