1DIALRULES(5F)                                                    DIALRULES(5F)


6       dialrules - HylaFAX dial string processing rules


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.
25       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.
34       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.
63       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.
68       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.
86       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.
92       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.


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.
139       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''.


155       sendfax(1), dialtest(8C), faxq(8C), faxsend(8C), faxgetty(8C), hylafax-
156       config(5F)
160                                  May 8, 1996                    DIALRULES(5F)