type_is_enum 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0404f23335ab5f97a1afd40dfd03b867fb2b820a
+  data.tar.gz: 7f7cc6cf0103fb2e158813f2c638b9757d3075dd
+SHA512:
+  metadata.gz: 99ab72b0c8fca5006bbe28e3f77b9615e3537ea7df28ffcaeb03df588b28368619394b5718545f373e1ac1cb3ccb53545df4cfb8564cfa69648b6e2565047fe0
+  data.tar.gz: b28d6949c5447d1135700a3e0acc1f9ac263023f79aa432155bf5afe787aebb58b333a93a8cc616b1aced7c8cf1dbb254a4f99baaa901089a6bde6b6e5a51571

data/.gitignore

@@ -0,0 +1,45 @@
+# Ruby defaults
+
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+
+# Build output
+*.gem
+
+# Database
+
+db/*.sqlite3
+
+# Logs
+
+/log/
+
+# IntellJ
+
+*.iml
+*.ipr
+*.iws
+*.ids
+.rakeTasks
+
+# Emacs
+
+*~
+\#*
+.#*
+
+# Mac OS
+
+.DS_Store

data/.rubocop.yml

@@ -0,0 +1,24 @@
+# Disable compact style check for example.rb
+Style/ClassAndModuleChildren:
+  Exclude:
+    - 'example.rb'
+
+# Disable line-length check; it's too easy for the cure to be worse than the disease
+Metrics/LineLength:
+  Enabled: False
+
+# Disable problematic module documentation check (see https://github.com/bbatsov/rubocop/issues/947)
+Style/Documentation:
+  Enabled: false
+
+# Allow one line around class body (Style/EmptyLines will still disallow two or more)
+Style/EmptyLinesAroundClassBody:
+  Enabled: false
+
+# Allow one line around module body (Style/EmptyLines will still disallow two or more)
+Style/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+# Allow one line around block body (Style/EmptyLines will still disallow two or more)
+Style/EmptyLinesAroundBlockBody:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+2.2.3

data/.travis.yml

@@ -0,0 +1,2 @@
+language: ruby
+

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/CHANGES.md

@@ -0,0 +1,47 @@
+## 0.1.7 (28 April 2016)
+
+- The default `to_s` for `TypesafeEnum::Enum` now includes the enum's class, key, value,
+  and ordinal, e.g.
+
+      Suit::DIAMONDS.to_s
+      # => "Suit::DIAMONDS [1] -> diamonds"
+
+  (Fixes [#5](https://github.com/dmolesUC3/typesafe_enum/issues/5).)
+- `::find_by_value_str` now uses a hash lookup like the other `::find_by` methods.
+- Improved method documentation.
+
+## 0.1.6 (15 Mar 2016)
+
+- [#3](https://github.com/dmolesUC3/typesafe_enum/pull/3) - No need for `instance_eval`
+  when creating new enum instance methods - [@dblock](https://github.com/dblock).
+
+## 0.1.5 (27 Jan 2016)
+
+- Include the original call site in the warning message for duplicate instances to help
+  with debugging.
+- Modified gemspec to take into account SSH checkouts when determining the homepage URL.
+
+## 0.1.4 (18 Dec 2015))
+
+- Exact duplicate instances (e.g. due to multiple `requires`) are now ignored with a warning,
+  instead of causing a `NameError`. Duplicate keys with different values, and duplicate values
+  with different keys, still raise a `NameError`.
+- `NameErrors` due to invalid keys or values no longer cause the enum class to be undefined.
+  However, the invalid instances will still not be registered and no constants created for them.
+
+## 0.1.3 (17 Dec 2015)
+
+- Fixed issue where invalid classes weren't properly removed after duplicate name declarations,
+  polluting the namespace and causing duplicate declration error messages to be lost.
+
+## 0.1.2 (19 Nov 2015)
+
+- Fixed issue where `::find_by_value_str` failed to return `nil` for bad values
+
+## 0.1.1 (19 Nov 2015)
+
+- Added `::find_by_value_str`
+
+## 0.1.0 (18 Nov 2015)
+
+- Initial release

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 The Regents of the University of California
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,478 @@
+# TypeIsEnum
+
+[![Build Status](https://travis-ci.org/dmolesUC3/typesafe_enum.svg?branch=master)](https://travis-ci.org/dmolesUC3/typesafe_enum)
+[![Code Climate](https://codeclimate.com/github/dmolesUC3/typesafe_enum.svg)](https://codeclimate.com/github/dmolesUC3/typesafe_enum)
+[![Inline docs](http://inch-ci.org/github/dmolesUC3/typesafe_enum.svg)](http://inch-ci.org/github/dmolesUC3/typesafe_enum)
+[![Gem Version](https://img.shields.io/gem/v/typesafe_enum.svg)](https://github.com/dmolesUC3/typesafe_enum/releases)
+
+A Ruby implementation of Joshua Bloch's
+[typesafe enum pattern](http://www.oracle.com/technetwork/java/page1-139488.html#replaceenums),
+with syntax loosely inspired by [Ruby::Enum](https://github.com/dblock/ruby-enum).
+
+## Table of contents
+
+- [Basic usage](#basic-usage)
+- [Ordering](#ordering)
+- [String representations](#string-representations)
+- [Convenience methods on enum classes](#convenience-methods-on-enum-classes)
+    - [::to\_a](#to_a)
+    - [::size](#size)
+    - [::each, ::each\_with\_index, and ::map](#each-each_with_index-and-map)
+    - [::find\_by\_key, ::find\_by\_value, ::find\_by\_ord](#find_by_key-find_by_value-find_by_ord)
+    - [::find\_by\_value\_str](#find_by_value_str)
+- [Enum classes with methods](#enum-classes-with-methods)
+- [Enum instances with methods](#enum-instances-with-methods)
+- [How is this different from Ruby::Enum?](#how-is-this-different-from-rubyenum)
+- [How is this different from java.lang.Enum?](#how-is-this-different-from-javalangenum)
+    - [Clunkier syntax](#clunkier-syntax)
+    - [No special switch/case support](#no-special-switchcase-support)
+    - [No serialization support](#no-serialization-support)
+    - [No support classes](#no-support-classes)
+    - [Enum classes are not closed](#enum-classes-are-not-closed)
+- [Contributing](#contributing)
+
+## Basic usage
+
+Create a new enum class and a set of instances:
+
+```ruby
+require 'typesafe_enum'
+
+class Suit < TypeIsEnum::Enum
+  new :CLUBS
+  new :DIAMONDS
+  new :HEARTS
+  new :SPADES
+end
+```
+
+A constant is declared for each instance, with an instance of the new
+class as the value of that constant:
+
+```ruby
+Suit::CLUBS
+# => #<Suit:0x007fe9b3ba2698 @key=:CLUBS, @value="clubs", @ord=0>
+```
+
+By default, the `value` of an instance is its `key` symbol, lowercased:
+
+```ruby
+Suit::CLUBS.key
+# => :CLUBS
+Suit::CLUBS.value
+# => 'clubs'
+```
+
+But you can also declare an explicit `value`:
+
+```ruby
+class Tarot < TypeIsEnum::ValueEnum
+  new :CUPS, 'Cups'
+  new :COINS, 'Coins'
+  new :WANDS, 'Wands'
+  new :SWORDS, 'Swords'
+end
+
+Tarot::CUPS.value
+# => 'Cups'
+```
+
+And `values` need not be strings:
+
+```ruby
+class Scale < TypeIsEnum::ValueEnum
+  new :DECA, 10
+  new :HECTO, 100
+  new :KILO, 1_000
+  new :MEGA, 1_000_000
+end
+
+Scale::KILO.value
+# => 1000
+```
+
+Declaring two instances with the same key will produce an error:
+
+```ruby
+class Suit < TypeIsEnum::Enum
+  new :CLUBS
+  new :DIAMONDS
+  new :HEARTS
+  new :SPADES
+  new :SPADES, '♠'
+end
+```
+
+```
+typesafe_enum/lib/typesafe_enum/base.rb:88:in `valid_key_and_value': Suit::SPADES already exists (NameError)
+	from /Users/dmoles/Work/Stash/typesafe_enum/lib/typesafe_enum/base.rb:98:in `register'
+	from /Users/dmoles/Work/Stash/typesafe_enum/lib/typesafe_enum/base.rb:138:in `block in initialize'
+	from /Users/dmoles/Work/Stash/typesafe_enum/lib/typesafe_enum/base.rb:137:in `class_exec'
+	from /Users/dmoles/Work/Stash/typesafe_enum/lib/typesafe_enum/base.rb:137:in `initialize'
+	from ./scratch.rb:11:in `new'
+	from ./scratch.rb:11:in `<class:Suit>'
+	from ./scratch.rb:6:in `<main>'
+```
+
+Likewise two instances with the same value but different keys:
+
+```ruby
+class Tarot < TypeIsEnum::ValueEnum
+  new :CUPS, 'Cups'
+  new :COINS, 'Coins'
+  new :WANDS, 'Wands'
+  new :SWORDS, 'Swords'
+  new :STAVES, 'Wands'
+end
+```
+
+```
+/typesafe_enum/lib/typesafe_enum/base.rb:92:in `valid_key_and_value': A Tarot instance with value 'Wands' already exists (NameError)
+	from /Users/dmoles/Work/Stash/typesafe_enum/lib/typesafe_enum/base.rb:98:in `register'
+	from /Users/dmoles/Work/Stash/typesafe_enum/lib/typesafe_enum/base.rb:138:in `block in initialize'
+	from /Users/dmoles/Work/Stash/typesafe_enum/lib/typesafe_enum/base.rb:137:in `class_exec'
+	from /Users/dmoles/Work/Stash/typesafe_enum/lib/typesafe_enum/base.rb:137:in `initialize'
+	from ./scratch.rb:11:in `new'
+	from ./scratch.rb:11:in `<class:Tarot>'
+	from ./scratch.rb:6:in `<main>'
+```
+
+However, declaring an identical key/value pair will be ignored with a warning, to avoid unnecessary errors
+when, e.g., a declaration file is accidentally loaded twice.
+
+```ruby
+class Tarot < TypeIsEnum::ValueEnum
+  new :CUPS, 'Cups'
+  new :COINS, 'Coins'
+  new :WANDS, 'Wands'
+  new :SWORDS, 'Swords'
+end
+
+class Tarot < TypeIsEnum::ValueEnum
+  new :CUPS, 'Cups'
+  new :COINS, 'Coins'
+  new :WANDS, 'Wands'
+  new :SWORDS, 'Swords'
+end
+
+# => ignoring redeclaration of Tarot::CUPS with value Cups (source: /tmp/duplicate_enum.rb:13:in `new')
+# => ignoring redeclaration of Tarot::COINS with value Coins (source: /tmp/duplicate_enum.rb:14:in `new')
+# => ignoring redeclaration of Tarot::WANDS with value Wands (source: /tmp/duplicate_enum.rb:15:in `new')
+# => ignoring redeclaration of Tarot::SWORDS with value Swords (source: /tmp/duplicate_enum.rb:16:in `new')
+```
+
+**Note:** If do you see these warnings, it probably means there's something wrong with your `$LOAD_PATH` (e.g.,
+the same directory present both via its real path and via a symlink). This can cause all sorts of problems,
+and Ruby's `require` statement is [known to be not smart enough to deal with it](https://bugs.ruby-lang.org/issues/4403),
+so it's worth tracking down and fixing the root cause.
+
+## Ordering
+
+Enum instances have an ordinal value corresponding to their declaration
+order:
+
+```ruby
+Suit::SPADES.ord
+# => 3
+```
+
+And enum instances are comparable (within a type) based on that order:
+
+```ruby
+Suit::SPADES.is_a?(Comparable)
+# => true
+Suit::SPADES > Suit::DIAMONDS
+# => true
+Suit::SPADES > Tarot::CUPS
+# ArgumentError: comparison of Suit with Tarot failed
+```
+
+## String representations
+
+The default `to_s` implementation provides the enum's class, key, value,
+and ordinal, e.g.
+
+```ruby
+Suit::DIAMONDS.to_s
+# => "Suit::DIAMONDS [1] -> diamonds"
+```
+
+It can of course be overridden.
+
+## Convenience methods on enum classes
+
+### `::to_a`
+
+Returns an array of the enum instances in declaration order:
+
+```ruby
+Tarot.to_a
+# => [#<Tarot:0x007fd4db30eca8 @key=:CUPS, @value="Cups", @ord=0>, #<Tarot:0x007fd4db30ebe0 @key=:COINS, @value="Coins", @ord=1>, #<Tarot:0x007fd4db30eaf0 @key=:WANDS, @value="Wands", @ord=2>, #<Tarot:0x007fd4db30e9b0 @key=:SWORDS, @value="Swords", @ord=3>]
+```
+
+### `::size`
+
+Returns the number of enum instances:
+
+```ruby
+Suit.size
+# => 4
+```
+
+### `::each`, `::each_with_index`, and `::map`
+
+Iterate over the set of enum instances:
+
+```ruby
+Suit.each { |s| puts s.value }
+# clubs
+# diamonds
+# hearts
+# spades
+
+Suit.each_with_index { |s, i| puts "#{i}: #{s.key}" }
+# 0: CLUBS
+# 1: DIAMONDS
+# 2: HEARTS
+# 3: SPADES
+
+Suit.map(&:value)
+# => ["clubs", "diamonds", "hearts", "spades"]
+```
+
+### `::find_by_key`, `::find_by_value`, `::find_by_ord`
+
+Look up an enum instance based on its key, value, or ordinal:
+
+```ruby
+Tarot.find_by_key(:CUPS)
+# => #<Tarot:0x007faab19fda40 @key=:CUPS, @value="Cups", @ord=0>
+Tarot.find_by_value('Wands')
+# => #<Tarot:0x007faab19fd8b0 @key=:WANDS, @value="Wands", @ord=2>
+Tarot.find_by_ord(3)
+# => #<Tarot:0x007faab19fd810 @key=:SWORDS, @value="Swords", @ord=3>
+```
+
+### `::find_by_value_str`
+
+Look up an enum instance based on the string form of its value (as returned by `to_s`) --
+useful for, e.g., XML or JSON mapping of enums with non-string values:
+
+```ruby
+Scale.find_by_value_str('1000000')
+# => #<Scale:0x007f8513a93810 @key=:MEGA, @value=1000000, @ord=3>
+```
+
+## Enum classes with methods
+
+Enum classes are just classes. They can have methods, and other non-enum constants.
+(The `:initialize` method for each class, though, is declared programmatically by
+the base class. If you need to redefine it, be sure to alias and call the original.)
+
+```ruby
+class Suit < TypeIsEnum::Enum
+  new :CLUBS
+  new :DIAMONDS
+  new :HEARTS
+  new :SPADES
+
+  ALL_PIPS = %w(♣ ♦ ♥ ♠)
+
+  def pip
+    ALL_PIPS[self.ord]
+  end
+end
+
+Suit::ALL_PIPS
+# => ["♣", "♦", "♥", "♠"]
+
+Suit::CLUBS.pip
+# => "♣"
+
+Suit.map(&:pip)
+# => ["♣", "♦", "♥", "♠"]
+```
+
+## Enum instances with methods
+
+Enum instances can declare their own methods:
+
+```ruby
+class Operation < TypeIsEnum::Enum
+  new(:PLUS, '+') do
+    def eval(x, y)
+      x + y
+    end
+  end
+  new(:MINUS, '-') do
+    def eval(x, y)
+      x - y
+    end
+  end
+end
+
+Operation::PLUS.eval(11, 17)
+# => 28
+
+Operation::MINUS.eval(28, 11)
+# => 17
+
+Operation.map { |op| op.eval(39, 23) }
+# => [62, 16]
+```
+
+## How is this different from [Ruby::Enum](https://github.com/dblock/ruby-enum)?
+
+[Ruby::Enum](https://github.com/dblock/ruby-enum) is much closer to the classic
+[C enumeration](https://www.gnu.org/software/gnu-c-manual/gnu-c-manual.html#Enumerations)
+as seen in C, [C++](https://msdn.microsoft.com/en-us/library/2dzy4k6e.aspx),
+[C#](https://msdn.microsoft.com/en-us/library/sbbt4032.aspx), and
+[Objective-C](https://developer.apple.com/library/ios/releasenotes/ObjectiveC/ModernizationObjC/AdoptingModernObjective-C/AdoptingModernObjective-C.html#//apple_ref/doc/uid/TP40014150-CH1-SW6).
+In C and most C-like languages, an `enum` is simply a named set of `int` values
+(though C++ and others require an explicit cast to assign an `enum` value to
+an `int` variable).
+
+Similarly, a `Ruby::Enum` class is simply a named set of values of any type,
+with convenience methods for iterating over the set. Usually the values are
+strings, but they can be of any type.
+
+```ruby
+# String enum
+class Foo
+  include Ruby::Enum
+
+  new :BAR, 'bar'
+  new :BAZ, 'baz'
+end
+
+Foo::BAR
+#  => "bar"
+Foo::BAR == 'bar'
+# => true
+
+# Integer enum
+class Bar
+  include Ruby::Enum
+
+  new :BAR, 1
+  new :BAZ, 2
+end
+
+Bar::BAR
+#  => "bar"
+Bar::BAR == 1
+# => true
+```
+
+Java introduced the concept of "typesafe enums", first as a
+[design pattern](http://www.oracle.com/technetwork/java/page1-139488.html#replaceenums)
+and later as a
+[first-class language construct](https://docs.oracle.com/javase/1.5.0/docs/guide/language/enums.html).
+In Java, an `Enum` class defines a closed, valued set of _instances of that class,_ rather than
+of a primitive type such as an `int`, and those instances have all the features of other objects,
+such as methods, fields, and type membership. Likewise, a `TypeIsEnum` class defines a valued set
+of instances of that class, rather than of a set of some other type.
+
+```ruby
+Suit::CLUBS.is_a?(Suit)
+# => true
+Tarot::CUPS == 'Cups'
+# => false
+```
+
+## How is this different from `java.lang.Enum`?
+
+### Clunkier syntax
+
+In Java 5+, you can define an enum in one line and instance-specific methods with a pair of braces.
+
+```java
+enum CMYKColor {
+  CYAN, MAGENTA, YELLOW, BLACK
+}
+
+enum Suit {
+  CLUBS    { char pip() { return '♣'; } },
+  DIAMONDS { char pip() { return '♦'; } },
+  HEARTS   { char pip() { return '♥'; } },
+  SPADES   { char pip() { return '♠'; } };
+
+  abstract char pip();
+}
+```
+
+With `TypeIsEnum`, instance-specific methods require extra parentheses,
+as shown above, and about the best you can do even for simple enums is something like:
+
+```ruby
+class CMYKColor < TypeIsEnum::Enum
+  [:CYAN, :MAGENTA, :YELLOW, :BLACK].each { |c| new c }
+end
+```
+
+### No special `switch`/`case` support
+
+The Java compiler will warn you if a `switch` statement doesn't include all instances of a Java enum.
+Ruby doesn't care whether you cover all instances of a `TypeIsEnum`, and in fact it doesn't care if
+your `when` statements include a mix of enum instances of different classes, or of enum instances and
+other things. (In some respects this latter is a feature, of course.)
+
+### No serialization support
+
+The Java `Enum` class has special code to ensure that enum instances are deserialized to the existing
+singleton constants. This can be done with Ruby [`Marshal`](http://ruby-doc.org/core-2.2.3/Marshal.html)
+(by defining `marshal_load`) but it didn't seem worth the trouble, so a deserialized `TypeIsEnum` will
+not be identical to the original:
+
+```ruby
+clubs2 = Marshal.load(Marshal.dump(Suit::CLUBS))
+Suit::CLUBS.equal?(clubs2)
+# => false
+```
+
+However, `#==`, `#hash`, etc. are `Marshal`-safe:
+
+```ruby
+Suit::CLUBS == clubs2
+# => true
+clubs2 == Suit::CLUBS
+# => true
+Suit::CLUBS.hash == clubs2.hash
+# => true
+```
+
+If this isn't enough, and the lack of object identity across marshalling is a problem, it could be added
+in a later version. (Pull requests welcome!)
+
+### No support classes
+
+Java has `Enum`-specific classes like
+[`EnumSet`](http://docs.oracle.com/javase/8/docs/api/java/util/EnumSet.html) and
+[`EnumMap`](http://docs.oracle.com/javase/8/docs/api/java/util/EnumMap.html) that provide special
+high-performance, optimized versions of its collection interfaces. `TypeIsEnum` doesn't.
+
+### Enum classes are not closed
+
+It's Ruby, so even though `:new` is private to each enum class, you
+can work around that in various ways:
+
+```ruby
+Suit.send(:new, :JOKERS)
+# => #<Suit:0x007fc9e44e4778 @key=:JOKERS, @value="jokers", @ord=4>
+
+class Tarot
+  new :MAJOR_ARCANA, 'Major Arcana'
+end
+# => #<Tarot:0x007f8513b39b20 @key=:MAJOR_ARCANA, @value="Major Arcana", @ord=4>
+
+Suit.map(&:key)
+# => [:CLUBS, :DIAMONDS, :HEARTS, :SPADES, :JOKERS]
+
+Tarot.map(&:key)
+# => [:CUPS, :COINS, :WANDS, :SWORDS, :MAJOR_ARCANA]
+```
+
+## Contributing
+
+Pull requests are welcome, but please make sure the tests pass, the code has 100% coverage, and the
+code style passes Rubocop. (The default rake task should check all of these for you.)