Skip to content

Commit

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

Ref: #2050
  • Loading branch information
paulmelnikow authored Nov 8, 2018
1 parent 611e58e commit 291f35d
Show file tree
Hide file tree
Showing 8 changed files with 311 additions and 245 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` defines the variable part of the route. It can include any
number of named parameters. These are converted into
regular expressions 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'],
pattern: ':gem',
}
}

Expand Down
Loading

0 comments on commit 291f35d

Please sign in to comment.