lamy_result 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9de251784cf83e80ac19a2f8d08bd00de25269ccae683b518570bcf710cf5918
+  data.tar.gz: 287d464139c3ae445e4cbdf477e9ea4109f08dde36db4394e79f5613fc5be00d
+SHA512:
+  metadata.gz: 6845ef3a74016eebfdd7c34aa55cca0f4044cf0bdf89fff49f5c31d24393b7165b5e6a648dd08ae5ab17c079d1cbfff8d9a5be31c83693f934a3e6cfcc65141f
+  data.tar.gz: 7eb32ea5eb7c3d4da5ff15905fece148885fcdd352d3c06cf4a80e455fd90d88eeacf5212a23fe79c658c3ccd7d787488e609e6a0ab976ba632c134d669ce5a7

data/.rspec

@@ -0,0 +1,5 @@
+--format documentation
+--color
+--force-color
+--require spec_helper
+--order random

data/.rubocop.yml

@@ -0,0 +1,25 @@
+AllCops:
+  TargetRubyVersion: 2.5
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 79
+
+Layout/EndOfLine:
+  EnforcedStyle: lf
+
+Layout/SpaceInsideBlockBraces:
+  SpaceBeforeBlockParameters: false
+
+Style/RegexpLiteral:
+  EnforcedStyle: slashes
+
+Lint/BooleanSymbol:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+## [Unreleased]
+
+## [0.2.0] - 2022-03-07
+
+### Add
+
+- Allow aliases of the status tags to be defined with the .define_status_tags
+  method.
+
+### Remove
+
+- No longer define methods with the method_missing hook.
+
+## [0.1.0] - 2022-03-04
+
+- Initial release

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in Lamy.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.7"

data/Gemfile.lock

@@ -0,0 +1,55 @@
+PATH
+  remote: .
+  specs:
+    lamy_result (0.2.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    diff-lcs (1.5.0)
+    parallel (1.21.0)
+    parser (3.1.1.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.2.1)
+    rexml (3.2.5)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-support (3.11.0)
+    rubocop (1.25.1)
+      parallel (~> 1.10)
+      parser (>= 3.1.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.15.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.16.0)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.1.0)
+
+PLATFORMS
+  x64-mingw32
+
+DEPENDENCIES
+  lamy_result!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.7)
+
+BUNDLED WITH
+   2.2.27

data/LICENSE.txt

