DIALRULES(5)							File Formats Manual						      DIALRULES(5)

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 send-
       ing to a modem.	In addition client applications may need to process a dial string to formulate an external form that does not include pri-
       vate  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/dial-
       rules 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 expres-
       sion 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 cur-
       rent 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 trail-
       ing ``]'' 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 por-
       tion of the dial string that is matched by the regular-expression.  White space is significant in parsing transformation rules.	If a regu-
       lar 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 ``
'' where n is a  sin-
       gle 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 defini-
       tions.  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 initial-
       ized 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 con-
       vert 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)