1DIALRULES(5F)                                                    DIALRULES(5F)
2
3
4

NAME

6       dialrules - HylaFAX dial string processing rules
7

DESCRIPTION

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
14       receiver's capabilities, and to process into a form suitable for  send‐
15       ing  to a modem.  In addition client applications may need to process a
16       dial string to formulate an external form that does not include private
17       information 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
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
27       sequentially  applied  to  a  dial string.  Each rule set is associated
28       with an identifier, with certain well-known identifiers being  used  by
29       the  facsimile  server or client application.  Each transformation rule
30       is a regular expression and a replacement string; the  regular  expres‐
31       sion  is repeatedly applied to a dial string and any matching substring
32       is replaced by the replacement string.
33
34       The syntax of a dial string rules file is  as  follows.   Comments  are
35       introduced 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
54       expression  or  replacement string has embedded white space in it, then
55       the white space needs to be escaped  with  a  ``\''  character  or  the
56       entire  string  should be enclosed in quote (``"'') marks.  Replacement
57       strings may reference the entire string matched by the regular  expres‐
58       sion  with  the ``&'' character.  Substrings matched with the ``(...)''
59       constructs may be referenced by  using  ``\n''  where  n  is  a  single
60       numeric  digit  between  1  and  9 that refers to the n-th matched sub‐
61       string; c.f.  re_format(7), sed(1), etc.
62
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.
67
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.
85
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.
91

EXAMPLES

93       This  is the default set of rules for transforming a dial string into a
94       canonical phone number:
95              Area=${AreaCode}                  ! local area code
96              Country=${CountryCode}            ! local country code
97              IDPrefix=${InternationalPrefix}   ! prefix for placing an international call
98              LDPrefix=${LongDistancePrefix}    ! prefix for placing a long distance call
99              !
100              ! Convert a phone number to a canonical format:
101              !
102              !    +<country><areacode><rest>
103              !
104              ! by (possibly) stripping off leading dialing prefixes for
105              ! long distance and/or international dialing.
106              !
107              CanonicalNumber := [
108              %.*               =                          ! strip calling card stuff
109              [abcABC]          = 2                        ! these convert alpha to numbers
110              [defDEF]          = 3
111              [ghiGHI]          = 4
112              [jklJKL]          = 5
113              [mnoMNO]          = 6
114              [prsPRS]          = 7
115              [tuvTUV]          = 8
116              [wxyWXY]          = 9
117              [^+0-9]+          =                          ! strip white space etc.
118              ^${IDPrefix}      = +                        ! replace int. dialing code
119              ^${LDPrefix}      = +${Country}              ! replace l.d. dialing code
120              ^[^+]             = +${Country}${Area}&      ! otherwise, insert canon form
121              ]
122       The first rule simply strips anything  following  a  ``%'';  this  will
123       remove any calling card-related information.  The next eight rules con‐
124       vert upper and lower case alphabetics to  the  equivalent  key  numbers
125       (this  is  convenient  for users that use mnemonic phone numbers).  The
126       tenth rule removes everything but numbers and plus signs.  The eleventh
127       rule  translates  any  explicit  international  dialing prefix into the
128       ``+'' symbol used to identify country codes.  The twelfth rule replaces
129       a  leading  long  distance  dialing  prefix with the local country code
130       string.  The last rule matches local  phone  numbers  and  inserts  the
131       local country code and area code.
132
133       As an example, assume that
134              AreaCode=415
135              CountryCode=1
136              InternationalPrefix=011
137              LongDistancePrefix=1
138       then  if  the  above set of rules is applied to ``01123965-Tube%2345'',
139       the transformations would be:
140              01123965-Tube%2345    01123965-Tube    ! strip calling card stuff
141              01123965-Tube         01123965-8823    ! convert alphabetics
142              01123965-8823         011239658823     ! strip white space etc.
143              011239658823          +239658823       ! replace int. dialing code
144              +239658823            +239658823       ! replace l.d. dialing code
145              +239658823            +239658823       ! otherwise, insert canon form
146       for a final result of ``+239658823''.
147

SEE ALSO

149       sendfax(1), dialtest(8C), faxq(8C), faxsend(8C), faxgetty(8C), hylafax-
150       config(5F)
151
152
153
154                                  May 8, 1996                    DIALRULES(5F)
Impressum