10,082
edits
Changes
Module:Road data/parser/hooks/doc (view source)
Revision as of 05:40, 16 July 2021
, 05:40, 16 July 2021Pywikibot 6.4.0
This module includes hook functions that provide extra functionality to [[Module:Road data/parser]] and its associated string modules.
==Basics==
Each hook is simply a function stored in the <code>p</code> package table exported by this module. Each function accepts two arguments:
* <code>parameters</code>: The table in the string module that references the hook. In this example, this argument would be the table stored in the <code>shield</code> field of the type table (from [[Module:Road data/strings/USA/KY]]):
<syntaxhighlight lang="lua">
KY["KY 1966"] = {shield = {hook = "split",
split = 100,
below = "Elongated circle %route%.svg",
above = "Circle sign %route%.svg"},
link = KY.KY.link,
abbr = KY.KY.abbr}
</syntaxhighlight>
* <code>args</code>: The arguments originally passed to the parser.
Hooks may modify the argument table by simply setting a new key as equal to a computed value. Modifying existing values is allowed, but discouraged.
The return value of a hook is an ordinary format string, which may be computed within the function or pulled from the <code>parameters</code> argument. Generally, if the hook does not compute the format string to be returned, the hook should return <code>parameters.default</code>, which should equal a format string.
==Hooks==
===<code>split</code>===
This hook determines the format string to be used by the parser based on whether the route number is above or below a particular number.
Parameters:
* <code>split</code>: The number on which to split.
* <code>below</code>: The format string to use if the route number is below <code>split</code>.
* <code>above</code>: The format string to use if the route number is equal to or above <code>split</code>.
===<code>splitlen</code>===
This hook operates in a similar fashion to <code>split</code>, but tests the length of the route number instead of its value.
Parameters:
* <code>split</code>: The length on which to split.
* <code>below</code>: The format string to use if the route number's length is below <code>split</code>.
* <code>above</code>: The format string to use if the route number's length is equal to or above <code>split</code>.
===<code>between</code>===
This hook determines the format string to be used by the parser based on whether the route number is between two given numbers.
Parameters:
* <code>lower</code>: The lower limit of the test (inclusive).
* <code>upper</code>: The upper limit of the test (exclusive).
* <code>yes</code>: The format string to use if the route number is between <code>lower</code> and <code>upper</code>.
* <code>no</code>: The format string to use if the route number is not between <code>lower</code> and <code>upper</code>.
===<code>mask</code>===
This hook adds an argument to the <code>args</code> table based on the result of applying a supplied mask to a particular argument.
Parameters:
* <code>base</code>: The argument to be masked.
* <code>masked</code>: The key used to store the mask result in the <code>args</code> table.
* <code>mask</code>: The name of the module to be used as a mask, without the "Module:" prefix. The module must return a table which maps a <code>base</code> argument to the value stored in the <code>masked</code> field of <code>args</code>.
* <code>default</code>: The format string to be processed by the parser. This string may reference the argument stored in <code>args</code> by this hook.
===<code>padroute</code>===
This hook zero-pads the route number so that the route number has a particular number of digits.
Parameters:
* <code>paddedLength</code>: The length to which the route number should be zero-padded.
* <code>default</code>: The format string to be processed by the parser. This string may reference the zero-padded route number as the <code>paddedRoute</code> argument.
===<code>lowercase</code>===
This hook converts the route "number" to lowercase.
Parameters:
* <code>default</code>: The format string to be processed by the parser. This string may reference the lowercased route number as the <code>lowercase</code> argument.
===<code>startswith</code>===
This hook determines whether a particular argument starts with any of the given patterns, and returns the value associated with the matching pattern.
Parameters:
* <code>base</code>: The argument to test.
* <code>startPatterns</code>: Key-value pairs of starting patterns and the values to return if a match is found.
* <code>default</code>: The value to return if no match is found.
==Basics==
Each hook is simply a function stored in the <code>p</code> package table exported by this module. Each function accepts two arguments:
* <code>parameters</code>: The table in the string module that references the hook. In this example, this argument would be the table stored in the <code>shield</code> field of the type table (from [[Module:Road data/strings/USA/KY]]):
<syntaxhighlight lang="lua">
KY["KY 1966"] = {shield = {hook = "split",
split = 100,
below = "Elongated circle %route%.svg",
above = "Circle sign %route%.svg"},
link = KY.KY.link,
abbr = KY.KY.abbr}
</syntaxhighlight>
* <code>args</code>: The arguments originally passed to the parser.
Hooks may modify the argument table by simply setting a new key as equal to a computed value. Modifying existing values is allowed, but discouraged.
The return value of a hook is an ordinary format string, which may be computed within the function or pulled from the <code>parameters</code> argument. Generally, if the hook does not compute the format string to be returned, the hook should return <code>parameters.default</code>, which should equal a format string.
==Hooks==
===<code>split</code>===
This hook determines the format string to be used by the parser based on whether the route number is above or below a particular number.
Parameters:
* <code>split</code>: The number on which to split.
* <code>below</code>: The format string to use if the route number is below <code>split</code>.
* <code>above</code>: The format string to use if the route number is equal to or above <code>split</code>.
===<code>splitlen</code>===
This hook operates in a similar fashion to <code>split</code>, but tests the length of the route number instead of its value.
Parameters:
* <code>split</code>: The length on which to split.
* <code>below</code>: The format string to use if the route number's length is below <code>split</code>.
* <code>above</code>: The format string to use if the route number's length is equal to or above <code>split</code>.
===<code>between</code>===
This hook determines the format string to be used by the parser based on whether the route number is between two given numbers.
Parameters:
* <code>lower</code>: The lower limit of the test (inclusive).
* <code>upper</code>: The upper limit of the test (exclusive).
* <code>yes</code>: The format string to use if the route number is between <code>lower</code> and <code>upper</code>.
* <code>no</code>: The format string to use if the route number is not between <code>lower</code> and <code>upper</code>.
===<code>mask</code>===
This hook adds an argument to the <code>args</code> table based on the result of applying a supplied mask to a particular argument.
Parameters:
* <code>base</code>: The argument to be masked.
* <code>masked</code>: The key used to store the mask result in the <code>args</code> table.
* <code>mask</code>: The name of the module to be used as a mask, without the "Module:" prefix. The module must return a table which maps a <code>base</code> argument to the value stored in the <code>masked</code> field of <code>args</code>.
* <code>default</code>: The format string to be processed by the parser. This string may reference the argument stored in <code>args</code> by this hook.
===<code>padroute</code>===
This hook zero-pads the route number so that the route number has a particular number of digits.
Parameters:
* <code>paddedLength</code>: The length to which the route number should be zero-padded.
* <code>default</code>: The format string to be processed by the parser. This string may reference the zero-padded route number as the <code>paddedRoute</code> argument.
===<code>lowercase</code>===
This hook converts the route "number" to lowercase.
Parameters:
* <code>default</code>: The format string to be processed by the parser. This string may reference the lowercased route number as the <code>lowercase</code> argument.
===<code>startswith</code>===
This hook determines whether a particular argument starts with any of the given patterns, and returns the value associated with the matching pattern.
Parameters:
* <code>base</code>: The argument to test.
* <code>startPatterns</code>: Key-value pairs of starting patterns and the values to return if a match is found.
* <code>default</code>: The value to return if no match is found.