Skip to content

Commit

Permalink
fix(visuals): using visual markers now
Browse files Browse the repository at this point in the history 
Makes everything evaluate faster, and is good enough as well.
Besides, you don't have to think about whitespace too much, keeping
things simpler is usually better
  • Loading branch information
@Byron
Byron committed Mar 4, 2015
1 parent e96260b commit 8746f5e
Show file tree
Hide file tree
Showing 4 changed files with 82 additions and 65 deletions.
1 change: 1 addition & 0 deletions gen/youtube3/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 3 additions & 2 deletions gen/youtube3/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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(),
/// <MemoryStorage as Default>::default(), None);
/// hyper::Client::new(),
/// <MemoryStorage as Default>::default(), None);
/// let mut hub = YouTube::new(hyper::Client::new(), auth);
/// # }
/// ```
Expand Down
133 changes: 71 additions & 62 deletions src/mako/lib/lib.mako
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
</%def>

## 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(),
<MemoryStorage as Default>::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(),
<MemoryStorage as Default>::default(), None);
let mut hub = ${hub_type}::new(hyper::Client::new(), auth);\
</%def>

## 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
Expand All @@ -114,11 +121,13 @@ ${self.test_hub(canonical_type_name(canonicalName))}\
</%block>
</%def>

<%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'}
</%def>
8 changes: 7 additions & 1 deletion src/mako/lib/util.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 8746f5e

Please sign in to comment.