Provided by: hylafax-server_6.0.6-5_amd64 bug

NAME

       dialrules - HylaFAX dial string processing rules

DESCRIPTION

       A  dial  string  specifies  how  to  dial  the  telephone  in order to reach a destination
       facsimile machine, or similar device.  This  string  is  supplied  by  a  user  with  each
       outgoing  facsimile  job.   User-supplied dial strings need to be processed in two ways by
       the HylaFAX server processes: to craft a canonical phone number for use  in  locating  the
       receiver's  capabilities,  and to process into a form suitable for sending to a modem.  In
       addition client applications may need to process a dial string to  formulate  an  external
       form  that  does not include private information such as a credit card access code.  Phone
       number canonicalization and dial string preparation are  done  according  to  dial  string
       processing  rules  that  are located in a file specified in the server configuration file;
       see the DialStringRules parameter in hylafax-config(5).  The generation of an externalized
       form  for  a dial string is done by rules that optionally appear in /etc/hylafax/dialrules
       on client machines.

       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:
              Identifier := [
                  rule1
                  rule2
                  ...
              ]
       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
       form:
            regular-expression = 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.

       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:
            foo=string
       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:
            ${var}
       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.

EXAMPLES

       This  is  the  default  set of rules for transforming a dial string into a canonical phone
       number:
              Area=${AreaCode}                  ! local area code
              Country=${CountryCode}            ! local country code
              IDPrefix=${InternationalPrefix}   ! prefix for placing an international call
              LDPrefix=${LongDistancePrefix}    ! prefix for placing a long distance call
              !
              ! Convert a phone number to a canonical format:
              !
              !    +<country><areacode><rest>
              !
              ! by (possibly) stripping off leading dialing prefixes for
              ! long distance and/or international dialing.
              !
              CanonicalNumber := [
              %.*               =                          ! strip calling card stuff
              [abcABC]          = 2                        ! these convert alpha to numbers
              [defDEF]          = 3
              [ghiGHI]          = 4
              [jklJKL]          = 5
              [mnoMNO]          = 6
              [prsPRS]          = 7
              [tuvTUV]          = 8
              [wxyWXY]          = 9
              [^+0-9]+          =                          ! strip white space etc.
              ^${IDPrefix}      = +                        ! replace int. dialing code
              ^${LDPrefix}      = +${Country}              ! replace l.d. dialing code
              ^[^+]             = +${Country}${Area}&      ! otherwise, insert canon form
              ]
       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
              AreaCode=415
              CountryCode=1
              InternationalPrefix=011
              LongDistancePrefix=1
       then  if  the above set of rules is applied to ``01123965-Tube%2345'', the transformations
       would be:
              01123965-Tube%2345    01123965-Tube    ! strip calling card stuff
              01123965-Tube         01123965-8823    ! convert alphabetics
              01123965-8823         011239658823     ! strip white space etc.
              011239658823          +239658823       ! replace int. dialing code
              +239658823            +239658823       ! replace l.d. dialing code
              +239658823            +239658823       ! otherwise, insert canon form
       for a final result of ``+239658823''.

SEE ALSO

       sendfax(1), dialtest(8), faxq(8), faxsend(8), faxgetty(8), hylafax-config(5)

                                           May 8, 1996                               DIALRULES(5)