simple_enumeration 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db482227bb77ad9212fc6077487d30784764163e517ecc6afba0edb2b2c64d77
-  data.tar.gz: 302b4da499d755e061cabfe66499bd4ad3de820c853b1f3f485a88ed09821462
+  metadata.gz: 9f607cb4dec057ddd252e3cbe5a59c1d8cb785dc45ce18edeaf00bf5d6506dd9
+  data.tar.gz: 872b7be3fc3ca5d2a2aaede66330c619e342338e59f37bb930c8cfd5d28d8df5
 SHA512:
-  metadata.gz: 3516edf3c82716566abc62d4d7c887e6498f7e8900a81b1c9e1ef641886cd6f8068e0d160667fce7914f3ae9c85c02f377682c92ed3d8034145354b5604d7af7
-  data.tar.gz: a870839c4f45381fa4b6320d1ecad91e78cfc0ffc78d722b4eef53a28a4bbdb83e01f5b970c7a380ff242d2eee1149af695a25d094d472f7f0e3632c508cc8e1
+  metadata.gz: 88b6b07d6ebb1f9124d117033df3ad0e47c9da9c019281e3baa213f95f41de8fc866b5bebe105a52c6ba24e7b19730fd93281b6501426310c78ef7c939f243cf
+  data.tar.gz: 585579183a525ab76a0f0d64bda899b0812c92edcfcf6d6acc4eca17b700fac99193c00407c1610b662021e286e364c4b0553e0bc1e0fc0eb8ffa5a76afdb9c2

data/.rubocop.yml

@@ -13,6 +13,7 @@ Style/Documentation:
 
 Metrics/BlockLength:
   Exclude:
+    - simple_enumeration.gemspec
     - "spec/**/*.rb"
 
 RSpec/MultipleExpectations:

data/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 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] - 2021-10-28
+
+### Added
+- Fill gem summary and description
+- Fill "Usage" section in readme
+- Add new model definiton using `define_simple_enumeration` method
+
 ## [0.2.0] - 2021-10-27
 
 First public release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    simple_enumeration (0.2.0)
+    simple_enumeration (0.2.1)
       activesupport
       callee
       dry-initializer

data/README.md

