postal

libpostal address parsing and normalization library bindings for Kit

Files

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-postal.git

System Requirements

Note: libpostal requires a one-time model download (~2 GB) on first use.

Usage

import Kit.Postal as Postal

main = fn =>
  match Postal.setup
    | Ok _ ->
      match Postal.setup-parser
        | Ok _ ->
          # Parse a US address
          components = Postal.parse-address "123 Main Street, New York, NY 10001"
          println ("Components: " ++ components)

          # Parse with country hint
          uk = Postal.parse-address-with-hint "10 Downing Street, London" "en" "GB"
          println ("UK: " ++ uk)

          # Parse international address
          fr = Postal.parse-address "5 Avenue Anatole France, 75007 Paris, France"
          println ("French: " ++ fr)

          # Normalize an address
          match Postal.setup-language-classifier
            | Ok _ ->
              normalized = Postal.normalize "123 E Main St, Apt 4B, NYC, NY"
              println ("Normalized: " ++ normalized)
              Postal.teardown-language-classifier
            | Err e -> println ("Classifier error: " ++ e)

          Postal.teardown-parser
        | Err e -> println ("Parser error: " ++ e)
      Postal.teardown
    | Err e -> println ("Setup error: " ++ e)

main

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit

Compile examples to a native binary:

kit build examples/basic.kit && ./basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Format and check source files in src/
2. Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/postal/, making it available for import as Kit.Postal in other projects.

License

This package is released under the MIT License - see LICENSE for details.

libpostal is released under the MIT License.

Exported Functions & Types

setup

Initialize the libpostal library. Must be called before any other function.

Returns:

Result Unit String

setup-parser

Initialize the address parser. Call after setup.

Returns:

Result Unit String

setup-language-classifier

Initialize the language classifier. Call after setup.

Returns:

Result Unit String

teardown

Tear down the libpostal library. Call when done.

Unit

teardown-parser

Tear down the address parser.

Unit

teardown-language-classifier

Tear down the language classifier.

Unit

parse-address

Parse an address into labeled components.

Returns pipe-separated "label:value" pairs. Labels include: house_number, road, city, state, postcode, country, etc.

Parameters:

Returns:

String -> String

parse-address-with-hint

Parse an address with language and country hints.

Parameters:

Returns:

String -> String -> String -> String

normalize

Normalize an address to canonical forms.

Returns pipe-separated normalized variations. Expands abbreviations, normalizes directions, etc.

Parameters:

Returns:

String -> String

normalize-with-language

Normalize an address with a language hint.

Parameters:

Returns:

String -> String -> String