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