Merge branch 'release/0.2.1'

Author: ejpcmac

CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic
 Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2020-07-19
+
+### Added
+
+* Add the `module: ModuleName` top-level option to create the typed struct in a
+    submodule.
+
+### Changed
+
+* Update the `@typedoc` example in the documentation to put it inside the
+    `typedstruct` block and not above. While putting it above works in the
+    general case, it is mandatory to put it inside the block when defining a
+    submodule.
+
 ## [0.2.0] - 2020-05-31
 
 ### Added
@@ -64,6 +78,7 @@ Versioning](https://semver.org/spec/v2.0.0.html).
 * Default values
 * Enforced keys
 
+[0.2.1]: https://github.com/ejpcmac/typed_struct/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/ejpcmac/typed_struct/compare/v0.1.4...v0.2.0
 [0.1.4]: https://github.com/ejpcmac/typed_struct/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/ejpcmac/typed_struct/compare/v0.1.2...v0.1.3

CONTRIBUTING.md

@@ -144,9 +144,7 @@ To make a change, please use this workflow:
 6. Run the tests and static analyzers to ensure there is no regression and all
     works as expected:
 
-        $ mix test
-        $ mix dialyzer
-        $ mix credo
+        $ mix check
 
 7. If it’s all good, open a pull request to merge your branch into the `develop`
     branch on the main repository.

README.md

@@ -63,8 +63,9 @@ defmodule Person do
 
   use TypedStruct
 
-  @typedoc "A person"
   typedstruct do
+    @typedoc "A person"
+
     field :name, String.t(), enforce: true
     field :age, non_neg_integer()
     field :happy?, boolean(), default: true
@@ -82,7 +83,7 @@ Thanks to TypedStruct, this is now possible :)
 To use TypedStruct in your project, add this to your Mix dependencies:
 
 ```elixir
-{:typed_struct, "~> 0.2.0"}
+{:typed_struct, "~> 0.2.1"}
 ```
 
 If you do not plan to compile modules using TypedStruct at runtime, you can add
@@ -162,14 +163,41 @@ defmodule MyOpaqueStruct do
 end
 ```
 
+If you often define submodules containing only a struct, you can avoid
+boilerplate code:
+
+```elixir
+defmodule MyModule do
+  use TypedStruct
+
+  # You now have %MyModule.Struct{}.
+  typedstruct module: Struct do
+    field :field, term()
+  end
+end
+```
+
 ### Documentation
 
-To add a `@typedoc` to the struct type, just add the attribute above the
+To add a `@typedoc` to the struct type, just add the attribute in the
 `typedstruct` block:
 
 ```elixir
-@typedoc "A typed struct"
 typedstruct do
+  @typedoc "A typed struct"
+
+  field :a_string, String.t()
+  field :an_int, integer()
+end
+```
+
+ You can also document submodules this way:
+
+```elixir
+typedstruct module: MyStruct do
+  @moduledoc "A submodule with a typed struct."
+  @typedoc "A typed struct in a submodule"
+
   field :a_string, String.t()
   field :an_int, integer()
 end
@@ -305,14 +333,44 @@ specification:
 typedstruct opaque: true do
   field :name, String.t()
 end