@@ -0,0 +1,15 @@
+Apache License, Version 2.0 (Apache-2.0)
+
+Copyright 2022 Jed Burke
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,89 @@
+# Lamy Result
+
+Lamy Result is a simple utility used to wrap method results with a status and a value.
+
+The project is inspired by Elixir and Erlang's tagged tuple and Rust's Result/Option. Despite inspiration from other languages, Lamy Result aims to be idiomatic Ruby and runtime dependency-free.
+
+Rather than change the way you're doing things. Returning a single result is great for most cases. You'll know if and when you need something more.
+
+```ruby
+include LamyResult
+
+result = Lamy.ok('Lamy is awesome')
+
+if result.ok?
+  do_something_cool result.value
+end
+
+# or
+
+# Will only evaluate if the status is :ok
+result.ok_then do |v|
+  do_something_cool v
+end
+
+result.to_a
+# Output: [:ok, 'Lamy is awesome']
+
+result.to_h
+# Output: { status: :ok, value: 'Lamy is awesome' }
+
+
+# Aliases allow for natural expression.
+
+def do_another_cool_thing
+  # Report success
+  Lamy.success('It worked')
+end
+
+another_result = do_another_cool_thing
+
+# As in "Was the operation successful?"
+another_result.successful?
+
+# As in "Has the operation succeeded?"
+another_result.succeeded?
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'lamy_result'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install lamy_result
+
+## Usage
+
+A few pre-designed status labels are included: `success` `ok` `failed` `error` `true` `false`
+
+As a short-hand way to create a result, each one corresponds to a static method (or class method) on the Lamy class.
+
+For example, `Lamy.failed('You did not think this through.')` will instantize a Lamy instance with the status set to `:failed` and the value to `You did not think this through.`
+
+
+## Motivation
+
+The idea came from a function which would check if a file exists with either dashes or underscores. If I was looking for `./ecchi/ecchi-pic-7.jpg`, it should also check for `./ecchi/ecchi_pic_7.jpg`. Without going on a tangent, the function is meant to reconcile file name inconsistencies.
+
+The return value could  be the file name if it exists and false if does not. Returning a hash with `status` and `value` was more appealing. And that's where we are now.
+
+## Name?
+
+Named after the hololive VTuber Yukihana Lamy. I was watching her content while designing the class. Thought that maybe naming it in honor of her would give me the motivation to deliver a documented and tested production-ready gem. It's now more complicated than initially intended. So maybe it wasn't a good idea.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/JedBurke/LamyResult.
+
+## License
+
+The gem is available as open source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'lamy'
+
+# 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 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lamy_result.gemspec

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative 'lib/lamy_result/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lamy_result'
+  spec.version       = LamyResult::VERSION
+  spec.authors       = ['Jed Burke']
+  spec.email         = ['opensource@evrnetwork.co.za']
+
+  spec.summary       = 'Wrap results with a status and a value.'
+  spec.description   = <<~EOF
+    The project is inspired by Elixir and Erlang's tagged tuple and Rust's Result/Option. Despite inspiration from other languages, Lamy Result aims to be idiomatic Ruby and runtime dependency-free.
+
+    Rather than change the way you're doing things. Returning a single result is great for most cases. You'll know if and when you need something more.
+
+    ```ruby
+    include LamyResult
+
+    result = Lamy.ok('Lamy is awesome')
+
+    if result.ok?
+      do_something_cool result.value
+    end
+
+    # or
+
+    # Will only evaluate if the status is :ok
+    result.ok_then do |v|
+      do_something_cool v
+    end
+
+    result.to_a
+    # Output: [:ok, 'Lamy is awesome']
+
+    result.to_h
+    # Output: { status: :ok, value: 'Lamy is awesome' }
+
+
+    # Aliases allow for natural expression.
+
+    def do_another_cool_thing
+      # Report success
+      Lamy.success('It worked')
+    end
+
+    another_result = do_another_cool_thing
+
+    # As in "Was the operation successful?"
+    another_result.successful?
+
+    # As in "Has the operation succeeded?"
+    another_result.succeeded?
+    ```
+  EOF
+
+  spec.homepage      = 'https://evrnetwork.co.za'
+  spec.license       = 'Apache-2.0'
+  spec.required_ruby_version = ">= 2.5.0"
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/JedBurke/LamyResult'
+  spec.metadata['changelog_uri'] = 'https://github.com/JedBurke/LamyResult/blob/master/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/lamy_result/lamy.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module LamyResult
+
+  # Creates and checks result instances.
+  #
+  # A quick reference for class and instance methods.
+  #   Lamy.ok is a class method to be called on the `Lamy` class.
+  #
+  #   Lamy#ok? is an instance method called on a Lamy instance, which is
+  #   returned by Lamy.ok.
+  #     result = Lamy.ok(Excon.get('https://example.com'))
+  #     result.ok? => true
+  #
+  #   See .define_status_tags for the method defined at runtime.
+  class Lamy
+    def initialize(status:, value: nil)
+      @status = status
+                .to_s
+                .downcase
+                .to_sym
+
+      @value = value
+    end
+
+    # The raw attributes may be accessed from outside the class, but
+    # shouldn't be changed once set.
+    attr_reader :status,
+                :value
+
+    # Compares the current instance's status to the input value. This is a
+    # lov-level method meant to be used by the #ok? and #success? methods.
+    def status_is?(value)
+      @status == value.to_sym
+    end
+
+    # Calls #status_is? on the `status_to_check` and if true, yields the value.
+    # Otherwise, returns the instance. This is a low-level method meant to be
+    # used by #ok_then and #success_then methods.
+    def assert_status_then(status_to_check:)
+      if status_is?(status_to_check)
+        return yield @value if block_given?
+
+        return @value
+      end
+
+      self
+    end
+
+    # Returns the status attribute as a symbol or a TrueClass/FalseClass. This
+    # is a low-level method meant to be used by #to_a and #to_h.
+    def export_status
+      # If the status is a boolean, return the status as a boolean.
+      # Otherwise, return it as a symbol, which it should already be.
+      if true? || false?
+        @status.to_s.to_sym == true.to_s.to_sym
+      else
+        @status.to_s.to_sym
+      end
+    end
+
+    # Returns an array of the instance. The status instance attribute is
+    # first and the value attribute is second. The status will be returned
+    # as a symbol unless it is true or false. At which point, it will
+    # be converted.
+    def to_a
+      [
+        export_status,
+        @value
+      ]
+    end
+
+    # Returns a hash of the instance with @status under the `status` key
+    # and @value under the `value` key. The status will be returned as a
+    # symbol unless it is true or false. At which point, it will be converted.
+    def to_h
+      {
+        status: export_status,
+        value: @value
+      }
+    end
+
+    # Adds one or more new status tags to be used by the
+    def self.define_status_tags(*status_tags)
+      # Use Array() over [] to create an array if status_tags is not an array,
+      # but not create an array within an array.
+      Array(
+        status_tags
+      ).each do |status|
+        new_status, *new_status_aliases = Array(status)
+
+        # Defines the short-hand class method like .ok(input)
+        self.define_status_method(new_status, *new_status_aliases)
+
+        # Define status check instance methods like #ok?
+        self.define_status_check_method(new_status, *new_status_aliases)
+
+        # Define conditional instance methods like #ok_then
+        self.define_conditional_then_method(new_status, *new_status_aliases)
+      end
+    end
+
+    def self.format_status_check_method(status)
+      "#{status.to_s}?".to_sym
+    end
+
+    def self.format_conditional_method(status)
+      "#{status.to_s}_then".to_sym
+    end
+
+    def self.define_status_method(status, *aliases)
+      self
+      .class
+      .send(:define_method, status) do |value|
+        Lamy.new(status: status, value: value)
+      end
+
+      # Define aliases for the new status if we got any.
+      define_class_aliases_for(status, *aliases)
+    end
+
+    # Defines an instance method to check the status label. E.g. #ok?
+    def self.define_status_check_method(status, *aliases)
+      method_symbol = format_status_check_method(status)
+      status_check_aliases = aliases.map do |s|
+        format_status_check_method(s)
+      end
+
+      define_method(method_symbol) do
+        # Get the status that we need to check. It should have
+        # been captured.
+        status_is?(status.to_sym)
+      end
+
+      assert_new_instance_method! method_symbol
+
+      self.define_instance_aliases_for(method_symbol, *status_check_aliases)
+    end
+
+    def self.define_conditional_then_method(status, *aliases)
+      method_symbol = format_conditional_method(status)
+      status_conditional_aliases = aliases.map do |s|
+        format_conditional_method(s)
+      end
+
+      define_method(method_symbol) do |&method_block|
+        assert_status_then(status_to_check: status, &method_block)
+      end
+
+      assert_new_instance_method! method_symbol
+
+      define_instance_aliases_for(
+        method_symbol,
+        *status_conditional_aliases
+      )
+    end
+
+    # Checks if the method is an instance method, otherwise raises a
+    # StandardError.
+    def self.assert_new_instance_method!(method_symbol)
+      unless self.instance_methods.include?(method_symbol)
+        raise StandardError.new "##{method_symbol} is not an instance method."
+      end
+
+      true
+    end
+
+    # Defines a class or instance alias for the supplied method with each of
+    # the supplied array items.
+    def self.define_aliases_for(
+      method_symbol,
+      instance_alias,
+      *method_aliases
+    )
+      method_aliases.each do |method_alias|
+        if instance_alias
+          alias_method(method_alias, method_symbol)
+        else
+          self.class.alias_method(method_alias, method_symbol)
+        end
+      end
+
+      true
+    end
+
+    def self.define_class_aliases_for(method_symbol, *method_aliases)
+      define_aliases_for(method_symbol, false, *method_aliases)
+    end
+
+    # Defines an instance alias for the supplied method with each of
+    # the supplied array items.
+    def self.define_instance_aliases_for(method_symbol, *method_aliases)
+      define_aliases_for(
+        method_symbol,
+        true,
+        *method_aliases
+      )
+    end
+
+    # Override the equality operators and set them as aliases for
+    # the #status_is? method.
+    alias == status_is?
+    alias eql? status_is?
+
+    class << self
+      # The singular form may be more comfortable for users wanting to define
+      # a single tag.
+      alias define_status_tag define_status_tags
+
+      # `add_status_tags` might be more comfortable or easier to remember than
+      # `define_status_tags`
+      alias add_status_tags define_status_tags
+      alias add_status_tag define_status_tags
+    end
+
+    # Add the basic tags to the class.
+    Lamy.define_status_tags(
+      [:succeeded, :success, :successful],
+      [:failed, :fail, :error],
+      :ok,
+      :true,
+      :false
+    )
+  end
+end

data/lib/lamy_result/version.rb

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

data/lib/lamy_result.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'lamy_result/lamy'
+require_relative 'lamy_result/version'

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: lamy_result
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Jed Burke
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2022-04-10 00:00:00.000000000 Z
+dependencies: []
+description: |
+  The project is inspired by Elixir and Erlang's tagged tuple and Rust's Result/Option. Despite inspiration from other languages, Lamy Result aims to be idiomatic Ruby and runtime dependency-free.
+
+  Rather than change the way you're doing things. Returning a single result is great for most cases. You'll know if and when you need something more.
+
+  ```ruby
+  include LamyResult
+
+  result = Lamy.ok('Lamy is awesome')
+
+  if result.ok?
+    do_something_cool result.value
+  end
+
+  # or
+
+  # Will only evaluate if the status is :ok
+  result.ok_then do |v|
+    do_something_cool v
+  end
+
+  result.to_a
+  # Output: [:ok, 'Lamy is awesome']
+
+  result.to_h
+  # Output: { status: :ok, value: 'Lamy is awesome' }
+
+
+  # Aliases allow for natural expression.
+
+  def do_another_cool_thing
+    # Report success
+    Lamy.success('It worked')
+  end
+
+  another_result = do_another_cool_thing
+
+  # As in "Was the operation successful?"
+  another_result.successful?
+
+  # As in "Has the operation succeeded?"
+  another_result.succeeded?
+  ```
+email:
+- opensource@evrnetwork.co.za
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lamy_result.gemspec
+- lib/lamy_result.rb
+- lib/lamy_result/lamy.rb
+- lib/lamy_result/version.rb
+homepage: https://evrnetwork.co.za
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://evrnetwork.co.za
+  source_code_uri: https://github.com/JedBurke/LamyResult
+  changelog_uri: https://github.com/JedBurke/LamyResult/blob/master/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.3
+signing_key: 
+specification_version: 4
+summary: Wrap results with a status and a value.
+test_files: []