Add the package interface decoders

* add decoders * run js tests in CI * README!
gleam-lang · Feb 29, 2024 · 162e077 · 162e077
1 parent 869903a
commit 162e077
Show file tree

Hide file tree

Showing 10 changed files with 1,227 additions and 14 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -17,7 +17,7 @@ jobs:
           otp-version: "26.0.2"
           gleam-version: "0.34.1"
           rebar3-version: "3"
-          # elixir-version: "1.15.4"
       - run: gleam deps download
-      - run: gleam test
+      - run: gleam test --target=erlang
+      - run: gleam test --target=javascript
       - run: gleam format --check src test
diff --git a/CHANGELOG b/CHANGELOG
@@ -0,0 +1 @@
+# Changelog
diff --git a/README.md b/README.md
@@ -2,17 +2,94 @@
 
 [![Package Version](https://img.shields.io/hexpm/v/gleam_package_interface)](https://hex.pm/packages/gleam_package_interface)
 [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/gleam_package_interface/)
+![Supported targets](https://img.shields.io/badge/supports-all_targets-ffaff3)
+
+## Installation
+
+Add `gleam_package_interface` to your Gleam project:
 
 ```sh
 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:
+
 ```gleam
-import gleam_package_interface
+/// Documentation!
+pub fn wibbler(label n: Int) -> Int {
+  todo
+}
+```
 
-pub fn main() {
-  // TODO: An example of the project in use
+The resulting package interface will look something like this (some keys where
+omitted to keep the example short):
+
+```json
+{
+  "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"
+          }
+        }
+      }
+    }
+  }
 }
 ```
 
-Further documentation can be found at <https://hexdocs.pm/gleam_package_interface>.
+To get a proper feel of the structure of the generated package interface you can
+have a look at this
+[package's types](https://hexdocs.pm/gleam_package_interface/).
+
+## 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
+// 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!"
+}
+```
diff --git a/birdie_snapshots/decoding_a_module_interface.accepted b/birdie_snapshots/decoding_a_module_interface.accepted
@@ -0,0 +1,164 @@
+---
+version: 1.0.4
+title: Decoding a module interface
+---
+Package(
+  name: "gleam_package_interface",
+  version: "1.0.0",
+  gleam_version_contraint: None(),
+  modules: {
+    my_module: Module(
+        documentation: [],
+        type_aliases: {
+          Wobble: TypeAlias(
+              alias: Named(
+                package: "gleam_package_interface",
+                module: "my_module",
+                name: "Wibble",
+                parameters: [
+                  Named(
+                    package: "",
+                    module: "gleam",
+                    name: "Int",
+                    parameters: [],
+                  ),
+                ],
+              ),
+              deprecation: Some(
+                item: Deprecation(message: "this is deprecated!"),
+              ),
+              documentation: Some(item: " Documentation!"),
+              parameters: 0,
+            ),
+        },
+        constants: {
+          wabble: Constant(
+              deprecation: None(),
+              documentation: None(),
+              implementations: Implementations(
+                gleam: True,
+                uses_erlang_externals: False,
+                uses_javascript_externals: False,
+              ),
+              type_: Fn(
+                parameters: [
+                  Named(
+                    package: "",
+                    module: "gleam",
+                    name: "String",
+                    parameters: [],
+                  ),
+                ],
+                return: Named(
+                  package: "gleam_package_interface",
+                  module: "my_module",
+                  name: "Wibble",
+                  parameters: [Variable(id: 0)],
+                ),
+              ),
+            ),
+          wibble: Constant(
+              deprecation: None(),
+              documentation: Some(item: " Documentation!"),
+              implementations: Implementations(
+                gleam: True,
+                uses_erlang_externals: False,
+                uses_javascript_externals: False,
+              ),
+              type_: Named(
+                package: "gleam_package_interface",
+                module: "my_module",
+                name: "Wibble",
+                parameters: [
+                  Named(
+                    package: "",
+                    module: "gleam",
+                    name: "Int",
+                    parameters: [],
+                  ),
+                ],
+              ),
+            ),
+          wobble: Constant(
+              deprecation: None(),
+              documentation: None(),
+              implementations: Implementations(
+                gleam: True,
+                uses_erlang_externals: False,
+                uses_javascript_externals: False,
+              ),
+              type_: Tuple(
+                elements: [
+                  Named(
+                    package: "",
+                    module: "gleam",
+                    name: "Int",
+                    parameters: [],
+                  ),
+                  Named(
+                    package: "",
+                    module: "gleam",
+                    name: "Int",
+                    parameters: [],
+                  ),
+                ],
+              ),
+            ),
+        },
+        functions: {
+          main: Function(
+              deprecation: None(),
+              documentation: Some(item: " Documentation!"),
+              implementations: Implementations(
+                gleam: True,
+                uses_erlang_externals: False,
+                uses_javascript_externals: False,
+              ),
+              parameters: [
+                Parameter(
+                  label: Some(item: "wibble"),
+                  type: Named(
+                    package: "",
+                    module: "gleam",
+                    name: "String",
+                    parameters: [],
+                  ),
+                ),
+              ],
+              return: Named(
+                package: "gleam_package_interface",
+                module: "my_module",
+                name: "Wibble",
+                parameters: [Variable(id: 0)],
+              ),
+            ),
+        },
+        types: {
+          Wibble: TypeDefinition(
+              constructors: [
+                TypeConstructor(
+                  documentation: Some(item: " Documentation!"),
+                  name: "Wibble",
+                  parameters: [
+                    Parameter(label: Some(item: "label"), type: Variable(id: 0)),
+                  ],
+                ),
+                TypeConstructor(
+                  documentation: Some(item: " Documentation!"),
+                  name: "Wobble",
+                  parameters: [Parameter(label: None(), type: Variable(id: 0))],
+                ),
+                TypeConstructor(
+                  documentation: None(),
+                  name: "Wabble",
+                  parameters: [],
+                ),
+              ],
+              deprecation: None(),
+              documentation: Some(item: " Documentation!"),
+              parameters: 1,
+            ),
+        },
+      ),
+  },
+)
diff --git a/gleam.toml b/gleam.toml
@@ -8,6 +8,10 @@ links = [{ title = "Website", href = "https://gleam.run" }]
 
 [dependencies]
 gleam_stdlib = "~> 0.34 or ~> 1.0"
