Munurin millum rættingarnar hjá "Module:Road data/strings/doc"

At its most basic level, this module is a nested table of strings. At the top is the root table, named for the abbreviation of a country, state, or province. This table stores the type data for a particular place, which is named in the comment in the first line, and is returned at the end of the module. The table is composed of further tables, one per type. The basic syntax for a type table is:

 

place.type = {shield = "",

link = "",

abbr = ""}

 

The three main fields in a type table are <code>shield</code>, <code>link</code>, and <code>abbr</code>. Generally, <code>shield</code> determines the shield that is displayed, if any; <code>link</code> specifies the target of the link generated by a including module, if any; and <code>abbr</code> determines the displayed abbreviation. Currently, these are the three types used by all countries. By convention, they are always specified, using an empty string if there is no value.

 

Once a type is defined, it can be referred to later in the code. A common idiom used for bannered types is defining the shield to be the shield field of the base type (from [[Module:Road data/strings/USA/MO]]):

MO.US = {shield = "US %route%.svg",

link = "U.S. Route %route% in Missouri",

banner = "Alternate plate.svg",

width = "expand"}

 

Another common idiom is defining a type alias by setting an entry in the root table equal to a previously defined type (from [[Module:Road data/strings/HKG]]):

HKG.Route = {shield = "HK Route%route%.svg",

link = "Route %route% (Hong Kong)",

HKG.route = HKG.Route

 

===Parser arguments===

 

The two statements may be combined. The parser will parse the if-then-else statement first, and then perform the argument inclusion. This combination is commonly used with bannered routes in the United States, where the <code>dab</code> argument is tested and the link disambiguation is adjusted accordingly, as follows (from [[Module:Road data/strings/USA/AL]]):

AL["US-Bus"] = {shield = "US %route%.svg",

link = "U.S. Route %route% Business ([dab||%dab%, |]Alabama)",

banner = "Business plate.svg",

width = "expand"}

 

When parsing the <code>link</code> field, the parser first checks to see if the <code>dab</code> argument was provided. If so, it replaces the statement with <code>%dab%, </code>. If not, the statement is replaced with the empty string placed in the <code>else</code> block. Then, the parser replaces <code>%route%</code> with the route number and, if the <code>dab</code> argument was provided, <code>%dab%</code> with the value of that argument.

 

The most straightforward functionality provided by nested tables is switching. In its most basic form, the table consists of a series of key-value pairs, with the keys being route numbers and the values being the format strings used by those routes. Usually, the format string returned does not need parsing, but the option is there. A <code>default</code> entry should be provided to handle any route numbers not explicitly stated. The following is a representative example of route-based switching (from [[Module:Road data/strings/USA/AR]]):

AR.AR = {shield = {default = "Arkansas %route%.svg",

["917"] = "Arkansas 917-1.svg",

abbr = "Hwy.&nbsp;%route%",

width = "expand"}

 

In this example, Highways 917 and 980 have non-standard shield names, which are explicitly provided. Other route numbers use the default format.

 

Switching on other arguments is also allowed. The name of the argument to be used for switching is stated in the <code>arg</code> field of the table. Nesting switches on different arguments is also allowed. A good example that uses both forms of switching can be found in [[Module:Road data/strings/CAN/ON|Ontario]]:

local regionalShields = {arg = "county",

["Essex"] = "Essex County Road %route%.png",

["Simcoe"] = {["52"] = "Simcoe county road 52.png",

default = "Simcoe County Road %route%.JPG"}}

 

In this example, which is a shield table that is reused by several types in Ontario, the <code>county</code> argument is used for the primary switch. If the route is in Simcoe County, a second switch is performed, this time on the route number.

===Existence testing===

Another use for tables is existence testing. If a table has the <code>ifexists</code> field set to <code>true</code>, the parser will perform existence testing on the result of parsing the <code>default</code> field. If the test fails, the result of parsing the <code>otherwise</code> field is returned. Existence testing may be chained by using a second ifexists table as the value of the first table's <code>otherwise</code> field, and so on. Here's an example of nested existence testing (from [[Module:Road data/strings/GBR]]):

GBR.B = {shield = {ifexists = true,

default = "UK road B%route%.svg",

link = "",

abbr = "B%route%"}

 

===Hooks===

 

Generally speaking, a hook is called by setting the <code>hook</code> field in a table as equal to the name of a hook. Hooks receive two arguments, both tables: <code>parameters</code>, which is the table in the definition; and <code>args</code>, which is simply the table of arguments normally passed to the parser. The hook returns a string, which is then parsed as usual. A powerful feature of hooks is that they can add arbitrary values to the argument table, which may be referenced in the string returned by the hook. Generally, the format string returned by the hook is specified in some form by the <code>default</code> field of the table, though there are exceptions. Here is an example of a hook (from [[Module:Road data/strings/MEX]]):

MEX.SH = {shield = {ifexists = true,

arg = "state",

default = "%fullstate% State Highway %route%"},

abbr = "SH&nbsp;%route%"}

 

In this example, the parser will process the link by calling the <code>mask</code> hook. In short, this hook takes the argument referenced in <code>base</code>, passes it through the mask module specified in <code>mask</code>, and stores it in the field in the arguments noted in <code>masked</code>. The hook returns the string given in <code>default</code>, which has access to the <code>fullstate</code> argument added by the hook.

===Other functionality===

Functionality exists to display multiple shields for one route, which is used to display tolled and free shields for routes where they differ. This is done by supplying a table with two values, which are listed without indices. The parser is called twice by the calling module, and it returns one shield per call. An example may be found in [[Module:Road data/strings/USA/TX|Texas]]:

TX.Both = {shield = {"Texas %route%.svg", "Toll Texas %route% new.svg"},

link = "Texas State Highway %route%",

abbr = "SH&nbsp;%route%",

width = 40}

 

==Structure==

Each country has its own module. In the United States and Canada, each state/territory/province also has its own module. Each module begins with a comment stating the name of the country or state, followed by the root table declaration, as follows (from [[Module:Road data/strings/USA/AS]]):

-- American Samoa

local AS = {}

 

The root table is named based on the established abbreviation for the country or state, which is the same as the abbreviation used in the module title. This table stores the various types used in that particular place. Most of the remaining code in the module defines these various types. The module ends by returning the root table:

return AS

 

===Aliasing===

There are two ways to define a type as an alias. If the type is defined within the module, simply set the new type as equal to the type being aliased, as shown above (from [[Module:Road data/strings/HKG]]):

HKG.Route = {shield = "HK Route%route%.svg",

link = "Route %route% (Hong Kong)",

HKG.route = HKG.Route

 

If the type is defined in a separate module, such as a state highway type being used in another state's module, a special syntax may be used to refer to that module (from [[Module:Road data/strings/USA/NJ]]):

NJ.NY = {alias = {module = "USA/NY", type = "NY"}}

 

This code sets the <code>NY</code> type as a link to the <code>NY</code> type in [[Module:Road data/strings/USA/NY]]. The parser will import that module and process the type as if the original module had declared it itself. The alias declaration may not add or override any data in the type table it points to.