feat(setters): properties and setters for mbuilder

This includes descriptions, of course, and generally seems to look
quite neat. For now, we brutally consume all input to own it,
but in future we might be able to put in Borrow to support them all.

Author: Byron

etc/api/shared.yaml

@@ -15,7 +15,7 @@ api:
   base_path: "etc/api"
   terms:
     # how to actually do something with the API
-    action: do
+    action: doit
   templates:
   # all output directories are relative to the one set for the respective API
     - source: README.md

gen/youtube3/README.md

@@ -45,24 +45,24 @@ The API is structured into the following primary items:
 Generally speaking, you can invoke *Activities* like this:
 
 ```Rust,ignore
-let r = hub.resource().activity(...).do()
+let r = hub.resource().activity(...).doit()
 ```
 
 Or specifically ...
 
 ```ignore
-let r = hub.videos().rate(...).do()
-let r = hub.videos().getRating(...).do()
-let r = hub.videos().list(...).do()
-let r = hub.videos().insert(...).do()
-let r = hub.videos().update(...).do()
-let r = hub.videos().delete(...).do()
+let r = hub.videos().rate(...).doit()
+let r = hub.videos().getRating(...).doit()
+let r = hub.videos().list(...).doit()
+let r = hub.videos().insert(...).doit()
+let r = hub.videos().update(...).doit()
+let r = hub.videos().delete(...).doit()
 ```
 
 The `resource()` and `activity(...)` calls create [builders][builder-pattern]. The second one dealing with `Activities` 
 supports various methods to configure the impending operation (not shown here). It is made such that all required arguments have to be 
 specified right away (i.e. `(...)`), whereas all optional ones can be [build up][builder-pattern] as desired.
-The `do()` method performs the actual communication with the server and returns the respective result.
+The `doit()` method performs the actual communication with the server and returns the respective result.
 
 # Usage (*TODO*)
 

gen/youtube3/src/lib.rs

@@ -1,6 +1,6 @@
 <% 
 	from util import (iter_nested_types, new_context, rust_comment, rust_doc_comment,
-                      rust_module_doc_comment, rb_type, hub_type)
+                      rust_module_doc_comment, rb_type, hub_type, mangle_ident)
 	nested_schemas = list(iter_nested_types(schemas))
 
  	c = new_context(resources)
@@ -21,7 +21,6 @@
 ${lib.docs(c)}
 </%block>
 #![feature(core)]
-#![allow(non_snake_case)]
 
 extern crate hyper;
 extern crate "rustc-serialize" as rustc_serialize;
@@ -71,7 +70,7 @@ impl<'a, C, NC, A> ${hub_type}<C, NC, A>
     }
 
     % for resource in sorted(c.rta_map.keys()):
