diff --git a/gen/youtube3/README.md b/gen/youtube3/README.md index 2608559137c..6027b857c29 100644 --- a/gen/youtube3/README.md +++ b/gen/youtube3/README.md @@ -93,6 +93,7 @@ let mut hub = YouTube::new(hyper::Client::new(), auth); ``` **TODO** Example calls - there should soon be a generator able to do that with proper inputs + ## About error handling ## About Customization/Callbacks diff --git a/gen/youtube3/src/lib.rs b/gen/youtube3/src/lib.rs index d7d54ccd138..a4c27a12502 100644 --- a/gen/youtube3/src/lib.rs +++ b/gen/youtube3/src/lib.rs @@ -92,6 +92,7 @@ //! ``` //! //! **TODO** Example calls - there should soon be a generator able to do that with proper inputs +//! //! ## About error handling //! //! ## About Customization/Callbacks @@ -146,8 +147,8 @@ pub use cmn::{Hub, Resource, Part, ResponseResult, RequestResult, NestedType}; /// // Provide your own `AuthenticatorDelegate` to adjust the way it operates and get feedback about what's going on /// // You probably want to bring in your own `TokenStorage` to persist tokens and retrieve them from storage. /// let auth = Authenticator::new(&secret, DefaultAuthenticatorDelegate, -/// hyper::Client::new(), -/// ::default(), None); +/// hyper::Client::new(), +/// ::default(), None); /// let mut hub = YouTube::new(hyper::Client::new(), auth); /// # } /// ``` diff --git a/src/mako/lib/lib.mako b/src/mako/lib/lib.mako index 60b4e02dd97..c95b994ba98 100644 --- a/src/mako/lib/lib.mako +++ b/src/mako/lib/lib.mako @@ -1,11 +1,13 @@ <%! from util import (activity_split, put_and, md_italic, split_camelcase_s, canonical_type_name, rust_test_fn_invisible, rust_doc_test_norun, rust_doc_comment, markdown_rust_block, - unindent, indent) %>\ + unindent_first_by) %>\ <%namespace name="util" file="util.mako"/>\ ## If rust-doc is True, examples will be made to work for rust doc tests. Otherwise they are set ## for github markdown. -<%def name="docs(c, rust_doc=True)" filter="unindent">\ +############################################################################################### +############################################################################################### +<%def name="docs(c, rust_doc=True)">\ <% # fr == fattest resource, the fatter, the more important, right ? fr = None @@ -17,86 +19,91 @@ resource, activity = activity_split(an) amap.setdefault(resource, list()).append(activity) %>\ - # Features +# Features - Handle the following *Resources* with ease ... +Handle the following *Resources* with ease ... - % for r in sorted(amap.keys()): - * ${split_camelcase_s(r)} (${put_and(md_italic(sorted(amap[r])))}) - % endfor +% for r in sorted(amap.keys()): +* ${split_camelcase_s(r)} (${put_and(md_italic(sorted(amap[r])))}) +% endfor - # Structure of this Library +# Structure of this Library - The API is structured into the following primary items: +The API is structured into the following primary items: - * **Hub** - * a central object to maintain state and allow accessing all *Activities* - * **Resources** - * primary types that you can apply *Activities* to - * a collection of properties and *Parts* - * **Parts** - * a collection of properties - * never directly used in *Activities* - * **Activities** - * operations to apply to *Resources* +* **Hub** + * a central object to maintain state and allow accessing all *Activities* +* **Resources** + * primary types that you can apply *Activities* to + * a collection of properties and *Parts* + * **Parts** + * a collection of properties + * never directly used in *Activities* +* **Activities** + * operations to apply to *Resources* - Generally speaking, you can invoke *Activities* like this: +Generally speaking, you can invoke *Activities* like this: - ```Rust,ignore - let r = hub.resource().activity(...).${api.terms.action}() - ``` +```Rust,ignore +let r = hub.resource().activity(...).${api.terms.action}() +``` - Or specifically ... +Or specifically ... - ```ignore +```ignore % for an, a in c.sta_map[fr.id].iteritems(): <% resource, activity = activity_split(an) %>\ - let r = hub.${resource}().${activity}(...).${api.terms.action}() +let r = hub.${resource}().${activity}(...).${api.terms.action}() % endfor - ``` +``` + +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 `${api.terms.action}()` method performs the actual communication with the server and returns the respective result. - 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 `${api.terms.action}()` method performs the actual communication with the server and returns the respective result. +# Usage (*TODO*) - # Usage (*TODO*) +${'##'} Instantiating the Hub - ${'##'} Instantiating the Hub +${self.hub_usage_example(rust_doc)}\ -${self.hub_usage_example(rust_doc) | indent}\ +**TODO** Example calls - there should soon be a generator able to do that with proper inputs - **TODO** Example calls - there should soon be a generator able to do that with proper inputs - ${'##'} About error handling +${'##'} About error handling - ${'##'} About Customization/Callbacks +${'##'} About Customization/Callbacks - [builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern - [google-go-api]: https://github.com/google/google-api-go-client +[builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern +[google-go-api]: https://github.com/google/google-api-go-client ## Sets up a hub ready for use. You must wrap it into a test function for it to work ## Needs test_prelude. -<%def name="test_hub(hub_type)" filter="unindent">\ - use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage}; - use std::default::Default; - - use ${util.library_name()}::${hub_type}; - - // Get an ApplicationSecret instance by some means. It contains the `client_id` and `client_secret`, - // among other things. - let secret: ApplicationSecret = Default::default(); - // Instantiate the authenticator. It will choose a suitable authentication flow for you, - // unless you replace `None` with the desired Flow - // Provide your own `AuthenticatorDelegate` to adjust the way it operates and get feedback about what's going on - // You probably want to bring in your own `TokenStorage` to persist tokens and retrieve them from storage. - let auth = Authenticator::new(&secret, DefaultAuthenticatorDelegate, - hyper::Client::new(), - ::default(), None); - let mut hub = ${hub_type}::new(hyper::Client::new(), auth);\ +############################################################################################### +############################################################################################### +<%def name="test_hub(hub_type)">\ +use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage}; +use std::default::Default; + +use ${util.library_name()}::${hub_type}; + +// Get an ApplicationSecret instance by some means. It contains the `client_id` and `client_secret`, +// among other things. +let secret: ApplicationSecret = Default::default(); +// Instantiate the authenticator. It will choose a suitable authentication flow for you, +// unless you replace `None` with the desired Flow +// Provide your own `AuthenticatorDelegate` to adjust the way it operates and get feedback about what's going on +// You probably want to bring in your own `TokenStorage` to persist tokens and retrieve them from storage. +let auth = Authenticator::new(&secret, DefaultAuthenticatorDelegate, + hyper::Client::new(), + ::default(), None); +let mut hub = ${hub_type}::new(hyper::Client::new(), auth);\ ## You will still have to set the filter for your comment type - either nothing, or rust_doc_comment ! +############################################################################################### +############################################################################################### <%def name="hub_usage_example(rust_doc=True)">\ <% test_filter = rust_test_fn_invisible @@ -114,11 +121,13 @@ ${self.test_hub(canonical_type_name(canonicalName))}\ -<%def name="license()" filter="unindent">\ - # License - The **${util.library_name()}** library was generated by ${put_and(copyright.authors)}, and is placed - under the *${copyright.license_abbrev}* license. - You can read the full text at the repository's [license file][repo-license]. +############################################################################################### +############################################################################################### +<%def name="license()">\ +# License +The **${util.library_name()}** library was generated by ${put_and(copyright.authors)}, and is placed +under the *${copyright.license_abbrev}* license. +You can read the full text at the repository's [license file][repo-license]. - [repo-license]: ${cargo.repo_base_url + 'LICENSE.md'} +[repo-license]: ${cargo.repo_base_url + 'LICENSE.md'} \ No newline at end of file diff --git a/src/mako/lib/util.py b/src/mako/lib/util.py index 4b6adc3efd0..e9410303385 100644 --- a/src/mako/lib/util.py +++ b/src/mako/lib/util.py @@ -2,7 +2,7 @@ import collections re_linestart = re.compile('^', flags=re.MULTILINE) -re_first_4_spaces = re.compile('^ ', flags=re.MULTILINE) +re_first_4_spaces = re.compile('^ {1,4}', flags=re.MULTILINE) USE_FORMAT = 'use_format_field' TYPE_MAP = {'boolean' : 'bool', @@ -48,6 +48,12 @@ def hash_comment(s): def unindent(s): return re_first_4_spaces.sub('', 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 unindent_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