#dialnumber

#What it does

• Parse an E.164 number (+81 90-1234-5678), a number dialled internationally (011 44 20 7946 0958 from the NANP), or a number dialled nationally with a region hint (090-1234-5678 in Japan) into a PhoneNumber.
• Check possibility — the cheap test: a known calling code and a length the plan uses.
• Check validity — the rule test: the national number must match one of the plan's published patterns. This is libphonenumber's "valid" verdict, and it is a real decision procedure rather than a length check.
• Name the number type the rules report: fixed-line, mobile, the shared fixed-line-or-mobile, toll-free, premium-rate, shared-cost, voip, uan, personal, pager, voicemail — with libphonenumber's precedence between them.
• Resolve the region of a number, including every calling code several territories share. All 25 territories of the +1 space resolve from their own area-code allocation, so +1 204… is Canada, +1 787… is Puerto Rico and +1 868… is Trinidad and Tobago.
• Format to E.164, international, national, or an RFC 3966 tel: URI — and the two human renderings carry the plan's own grouping: (201) 555-0123, 020 7946 0958, 090-1234-5678, +55 11 98765-4321.
• Look up regions by code or by calling code, with the plan's international and national prefixes, the lengths it uses and the raw rules behind a verdict.
• Read and write RFC 3966 tel: URIs with the full grammar: global and local numbers, numeric or domain ;phone-context=, ;ext= and ;isub=. Parsing keeps each part separate, and the parser and serialiser are inverses.

#Two levels of validation

///|
let pn = @dialnumber.parse("+1 204-254-5000", "")

///|
match pn {
  Some(n) => {
    @dialnumber.region_of_number(n)  // Some("CA")
    @dialnumber.is_possible(n)      // true
    @dialnumber.is_valid(n)         // true
    @dialnumber.number_type(n)      // Some(FixedLineOrMobile)
  }
  None => ()
}

#The plans' own grouping

///|
let us = @dialnumber.PhoneNumber::new(1, "2015550123")
@dialnumber.format_national(us, "US")        // Some("(201) 555-0123")
@dialnumber.format_international(us)         // "+1 201-555-0123"

///|
let gb = @dialnumber.PhoneNumber::new(44, "2079460958")
@dialnumber.format_national(gb, "GB")        // Some("020 7946 0958")
@dialnumber.format_international(gb)         // "+44 20 7946 0958"

#The rule engine

• Linear in pattern size times input length. There is no backtracking, so no pattern can make a validation call explode — the failure mode that makes regex-based validators unsafe on hostile input simply does not exist here.
• Total. A pattern that does not parse matches nothing, so a bad data row can never become a false positive. pattern_well_formed exposes the same check.
• Data, not code. The rules are strings in the generated table; a plan that changes its ranges is a data refresh, not a source change.

///|
@dialnumber.matches_pattern("[2-9]\\d{9}", "2042545000")  // true
@dialnumber.matches_pattern("[2-9]\\d{9}", "204254500")   // false: full match only
@dialnumber.pattern_well_formed("[2-9]\\d{9}")            // true
@dialnumber.plan_pattern("DK")                            // Some("[2-9]\\d{7}")

#Where the data comes from, and how it is maintained

PhoneNumberMetadata.xml          upstream, Apache-2.0, pinned by SHA-256
        |  scripts/update-metadata.mjs      fetch, extract, validate the grammar
        v
data/numbering-plans.json        one record per region: prefixes, types,
        |                        patterns, lengths, example numbers,
        |                        and the formatting rules
        |  scripts/gen-metadata.mjs         emit MoonBit
        v
plan_data.mbt                    the table the library compiles
plan_examples_test.mbt           1 132 published example numbers as golden tests
plan_corpus_test.mbt             the engine cross-checked against a regex engine

node scripts/update-metadata.mjs   # fetch a fresh copy of the upstream XML
node scripts/gen-metadata.mjs      # regenerate the table and the example tests
node scripts/gen-corpus.mjs        # regenerate the differential corpus
node scripts/check-docs.mjs        # verify the docs still match real output

#Coverage: 245 plans and the whole NANP

///|
@dialnumber.nanp_region_codes().length()  // 25
@dialnumber.nanp_region_of("2042545000")  // Some("CA")
@dialnumber.nanp_region_of("7872345678")  // Some("PR")
@dialnumber.nanp_region_of("2011550123")  // None: NXX starts with 1

#RFC 3966 without losing the context

• numeric context resolves: the context prefix and the local digits form an E.164 number;
• domain context parses, serialises and round-trips, but does not resolve, because answering it requires asking that domain.

#Relationship to other MoonBit libraries

#Install

moon add sssssurf/dialnumber

#Quick start

///|
let pn = @dialnumber.parse("011 44 20 7946 0958", "US")

///|
match pn {
  Some(n) => {
    @dialnumber.format_e164(n)           // "+442079460958"
    @dialnumber.format_national(n, "GB") // Some("020 7946 0958")
    @dialnumber.is_possible(n)           // true
    @dialnumber.is_valid(n)              // true
    @dialnumber.region_of_number(n)      // Some("GB")
  }
  None => ()
}

#Command line

moon run cmd/main -- parse "+81 90-1234-5678"
moon run cmd/main -- valid "+1 787-234-5678"
moon run cmd/main -- possible "090-1234-5678" JP
moon run cmd/main -- format "090-1234-5678" JP
moon run cmd/main -- types "+86 131 2345 6789"
moon run cmd/main -- region "+442079460958"
moon run cmd/main -- info JP
moon run cmd/main -- cc de
moon run cmd/main -- tel "tel:555-0123;phone-context=+1-919;ext=42"
moon run cmd/main -- match "\d{8}" 12345678
moon run cmd/main -- list

$ moon run cmd/main -- parse "+81 90-1234-5678"
country_code: 81
national_number: 9012345678
e164: +819012345678
region: JP

$ moon run cmd/main -- valid "+1 787-234-5678"
valid: yes
type: fixed-line-or-mobile
region: PR

$ moon run cmd/main -- types "+86 131 2345 6789"
length candidates: fixed-line,mobile,shared-cost
pattern verdict: mobile

$ moon run cmd/main -- info JP
region: JP
name: Japan
calling_code: 81
idd: 010
national_prefix: 0
lengths: 8,9,10,11,12,13,14,15,16,17

$ moon run cmd/main -- tel "tel:555-0123;phone-context=+1-919;ext=42"
global_number: (none)
local_number: 5550123
phone_context: +1919
extension: 42
isub: (none)
resolved: +19195550123

$ moon run cmd/main -- match "\d{8}" 12345678
well_formed: yes
matches: yes

#API

#Performance

#Tests

• one block per region, asserting that every published example number is accepted by its plan, resolves to the region the data says, reports a plausible type, and — for fixed-line and mobile examples — reads back as the same number when its national rendering is parsed again;
• a differential corpus that runs every published rule against its example and a mutated near miss, with the expected answer computed by an independent regular-expression engine;
• property tests: a deterministic generator walks random numbers through the invariants (an E.164 rendering parses back to itself, a valid number is always possible, a reported type implies validity), and random text through every entry point;
• whitebox checks that the table matches the metadata counts, that every rule is inside the engine's grammar, and that the NANP is complete;
• unit tests for the grammar, the operators, the refusals, matching time on long input, the grouping of a dozen plans, and the round-trip invariant;
• a robustness suite that feeds junk, 500-digit numbers and lone separators through every public entry point.

moon test

#License