1DIALRULES(5F) DIALRULES(5F)
2
6 dialrules - HylaFAX dial string processing rules
7
9 A dial string specifies how to dial the telephone in order to reach a
10 destination facsimile machine, or similar device. This string is sup‐
11 plied by a user with each outgoing facsimile job. User-supplied dial
12 strings need to be processed in two ways by the HylaFAX server pro‐
13 cesses: to craft a canonical phone number for use in locating the re‐
14 ceiver's capabilities, and to process into a form suitable for sending
15 to a modem. In addition client applications may need to process a dial
16 string to formulate an external form that does not include private in‐
17 formation such as a credit card access code. Phone number canonical‐
18 ization and dial string preparation are done according to dial string
19 processing rules that are located in a file specified in the server
20 configuration file; see the DialStringRules parameter in hylafax-con‐
21 fig(5F). The generation of an externalized form for a dial string is
22 done by rules that optionally appear in /etc/hylafax/dialrules on
23 client machines.
24 A dial string rules file is an ASCII file containing one or more rule
26 sets. A rule set defines a set of transformation rules that are se‐
27 quentially applied to a dial string. Each rule set is associated with
28 an identifier, with certain well-known identifiers being used by the
29 facsimile server or client application. Each transformation rule is a
30 regular expression and a replacement string; the regular expression is
31 repeatedly applied to a dial string and any matching substring is re‐
32 placed by the replacement string.
33 The syntax of a dial string rules file is as follows. Comments are in‐
35 troduced with the ``!'' character and continue to the end of the cur‐
36 rent line. Identifiers are formed from a leading alphabetic and any
37 number of subsequent alpha-numeric characters. A rule set is of the
38 form:
39 Identifier := [
40 rule1
41 rule2
42 ...
43 ]
44 where rule1, rule2, and so on are transformation rules. Line breaks
45 are significant. The initial rule set definition line and the trailing
46 ``]'' must be on separate lines; and each transformation rule must also
47 be on a single line. Transformation rules are of the two forms:
48 regular-expression = replacement
49 regular-expression = \RuleName(replacement)
50 where regular-expression is a POSIX 1003.2 extended regular expression
51 and replacement is a string that is substituted in place of any portion
52 of the dial string that is matched by the regular-expression. White
53 space is significant in parsing transformation rules. If a regular ex‐
54 pression or replacement string has embedded white space in it, then the
55 white space needs to be escaped with a ``\'' character or the entire
56 string should be enclosed in quote (``"'') marks. Replacement strings
57 may reference the entire string matched by the regular expression with
58 the ``&'' character. Substrings matched with the ``(...)'' constructs
59 may be referenced by using ``\n'' where n is a single numeric digit be‐
60 tween 1 and 9 that refers to the n-th matched substring; c.f. re_for‐
61 mat(7), sed(1), etc.
62 If \RuleName(replacement) is used, then the dial rule set RuleName will
64 be recursively applied to the expanded replacement and the result used
65 as the replacement for the matched pattern before continuing to process
66 the transformation rules.
67 To simplify and parameterize the construction of rule sets, dial string
69 rules files may also include simple text-oriented variable definitions.
70 A line of the form:
71 foo=string
72 defines a variable named foo that has the value string. String values
73 with embedded whitespace must use the ``\'' character or be enclosed in
74 quote marks. Variables are interpolated into transformation rules by
75 referencing them as:
76 ${var}
77 Note that variable interpolation is done only once, at the time a
78 transformation rule is defined. This means that forward references are
79 not supported and that circular definitions will not cause loops. The
80 facsimile server automatically defines four variables to have the val‐
81 ues defined in its configuration file: AreaCode, CountryCode, LongDis‐
82 tancePrefix, and InternationalPrefix These variables are initialized
83 before parsing a dial string rules file; thus if they are defined in
84 the rules file then they will override any definition by the server.
85 There are three well known rule set names: CanonicalNumber to convert a
87 dial string to a canonical format, DialString to prepare a dial string
88 before using it to dial the telephone, and DisplayNumber to convert a
89 dial string to an external ``displayable'' form that does not include
90 the private information that might appear in the raw dial string.
91 External transformation rules are interpolated by referencing them as:
93 ~{executable}
94 Here, ``executable'' refers to the path to an executable which will be
95 provided the matched data as its first parameter. The full output of
96 the executable will be used as the replacement for the matched data.
97
99 This is the default set of rules for transforming a dial string into a
100 canonical phone number:
101 Area=${AreaCode} ! local area code
102 Country=${CountryCode} ! local country code
103 IDPrefix=${InternationalPrefix} ! prefix for placing an international call
104 LDPrefix=${LongDistancePrefix} ! prefix for placing a long distance call
105 !
106 ! Convert a phone number to a canonical format:
107 !
108 ! +<country><areacode><rest>
109 !
110 ! by (possibly) stripping off leading dialing prefixes for
111 ! long distance and/or international dialing.
112 !
113 CanonicalNumber := [
114 %.* = ! strip calling card stuff
115 [abcABC] = 2 ! these convert alpha to numbers
116 [defDEF] = 3
117 [ghiGHI] = 4
118 [jklJKL] = 5
119 [mnoMNO] = 6
120 [prsPRS] = 7
121 [tuvTUV] = 8
122 [wxyWXY] = 9
123 [^+0-9]+ = ! strip white space etc.
124 ^${IDPrefix} = + ! replace int. dialing code
125 ^${LDPrefix} = +${Country} ! replace l.d. dialing code
126 ^[^+] = +${Country}${Area}& ! otherwise, insert canon form
127 ]
128 The first rule simply strips anything following a ``%''; this will re‐
129 move any calling card-related information. The next eight rules con‐
130 vert upper and lower case alphabetics to the equivalent key numbers
131 (this is convenient for users that use mnemonic phone numbers). The
132 tenth rule removes everything but numbers and plus signs. The eleventh
133 rule translates any explicit international dialing prefix into the
134 ``+'' symbol used to identify country codes. The twelfth rule replaces
135 a leading long distance dialing prefix with the local country code
136 string. The last rule matches local phone numbers and inserts the lo‐
137 cal country code and area code.
138 As an example, assume that
140 AreaCode=415
141 CountryCode=1
142 InternationalPrefix=011
143 LongDistancePrefix=1
144 then if the above set of rules is applied to ``01123965-Tube%2345'',
145 the transformations would be:
146 01123965-Tube%2345 01123965-Tube ! strip calling card stuff
147 01123965-Tube 01123965-8823 ! convert alphabetics
148 01123965-8823 011239658823 ! strip white space etc.
149 011239658823 +239658823 ! replace int. dialing code
150 +239658823 +239658823 ! replace l.d. dialing code
151 +239658823 +239658823 ! otherwise, insert canon form
152 for a final result of ``+239658823''.
153
155 sendfax(1), dialtest(8C), faxq(8C), faxsend(8C), faxgetty(8C), hylafax-
156 config(5F)
157 May 8, 1996 DIALRULES(5F)