diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..f2a43c4 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,10 @@ +language: node_js +node_js: + - "7" +after_success: npm run coverage +notifications: + email: + recipients: + - post@kjellmorten.no + on_success: never # default: change + on_failure: always # default: always diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..13fae58 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,95 @@ +# Contributing + +When contributing to this repository, please first discuss the change you wish +to make via [issues](https://github.com/kjellmorten/great-uri-template/issues) +with the owners of this repository before making a change. + +Please note we have a code of conduct, please follow it in all your interactions +with the project. + +## Pull Request Process + +1. Make sure all tests pass, and that your contributions are well tested. We + strive for 100 % coverage. +2. Update the README.md with details of changes to the interface. +3. Increase the version numbers in package.json to the new version that this + Pull Request would represent. The versioning scheme we use is + [SemVer](http://semver.org/). +4. Create a Pull Request and request one of the maintainers to review and merge + it for you. + +## Code of Conduct + +### Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of +experience, nationality, personal appearance, race, religion, or sexual identity +and orientation. + +### Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or +advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic + address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +### Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +### Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +### Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at post@kjellmorten.no. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an +incident. Further details of specific enforcement policies may be posted +separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +### Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ diff --git a/LICENSE b/LICENSE index eb2b90a..898437f 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ ISC License -Copyright (c) 2016, Kjell-Morten Bratsberg Thorsen +Copyright (c) 2017, Kjell-Morten Bratsberg Thorsen, post@kjellmorten.no Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice diff --git a/README.md b/README.md index 9590a2b..667c5df 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,22 @@ This template format is loosely based on the [RFC 6570 standard](https://tools.ietf.org/html/rfc6570), but with some omissions and some extra features needed for -[Integreat](https://github.com/kjellmorten/integreat). +[Integreat](https://github.com/kjellmorten/integreat). A main feature is the +compilation of the template format to a more runtime friendly format. -A main feature is the compilation of the template format to a more runtime -friendly format. +## Getting started + +### Prerequisits + +Requires node v7, but has no other production dependencies. + +### Installing + +Install from npm: + +``` +npm install great-uri-template +``` Example of use: ``` @@ -22,13 +34,14 @@ console.log(uri) //--> http://example.com/entry/ent1?first=0&max=20 ``` -## A word on encoding -The RFC 6570 standard is very specific on encoding of the different parts of the -url. Integreat URI Template simply uses JavaScript's `encodeURI` method, which -will do in most cases, and for most part are pretty close to the RFC 6570 -specification. +### Running the tests + +The tests can be run with `npm test`. + +## The template format + +### Parameter replacement -## Parameter replacement The simplest template features parameter replacements. Parameters are indicated in the template by putting parameter names in curly brackets: `{id}`. @@ -45,7 +58,8 @@ be excluded from the resulting uri. With the `type` parameter set to `entry` and an undefined `id` parameter, this template would expand to the uri `http://example.com/entry/`. -## Query parameters +### Query parameters + Including several parameters in the query string is such a common case, that it has its own modifier. Prefixing a parameter with a question mark creates a query component, where several parameters may be included, seperated by a comma. @@ -65,7 +79,8 @@ query continuation component should be used, to avoid a second question mark. The template `http://example.com?section=archive{&first,max}` will expand to the uri `http://example.com?section=archive&first=0&max=20`. -## Other modifiers +### Other modifiers + RFC 6570 specifies several modifiers like the query component, where a list of parameters will be expanded to a list with relevant prefix and delimiters. @@ -79,7 +94,8 @@ parameter as an array of three values): Note: For Label and Path Segment Expansion, the 'explode' flag is on by default. -## Filter functions +### Filter functions + Functions may be added to a parameter after a pipe character, to filter or modify the parameter value before it is expanded in the uri. This is an extension to RFC 6570. @@ -95,7 +111,7 @@ value for the next, etc. For filter functions without arguments, parentheses are optional. -### `append(string)` +#### `append(string)` Append the given string to the value. Will not touch null values or empty strings. @@ -107,7 +123,7 @@ const template = 'http://example.com/{section|append(_archive)}' //--> http://example.com/news_archive ``` -### `prepend(string)` +#### `prepend(string)` Prepend the given string to the value. Will not touch null values or empty strings. @@ -119,7 +135,7 @@ const template = 'http://example.com/{section|prepend(local_)}' //--> http://example.com/local_news ``` -### `lower()` +#### `lower()` Transform the given value to lower case. Example: @@ -130,7 +146,7 @@ const template = 'http://example.com/{section|lower}' //--> http://example.com/news ``` -### `upper()` +#### `upper()` Transform the given value to upper case. Example: @@ -141,7 +157,7 @@ const template = 'http://example.com/{?section|upper}' //--> http://example.com/?section=NEWS ``` -### `max(length)` +#### `max(length)` Cut the value to a string of the given length. If length is higher than the number of characters in value, value is left untouched. @@ -153,7 +169,7 @@ const template = 'http://example.com/{section|max(3)}' //--> http://example.com/ent ``` -### `wrap(outerLeft, [innerLeft, innerRight,] outerRight)` +#### `wrap(outerLeft, [innerLeft, innerRight,] outerRight)` Wrap the value in the given strings. The value is wrapped in `outerLeft` and `outerRight`. If the value is an array, @@ -172,7 +188,7 @@ const template = 'http://example.com/{section|wrap(_, _)}{?ids|wrap([, ", ", ])} //--> http://example.com/_news_/?ids=["ent1", "ent2", "ent5"] ``` -### `map(from=to[, from=to[, ...]])` +#### `map(from=to[, from=to[, ...]])` Will map the given value to a replacement according to the `from=to` pairs given as arguments to the `map` function. If no match is found, the value is not replaced. @@ -184,7 +200,8 @@ const template = 'http://example.com/{type|map(article=articles, entry=entries)} //--> http://example.com/entries ``` -## Max length +### Max length + RFC 6570 specifies a 'prefix modifier', that limits the length of the value, by suffixing a parameter with a colon and the max number of characters. This is implemented in Integreat URI Template through the `max` filter function, but the @@ -193,3 +210,16 @@ RFC 6570 syntax is available as a handy shortcut. Example: With the `section` parameter set to `entertainment`, the template segment `{section:3}` will expand to `ent`. This is equivalent to `{section|max(3)}`. + +## Contributing + +Please read +[CONTRIBUTING](https://github.com/kjellmorten/great-uri-template/blob/master/CONTRIBUTING.mnd) +for details on our code of conduct, and the process for submitting pull +requests. + +## License + +This project is licensed under the ISC License - see the +[LICENSE](https://github.com/kjellmorten/great-uri-template/blob/master/LICENSE) +file for details. diff --git a/index.js b/index.js new file mode 100644 index 0000000..2ce81ec --- /dev/null +++ b/index.js @@ -0,0 +1,4 @@ +module.exports = { + compile: require('./lib/compile'), + generate: require('./lib/generate') +} diff --git a/package.json b/package.json index f741362..6ff545e 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "great-uri-template", "version": "0.1.0", - "description": "URI template format for Integreat, inspired by RFC 6570", + "description": "URI template format for Integreat, loosely based on RFC 6570", "author": "Kjell-Morten Bratsberg Thorsen (http://kjellmorten.no/)", "license": "ISC", "main": "index.js",