skyway 0.5.0

A command-line OpenStreetMap file converter
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

# SkyFilter

SkyFilter is a bespoke filtering language designed for skyway, allowing you to transform element data as they pass through skyway.

<div class="warning">
This feature is intended to be the biggest value-add of skyway, but I haven't yet settled on a syntax that feels right.
I would <strong>massively appreciate</strong> your feedback!
How would your ideal filter language work?
</div>

## Specification

An SkyFilter file must start with a header as shown below, with the version matching the version of skyway that you are using, **followed by at least two newlines**.
skyway will warn you if there is a version mismatch.
After the header, you can use any combination of **selectors** and **modifiers** to manipulate the elements.
Every selector must be followed by a **tab-indented** block of one or more modifiers or nested selectors.
Comments start with `#` and extend through the end of a line.
```skyfilter
SkyFilter v0.5.0

TYPE way                                 # selects ways
	HAS "footway"                    # selects elements with a "footway" tag (any value)
		SET "surface" "concrete" # changes the value of the "surface" tag to be "concrete"
		COMMIT                   # immediately commit this element (skip the rest of the filter)
TYPE relation                            # selects relations
	EQUALS "type" "route"            # selects elements with the tag "type" set to "route"
		DROP                     # do not include element in output (skip the rest of the filter)
COMMIT                                   # commit the element
```

## Statements

Below you can find descriptions of each statement supported by SkyFilter.

### Selectors

A selector must be followed by one or more tab-indented statements (either a modifier or selection block).
You can nest selection blocks.

- `TYPE way, node` — Selects elements of specified type(s), in a comma-separated list.
- `HAS "key"` — Selects elements with tag `key`. This can be a regular expression (regex, see below).
- `EQUALS "key" "value"` — Selects elements with tag `key` equalling `value`. The `value` may be a regular expression.

### Modifiers

- `COMMIT` — Commits element as it currently is to be written to output. Short-circuits the rest of the filter for that element.
- `DROP` — Drops element, i.e. excluding it entirely from the output. Short-circuits the rest of the filter for that element.
- `SET "key" "value"` — Sets tag `key` to `value`.
- `KEEP "key_one", "key_two"` — Only keep tags with specified key(s), removing any others from the element. These may be regular expressions.
- `RENAME "oldkey" "newkey"` — Renames tag `oldkey` to `newkey`, keeping the value of the tag the same.
- `DELETE "key_one", "key_two"` — Removes tag(s) with specified key(s) from the element. These may be regular expressions.

## Using Regular Expressions (Regex)

Many SkyFilter statements accept regular expressions (see above).
While regular strings are wrapped in double quotes (e.g. `"footway"`) regex strings are prefixed with `r` before the first quote, like this: `r"^tiger:"`.

### Regex Syntax

SkyFilter uses the [regex](https://docs.rs/regex/latest/regex/) crate to parse regex expressions. See [here](https://docs.rs/regex/latest/regex/#syntax) for a detailed description of its syntax.