Skip to content

Commit

Permalink
chore: Rename project to TinyMaps
Browse files Browse the repository at this point in the history
  • Loading branch information
abshierjoel committed Jun 28, 2024
1 parent 11a6e4f commit 379708d
Show file tree
Hide file tree
Showing 5 changed files with 161 additions and 111 deletions.
66 changes: 35 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,48 +1,50 @@
## ShorterMaps
## TinyMaps

_A successor to the [shorter_maps](https://github.com/meyercm/shorter_maps) package._

`~M` sigil for map shorthand. `~M{a} ~> %{a: a}`

[![Build Status](https://travis-ci.org/meyercm/shorter_maps.svg?branch=master)](https://travis-ci.org/meyercm/shorter_maps)

### Getting started

1) Add `{:shorter_maps, "~> 2.0"},` to your mix deps
2) Add `import ShorterMaps` to the top of your module
3) DRY up your maps and structs with `~M` and `~m`. Instead of `%{name: name}`
1. Add `{:tiny_maps, "~> 3.0"},` to your mix deps
2. Add `import TinyMaps` to the top of your module
3. DRY up your maps and structs with `~M` and `~m`. Instead of `%{name: name}`
use `~M{name}`, and for `%{"name" => name}` use `~m{name}`. When the key and
the variable don't match, don't fret: `~M{name, id: current_id}` expands
to `%{name: name, id: current_id}`.

### Motivation

Code like `%{id: id, name: name, address: address}` occurs with high frequency
in many programming languages. In Elixir, additional uses occur as we pattern
in many programming languages. In Elixir, additional uses occur as we pattern
match to destructure existing maps.

ES6 provided javascript with a shorthand to create maps with keys inferred by
variable names, and allowed destructuring those maps into variables named for
the keys. `ShorterMaps` provides that functionality to Elixir.
the keys. `TinyMaps` provides that functionality to Elixir.

### Syntax:

`~M` and `~m` can be used to replace maps __anywhere__ in your code. The
`ShorterMaps` sigil syntax operates just like a vanilla elixir map, with two
`~M` and `~m` can be used to replace maps **anywhere** in your code. The
`TinyMaps` sigil syntax operates just like a vanilla elixir map, with two
main differences:

1) When a variable name stands alone, it is replaced with a key-value pair,
where the key is the variable name as a string (~m) or an atom (~M). The value
will be the variable. For example, `~M{name, id: get_free_id()}` expands to
`%{name: name, id: get_free_id()}`.
1. When a variable name stands alone, it is replaced with a key-value pair,
where the key is the variable name as a string (~m) or an atom (~M). The value
will be the variable. For example, `~M{name, id: get_free_id()}` expands to
`%{name: name, id: get_free_id()}`.

2) Struct names are enclosed in the sigil, rather than outside, e.g.:
`~M{%StructName key, key2}` === `%StructName{key: key, key2: key2}`. The
struct name must be followed by a space, and then comma-separated keys.
Structs can be updated just like maps: `~M{%StructName old_struct|key_to_update}`
2. Struct names are enclosed in the sigil, rather than outside, e.g.:
`~M{%StructName key, key2}` === `%StructName{key: key, key2: key2}`. The
struct name must be followed by a space, and then comma-separated keys.
Structs can be updated just like maps: `~M{%StructName old_struct|key_to_update}`

### Examples

