MAN page from RedHat Other hylafax-man-4.0pl1-9.i386.rpm

DIALRULES

Section: Misc. Reference Manual Pages (5F)
Updated: May 8, 1996
Index

NAME

dialrules - HylaFAX dial string processing rules

DESCRIPTION

A dial string specifies how to dial the telephone in order toreach 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 theHylaFAX server processes:to craft a canonical phone number for use in locating thereceiver's capabilities, andto process into a form suitable for sending to a modem.In addition client applications may need to process a dial stringto formulate an external form that does not include private informationsuch as a credit card access code.Phone number canonicalization and dial string preparationare done according to dial string processing rulesthat are located in a file specified in the server configurationfile; see theDialStringRulesparameter inconfig(5F).The generation of an externalized form for a dial string is done byrules that optionally appear in/usr/share/fax/dialruleson client machines.

A dial string rules file is anASCIIfile containing one or more rule sets.A rule set defines a set oftransformation rulesthat are sequentially applied to a dial string.Each rule set is associated with an identifier, with certain well-knownidentifiers 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 anymatching 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 theend of the current line.Identifiers are formed from a leading alphabetic and any number ofsubsequent 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 beon separate lines; and each transformation rule must also be on asingle line.Transformation rules are of the form:


     regular-expression = replacement

whereregular-expressionis aPOSIX1003.2 extended regular expression andreplacementis a string that is substituted in place of any portion of the dialstring that is matched by theregular-expression.White space is significant in parsing transformation rules.If a regular expression or replacement string has embedded white spacein it, then the white space needs to be escaped with a ``\'' characteror the entire string should be enclosed in quote (``"'') marks.Replacement strings may reference the entire string matched by theregular expression with the ``&'' character.Substrings matched with the ``(...)'' constructs may be referencedby using ``\n'' wherenis a single numeric digit between 1 and 9 that refers to then-thmatched substring; c.f.re_format(7),sed(1),etc.

To simplify and parameterize the construction of rule sets, dial stringrules files may also include simple text-oriented variable definitions.A line of the form:


     foo=string

defines a variable namedfoothat has the valuestring.String values with embedded whitespace must use the ``\'' characteror be enclosed in quote marks.Variables are interpolated into transformation rules by referencing themas:


     ${var}

Note that variable interpolation is done only once, at the time atransformation rule is defined.This means that forward references are not supported and thatcircular definitions will not cause loops.The facsimile server automatically defines four variables to havethe values defined in its configuration file:AreaCode,CountryCode,LongDistancePrefix,andInternationalPrefixThese variables are initialized before parsing a dial string rulesfile; thus if they are defined in the rules file then they willoverride any definition by the server.

There are three well known rule set names:CanonicalNumberto convert a dial string to a canonical format,DialStringto prepare a dial string before using it to dial the telephone, andDisplayNumberto convert a dial string to an external ``displayable'' formthat does not include theprivate information that might appear in the raw dial string.

EXAMPLES

This is the default set of rules for transforming a dial string intoa canonical phone number:


Area=${AreaCode}                  ! local area codeCountry=${CountryCode}            ! local country codeIDPrefix=${InternationalPrefix}   ! prefix for placing an international callLDPrefix=${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 ``#''; thiswill remove any calling card-related information.The next eight rules convert upper and lower case alphabetics to theequivalent key numbers (this is convenient for users that usemnemonic phone numbers).The tenth rule removes everything but numbers and plus signs.The eleventh rule translates any explicit international dialing prefixinto the ``+'' symbol used to identify country codes.The twelfth rule replaces a leading long distance dialing prefixwith the local country code string.The last rule matches local phone numbers and inserts the localcountry code and area code.

As an example, assume that


AreaCode=415CountryCode=1InternationalPrefix=011LongDistancePrefix=1

then if the above set of rules is appliedto ``01123965-Tube#2345'', the transformations would be:


01123965-Tube#2345    01123965-Tube    ! strip calling card stuff01123965-Tube         01123965-8823    ! convert alphabetics01123965-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''.

This document was created byman2html,using the manual pages.

DIALRULES

NAME

DESCRIPTION

EXAMPLES

SEE ALSO

Index