ExConstructor

https://hexdocs.pm/exconstructor/1.3.1/
Admin
ExConstructor is an Elixir library that makes it easy to instantiate structs from external data,...
Tokens:1,841
Snippets:16
Trust Score:9
Update:4 months ago
Show doc for...
Tokens:
Raw
### ExConstructor Usage Example

Source: https://hexdocs.pm/exconstructor/ExConstructor.html

Demonstrates how to use ExConstructor with a sample struct. The `new` function automatically handles various key formats and data types.

```APIDOC
## Example
```elixir
defmodule TestStruct do
  use ExConstructor
  defstruct field_one: 1,
            field_two: 2,
            field_three: 3,
            field_four: 4
end

TestStruct.new(%{"field_one" => "a", "fieldTwo" => "b", :field_three => "c", :FieldFour => "d"})
# => %TestStruct{field_one: "a", field_two: "b", field_three: "c", field_four: "d"}
```
```

--------------------------------

### Populate Struct with Map, Keyword List, and Options

Source: https://hexdocs.pm/exconstructor/ExConstructor.html

The `populate_struct/3` function allows for more control by accepting an explicit options map to customize key format handling (e.g., disabling string keys or camelCase).

```elixir
@spec populate_struct(
  struct(),
  map_or_kwlist(),
  %ExConstructor.Options{
    atoms: term(),
    camelcase: term(),
    strings: term(),
    underscore: term(),
    uppercamelcase: term()
  }
  | map_or_kwlist()
) :: struct()
```

--------------------------------

### __using__(name_or_opts \\ :new)

Source: https://hexdocs.pm/exconstructor/ExConstructor.html

Macro to define a constructor for the current module's struct. It accepts an atom for the constructor name or a keyword list. It uses `populate_struct/3` internally and handles various key formats automatically.

```APIDOC
## __using__(name_or_opts \\ :new)
(macro)
`use ExConstructor` defines a constructor for the current module's struct.
If `name_or_opts` is an atom, it will be used as the constructor name. If `name_or_opts` is a keyword list, `name_or_opts[:name]` will be used as the constructor name. By default, `:new` is used.
Additional options in `name_or_opts` are stored in the `@exconstructor_default_options` module attribute.
The constructor is implemented in terms of `populate_struct/3`. It accepts a map or keyword list of keys and values `map_or_kwlist`, and an optional `opts` keyword list.
Keys of `map_or_kwlist` may be strings or atoms, in camelCase or under_score format.
`opts` may contain keys `strings`, `atoms`, `camelcase` and `underscore`. Set these keys false to prevent testing of that key format in `map_or_kwlist`. All default to `true`.
For the default name `:new`, the constructor's definition looks like:
```elixir
@spec new(ExConstructor.map_or_kwlist, Keyword.t) :: %__MODULE__{}
def new(map_or_kwlist, opts \ []) do
  ExConstructor.populate_struct(%__MODULE__{}, map_or_kwlist, Keyword.merge(@exconstructor_default_options, opts))
end
defoverridable [new: 1, new: 2]
```

Overriding `new/2` is allowed; the generated function can be called by `super`. Example uses include implementing your own `opts` handling.
```

--------------------------------

### define_constructor(name_or_opts \\ :new)

Source: https://hexdocs.pm/exconstructor/ExConstructor.html

Alias for `__using__/1`, providing an alternative way to explicitly invoke the constructor definition.

```APIDOC
## define_constructor(name_or_opts \\ :new)
(macro)
Alias for `__using__`, for those who prefer an explicit invocation.
```

--------------------------------

### Populate Struct with Map or Keyword List

Source: https://hexdocs.pm/exconstructor/ExConstructor.html

The `populate_struct/2` function creates a copy of a given struct and applies values from a map or keyword list. It handles various key formats automatically.

```elixir
@spec populate_struct(
  struct(),
  map_or_kwlist()
) :: struct()
```

--------------------------------

### populate_struct(struct, map_or_kwlist, opts)

Source: https://hexdocs.pm/exconstructor/ExConstructor.html

Returns a copy of the struct with values applied from the map or keyword list, allowing for custom options to control key format handling (strings, atoms, camelCase, underscore, UpperCamelCase).

```APIDOC
## populate_struct(struct, map_or_kwlist, opts)
```elixir
@spec populate_struct(
  struct(),
  map_or_kwlist(),
  %ExConstructor.Options{
    atoms: term(),
    camelcase: term(),
    strings: term(),
    underscore: term(),
    uppercamelcase: term()
  }
  | map_or_kwlist()
) :: struct()
```

Returns a copy of `struct` into which the values in `map_or_kwlist` have been applied.
Keys of `map_or_kwlist` may be strings or atoms, in camelCase, UpperCamelCase, or under_score format.
`opts` may contain keys `strings`, `atoms`, `camelcase`, `uppercamelcase`, and `underscore`. Set these keys false to prevent testing of that key format in `map_or_kwlist`. All default to `true`.
```

--------------------------------

### Add ExConstructor to Mix Dependencies

Source: https://hexdocs.pm/exconstructor/ExConstructor.html

To use ExConstructor, add it to your project's `mix.exs` file under the `deps` function.

```elixir
def deps do
  [{:exconstructor, "~> 1.3.1"}]
end
```

--------------------------------

### populate_struct(struct, map_or_kwlist)

Source: https://hexdocs.pm/exconstructor/ExConstructor.html

Returns a copy of the given struct with values applied from the provided map or keyword list. Handles string/atom keys and camelCase/under_score formats.

```APIDOC
## populate_struct(struct, map_or_kwlist)
```elixir
@spec populate_struct(
  struct(),
  map_or_kwlist()
) :: struct()
```

Returns a copy of `struct` into which the values in `map_or_kwlist` have been applied.
Keys of `map_or_kwlist` may be strings or atoms, in camelCase or under_score format.
```

--------------------------------

### Generated `new/2` Function Signature

Source: https://hexdocs.pm/exconstructor/ExConstructor.html

Shows the default generated `new/2` function signature when using `ExConstructor`, which accepts a map or keyword list and an optional options list.

```elixir
@spec new(ExConstructor.map_or_kwlist, Keyword.t) :: %__MODULE__{}
```

--------------------------------

### Basic ExConstructor Usage with Struct Definition

Source: https://hexdocs.pm/exconstructor/ExConstructor.html

Use `ExConstructor` after a `defstruct` to automatically generate a `new` function for your struct. This function handles various input key formats.

```elixir
defmodule TestStruct do
  use ExConstructor
  defstruct field_one: 1,
            field_two: 2,
            field_three: 3,
            field_four: 4,
end

TestStruct.new(%{"field_one" => "a", "fieldTwo" => "b", :field_three => "c", :FieldFour => "d"})
# => %TestStruct{field_one: "a", field_two: "b", field_three: "c", field_four: "d"}
```

--------------------------------

### ExConstructor Type Definition for Input Data

Source: https://hexdocs.pm/exconstructor/ExConstructor.html

Defines the accepted types for data passed to ExConstructor functions, including maps and keyword lists with string or atom keys.

```elixir
@type map_or_kwlist() ::
  %{required(String.t()) => any()} 
  | %{required(atom()) => any()} 
  | [{String.t(), any()}]
  | [{atom(), any()}]
```
Tokens:
Raw