Skip to content

Commit

Permalink
Reduce duplication in badge regex/url patterns
Browse files Browse the repository at this point in the history
This reduces duplication in badge regex/url patterns, and reduce the need to understand regexes in order to create badges.

The badge examples could be harmonized to reduce the duplication even further, though that could be handled in a follow-on PR.

Ref: #2050
  • Loading branch information
paulmelnikow committed Nov 6, 2018
1 parent 88402dd commit c08b4bf
Show file tree
Hide file tree
Showing 7 changed files with 301 additions and 238 deletions.
14 changes: 7 additions & 7 deletions doc/TUTORIAL.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,8 +102,7 @@ module.exports = class Example extends BaseService { // (3)
static get url() { // (4)
return {
base: 'example',
format: '([^/]+)',
capture: ['text'],
pattern: ':text',
}
}

Expand All @@ -124,9 +123,9 @@ Description of the code:
3. Our module must export a class which extends `BaseService`
4. `url()` declares a route. We declare getters as `static`.
* `base` defines the static part of the route.
* `format` is a [regular expression](https://www.w3schools.com/jsref/jsref_obj_regexp.asp) defining the variable part of the route.
* We can use `capture` to extract matched regex clauses into one or more named variables. Here we are declaring that we want to store the string matched by `([^/]+)` in a variable called `text`.
This declaration adds the route `/^\/test\/([^\/]+)\.(svg|png|gif|jpg|json)$/` to our application.
* `pattern` is a pattern defining the variable part of the route. It can
include any number of named parameters. These are handled by
[`path-to-regexp`][path-to-regexp].
5. All badges must implement the `async handle()` function. This is called to invoke our code. Note that the signature of `handle()` will match the capturing group defined in `url()` Because we're capturing a single variable called `text` our function signature is `async handle({ text })`. Although in this simple case, we aren't performing any asynchronous calls, `handle()` would usually spend some time blocked on I/O. We use the `async`/`await` pattern for asynchronous code. Our `handle()` function returns an object with 3 properties:
* `label`: the text on the left side of the badge
* `message`: the text on the right side of the badge - here we are passing through the parameter we captured in the URL regex
Expand All @@ -143,6 +142,8 @@ To try out this example badge:
4. Visit the badge at <http://[::]:8080/example/foo.svg>.
It should look like this: ![](https://img.shields.io/badge/example-foo-blue.svg)

[path-to-regexp]: https://github.com/pillarjs/path-to-regexp#parameters

### (4.3) Querying an API

The example above was completely static. In order to make a useful service badge we will need to get some data from somewhere. The most common case is that we will query an API which serves up some JSON data, but other formats (e.g: XML) may be used.
Expand All @@ -165,8 +166,7 @@ module.exports = class GemVersion extends BaseJsonService { // (5)
static get url() { // (6)
return {
base: 'gem/v',
format: '(.+)',
capture: ['gem'],
format: ':gem',
}
}

Expand Down
Loading

0 comments on commit c08b4bf

Please sign in to comment.