API renovation

Author: lpil

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v1.0.0-rc1 - Unreleased
+
+- The `gleam/erlang/os` module has been removed.
+- The `gleam/erlang` module has been removed.
+- The `gleam/erlang/reference` module has been created with the `Reference`
+  type, and the `new` function.
+- In the `gleam/erlang/atom` module:
+  - The `AtomNotLoaded` type has been removed.
+  - The error type of `from_string` is now `Nil`.
+  - The `from_string` function has been renamed to `get`.
+  - The `create_from_string` function has been renamed to `create`.
+- The `gleam/erlang/application` module was created with:
+  - The `priv_directory` function, formerly of the `gleam/erlang` module.
+  - The `StartType` type.
+
 ## v0.34.0 - 2025-02-02
 
 - Fixed deprecation warnings with the Gleam standard library v0.53.0 or later.

src/gleam/erlang.gleam

@@ -0,0 +1,35 @@
+//// An Erlang application is a collection of code that can be loaded into the
+//// Erlang virtual machine and even started and stopped if they define a
+//// start module and supervision tree. Each Gleam package is an Erlang
+//// application.
+
+import gleam/erlang/node.{type Node}
+
+pub type StartType {
+  /// A normal application start.
+  Normal
+  /// The application is distributed and started at the current node because of
+  /// a takeover from Node, either because Erlang's `application:takeover/2`
+  /// function has been called, or because the current node has higher priority
+  /// than the previous node.
+  Takeover(previous: Node)
+  // The application is distributed and started at the current node because of
+  // a failover from the previous node.
+  Failover(previous: Node)
+}
+
+/// Returns the path of an application's `priv` directory, where extra non-Gleam
+/// or Erlang files are typically kept. Each Gleam package is an Erlang
+/// application.
+///
+/// Returns an error if no application was found with the given name.
+///
+/// # Example
+///
+/// ```gleam
+/// application.priv_directory("my_app")
+/// // -> Ok("/some/location/my_app/priv")
+/// ```
+///
+@external(erlang, "gleam_erlang_ffi", "priv_directory")
+pub fn priv_directory(name: String) -> Result(String, Nil)

src/gleam/erlang/application.gleam

@@ -1,6 +1,3 @@
-import gleam/dynamic.{type Dynamic}
-import gleam/dynamic/decode.{type DecodeError}
-
 /// Atom is a special string-like data-type that is most commonly used for
 /// interfacing with code written in other BEAM languages such as Erlang and
 /// Elixir. It is preferable to define your own custom types to use instead of
@@ -18,29 +15,13 @@ import gleam/dynamic/decode.{type DecodeError}
 ///
 pub type Atom
 
-/// An error returned when no atom is found in the virtual machine's atom table
-/// for a given string when calling the [`from_string`](#from_string) function.
-pub type FromStringError {
-  AtomNotLoaded
-}
-
-/// Finds an existing Atom for the given String.
+/// Finds an existing atom for the given string.
 ///
-/// If no atom is found in the virtual machine's atom table for the String then
+/// If no atom is found in the virtual machine's atom table for the string then
 /// an error is returned.
 ///
-/// ## Examples
-/// ```gleam
-/// from_string("ok")
-/// // -> Ok(create_from_string("ok"))
-/// ```
-/// ```gleam
-/// from_string("some_new_atom")
-/// // -> Error(AtomNotLoaded)
-/// ```
-///
 @external(erlang, "gleam_erlang_ffi", "atom_from_string")
-pub fn from_string(a: String) -> Result(Atom, FromStringError)
+pub fn get(a: String) -> Result(Atom, Nil)
 
 /// Creates an atom from a string, inserting a new value into the virtual
 /// machine's atom table if an atom does not already exist for the given
@@ -52,34 +33,17 @@ pub fn from_string(a: String) -> Result(Atom, FromStringError)
 /// virtual machine to crash!
 ///
 @external(erlang, "erlang", "binary_to_atom")
-pub fn create_from_string(a: String) -> Atom
+pub fn create(a: String) -> Atom
 
 /// Returns a `String` corresponding to the text representation of the given
 /// `Atom`.
 ///
 /// ## Examples
 /// ```gleam
-/// let ok_atom = create_from_string("ok")
+/// let ok_atom = create("ok")
 /// to_string(ok_atom)
 /// // -> "ok"
 /// ```
 ///
 @external(erlang, "erlang", "atom_to_binary")
 pub fn to_string(a: Atom) -> String
-
-/// Checks to see whether a `Dynamic` value is an atom, and return the atom if
-/// it is.
-///
-/// ## Examples
-/// ```gleam
-/// import gleam/dynamic
-/// from_dynamic(dynamic.from(create_from_string("hello")))
-/// // -> Ok(create_from_string("hello"))
-/// ```
-/// ```gleam
-/// from_dynamic(dynamic.from(123))
-/// // -> Error([DecodeError(expected: "Atom", found: "Int", path: [])])
-/// ```
-///
-@external(erlang, "gleam_erlang_ffi", "atom_from_dynamic")
-pub fn from_dynamic(from from: Dynamic) -> Result(Atom, List(DecodeError))

src/gleam/erlang/atom.gleam

@@ -5,21 +5,20 @@
 //// interfacing with Erlang, in particular when using older libraries that do
 //// not accept binaries as arguments.
 
-/// A list of characters represented as ints. Commonly used by older Erlang
-/// modules.
+/// A list of characters represented as ints. Commonly used with Erlang
+/// functions that do not accept binary strings such as Gleam's core string
+/// type.
+///
 pub type Charlist
 
-/// Transform a charlist to a string
+/// Convert a charlist to a string using Erlang's
+/// `unicode:characters_to_binary`.
+///
 @external(erlang, "unicode", "characters_to_binary")
 pub fn to_string(a: Charlist) -> String
 
-// Calls `unicode:characters_to_binary(Data, unicode, unicode)`
-// Note: `unicode is an alias for utf8`
-// See <https://www.erlang.org/doc/man/unicode.html#characters_to_binary-1>
-
-/// Transform a string to a charlist
+/// Convert a string to a charlist using Erlang's
+/// `unicode:characters_to_list`.
+///
 @external(erlang, "unicode", "characters_to_list")
 pub fn from_string(a: String) -> Charlist
-// Calls `unicode:characters_to_list(Data, unicode)`
-// Note: `unicode is an alias for utf8`
-// See <https://www.erlang.org/doc/man/unicode.html#characters_to_list-1>