-    pub fn ${resource}(&'a self) -> ${rb_type(resource)}<'a, C, NC, A> {
+    pub fn ${mangle_ident(resource)}(&'a self) -> ${rb_type(resource)}<'a, C, NC, A> {
         ${rb_type(resource)} { hub: &self }
     }
     % endfor

src/mako/lib.rs.mako

@@ -1,6 +1,8 @@
 <%!
 	from util import (put_and, rust_test_fn_invisible, rust_doc_test_norun, rust_doc_comment,
-                      rb_type, mb_type, singular, hub_type)
+                      rb_type, mb_type, singular, hub_type, to_fqan, indent_all_but_first_by,
+                      method_params, activity_rust_type, mangle_ident, activity_input_type, get_word,
+                      split_camelcase_s)
 %>\
 <%namespace name="util" file="util.mako"/>\
 <%namespace name="lib" file="lib.mako"/>\
@@ -9,7 +11,17 @@
 ###############################################################################################
 ###############################################################################################
 <%def name="new(resource, method, c)">\
-<% hub_type_name = hub_type(canonicalName) %>\
+<% 
+	hub_type_name = hub_type(canonicalName)
+	m = c.fqan_map[to_fqan(name, resource, method)]
+	# an identifier for a property. We prefix them to prevent clashes with the setters
+	property = lambda x: '_' + mangle_ident(x)
+	ThisType = mb_type(resource, method) + "<'a, C, NC, A>"
+%>\
+% if 'description' in m:
+${m.description | rust_doc_comment}
+///
+% endif
 /// A builder for the *${method}* method supported by a *${singular(resource)}* resource.
 /// It is not used directly, but through a `${rb_type(resource)}`.
 ///
@@ -33,13 +45,52 @@ ${lib.test_hub(hub_type_name, comments=False)}\
 // mb.do()
 </%block>
 </%block>
-pub struct ${mb_type(resource, method)}<'a, C, NC, A>
+pub struct ${ThisType}
     where NC: 'a,
            C: 'a,
            A: 'a, {
 
-    hub: &'a ${hub_type_name}<C, NC, A>
+    hub: &'a ${hub_type_name}<C, NC, A>,
+% for p in method_params(m):
+    ${property(p.name)}: ${activity_rust_type(p)},
+% endfor
 }
 
-impl<'a, C, NC, A> MethodBuilder for ${mb_type(resource, method)}<'a, C, NC, A> {}
+impl<'a, C, NC, A> MethodBuilder for ${ThisType} {}
+
+impl<'a, C, NC, A> ${ThisType} {
+
+	% if 'description' in m:
+	${m.description | rust_doc_comment, indent_all_but_first_by(1)}
+	///
+	% endif
+	/// TODO: Build actual call
+	pub fn ${api.terms.action}(self) {
+
+	}
+
+% for p in method_params(m):
+<%
+	InType = activity_input_type(p)
+%>\
+	/// Sets the *${split_camelcase_s(p.name)}* ${get_word(p, 'location')}property to the given value.
+	% if p.get('required', False):
+	/// Even though the property as already been set when instantiating this call, 
+	/// we provide this method for API completeness.
+	%endif
+	/// 
+	% if 'description' in p:
+    ${p.description | rust_doc_comment, indent_all_but_first_by(1)}
+	% endif
+	pub fn ${mangle_ident(p.name)}(&mut self, new_value: ${InType}) -> &mut ${ThisType} {
+		% if InType == '&str':
+		self.${property(p.name)} = Some(new_value.to_string());
+		% else:
+		self.${property(p.name)} = Some(new_value.clone());
+		% endif
+		return self;
+	}
+
+% endfor
+}
 </%def>

src/mako/lib/mbuild.mako

@@ -1,6 +1,6 @@
 <%!
 	from util import (put_and, rust_test_fn_invisible, rust_doc_test_norun, rust_doc_comment,
-                      rb_type, singular, hub_type)
+                      rb_type, singular, hub_type, mangle_ident)
 %>\
 <%namespace name="util" file="util.mako"/>\
 <%namespace name="lib" file="lib.mako"/>\
@@ -9,7 +9,10 @@
 ###############################################################################################
 ###############################################################################################
 <%def name="new(resource, c)">\
-<% hub_type_name = hub_type(canonicalName) %>\
+<% 
+	hub_type_name = hub_type(canonicalName) 
+	ThisType = rb_type(resource) + "<'a, C, NC, A>"
+%>\
 /// A builder providing access to all methods supported on *${singular(resource)}* resources.
 /// It is not used directly, but through the `${hub_type_name}` hub.
 ///
@@ -26,16 +29,16 @@ ${lib.test_hub(hub_type_name, comments=False)}\
 // Usually you wouldn't bind this to a variable, but keep calling *MethodBuilders*
 // like ${put_and(sorted('`%s(...)`' % f for f in c.rta_map[resource]))}
 // to build up your call.
-let rb = hub.${resource}();
+let rb = hub.${mangle_ident(resource)}();
 </%block>
 </%block>
-pub struct ${rb_type(resource)}<'a, C, NC, A>
+pub struct ${ThisType}
     where NC: 'a,
            C: 'a,
            A: 'a, {
 
     hub: &'a ${hub_type_name}<C, NC, A>
 }
 
-impl<'a, C, NC, A> ResourceMethodsBuilder for ${rb_type(resource)}<'a, C, NC, A> {}
+impl<'a, C, NC, A> ResourceMethodsBuilder for ${ThisType} {}
 </%def>

src/mako/lib/rbuild.mako

@@ -22,6 +22,7 @@
 DEL_METHOD = 'delete'
 
 NESTED_TYPE_MARKER = 'is_nested'
+SPACES_PER_TAB = 4
 
 # ==============================================================================
 ## @name Filters
