Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: Rename project to TinyMaps #6

Merged
merged 1 commit into from
Jun 28, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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