From e96260bacc959aee2d3baa1353d48087637f3df9 Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Wed, 4 Mar 2015 12:03:31 +0100 Subject: [PATCH] feat(visuals): defs are now more readable This works with a new `indent` and `unindent` filters respectively. There are a few things to consider, but I have understood how it works and can handle it. There is some overhead just to give me nicer visuals ... might choose a different route, like annotations. --- gen/youtube3/README.md | 1 - gen/youtube3/src/lib.rs | 5 +- src/mako/lib/lib.mako | 130 ++++++++++++++++++++-------------------- src/mako/lib/util.mako | 6 +- src/mako/lib/util.py | 11 ++++ 5 files changed, 80 insertions(+), 73 deletions(-) diff --git a/gen/youtube3/README.md b/gen/youtube3/README.md index eeed44c7769..2608559137c 100644 --- a/gen/youtube3/README.md +++ b/gen/youtube3/README.md @@ -100,7 +100,6 @@ let mut hub = YouTube::new(hyper::Client::new(), auth); [builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern [google-go-api]: https://github.com/google/google-api-go-client - # License The **youtube3** library was generated by Sebastian Thiel, and is placed under the *MIT* license. diff --git a/gen/youtube3/src/lib.rs b/gen/youtube3/src/lib.rs index 685297a4b21..d7d54ccd138 100644 --- a/gen/youtube3/src/lib.rs +++ b/gen/youtube3/src/lib.rs @@ -100,7 +100,6 @@ //! [google-go-api]: https://github.com/google/google-api-go-client //! //! -//! #![feature(core)] #![allow(non_snake_case)] @@ -147,8 +146,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 b2d6eec2097..60b4e02dd97 100644 --- a/src/mako/lib/lib.mako +++ b/src/mako/lib/lib.mako @@ -1,10 +1,11 @@ <%! 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) %>\ + rust_test_fn_invisible, rust_doc_test_norun, rust_doc_comment, markdown_rust_block, + unindent, indent) %>\ <%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)">\ +<%def name="docs(c, rust_doc=True)" filter="unindent">\ <% # fr == fattest resource, the fatter, the more important, right ? fr = None @@ -16,86 +17,83 @@ 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}() +<% resource, activity = activity_split(an) %>\ + 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. + ``` -# Usage (*TODO*) + 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. -${'##'} Instantiating the Hub + # Usage (*TODO*) -${self.hub_usage_example(rust_doc)}\ + ${'##'} Instantiating the Hub -**TODO** Example calls - there should soon be a generator able to do that with proper inputs -${'##'} About error handling +${self.hub_usage_example(rust_doc) | indent}\ -${'##'} About Customization/Callbacks + **TODO** Example calls - there should soon be a generator able to do that with proper inputs + ${'##'} About error handling -[builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern -[google-go-api]: https://github.com/google/google-api-go-client + ${'##'} About Customization/Callbacks + [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)">\ -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)" 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);\ ## You will still have to set the filter for your comment type - either nothing, or rust_doc_comment ! @@ -116,11 +114,11 @@ ${self.test_hub(canonical_type_name(canonicalName))}\ -<%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]. +<%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]. -[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.mako b/src/mako/lib/util.mako index bc4e2bcda99..2c0a2635dc8 100644 --- a/src/mako/lib/util.mako +++ b/src/mako/lib/util.mako @@ -9,17 +9,17 @@ DO NOT EDIT !\ ## This will only work within a substitution, not within python code -<%def name="to_api_version(v)">\ +<%def name="to_api_version(v)" buffered="True">\ <% assert len(v) >= 2 and v[0] == 'v'%>\ ## convert it once to int, just to be sure it is an int ${v[1:]}\ -<%def name="repository_url()">\ +<%def name="repository_url()" buffered="True">\ ${cargo.repo_base_url}/${OUTPUT_DIR}\ -<%def name="library_name()">\ +<%def name="library_name()" buffered="True">\ ${util.library_name(name, version)}\ diff --git a/src/mako/lib/util.py b/src/mako/lib/util.py index 57295457c52..4b6adc3efd0 100644 --- a/src/mako/lib/util.py +++ b/src/mako/lib/util.py @@ -2,6 +2,7 @@ import collections re_linestart = re.compile('^', flags=re.MULTILINE) +re_first_4_spaces = re.compile('^ ', flags=re.MULTILINE) USE_FORMAT = 'use_format_field' TYPE_MAP = {'boolean' : 'bool', @@ -43,6 +44,16 @@ def rust_comment(s): def hash_comment(s): return re_linestart.sub('# ', s) +# remove the first indentation (must be spaces !) +def unindent(s): + return re_first_4_spaces.sub('', s) + +# 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 +def indent(s): + return re_linestart.sub(' ', s) + # return s, with trailing newline def trailing_newline(s): if not s.endswith('\n'):