+gleam_json = "~> 1.0"
 
 [dev-dependencies]
 gleeunit = "~> 1.0"
+simplifile = "~> 1.4"
+birdie = "~> 1.0"
+glam = "~> 2.0"
diff --git a/manifest.toml b/manifest.toml
@@ -2,10 +2,27 @@
 # You typically do not need to edit this file
 
 packages = [
+  { name = "argv", version = "1.0.1", build_tools = ["gleam"], requirements = [], otp_app = "argv", source = "hex", outer_checksum = "A6E9009E50BBE863EB37D963E4315398D41A3D87D0075480FC244125808F964A" },
+  { name = "birdie", version = "1.0.4", build_tools = ["gleam"], requirements = ["argv", "filepath", "gap", "gleam_community_ansi", "gleam_erlang", "gleam_stdlib", "gleeunit", "justin", "rank", "simplifile"], otp_app = "birdie", source = "hex", outer_checksum = "0F7E16A3B12957B5B4A3B39152BD6D6175941AF40C1838F86C5A909DCFF7CF04" },
+  { name = "filepath", version = "0.2.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "filepath", source = "hex", outer_checksum = "FC1B1B29438A5BA6C990F8047A011430BEC0C5BA638BFAA62718C4EAEFE00435" },
+  { name = "gap", version = "1.1.0", build_tools = ["gleam"], requirements = ["gleam_community_ansi", "gleam_stdlib"], otp_app = "gap", source = "hex", outer_checksum = "2EE1B0A17E85CF73A0C1D29DA315A2699117A8F549C8E8D89FA8261BE41EDEB1" },
+  { name = "glam", version = "2.0.0", build_tools = ["gleam"], requirements = ["birdie", "gleam_stdlib"], otp_app = "glam", source = "hex", outer_checksum = "1C10BE5EA72659E409DC2325BA5E94E0CC92C6C50B2A1DBADE6D07E8C9484D51" },
+  { name = "gleam_community_ansi", version = "1.4.0", build_tools = ["gleam"], requirements = ["gleam_community_colour", "gleam_stdlib"], otp_app = "gleam_community_ansi", source = "hex", outer_checksum = "FE79E08BF97009729259B6357EC058315B6FBB916FAD1C2FF9355115FEB0D3A4" },
+  { name = "gleam_community_colour", version = "1.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_community_colour", source = "hex", outer_checksum = "A49A5E3AE8B637A5ACBA80ECB9B1AFE89FD3D5351FF6410A42B84F666D40D7D5" },
+  { name = "gleam_erlang", version = "0.24.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "26BDB52E61889F56A291CB34167315780EE4AA20961917314446542C90D1C1A0" },
+  { name = "gleam_json", version = "1.0.0", build_tools = ["gleam"], requirements = ["gleam_stdlib", "thoas"], otp_app = "gleam_json", source = "hex", outer_checksum = "8B197DD5D578EA6AC2C0D4BDC634C71A5BCA8E7DB5F47091C263ECB411A60DF3" },
   { name = "gleam_stdlib", version = "0.34.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "1FB8454D2991E9B4C0C804544D8A9AD0F6184725E20D63C3155F0AEB4230B016" },
   { name = "gleeunit", version = "1.0.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "D364C87AFEB26BDB4FB8A5ABDE67D635DC9FA52D6AB68416044C35B096C6882D" },
+  { name = "justin", version = "1.0.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "justin", source = "hex", outer_checksum = "7FA0C6DB78640C6DC5FBFD59BF3456009F3F8B485BF6825E97E1EB44E9A1E2CD" },
+  { name = "rank", version = "1.0.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "rank", source = "hex", outer_checksum = "5660E361F0E49CBB714CC57CC4C89C63415D8986F05B2DA0C719D5642FAD91C9" },
+  { name = "simplifile", version = "1.4.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "simplifile", source = "hex", outer_checksum = "C93A62CE23B2E44F969DC3134F9EE899C362B0A2F4181233CDD5D759F82EE486" },
+  { name = "thoas", version = "0.4.1", build_tools = ["rebar3"], requirements = [], otp_app = "thoas", source = "hex", outer_checksum = "4918D50026C073C4AB1388437132C77A6F6F7C8AC43C60C13758CC0ADCE2134E" },
 ]
 
 [requirements]
+birdie = { version = "~> 1.0" }
+glam = { version = "~> 2.0" }
+gleam_json = { version = "~> 1.0" }
 gleam_stdlib = { version = "~> 0.34 or ~> 1.0" }
 gleeunit = { version = "~> 1.0" }
+simplifile = { version = "~> 1.4" }