gleam-lang / package-interface

📦 Work with Gleam's package interfaces

gleam_package_interface

Installation

Add gleam_package_interface to your Gleam project:

gleam add gleam_package_interface

What's a package interface?

Whenever you build your project's documentation with gleam docs build, the Gleam compiler will also produce a handy json file ./build/dev/docs/<your package>/package-interface.json containing data about your package: that's the package interface.

It has all public information your package exposes to the outside world: type definitions, type aliases, public functions and constants — each annotated with its own type and with its documentation.

You can also have the compiler build the package interface using the gleam export package-interface command.

Let's have a look at a small example. Imagine you have a module called wibble with the following definition:

/// Documentation!
pub fn wibbler(label n: Int) -> Int {
  todo
}

The resulting package interface will look something like this (some keys where omitted to keep the example short):

{
  "package": "your package",
  "modules": {
    "wibble": {
      "functions": {
        "wibbler": {
          "documentation": "Documentation!\n",
          "parameters": [
            {
              "label": "label",
              "type": {
                "kind": "named",
                "package": "",
                "module": "gleam",
                "name": "Int"
              }
            }
          ],
          "return": {
            "kind": "named",
            "package": "",
            "module": "gleam",
            "name": "Int"
          }
        }
      }
    }
  }
}

To get a proper feel of the structure of the generated package interface you can have a look at this package's types.

Usage

This package provides Gleam types to describe a package interface and a decoder to decode the json package interface into a Gleam value.

// gleam add gleam_json
// gleam add simplifile
import gleam/json
import gleam/package_interface
import simplifile

pub fn main() {
  let assert Ok(json) = simplifile.read("path to the package interface")
  let assert Ok(interface) = json.decode(json, using: package_interface.decoder)
  todo as "now you can use the package interface however you want!"
}