DIALRULES(5F)

💖 NAME 💖

dialrules — HylaFAX dial string processing rules. That's it, that's the whole vibe. ✨ (Yes bestie, this is the page from section 5F of the manual — DIALRULES(5F), if you're keeping receipts. 🧚)

---

🌸 DESCRIPTION 🌸

Okay so. A dial string is literally just the thing that says how to dial the telephone so you can reach the destination facsimile machine (or whatever similar device is on the other end 👀). The user hands you this string with every outgoing facsimile job, and then it needs processing. And not just one kind — the HylaFAX server processes gotta do it in two ways:

• craft a canonical phone number that gets used to look up the receiver's capabilities, and
• process it into a form that's actually suitable for sending to a modem.

And on top of that, client applications may also need to process a dial string to formulate an external form — one that does not include private information like a credit card access code. 🫣 (Not the credit card digits leaking, absolutely not, we don't do that here.)

Phone number canonicalization and dial string preparation both happen according to dial string processing rules that live in a file specified in the server configuration file. Go look at the DialStringRules parameter in hylafax-config(5F) for that. 💅 And 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 get sequentially applied to a dial string. Each rule set is associated with an identifier, and certain well-known identifiers are the ones the facsimile server or client application actually uses. Each transformation rule is a regular expression plus a replacement string; the regular expression is repeatedly applied to a dial string and any matching substring gets replaced by the replacement string. 🔁

---

🎀 The syntax, bestie 🎀

Comments are introduced with the ! character and continue to the end of the current line. (Iconic. Short. Perfect. 😌)

Identifiers are formed from a leading alphabetic and any number of subsequent alpha-numeric characters.

A rule set looks like this:

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. No sneaking them onto the same line, fr fr.

Transformation rules come in two forms:

regular-expression = replacement
regular-expression = \RuleName(replacement)

where regular-expression is a POSIX 1003.2 extended regular expression, and replacement is a string that gets substituted in place of any portion of the dial string 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 that white space needs to be escaped with a \ character or the entire string should be enclosed in quote (") marks. Don't get caught slipping. 💀

Replacement strings may reference the entire string matched by the regular expression with the & character. And 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. 👑

If \RuleName(replacement) is used, then the dial rule set RuleName will be recursively applied to the expanded replacement, and the result is used as the replacement for the matched pattern before continuing to process the transformation rules. Recursion, but make it dialing. 🌀

---

🦋 Variables, because parameterizing is self-care 🦋

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 get 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. Main character energy only. 👑

---

✨ The three well-known rule set names ✨

There are three well known rule set names, and you should know them by heart, no cap:

• CanonicalNumber — to convert a dial string to a canonical format.
• DialString — to prepare a dial string before using it to dial the telephone.
• 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.

---

🌈 External transformation rules 🌈

External transformation rules are interpolated by referencing them as:

~{executable}

Here, executable refers to the path to an executable which will be provided the matched data as its first parameter. The full output of the executable will be used as the replacement for the matched data. Go off, little subprocess. 🫶

---

🔥 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
]

Let's break it down, because it's lowkey genius:

• 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). Cute AND functional.
• 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. Slay. 💅

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''. 🎉 Ate and left no crumbs.

---

💜 SEE ALSO 💜

• sendfax(1)
• dialtest(8C)
• faxq(8C)
• faxsend(8C)
• faxgetty(8C)
• hylafax-config(5F)

---

Okay bestie that's the whole page!! 💖✨ This was DIALRULES(5F), dated May 8, 1996 — yes, the date is literally from the nineties and it's still serving, periodt. 🎀 Go forth and canonicalize responsibly. 🦋