fix(CLI): request value cursor handling and docs

* now the cursor will only be set permanently if the -r flag is used in
  'cursor' mode. In 'cursor=value' mode, the cursor change doesn't
  persist among the flags. That way, one can easily distinguish
  between setting the cursor, and setting a field. However,
  '...sublevel.level=value' will still work as it did previously, yet
  the cursor change will not persist.
* Documentation was adjusted to represent the new cursor style.

Fixes #86

src/mako/api/lib/rbuild.mako

@@ -95,6 +95,9 @@ impl${rb_params} ${ThisType} {
     % endfor
     % endif
     pub fn ${mangle_ident(a)}${type_params}(&self${method_args}) -> ${RType}${mb_tparams} {
+        % if part_prop and request_value:
+        let parts = ${mangle_ident(REQUEST_VALUE_PROPERTY_NAME)}.to_parts();
+        % endif
         ${RType} {
             hub: self.hub,
             % for p in required_props:
@@ -102,7 +105,7 @@ impl${rb_params} ${ThisType} {
             % endfor
             ## auto-generate parts from request resources
             % if part_prop and request_value:
-            ${property(part_prop.name)}: ${mangle_ident(REQUEST_VALUE_PROPERTY_NAME)}.to_parts(),
+            ${property(part_prop.name)}: parts,
             % endif
             % for p in optional_props:
             ${property(p.name)}: Default::default(),

src/mako/cli/docs/commands.md.mako

@@ -134,7 +134,9 @@ The method's return value is a byte stream of the downloadable resource.
 % if oprops:
 # Optional Method Properties
 
-You may set the following properties to further configure the call.
+You may set the following properties to further configure the call. Please note that `-${PARAM_FLAG}` is followed by one 
+or more key-value-pairs, and is called like this `-${PARAM_FLAG} k1=v1 k2=v2` even though the listing below repeats the
+`-${PARAM_FLAG}` for completeness.
 
 % for p in sorted(oprops):
 ${self._md_property(p)}
@@ -162,10 +164,12 @@ ${SPLIT_END}
     - ${p.get('description') or NO_DESC | xml_escape ,indent_all_but_first_by(2)}
 </%def>
 
-<%def name="_list_schem_args(schema, cursor_tokens=list())">\
+<%def name="_list_schem_args(schema, cursor_tokens=list(), first_flag=None)">\
 <%
     if len(cursor_tokens) == 0:
         cursor_tokens = [FIELD_SEP]
+    if first_flag is None:
+        first_flag = '-%s ' % STRUCT_FLAG
 
     def cursor_fmt(cursor):
         fndfi = 0 # first non-dot field index
@@ -173,8 +177,7 @@ ${SPLIT_END}
             if v != FIELD_SEP:
                 break
         res = ''.join(cursor[:fndfi]) + FIELD_SEP.join(cursor[fndfi:])
-        if not res.endswith(FIELD_SEP):
-            res += FIELD_SEP
+        res += ' '
         return res
 
     def cursor_arg(field):
@@ -184,12 +187,14 @@ ${SPLIT_END}
             del cursor_tokens[:]
         return prefix + field
 %>\
-% for fn in sorted(schema.fields.keys()):
+% for fni, fn in enumerate(sorted(schema.fields.keys())):
 <% 
-    f = schema.fields[fn] 
+    f = schema.fields[fn]
+    if fni > 0:
+        first_flag = ''
 %>\
 % if isinstance(f, SchemaEntry):
-* **-${STRUCT_FLAG} ${cursor_arg(mangle_subcommand(fn))}=${field_to_value(f)}**
+* **${first_flag}${cursor_arg(mangle_subcommand(fn))}=${field_to_value(f)}**
     - ${f.property.get('description', NO_DESC) | xml_escape, indent_all_but_first_by(2)}
 % if f.container_type == CTYPE_ARRAY:
     - Each invocation of this argument appends the given value to the array.
@@ -200,7 +205,7 @@ ${SPLIT_END}
 <%
     cursor_tokens.append(mangle_subcommand(fn))
 %>\
-${self._list_schem_args(f, cursor_tokens)}
+${self._list_schem_args(f, cursor_tokens, first_flag)}
 <%
     assert not cursor_tokens or cursor_tokens[-1] == FIELD_SEP
     if not cursor_tokens:

src/mako/cli/lib/engine.mako

@@ -382,16 +382,25 @@ if dry_run {
     flatten_schema_fields(request_cli_schema, schema_fields, init_fn_map)
 %>\
 let mut ${request_prop_name} = api::${request_prop_type}::default();
-let mut field_name = FieldCursor::default();
+let mut field_cursor = FieldCursor::default();
 for kvarg in ${SOPT + arg_ident(KEY_VALUE_ARG)}.iter() {
+    let last_errc = err.issues.len();
     let (key, value) = parse_kv_arg(&*kvarg, err, false);
-    if let Err(field_err) = field_name.set(&*key) {
+    let mut temp_cursor = field_cursor.clone();
+    if let Err(field_err) = temp_cursor.set(&*key) {
         err.issues.push(field_err);
     }
+    if value.is_none() {
+        field_cursor = temp_cursor.clone();
+        if err.issues.len() > last_errc {
+            err.issues.remove(last_errc);
+        }
+        continue;
+    }
     % for name in sorted(init_fn_map.keys()):
 ${init_fn_map[name] | indent_by(4)}
     % endfor
-    match &field_name.to_string()[..] {
+    match &temp_cursor.to_string()[..] {
     % for init_call, schema, fe, f in schema_fields:
 <%
     ptype = actual_json_type(f[-1][1], fe.actual_property.type)
@@ -439,7 +448,7 @@ ${opt_suffix}\
             },
         % endfor # each nested field
         _ => {
-            err.issues.push(CLIError::Field(FieldError::Unknown(field_name.to_string())));
+            err.issues.push(CLIError::Field(FieldError::Unknown(temp_cursor.to_string())));
         }
     }
 }

src/rust/cli/cmn.rs

@@ -103,7 +103,7 @@ pub fn parse_kv_arg<'a>(kv: &'a str, err: &mut InvalidOptionsError, for_hashmap:
             let key = &kv[..pos];
             if kv.len() <= pos + 1 {
                 add_err();
-                return (key, None)
+                return (key, Some(""))
             }
             (key, Some(&kv[pos+1..]))
         }