```elixir
iex> import ShorterMaps
iex> import TinyMaps
...> name = "Chris"
...> id = 6
...> ~M{name, id}
Expand Down Expand Up @@ -94,7 +96,9 @@ iex> import ShorterMaps

### Credits

ShorterMaps adds additional features to the original project, `ShortMaps`,
TinyMaps is continuation of the [ShorterMaps](https://github.com/meyercm/shorter_maps) which has become unmaintained and I have not been able to make contact with the maintainer.

ShorterMaps added additional features to the original project, `ShortMaps`,
located [here][original-repo]. The reasons for the divergence are summarized
[here][divergent-opinion-issue].

Expand All @@ -103,16 +107,16 @@ located [here][original-repo]. The reasons for the divergence are summarized

### Quick Reference:

* Atom keys: `~M{a, b}` => `%{a: a, b: b}`
* String keys: `~m{a, b}` => `%{"a" => a, "b" => b}`
* Structs: `~M{%Person id, name}` => `%Person{id: id, name: name}`
* Pinned variables: `~M{^a, b}` => `%{a: ^a, b: b}`
* Ignore matching: `~M{_a, b}` => `%{a: _a, b: b}`
* Map update (strings or atoms): `~M{old|a, b, c}` => `%{old|a: a, b: b, c: c}`
* Struct update: `~M{%Person old_struct|name} => %Person{old_struct|name: name}`
* Mixed mode: `~M{a, b: b_alt}` => `%{a: a, b: b_alt}`
* Expressions: `~M{a, b: a + 1}` => `%{a: a, b: a + 1}`
* Zero-arity: `~M{a, b()}` => `%{a: a, b: b()}`
* Modifiers: `~m{blah}a == ~M{blah}` or `~M{blah}s == ~m{blah}`

**Note**: you must `import ShorterMaps` for the sigils to work.
- Atom keys: `~M{a, b}` => `%{a: a, b: b}`
- String keys: `~m{a, b}` => `%{"a" => a, "b" => b}`
- Structs: `~M{%Person id, name}` => `%Person{id: id, name: name}`
- Pinned variables: `~M{^a, b}` => `%{a: ^a, b: b}`
- Ignore matching: `~M{_a, b}` => `%{a: _a, b: b}`
- Map update (strings or atoms): `~M{old|a, b, c}` => `%{old|a: a, b: b, c: c}`
- Struct update: `~M{%Person old_struct|name} => %Person{old_struct|name: name}`
- Mixed mode: `~M{a, b: b_alt}` => `%{a: a, b: b_alt}`
- Expressions: `~M{a, b: a + 1}` => `%{a: a, b: a + 1}`
- Zero-arity: `~M{a, b()}` => `%{a: a, b: b()}`
- Modifiers: `~m{blah}a == ~M{blah}` or `~M{blah}s == ~m{blah}`

**Note**: you must `import TinyMaps` for the sigils to work.
4 changes: 2 additions & 2 deletions lib/shorter_maps.ex → lib/tiny_maps.ex
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
defmodule ShorterMaps do
defmodule TinyMaps do
@readme Path.join(__DIR__, "../README.md")
@external_resource @readme
{:ok, readme_contents} = File.read(@readme)
Expand Down Expand Up @@ -92,7 +92,7 @@ defmodule ShorterMaps do
Code.string_to_quoted!(final_string, file: __ENV__.file, line: line)
else
{:error, step, reason} ->
raise(ArgumentError, "ShorterMaps parse error in step: #{step}, reason: #{reason}")
raise(ArgumentError, "TinyMaps parse error in step: #{step}, reason: #{reason}")
end
end

Expand Down
12 changes: 6 additions & 6 deletions mix.exs
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
defmodule ShorterMaps.Mixfile do
defmodule TinyMaps.Mixfile do
use Mix.Project

@version "2.2.5"
@repo_url "https://github.com/meyercm/shorter_maps"
@version "3.0.0"
@repo_url "https://github.com/abshierjoel/tiny_maps"

def project do
[
app: :shorter_maps,
app: :tiny_maps,
version: @version,
elixir: "~> 1.0",
build_embedded: Mix.env() == :prod,
Expand All @@ -16,7 +16,7 @@ defmodule ShorterMaps.Mixfile do
package: hex_package(),
description: "~M sigil for map shorthand. `~M{id, name} ~> %{id: id, name: name}`",
# Docs
name: "ShorterMaps"
name: "TinyMaps"
]
end

Expand All @@ -25,7 +25,7 @@ defmodule ShorterMaps.Mixfile do
end

defp hex_package do
[maintainers: ["Chris Meyer"], licenses: ["MIT"], links: %{"GitHub" => @repo_url}]
[maintainers: ["Joel Abshier"], licenses: ["MIT"], links: %{"GitHub" => @repo_url}]
end

defp deps do
Expand Down
Loading

0 comments on commit 379708d

Please sign in to comment.