Subversion Repositories mkgmap

//
// This is the list of variable filters.
//
.List of all substitution filters
[width="100%",grid="rows",cols="<1,<1,4a",options="header"]
|=======
| Name | Arguments | Description
| def | `default` |
If the variable is not set, then use the argument as a default value.
This means that the variable will never be `unset' in places where that
matters. 

`${oneway\|def:"no"}`

| conv | `m=>ft` |
Use for conversions between units.
With the argument +m\=\>ft+ the value is converted into feet, with the
value being assumed to be in meters, unless the value includes a unit
already.
If any of the units are not recognised then the value is unchanged.

`${height\|conv:"m=>ft"}`

So if +height+ is 10, then the result is 33, and if +height+ is 10ft,
then the result is 10, as it is already in feet.

The possible units are:

* Length: m, km, ft (feet), feet, mi (miles).
* Speed: mph, km/h (or kmh, kmph), knots
* Weight: t, kg, lb (or lbs)

| subst | `from=>to` +
`from~>to`|
Substitutes all occurrences of the string +from+ with the string +to+ in
the tag value. The +`=>`+ operator can be used for an exact matches while +`~>`+ accepts
regular expressions in the +from+ attribute.

+to+ can be empty to remove the +from+ string altogether.

Example, if name ="Queen Street" 

`${name\|subst:"Queen=>"}` returns " Street"

`${name\|subst:"Queen=>King"}` returns "King Street"

`${name\|subst:".*\s~>"}` returns "Street"

| part | `separator operator partnumber` |
Split a value in parts and returns one or more part(s) of it. If +partnumber+ is negative, the part returned is counted from the end of the split

If not specified, the default separator is ';' and the first part is returned (i.e. `${name\|part:""}`=`${name\|part:";:1"}`).

If the operator is `:` the part specified by +partnumber+ is returned.

If the operator is `<` or `>` the correspondent number of parts before or after the +partnumber+ are returned

Example: if the value is "Aa#Bb#Cc#Dd#Ee"

`${name\|part:"#:1"}`  returns Aa

`${name\|part:"#:-1"}` returns Ee

`${name\|part:"#:2"}`  returns Bb

`${name\|part:"#:-2"}` returns Dd

`${name\|part:"#>1"}`  returns Bb#Cc#Dd#Ee#

`${name\|part:"#<5"}`  returns Aa#Bb#Cc#Dd#

`${name\|part:"#<-1"}` returns Aa#Bb#Cc#Dd#

This can be especially useful for tags like ref, exit_to and destination or to switch words, 
example if value is "word1 word2 ... wordN-1 wordN"

`${name\|part:" :-1"}, ${name\|part:" <-1"}` returns "wordN, word1 word2 ... wordN-1 "

| highway-symbol | `symbol:max-num:max-alpha` |
Prepares the value as a highway reference such as "A21" "I-80" and so
on.
A code is added to the front of the string so that a highway shield is
displayed, any ";" are replaced by "/" and spaces are removed.

`${ref\|highway-symbol:"box:4:8"}`

See below for a list of the +highway-symbol+ values.

The first number is the maximum number of characters to allow for
references that contain numbers and letters.
The second is the maximum length of references that do not contain numbers.
If there is just the one number then it is used in both cases.
If no numbers are given, the default value 8 is used.

If the reference, after spaces have been removed, is longer than the maximum length
then the filter passes the string onwards unchanged; the highway-symbol is not prepended.

| height | `m=>ft` |
This is exactly the same as the +conv+ filter, except that it prepends a special
separation character before the value which is intended for elevations so that 
the Garmin software can convert it to the unit configured by the user.
If no argument is given the default is `m=>ft`, else the target unit 
must be ft (foot).

`${ele\|height:"m=>ft"}`

| country-ISO |  |
Use to normalize country names to the 3 character ISO 1366 code.
The filter has no arguments. It uses the list in LocatorConfig.xml.
Possible inputs are country names, or ISO codes in 2 or 3 characters,
for example "Deutschland", "Germany", "Bundesrepublik Deutschland", or "DE" 
will all return "DEU", also different cases like "GERMANY" or "   germany " 
will work.
 
If the value is not found in the list, then the value is unchanged.

| not-equal | `tag` |
Used to check for duplicate tags. If the value of this tag is equal to
the value of the tag named as the argument to +not-equal+, then value
of this tag is set to undefined.

....
place=* {
   name '${name} (${int_name\|not-equal:"name"})'
       \| '${name}'
   }
....

In that example, if the international name is different to the name then it will be placed
in parenthesis after the name. Otherwise there will just be the name as given in the "name" tag.

| substring | `start:end` |
Extract part of the string. The start and end positions
are counted starting from zero and the end position is not included.

`${name\|substring:"2:5"}`
If the "name" was "Dorset Lane", then the result is "rse".  If there is just the one number,
then the substring starts from that character until the end of the string.

| not-contained | `separator:tag` |
Used to check for duplicate values. If the value of this tag is contained in the list being
the value of the tag named as the argument to +not-contained+, then value
of this tag is set to undefined.

....
type=route & route=bus & ref=* {
   apply {
      set route_ref=
         '$(route_ref),${ref\|not-contained:",:route_ref"}'
             \| '$(route_ref)' \| '${ref}';
   }
}
....

Here, +ref+ value is only added to +route_ref+ when it is not already contained in that list
(with separator ','). Otherwise, the value of +route_ref+ is unchanged.
This helps to get correct labeling (no duplicates) for public transport lines where there can be multiple relations
with the same +ref+ attribute (e.g. one for the forward and one for the backward direction).

For example, if +route_ref+ was already "1,2,150" and +ref+ would again be "150",
this value would not be added to the list as it is already there.
In contrast, +ref+ equal to "229" would be added, so after that +route_ref+ would have the value "1,2,150,229"
|=====

=== Symbol codes
Here is a list of all the symbols that can be created with images to give an
idea of where they should be used.
The actual symbol will depend on the device that it is displayed on.

.Highway symbol codes
[width="60%",cols="1,1,2",options="header"]
|=====
| Shield name | Symbol | Description
| interstate | image:img/sym-interstate.png[] | US Interstate, digits only
| shield  | image:img/sym-shield.png[]        | US Highway shield, digits only
| round   | image:img/sym-round.png[]         | US Highway round, digits only
| hbox    | image:img/sym-hbox.png[]          | Box for major roads
| box     | image:img/sym-box.png[]           | Box for medium roads
| oval    | image:img/sym-oval.png[]          | Box for smaller roads
|====