@@ -51,9 +52,23 @@ def unindent(s):
 # tabs: 1 tabs is 4 spaces
 def unindent_first_by(tabs):
     def unindent_inner(s):
-        return re.sub("^ {1,%i}" % (tabs*4), '', s)
+        return re_linestart.sub(' ' * tabs * SPACES_PER_TAB, s)
     return unindent_inner
 
+# tabs: 1 tabs is 4 spaces
+def indent_all_but_first_by(tabs):
+    def indent_inner(s):
+        try:
+            i = s.index('\n')
+        except ValueError:
+            f = s
+            p = ''
+        else:
+            f = s[:i+1]
+            p = s[i+1:]
+        return f + re_linestart.sub(' ' * (tabs * SPACES_PER_TAB), p)
+    return indent_inner
+
 # add 4 spaces to the beginning of a line.
 # useful if you have defs embedded in an unindent block - they need to counteract. 
 # It's a bit itchy, but logical
@@ -119,6 +134,10 @@ def split_camelcase_s(s):
     s1 = re.sub('(.)([A-Z][a-z]+)', r'\1 \2', s)
     return re.sub('([a-z0-9])([A-Z])', r'\1 \2', s1).lower()
 
+def camel_to_under(s):
+    s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', s)
+    return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
+
 ## -- End Natural Language Utilities -- @}
 
 
@@ -137,6 +156,7 @@ def nested_type_name(sn, pn):
 
 # Make properties which are reserved keywords usable
 def mangle_ident(n):
+    n = camel_to_under(n)
     if n == 'type':
         return n + '_'
     return n
@@ -193,6 +213,14 @@ def is_nested_type_property(t):
 def is_nested_type(s):
     return NESTED_TYPE_MARKER in s
 
+# convert a rust-type to something that would be taken as input of a function
+# even though our storage type is different
+def activity_input_type(p):
+    n = activity_rust_type(p, allow_optionals=False)
+    if n == 'String':
+        n = 'str'
+    return '&%s' % n
+
 # return an iterator yielding fake-schemas that identify a nested type
 def iter_nested_types(schemas):
     for s in schemas.values():
@@ -243,6 +271,14 @@ def activity_split(fqan):
     assert len(t) == 3
     return t[1:]
 
+# Shorthand to get a type from parameters of activities
+def activity_rust_type(p, allow_optionals=True):
+    return to_rust_type(None, p.name, p, allow_optionals=allow_optionals)
+
+# the inverse of activity-split, but needs to know the 'name' of the API
+def to_fqan(name, resource, method):
+    return '%s.%s.%s' % (name, resource, method)
+
 # videos -> Video
 def activity_name_to_type_name(an):
     return an.capitalize()[:-1]
@@ -251,6 +287,33 @@ def activity_name_to_type_name(an):
 def iter_acitivities(c):
     return ((activity_split(an) + [a]) for an, a in c.fqan_map.iteritems())
 
+# return a list of parameter structures of all params of the given method dict
+# apply a prune filter to restrict the set of returned parameters.
+# The order will always be: partOrder + alpha
+def method_params(m, required=None, location=None):
+    res = list()
+    po = m.get('parameterOrder', [])
+    for pn, p in m.parameters.iteritems():
+        if required is not None and p.get('required', False) != required:
+            continue
+        if location is not None and p.get('location', '') != location:
+            continue
+        np = p.copy()
+        np['name'] = pn
+        try:
+            # po = ['part', 'foo']
+            # part_prio = 2 - 0 = 2
+            # foo_prio = 2 - 1 = 1
+            # default = 0
+            prio = len(po) - po.index(pn)
+        except ValueError:
+            prio = 0
+        np['priority'] = prio
+        res.append(np)
+    # end for each parameter
+    return sorted(res, key=lambda p: (p.priority, p.name), reverse=True)
+
+
 ## -- End Activity Utilities -- @}
 
 
@@ -322,3 +385,14 @@ def mb_type(r, m):
 
 def hub_type(canonicalName):
     return canonical_type_name(canonicalName)
+
+# return e + d[n] + e + ' ' or ''
+def get_word(d, n, e = ''):
+    if n in d:
+        v = e + d[n] + e
+        if not v.endswith(' '):
+            v += ' '
+        return v
+    else:
+        return ''
+