@@ -1,6 +1,8 @@
-# Enumeration
+# SimpleEnumeration
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/simple_enumeration`. To experiment with that code, run `bin/console` for an interactive prompt.
+Enumerations system for Ruby with awesome features!
+
+Helps you to declare enumerations in a very simple and flexible way. Define your enumerations in classes, it means you can add new behaviour and also reuse them.
 
 ## Installation
 
@@ -20,7 +22,227 @@ Or install it yourself as:
 
 ## Usage
 
-See code in the file `examples/payment_status` and `spec/simple_enumeration/entity_spec`.
+### Creating enumerations
+
+Enumerations are defined as plain Ruby classes. For rails usage you can put definitions inside `app/enumerations` folder.
+
+When we want define basic enumerations collection, we use `define_basic_collection` method like that:
+
+```ruby
+class PaymentStatusEnumeration < SimpleEnumeration::Entity
+  define_basic_collection(
+    :unpaid,
+    :failed,
+    :expired,
+    completed: :paid
+  )
+end
+```
+
+After that we have new class and instance methods at our disposal:
+
+* All enumeration's types have basic collection class methods:
+
+  ```ruby
+  PaymentStatusEnumeration.basic_collection
+  #=> #<SimpleEnumeration::Collection:0x000000010d73ec78 @name=:basic,
+  # @types={
+  #  "unpaid"=>#<SimpleEnumeration::Type:0x000000010d733210 @converted_value="unpaid", @definition=:unpaid, @enum_class=PaymentStatusEnumeration, @value="unpaid">,
+  #  "failed"=>#<SimpleEnumeration::Type:0x000000010d730358 @converted_value="failed", @definition=:failed, @enum_class=PaymentStatusEnumeration, @value="failed">,
+  #  "expired"=>#<SimpleEnumeration::Type:0x000000010d726880 @converted_value="expired", @definition=:expired, @enum_class=PaymentStatusEnumeration, @value="expired">,
+  #  "completed"=>#<SimpleEnumeration::Type:0x000000010d725570 @converted_value="paid", @definition={:completed=>:paid}, @enum_class=PaymentStatusEnumeration, @value="completed">
+  #  }>
+
+  PaymentStatusEnumeration.basic_collection_values
+  #=> ["unpaid", "failed", "expired", "paid"]
+
+  PaymentStatusEnumeration.basic_collection_value?('completed')
+  #=> false
+
+  PaymentStatusEnumeration.basic_collection_value?('paid')
+  #=> true
+
+  PaymentStatusEnumeration.basic_collection_for_select
+  #=> [["Nieopłacone", "unpaid"], ["Zakończone niepowodzeniem", "failed"], ["Wygasłe", "expired"], ["Zapłacone", "paid"]]
+
+  PaymentStatusEnumeration.basic_collection_humanized
+  #=> ["Nieopłacone", "Zakończone niepowodzeniem", "Wygasłe", "Zapłacone"]
+  ```
+
+* Each enumeration's type has own class method:
+
+  ```ruby
+  PaymentStatusEnumeration.unpaid
+  #=> #<SimpleEnumeration::Type:0x000000010d733210 @converted_value="unpaid", @definition=:unpaid, @enum_class=PaymentStatusEnumeration, @value="unpaid">
+
+  PaymentStatusEnumeration.failed
+  #=> #<SimpleEnumeration::Type:0x000000010d730358 @converted_value="failed", @definition=:failed, @enum_class=PaymentStatusEnumeration, @value="failed">
+
+  PaymentStatusEnumeration.expired
+  #=> #<SimpleEnumeration::Type:0x000000010d726880 @converted_value="expired", @definition=:expired, @enum_class=PaymentStatusEnumeration, @value="expired">
+
+  PaymentStatusEnumeration.completed
+  #=> #<SimpleEnumeration::Type:0x000000010d725570 @converted_value="paid", @definition={:completed=>:paid}, @enum_class=PaymentStatusEnumeration, @value="completed">
+
+  PaymentStatusEnumeration.completed.definition
+  # => :completed
+
+  PaymentStatusEnumeration.completed.value
+  #=> "completed"
+
+  PaymentStatusEnumeration.completed.converted_value
+  #=> "paid"
+
+  PaymentStatusEnumeration.completed.for_select
+  #=> ["Zapłacone", "paid"]
+
+  PaymentStatusEnumeration.completed.humanized
+  #=> "Zapłacone"
+
+  PaymentStatusEnumeration.completed.meta
+  #=> {:color=>"green"}
+
+  PaymentStatusEnumeration.completed.translations
+  #=> {:text=>"Zapłacone", :color=>"green"
+  ```
+
+When we want define custom enumerations collection, we use `define_custom_collection` method:
+
+```ruby
+class PaymentStatusEnumeration < SimpleEnumeration::Entity
+  define_basic_collection(
+    :unpaid,
+    :failed,
+    :expired,
+    completed: :paid
+  )
+
+  define_custom_collection(
+    :finished,
+    failed,
+    expired,
+    completed
+  )
+end
+```
+
+After that we have all methods described above and new ones at our disposal:
+
+```ruby
+  PaymentStatusEnumeration.finished_collection
+  #=> #<SimpleEnumeration::Collection:0x0000000109873bd8 @name=:finished,
+  # @types={
+  #  "failed"=>#<SimpleEnumeration::Type:0x000000010d730358 @converted_value="failed", @definition=:failed, @enum_class=PaymentStatusEnumeration, @value="failed">,
+  #  "expired"=>#<SimpleEnumeration::Type:0x000000010d726880 @converted_value="expired", @definition=:expired, @enum_class=PaymentStatusEnumeration, @value="expired">,
+  #  "completed"=>#<SimpleEnumeration::Type:0x000000010d725570 @converted_value="paid", @definition={:completed=>:paid}, @enum_class=PaymentStatusEnumeration, @value="completed">
+  #  }>
+
+  PaymentStatusEnumeration.finished_collection_values
+  #=> ["failed", "expired", "paid"]
+
+  PaymentStatusEnumeration.finished_collection_value?('completed')
+  #=> false
+
+  PaymentStatusEnumeration.finished_collection_value?('paid')
+  #=> true
+
+  PaymentStatusEnumeration.finished_collection_value?('unpaid')
+  #=> false
+
+  PaymentStatusEnumeration.finished_collection_for_select
+  #=> [["Zakończone niepowodzeniem", "failed"], ["Wygasłe", "expired"], ["Zapłacone", "paid"]]
+
+  PaymentStatusEnumeration.finished_collection_humanized
+  #=> ["Zakończone niepowodzeniem", "Wygasłe", "Zapłacone"]
+  ```
+
+
+### Model definition
+
+Initially, there is no special dsl extension, but we can simply do that:
+
+```ruby
+# ActiveRecord class
+#
+class Order < ApplicationRecord
+  extend SimpleEnumeration
+
+  define_simple_enumeration :payment_status
+end
+
+# Plain Ruby class
+#
+class Order
+  extend SimpleEnumeration
+
+  define_simple_enumeration :payment_status
+
+  attr_accessor :payment_status
+
+  def initialize(payment_status:)
+    @payment_status = payment_status
+  end
+end
+```
+
+This will allow us to use enumeration type methods:
+
+```ruby
+order = Order.new(payment_status: 'paid')
+
+order.payment_status_enumeration.type.humanized
+#=> "Zapłacone"
+order.payment_status_enumeration.type.meta
+#=> {:color=>"green"}
+order.payment_status_enumeration.type.translations
+#=> {:text=>"Zapłacone", :color=>"green"}
+order.payment_status_enumeration.type.for_select
+#=> ["Zapłacone", "paid"]
+
+order.payment_status_enumeration.unpaid_value?
+#=> false
+order.payment_status_enumeration.failed_value?
+#=> false
+order.payment_status_enumeration.expired_value?
+#=> false
+order.payment_status_enumeration.completed_value?
+#=> true
+order.payment_status_enumeration.basic_collection_value?
+#=> true
+order.payment_status_enumeration.finished_collection_value?
+#=> true
+```
+
+### Translations
+
+Translations are defined using i18n gem.
+
+#### I18n lokup
+
+The I18n strings are located on `simple_enumeration.<enumeration_name>.<value>.text`:
+
+```yaml
+pl:
+  simple_enumeration:
+    payments_status:
+      unpaid:
+        text: "Nieopłacone"
+        color: yellow
+```
+
+#### Translate a name-spaced enumeration
+
+In order to translate an enumeration in a specific namespace (say `Payments::StatusEnumeration`),
+you can add the following:
+
+```yaml
+pl:
+  simple_enumeration:
+    payments/status:
+      unpaid:
+        text: "Nieopłacone"
+        color: yellow
+```
 
 ## Development
 

data/bin/console

@@ -4,12 +4,10 @@
 require 'bundler/setup'
 require 'simple_enumeration'
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
+require_relative '../spec/support/i18n'
+require_relative '../examples/payment_status_enumeration'
 
+require 'pry'
 require 'irb'
+
 IRB.start(__FILE__)

data/examples/{payment_status.rb → payment_status_enumeration.rb}

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-require 'simple_enumeration'
-
-class PaymentStatus < SimpleEnumeration::Entity
+class PaymentStatusEnumeration < SimpleEnumeration::Entity
   define_basic_collection(
     :unpaid,
     :failed,
@@ -30,3 +28,15 @@ class PaymentStatus < SimpleEnumeration::Entity
     end
   end
 end
+
+class Order
+  extend SimpleEnumeration
+
+  define_simple_enumeration :payment_status
+
+  attr_accessor :payment_status
+
+  def initialize(payment_status:)
+    @payment_status = payment_status
+  end
+end

data/lib/simple_enumeration/define_simple_enumeration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SimpleEnumeration
+  module DefineSimpleEnumeration
+    def define_simple_enumeration(attribute, options = {})
+      enum_class = options[:with] || const_get([attribute.to_s.camelcase, 'Enumeration'].join)
+
+      define_method "#{attribute}_enumeration" do
+        enum_class.new(converted_value: send(attribute))
+      end
+    end
+  end
+end

data/lib/simple_enumeration/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleEnumeration
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/lib/simple_enumeration.rb

@@ -18,6 +18,10 @@ require_relative 'simple_enumeration/collections/basic_factory'
 require_relative 'simple_enumeration/collections/custom_factory'
 require_relative 'simple_enumeration/collection_methods_definer'
 require_relative 'simple_enumeration/entity'
+require_relative 'simple_enumeration/define_simple_enumeration'
 
 module SimpleEnumeration
+  def self.extended(receiver)
+    receiver.extend DefineSimpleEnumeration
+  end
 end

data/simple_enumeration.gemspec

@@ -8,8 +8,12 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Norbert Małecki']
   spec.email         = ['norbert.malecki@icloud.com']
 
-  spec.summary       = 'Enumeration'
-  spec.description   = 'Enumeration'
+  spec.summary       = 'Enumerations system for Ruby with awesome features!'
+  spec.description   = [
+    'Helps you to declare enumerations in a very simple and flexible way.',
+    'Define your enumerations in classes, it means you can add new behaviour and also reuse them.'
+  ].join(' ')
+
   spec.homepage      = 'https://github.com/norbertmaleckii/simple-enumeration-rb'
   spec.license       = 'MIT'
   spec.required_ruby_version = '>= 2.5.0'
@@ -23,6 +27,7 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
   end
+
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_enumeration
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Norbert Małecki
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-10-27 00:00:00.000000000 Z
+date: 2021-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -80,7 +80,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Enumeration
+description: Helps you to declare enumerations in a very simple and flexible way.
+  Define your enumerations in classes, it means you can add new behaviour and also
+  reuse them.
 email:
 - norbert.malecki@icloud.com
 executables: []
@@ -101,12 +103,13 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- examples/payment_status.rb
+- examples/payment_status_enumeration.rb
 - lib/simple_enumeration.rb
 - lib/simple_enumeration/collection.rb
 - lib/simple_enumeration/collection_methods_definer.rb
 - lib/simple_enumeration/collections/basic_factory.rb
 - lib/simple_enumeration/collections/custom_factory.rb
+- lib/simple_enumeration/define_simple_enumeration.rb
 - lib/simple_enumeration/entity.rb
 - lib/simple_enumeration/type.rb
 - lib/simple_enumeration/type_builder.rb
@@ -141,5 +144,5 @@ requirements: []
 rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
-summary: Enumeration
+summary: Enumerations system for Ruby with awesome features!
 test_files: []