gleam_package_interface - v1.0.0

gleam/package_interface

Types

Constant

</>

A Gleam constant.

pub const my_favourite_number = 11

pub type Constant {
  Constant(
    documentation: Option(String),
    deprecation: Option(Deprecation),
    implementations: Implementations,
    type_: Type,
  )
}

Constructors 

  • Constant(
  documentation: Option(String),
  deprecation: Option(Deprecation),
  implementations: Implementations,
  type_: Type,
)

    Arguments

    • documentation

      The constant’s documentation comment (that is every line preceded by ///).

    • deprecation

      If the constant is deprecated this will hold the reason of the deprecation.

Deprecation

</>

A deprecation notice that can be added to definition using the @deprecated annotation.

pub type Deprecation {
  Deprecation(message: String)
}

Constructors 

  • Deprecation(message: String)

Function

</>

A Gleam function definition.

pub fn reverse(list: List(a)) -> List(a) { todo }

pub type Function {
  Function(
    documentation: Option(String),
    deprecation: Option(Deprecation),
    implementations: Implementations,
    parameters: List(Parameter),
    return: Type,
  )
}

Constructors 

  • Function(
  documentation: Option(String),
  deprecation: Option(Deprecation),
  implementations: Implementations,
  parameters: List(Parameter),
  return: Type,
)

    Arguments

    • documentation

      The function’s documentation comment (that is every line preceded by ///).

    • deprecation

      If the function is deprecated this will hold the reason of the deprecation.

Implementations

</>

Metadata about how a value is implemented and the targets it supports.

pub type Implementations {
  Implementations(
    gleam: Bool,
    uses_erlang_externals: Bool,
    uses_javascript_externals: Bool,
  )
}

Constructors 

  • Implementations(
  gleam: Bool,
  uses_erlang_externals: Bool,
  uses_javascript_externals: Bool,
)

    Arguments

    • gleam

      Set to True if the const/function has a pure Gleam implementation (that is, it never uses external code). Being pure Gleam means that the function will support all Gleam targets, even future ones that are not present to this day.

      Consider the following function:

      @external(erlang, "foo", "bar")
pub fn a_random_number() -> Int {
  4
  // This is a default implementation.
}

      The implementations for this function will look like this:

      Implementations(
  gleam: True,
  uses_erlang_externals: True,
  uses_javascript_externals: False,
)
      • gleam: True means that the function has a pure Gleam implementation and thus it can be used on all Gleam targets with no problems.
      • uses_erlang_externals: True means that the function will use Erlang external code when compiled to the Erlang target.
      • uses_javascript_externals: False means that the function won’t use JavaScript external code when compiled to JavaScript. The function can still be used on the JavaScript target since it has a pure Gleam implementation.

    • uses_erlang_externals

      Set to True if the const/function is defined using Erlang external code. That means that the function will use Erlang code through FFI when compiled for the Erlang target.

    • uses_javascript_externals

      Set to True if the const/function is defined using JavaScript external code. That means that the function will use JavaScript code through FFI when compiled for the JavaScript target.

      Let’s have a look at an example:

      @external(javascript, "foo", "bar")
pub fn javascript_only() -> Int

      It’s implementations field will look like this:

      Implementations(
  gleam: False,
  uses_erlang_externals: False,
  uses_javascript_externals: True,
)
      • gleam: False means that the function doesn’t have a pure Gleam implementations. This means that the function is only defined using externals and can only be used on some targets.
      • uses_erlang_externals: False the function is not using external Erlang code. So, since the function doesn’t have a fallback pure Gleam implementation, you won’t be able to compile it on this target.
      • uses_javascript_externals: True the function is using JavaScript external code. This means that you will be able to use it on the JavaScript target with no problems.

Module

</>

A Gleam module.

pub type Module {
  Module(
    documentation: List(String),
    type_aliases: Dict(String, TypeAlias),
    types: Dict(String, TypeDefinition),
    constants: Dict(String, Constant),
    functions: Dict(String, Function),
  )
}

Constructors 

  • Module(
  documentation: List(String),
  type_aliases: Dict(String, TypeAlias),
  types: Dict(String, TypeDefinition),
  constants: Dict(String, Constant),
  functions: Dict(String, Function),
)

    Arguments

    • documentation

      All the lines composing the module’s documentation (that is every line preceded by a ////).

    • type_aliases

      The public type aliases defined in the module.

    • types

      The public custom types defined in the module.

    • constants

      The public constants defined in the module.

    • functions

      The public functions defined in the module.

Package

</>

A Gleam package.

pub type Package {
  Package(
    name: String,
    version: String,
    gleam_version_constraint: Option(String),
    modules: Dict(String, Module),
  )
}

Constructors 

  • Package(
  name: String,
  version: String,
  gleam_version_constraint: Option(String),
  modules: Dict(String, Module),
)

    Arguments

    • gleam_version_constraint

      The Gleam version constraint that the package specifies in its gleam.toml.

Parameter

</>

A parameter (that might be labelled) of a module function or type constructor.

pub fn map(over list: List(a), with fun: fn(a) -> b) -> b { todo }
//         ^^^^^^^^^^^^^^^^^^ A labelled parameter.

pub type Parameter {
  Parameter(label: Option(String), type_: Type)
}

Constructors 

  • Parameter(label: Option(String), type_: Type)

Type

</>

A Gleam type.

pub type Type {
  Tuple(elements: List(Type))
  Fn(parameters: List(Type), return: Type)
  Variable(id: Int)
  Named(
    name: String,
    package: String,
    module: String,
    parameters: List(Type),
  )
}

Constructors 

  • Tuple(elements: List(Type))

    A tuple type like #(Int, Float).

  • Fn(parameters: List(Type), return: Type)

    A function type like fn(Int, a) -> List(a).

  • Variable(id: Int)

    A type variable.

    pub fn foo(value: a) -> a { todo }
//                ^ This is a type variable.

  • Named(
  name: String,
  package: String,
  module: String,
  parameters: List(Type),
)

    A custom named type.

    let value: Bool = True
//         ^^^^ Bool is a named type coming from Gleam's prelude

    All prelude types - like Bool, String, etc. - are named types as well. In that case, their package is an empty string "" and their module name is the string "gleam".

    Arguments

    • package

      The package the type comes from.

    • module

      The module the type is defined in.

    • parameters

      The concrete type’s type parameters .

      let result: Result(Int, e) = Ok(1)
//                ^^^^^^^^ The `Result` named type has 2 parameters.
//                         In this case it's the `Int` type and a
//                         type variable.

TypeAlias

</>

A Gleam type alias.

// This is a type alias.
type Ints = List(Int)

pub type TypeAlias {
  TypeAlias(
    documentation: Option(String),
    deprecation: Option(Deprecation),
    parameters: Int,
    alias: Type,
  )
}

Constructors 

  • TypeAlias(
  documentation: Option(String),
  deprecation: Option(Deprecation),
  parameters: Int,
  alias: Type,
)

    Arguments

    • documentation

      The type alias’ documentation comment (that is every line preceded by ///).

    • deprecation

      If the type alias is deprecated this will hold the reason of the deprecation.

    • parameters

      The number of type variables of the type alias.

      type Results(a, b) = List(Result(a, b))
//   ^^^^^^^^^^^^^ This type alias has 2 type variables.

type Ints = List(Int)
//   ^^^^ This type alias has 0 type variables.

    • alias

      The aliased type.

      type Ints = List(Int)
//          ^^^^^^^^^ This is the aliased type.

TypeConstructor

</>

A Gleam type constructor.

type Result(a, b) {
  Ok(a)
  Error(b)
}
// `Ok` and `Error` are the type constructors
// of the `Error` type.

pub type TypeConstructor {
  TypeConstructor(
    documentation: Option(String),
    name: String,
    parameters: List(Parameter),
  )
}

Constructors 

  • TypeConstructor(
  documentation: Option(String),
  name: String,
  parameters: List(Parameter),
)

    Arguments

    • documentation

      The type constructor’s documentation comment (that is every line preceded by ///).

    • parameters

      The parameters required by the constructor.

      type Box(a) {
  Box(content: a)
//    ^^^^^^^^^^ The `Box` constructor has a single
//               labelled argument.
}

TypeDefinition

</>

A Gleam custom type definition.

// This is a custom type definition.
pub type Result(a, b) {
  Ok(a)
  Error(b)
}

pub type TypeDefinition {
  TypeDefinition(
    documentation: Option(String),
    deprecation: Option(Deprecation),
    parameters: Int,
    constructors: List(TypeConstructor),
  )
}

Constructors 

  • TypeDefinition(
  documentation: Option(String),
  deprecation: Option(Deprecation),
  parameters: Int,
  constructors: List(TypeConstructor),
)

    Arguments

    • documentation

      The type definition’s documentation comment (that is every line preceded by ///).

    • deprecation

      If the type definition is deprecated this will hold the reason of the deprecation.

    • parameters

      The number of type variables of the type definition.

      type Result(a, b) { ... }
//   ^^^^^^^^^^^^ This type definition has 2 type variables.

type Person { ... }
//   ^^^^^^ This type alias has 0 type variables.

    • constructors

      The type constructors. If the type is opaque this list will be empty as the type doesn’t have any public constructor.

      type Result(a, b) {
  Ok(a)
  Error(b)
}
// `Ok` and `Error` are the type constructors
// of the `Error` type.

Functions

constant_decoder

</> 
pub fn constant_decoder(
  dynamic: Dynamic,
) -> Result(Constant, List(DecodeError))

constructor_decoder

</> 
pub fn constructor_decoder(
  dynamic: Dynamic,
) -> Result(TypeConstructor, List(DecodeError))

decoder

</> 
pub fn decoder(
  dynamic: Dynamic,
) -> Result(Package, List(DecodeError))

The package the type comes from.

The module the type is defined in.

The concrete type’s type parameters .

let result: Result(Int, e) = Ok(1)
//                ^^^^^^^^ The `Result` named type has 2 parameters.
//                         In this case it's the `Int` type and a
//                         type variable.

deprecation_decoder

</> 
pub fn deprecation_decoder(
  dynamic: Dynamic,
) -> Result(Deprecation, List(DecodeError))

function_decoder

</> 
pub fn function_decoder(
  dynamic: Dynamic,
) -> Result(Function, List(DecodeError))

implementations_decoder

</> 
pub fn implementations_decoder(
  dynamic: Dynamic,
) -> Result(Implementations, List(DecodeError))

module_decoder

</> 
pub fn module_decoder(
  dynamic: Dynamic,
) -> Result(Module, List(DecodeError))

parameter_decoder

</> 
pub fn parameter_decoder(
  dynamic: Dynamic,
) -> Result(Parameter, List(DecodeError))

type_alias_decoder

</> 
pub fn type_alias_decoder(
  dynamic: Dynamic,
) -> Result(TypeAlias, List(DecodeError))

type_decoder

</> 
pub fn type_decoder(
  dynamic: Dynamic,
) -> Result(Type, List(DecodeError))

type_definition_decoder

</> 
pub fn type_definition_decoder(
  dynamic: Dynamic,
) -> Result(TypeDefinition, List(DecodeError))
✨ Search Document