+```
 
-# Becomes
+generates the following type:
 
+```elixir
 @opaque t() :: %__MODULE__{
           name: String.t()
         }
 ```
 
+When passing `module: ModuleName`, the whole `typedstruct` block is wrapped in a
+module definition. This way, the following definition:
+
+```elixir
+defmodule MyModule do
+  use TypedStruct
+
+  typedstruct module: Struct do
+    field :field, term()
+  end
+end
+```
+
+becomes:
+
+```elixir
+defmodule MyModule do
+  defmodule Struct do
+    @enforce_keys []
+    defstruct field: nil
+
+    @type t() :: %__MODULE__{
+            field: term() | nil
+          }
+  end
+end
+```
+
 ## [Contributing](CONTRIBUTING.md)
 
 Before contributing to this project, please read the

lib/typed_struct.ex

@@ -58,8 +58,9 @@ defmodule TypedStruct do
 
         use TypedStruct
 
-        @typedoc "A person"
         typedstruct do
+          @typedoc "A person"
+
           field :name, String.t(), enforce: true
           field :age, non_neg_integer()
           field :happy?, boolean(), default: true
@@ -144,13 +145,36 @@ defmodule TypedStruct do
         end
       end
 
+  If you often define submodules containing only a struct, you can avoid
+  boilerplate code:
+
+      defmodule MyModule do
+        use TypedStruct
+
+        # You now have %MyModule.Struct{}.
+        typedstruct module: Struct do
+          field :field, term()
+        end
+      end
+
   ### Documentation
 
-  To add a `@typedoc` to the struct type, just add the attribute above the
+  To add a `@typedoc` to the struct type, just add the attribute in the
   `typedstruct` block:
 
-      @typedoc "A typed struct"
       typedstruct do
+        @typedoc "A typed struct"
+
+        field :a_string, String.t()
+        field :an_int, integer()
+      end
+
+  You can also document submodules this way:
+
+      typedstruct module: MyStruct do
+        @moduledoc "A submodule with a typed struct."
+        @typedoc "A typed struct in a submodule"
+
         field :a_string, String.t()
         field :an_int, integer()
       end
@@ -257,11 +281,35 @@ defmodule TypedStruct do
         field :name, String.t()
       end
 
-      # Becomes
+  generates the following type:
 
       @opaque t() :: %__MODULE__{
                 name: String.t()
               }
+
+  When passing `module: ModuleName`, the whole `typedstruct` block is wrapped in
+  a module definition. This way, the following definition:
+
+      defmodule MyModule do
+        use TypedStruct
+
+        typedstruct module: Struct do
+          field :field, term()
+        end
+      end
+
+  becomes:
+
+      defmodule MyModule do
+        defmodule Struct do
+          @enforce_keys []
+          defstruct field: nil
+
+          @type t() :: %__MODULE__{
+                  field: term() | nil
+                }
+        end
+      end
   """
 
   @doc false
@@ -282,7 +330,8 @@ defmodule TypedStruct do
     * `enforce` - if set to true, sets `enforce: true` to all fields by default.
       This can be overridden by setting `enforce: false` or a default value on
       individual fields.
-    * `opaque` - if set to true, creates an opaque type for the struct
+    * `opaque` - if set to true, creates an opaque type for the struct.
+    * `module` - if set, creates the struct in a submodule named `module`.
 
   ## Examples
 
@@ -309,8 +358,48 @@ defmodule TypedStruct do
           field :field_four, atom(), default: :hey
         end
       end
+
+  You can create the struct in a submodule instead:
+
+      defmodule MyModule do
+        use TypedStruct
+
+        typedstruct, module: Struct do
+          field :field_one, String.t()
+          field :field_two, integer(), enforce: true
+          field :field_three, boolean(), enforce: true
+          field :field_four, atom(), default: :hey
+        end
+      end
   """
   defmacro typedstruct(opts \\ [], do: block) do
+    if is_nil(opts[:module]) do
+      quote do
+        Module.eval_quoted(
+          __ENV__,
+          TypedStruct.__typedstruct__(
+            unquote(Macro.escape(block)),
+            unquote(opts)
+          )
+        )
+      end
+    else
+      quote do
+        defmodule unquote(opts[:module]) do
+          Module.eval_quoted(
+            __ENV__,
+            TypedStruct.__typedstruct__(
+              unquote(Macro.escape(block)),
+              unquote(opts)
+            )
+          )
+        end
+      end
+    end
+  end
+
+  @doc false
+  def __typedstruct__(block, opts) do
     quote do
       Module.register_attribute(__MODULE__, :ts_plugins, accumulate: true)
       Module.register_attribute(__MODULE__, :ts_fields, accumulate: true)
@@ -342,6 +431,19 @@ defmodule TypedStruct do
     end
   end
 
+  @doc false
+  defmacro __type__(types, opts) do
+    if Keyword.get(opts, :opaque, false) do
+      quote bind_quoted: [types: types] do
+        @opaque t() :: %__MODULE__{unquote_splicing(types)}
+      end
+    else
+      quote bind_quoted: [types: types] do
+        @type t() :: %__MODULE__{unquote_splicing(types)}
+      end
+    end
+  end
+
   @doc """
   Registers a plugin for the currently defined struct.
 
@@ -408,10 +510,6 @@ defmodule TypedStruct do
     end
   end
 
-  ############################################################################
-  ##                               Callbacks                                ##
-  ############################################################################
-
   @doc false
   def __field__(mod, name, type, opts) when is_atom(name) do
     if mod |> Module.get_attribute(:ts_fields) |> Keyword.has_key?(name) do
@@ -437,23 +535,6 @@ defmodule TypedStruct do
     raise ArgumentError, "a field name must be an atom, got #{inspect(name)}"
   end
 
-  @doc false
-  defmacro __type__(types, opts) do
-    if Keyword.get(opts, :opaque, false) do
-      quote bind_quoted: [types: types] do
-        @opaque t() :: %__MODULE__{unquote_splicing(types)}
-      end
-    else
-      quote bind_quoted: [types: types] do
-        @type t() :: %__MODULE__{unquote_splicing(types)}
-      end
-    end
-  end
-
-  ############################################################################
-  ##                                Helpers                                 ##
-  ############################################################################
-
   # Makes the type nullable if the key is not enforced.
   defp type_for(type, false), do: type
   defp type_for(type, _), do: quote(do: unquote(type) | nil)

mix.exs

@@ -1,7 +1,7 @@
 defmodule TypedStruct.MixProject do
   use Mix.Project
 
-  @version "0.2.0"
+  @version "0.2.1"
   @repo_url "https://github.com/ejpcmac/typed_struct"
 
   def project do

test/typed_struct_test.exs

@@ -43,6 +43,14 @@ defmodule TypedStructTest do
     def enforce_keys, do: @enforce_keys
   end
 
+  defmodule TestModule do
+    use TypedStruct
+
+    typedstruct module: Struct do
+      field :field, term()
+    end
+  end
+
   @bytecode bytecode
   @bytecode_opaque bytecode_opaque
 
@@ -138,6 +146,10 @@ defmodule TypedStructTest do
     assert type1 == type2
   end
 
+  test "generates the struct in a submodule if `module: ModuleName` is set" do
+    assert TestModule.Struct.__struct__() == %TestModule.Struct{field: nil}
+  end
+
   ############################################################################
   ##                                Problems                                ##
   ############################################################################