From 3a72205a803ba35dc9260094ee8f533ea6d2c1e8 Mon Sep 17 00:00:00 2001 From: "Kian-Meng, Ang" Date: Thu, 21 Oct 2021 23:55:27 +0800 Subject: [PATCH] Misc doc changes Besides other documentation changes, this commit ensures the generated HTML doc for HexDocs.pm will become the source of truth for this Elixir library and leverage on latest features of ExDoc. --- .formatter.exs | 2 +- .gitignore | 6 +- LICENSE.md | 4 +- README.md | 14 +++++ lib/map_rewire.ex | 147 ++++++++++++++++++++++------------------------ mix.exs | 35 +++++++---- 6 files changed, 114 insertions(+), 94 deletions(-) diff --git a/.formatter.exs b/.formatter.exs index 525446d..d2cda26 100644 --- a/.formatter.exs +++ b/.formatter.exs @@ -1,4 +1,4 @@ # Used by "mix format" [ - inputs: ["mix.exs", "{config,lib,test}/**/*.{ex,exs}"] + inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"] ] diff --git a/.gitignore b/.gitignore index f0f431a..6a23aa6 100644 --- a/.gitignore +++ b/.gitignore @@ -7,7 +7,7 @@ # The directory Mix downloads your dependencies sources to. /deps/ -# Where 3rd-party dependencies like ExDoc output generated docs. +# Where third-party dependencies like ExDoc output generated docs. /doc/ # Ignore .fetch files in case you like to edit your project deps locally. @@ -22,5 +22,5 @@ erl_crash.dump # Ignore package tarball (built via "mix hex.build"). map_rewire-*.tar -# Ignore Elixir LS generated files -.elixir_ls +# Temporary files, for example, from tests. +/tmp/ diff --git a/LICENSE.md b/LICENSE.md index c823447..0729ab3 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ -The MIT License (MIT) +# The MIT License (MIT) -Copyright (c) 2018 Jordan Parker. +Copyright (c) 2018 Jordan Parker Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index a28fe70..2c62b44 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,12 @@ [![Elixir CI](https://github.com/byjpr/MapRewire/actions/workflows/elixir.yml/badge.svg)](https://github.com/byjpr/MapRewire/actions/workflows/elixir.yml) [![Coverage Status](https://img.shields.io/coveralls/github/byjord/MapRewire.svg?style=flat-square)](https://coveralls.io/github/byjord/MapRewire) [![Libraries.io for releases](https://img.shields.io/librariesio/release/hex/map_rewire.svg?style=flat-square)](https://libraries.io/hex/map_rewire) +[![Module Version](https://img.shields.io/hexpm/v/map_rewire.svg)](https://hex.pm/packages/map_rewire) +[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/map_rewire/) +[![Total Download](https://img.shields.io/hexpm/dt/map_rewire.svg)](https://hex.pm/packages/map_rewire) +[![License](https://img.shields.io/hexpm/l/map_rewire.svg)](https://github.com/byjpr/MapRewire/blob/master/LICENSE.md) +[![Last Updated](https://img.shields.io/github/last-commit/byjpr/MapRewire.svg)](https://github.com/byjpr/MapRewire/commits/master) + Bulk rekey your maps. Simple bud. (☞ﾟ ヮ ﾟ)☞ @@ -33,3 +39,11 @@ end | [![byjord](https://avatars0.githubusercontent.com/u/6415727?v=4&s=80)](https://github.com/byjord) | [![halostatue](https://avatars3.githubusercontent.com/u/11361?v=4&s=80)](https://github.com/halostatue) | | :-----------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------: | | [byjord](https://github.com/byjord) | [halostatue](https://github.com/halostatue) | + + +## Copyright and License + +Copyright (c) 2018 Jordan Parker + +This work is free. You can redistribute it and/or modify it under the +terms of the MIT License. See the [LICENSE.md](./LICENSE.md) file for more details. diff --git a/lib/map_rewire.ex b/lib/map_rewire.ex index 252418f..fc4be27 100644 --- a/lib/map_rewire.ex +++ b/lib/map_rewire.ex @@ -8,14 +8,12 @@ defmodule MapRewire do To rewire a map, build transformation rules and call `rewire/3`, or if MapRewire has been `import`ed, use the operator, `<~>`. - ``` - iex> map = %{"id" => "234923409", "title" => "asdf"} - iex> rules = "title=>name id=>shopify_id" - iex> map <~> rules - {%{"id" => "234923409", "title" => "asdf"}, %{"shopify_id" => "234923409", "name" => "asdf"}} - iex> MapRewire.rewire(map, rules) == (map <~> rules) - true - ``` + iex> map = %{"id" => "234923409", "title" => "asdf"} + iex> rules = "title=>name id=>shopify_id" + iex> map <~> rules + {%{"id" => "234923409", "title" => "asdf"}, %{"shopify_id" => "234923409", "name" => "asdf"}} + iex> MapRewire.rewire(map, rules) == (map <~> rules) + true ## Rewire Rules @@ -91,20 +89,19 @@ defmodule MapRewire do expecting any normal map value. The `:default` will work as the third parameter of `Map.get/3` and be used instead of `key_missing/0`. - ``` - iex> map = %{"title" => "asdf"} - iex> rules = %{"title" => {:name, transform: &String.reverse/1}} - iex> map <~> rules - {%{"title" => "asdf"}, %{name: "fdsa"}} - - # If "title" could be missing from the source map, the `transform` function - # should be written to handle `key_missing/0` values or have its own safe - # `default` value. - iex> map = %{} - iex> rules = %{"title" => {:name, default: "unknown", transform: &String.reverse/1}} - iex> map <~> rules - {%{}, %{name: "nwonknu"}} - ``` + iex> map = %{"title" => "asdf"} + iex> rules = %{"title" => {:name, transform: &String.reverse/1}} + iex> map <~> rules + {%{"title" => "asdf"}, %{name: "fdsa"}} + + If "title" could be missing from the source map, the `transform` function + should be written to handle `key_missing/0` values or have its own safe + `default` value. + + iex> map = %{} + iex> rules = %{"title" => {:name, default: "unknown", transform: &String.reverse/1}} + iex> map <~> rules + {%{}, %{name: "nwonknu"}} #### Producer Functions @@ -112,37 +109,38 @@ defmodule MapRewire do key/value tuples. It may be provided either as `producer` or `{producer, options}` as shown below. - iex> dcs = fn value -> - ...> unless MapRewire.key_missing?(value) do - ...> [dept, class, subclass] = - ...> value - ...> |> String.split("-", parts: 3) - ...> |> Enum.map(&String.to_integer/1) - ...> - ...> Enum.to_list(%{"department" => dept, "class" => class, "subclass" => subclass}) - ...> end - ...> end - iex> map = %{"title" => "asdf", "dcs" => "1-3-5"} - iex> rules = %{"title" => "name", "dcs" => dcs} - iex> map <~> rules - {%{"title" => "asdf", "dcs" => "1-3-5"}, %{"name" => "asdf", "department" => 1, "class" => 3, "subclass" => 5}} - - # If "title" could be missing from the source map, the `transform` function - # should be written to handle `key_missing/0` values or have its own safe - # `default` value. - - iex> dcs = fn value -> - ...> [dept, class, subclass] = - ...> value - ...> |> String.split("-", parts: 3) - ...> |> Enum.map(&String.to_integer/1) - ...> - ...> Enum.to_list(%{"department" => dept, "class" => class, "subclass" => subclass}) - ...> end - iex> map = %{"title" => "asdf"} - iex> rules = %{"title" => "name", "dcs" => {dcs, default: "0-0-0"}} - iex> map <~> rules - {%{"title" => "asdf"}, %{"name" => "asdf", "department" => 0, "class" => 0, "subclass" => 0}} + iex> dcs = fn value -> + ...> unless MapRewire.key_missing?(value) do + ...> [dept, class, subclass] = + ...> value + ...> |> String.split("-", parts: 3) + ...> |> Enum.map(&String.to_integer/1) + ...> + ...> Enum.to_list(%{"department" => dept, "class" => class, "subclass" => subclass}) + ...> end + ...> end + iex> map = %{"title" => "asdf", "dcs" => "1-3-5"} + iex> rules = %{"title" => "name", "dcs" => dcs} + iex> map <~> rules + {%{"title" => "asdf", "dcs" => "1-3-5"}, %{"name" => "asdf", "department" => 1, "class" => 3, "subclass" => 5}} + + If "title" could be missing from the source map, the `transform` function + should be written to handle `key_missing/0` values or have its own safe + `default` value. + + iex> dcs = fn value -> + ...> [dept, class, subclass] = + ...> value + ...> |> String.split("-", parts: 3) + ...> |> Enum.map(&String.to_integer/1) + ...> + ...> Enum.to_list(%{"department" => dept, "class" => class, "subclass" => subclass}) + ...> end + iex> map = %{"title" => "asdf"} + iex> rules = %{"title" => "name", "dcs" => {dcs, default: "0-0-0"}} + iex> map <~> rules + {%{"title" => "asdf"}, %{"name" => "asdf", "department" => 0, "class" => 0, "subclass" => 0}} + """ @transform_to "=>" @@ -159,18 +157,16 @@ defmodule MapRewire do If no keys are to be produced (possibly because `value` is `key_missing/0`), either `nil` or an empty list (`[]`) should be returned. - ``` - fn value -> - unless MapRewire.key_missing?(value) do - [dept, class, subclass] = - value - |> String.split("-", parts: 3) - |> Enum.map(&String.to_integer/1) + fn value -> + unless MapRewire.key_missing?(value) do + [dept, class, subclass] = + value + |> String.split("-", parts: 3) + |> Enum.map(&String.to_integer/1) - Enum.to_list(%{"department" => dept, "class" => class, "subclass" => subclass}) - end - end - ``` + Enum.to_list(%{"department" => dept, "class" => class, "subclass" => subclass}) + end + end """ @type producer :: (Map.value() -> nil | {Map.key(), Map.value()} | list({Map.key(), Map.value()})) @@ -185,20 +181,19 @@ defmodule MapRewire do If the key should be omitted when `rewire/3` is called, `key_missing/0` should be returned. - ``` - fn value -> - cond do - MapRewire.key_missing?(value) -> - value + fn value -> + cond do + MapRewire.key_missing?(value) -> + value - is_binary(value) -> - String.reverse(value) + is_binary(value) -> + String.reverse(value) + + true -> + String.reverse(to_string(value)) + end + end - true -> - String.reverse(to_string(value)) - end - end - ``` """ @type transformer :: (Map.value() -> Map.value()) diff --git a/mix.exs b/mix.exs index ca1798b..82cae5d 100644 --- a/mix.exs +++ b/mix.exs @@ -1,18 +1,21 @@ defmodule MapRewire.MixProject do use Mix.Project + @source_url "https://github.com/byjord/MapRewire" + @version "0.3.0" + def project do [ app: :map_rewire, - version: "0.3.0", + version: @version, elixir: "~> 1.6", build_embedded: Mix.env() == :prod, start_permanent: Mix.env() == :prod, test_coverage: [tool: ExCoveralls], preferred_cli_env: [coveralls: :test], - description: description(), package: package(), - deps: deps() + deps: deps(), + docs: docs() ] end @@ -29,22 +32,30 @@ defmodule MapRewire.MixProject do {:benchee, "~> 1.0", only: :dev}, {:excoveralls, "~> 0.9", only: :test}, {:exprof, "~> 0.2.0", only: :test}, - {:ex_doc, "~> 0.25.0", only: :dev} + {:ex_doc, "~> 0.25.0", only: :dev, runtime: false} ] end - defp description do - """ - Complete syntactic sugar to rekey maps. - """ - end - defp package do [ + description: "Complete syntactic sugar to rekey maps.", files: ["lib", "mix.exs", "config", "README*", "LICENSE*"], - licenses: ["The MIT License (MIT)"], + licenses: ["MIT"], maintainers: ["Jordan Parker"], - links: %{"GitHub" => "https://github.com/byjord/MapRewire"} + links: %{"GitHub" => @source_url} + ] + end + + defp docs do + [ + extras: [ + "LICENSE.md": [title: "License"], + "README.md": [title: "Overview"], + ], + main: "readme", + source_url: @source_url, + source_ref: "v#{@version}", + formatters: ["html"] ] end end