Making the Premier Open-Source Fax Management System Even Better
A dial string rules file is an ASCII file containing one or more rule sets. A rule set defines a set of transformation rules that are sequentially applied to a dial string. Each rule set is associated with an identifier, with certain well-known identifiers being used by the facsimile server or client application. Each transformation rule is a regular expression and a replacement string; the regular expression is repeatedly applied to a dial string and any matching substring is replaced by the replacement string.
The syntax of a dial string rules file is as follows. Comments are introduced with the ``!'' character and continue to the end of the current line. Identifiers are formed from a leading alphabetic and any number of subsequent alpha-numeric characters. A rule set is of the form:
where rule1, rule2, and so on are transformation rules. Line breaks are significant. The initial rule set definition line and the trailing ``]'' must be on separate lines; and each transformation rule must also be on a single line. Transformation rules are of the two forms:
regular-expression = replacement
regular-expression = \RuleName(replacement)
where regular-expression is a POSIX 1003.2 extended regular expression and replacement is a string that is substituted in place of any portion of the dial string that is matched by the regular-expression. White space is significant in parsing transformation rules. If a regular expression or replacement string has embedded white space in it, then the white space needs to be escaped with a ``\'' character or the entire string should be enclosed in quote (``"'') marks. Replacement strings may reference the entire string matched by the regular expression with the ``&'' character. Substrings matched with the ``(...)'' constructs may be referenced by using ``\n'' where n is a single numeric digit between 1 and 9 that refers to the n-th matched substring; c.f. re_format(7), sed(1), etc.
If \RuleName(replacement) is used, then the dial rule set RuleName will be recursively applied to the expanded replacement and the result used as the replacement for the matched pattern before continuing to process the transformation rules.
To simplify and parameterize the construction of rule sets, dial string rules files may also include simple text-oriented variable definitions. A line of the form:
defines a variable named foo that has the value string. String values with embedded whitespace must use the ``\'' character or be enclosed in quote marks. Variables are interpolated into transformation rules by referencing them as:
Note that variable interpolation is done only once, at the time a transformation rule is defined. This means that forward references are not supported and that circular definitions will not cause loops. The facsimile server automatically defines four variables to have the values defined in its configuration file: AreaCode, CountryCode, LongDistancePrefix, and InternationalPrefix These variables are initialized before parsing a dial string rules file; thus if they are defined in the rules file then they will override any definition by the server.
There are three well known rule set names: CanonicalNumber to convert a dial string to a canonical format, DialString to prepare a dial string before using it to dial the telephone, and DisplayNumber to convert a dial string to an external ``displayable'' form that does not include the private information that might appear in the raw dial string.
The first rule simply strips anything following a ``%''; this will remove any calling card-related information. The next eight rules convert upper and lower case alphabetics to the equivalent key numbers (this is convenient for users that use mnemonic phone numbers). The tenth rule removes everything but numbers and plus signs. The eleventh rule translates any explicit international dialing prefix into the ``+'' symbol used to identify country codes. The twelfth rule replaces a leading long distance dialing prefix with the local country code string. The last rule matches local phone numbers and inserts the local country code and area code.
As an example, assume that
then if the above set of rules is applied to ``01123965-Tube%2345'', the transformations would be: