semantic_boolean 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b3d9c2076d58203acfd4d286c8f0491a0403585af352e12a3f1477e0d3bd8d0a
+  data.tar.gz: 66dc456ae946024cee15a33d91fb87af31d191d05760178095e4a32850bd2e5e
+SHA512:
+  metadata.gz: 041dc449b3a8cf4d47cb3d4c97782d0cb7af6f4282e5a2c4e075d74d57d68c7843d1645bb6901a18e7866af1a6e03833e6958ee063ab202ce3a46e9616feb81f
+  data.tar.gz: 8912adf0a5e985ddea2141db7906e72b541f226fed6fce0cb6e3ac0486d61021924ef19bc0adec75ad48a4c875d8925dca9a4946bf6d60c98e6bdc3052232bdd

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Marian Kostyk
+
+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,141 @@
+# Semantic Boolean
+
+[![Ruby](https://img.shields.io/badge/ruby-%23CC342D.svg?style=for-the-badge&logo=ruby&logoColor=white)](https://www.ruby-lang.org/en/)
+
+[![Gem Version](https://badge.fury.io/rb/semantic_boolean.svg)](https://rubygems.org/gems/semantic_boolean) [![Gem Downloads](https://img.shields.io/gem/dt/semantic_boolean.svg)](https://rubygems.org/gems/semantic_boolean)  ![GitHub repo size](https://img.shields.io/github/repo-size/marian13/semantic_boolean) [![GitHub Actions CI](https://github.com/marian13/semantic_boolean/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/marian13/semantic_boolean/actions/workflows/ci.yml) [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard) [![Coverage Status](https://coveralls.io/repos/github/marian13/semantic_boolean/badge.svg)](https://coveralls.io/github/marian13/semantic_boolean?branch=main) [![yard docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://marian13.github.io/semantic_boolean)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Multiple ways to convert Ruby objects into booleans bundled in a single gem.
+
+## TL;DR
+
+```ruby
+require "semantic_boolean"
+
+##
+# Converts an object to the boolean using `!!`.
+#
+SemanticBoolean.to_ruby_bool(any_object)
+# => true or false
+
+##
+# Alias for `SemanticBoolean.to_ruby_bool`.
+#
+SemanticBoolean.to_bool(any_object)
+# => true or false
+
+##
+# Converts `true`, `"t"`, `"T"`, `"true"`, `"True"`, `"TRUE"`, `"on"`, `"On"`, `"ON"`, `"y"`,
+# `"Y"`, `"yes"`, `"Yes"`, `"YES"`, positive numbers (like `1`, `1.0`, `BibDecimal("1")`)
+# and strings with positive numbers (like `"1"`, `"1.0"`) to `true`.
+# Returns `false` for anything else.
+#
+# Useful for parsing values read from `ENV`, CLI options, etc.
+#
+SemanticBoolean.to_env_bool(any_object)
+# => true or false
+
+##
+# Converts to a boolean just like `ActiveModel::Type::Boolean.new.cast(object)` does.
+# - https://api.rubyonrails.org/classes/ActiveModel/Type/Boolean.html
+#
+SemanticBoolean.to_active_model_boolean_type(any_object)
+# => true, false, or nil
+
+##
+# Converts to a boolean just like Rails `blank?` does.
+# - https://api.rubyonrails.org/classes/Object.html#method-i-blank-3F
+#
+SemanticBoolean.blank?(any_object)
+# => true or false
+
+##
+# Converts to a boolean just like Rails `present?` does.
+# - https://api.rubyonrails.org/classes/Object.html#method-i-present-3F
+#
+SemanticBoolean.present?(any_object)
+# => true or false
+
+##
+# The following methods do not return boolean values, but they are often utilized in a boolean context.
+##
+SemanticBoolean.to_one_or_zero(any_object)
+# => 1 or 0
+
+SemanticBoolean.to_y_or_n(any_object)
+# => "y" or "n"
+
+SemanticBoolean.to_yes_or_no(any_object)
+# => "yes" or "no"
+
+SemanticBoolean.to_on_or_off(any_object)
+# => "on" or "off"
+
+SemanticBoolean.to_true_or_false(any_object)
+# => true or false
+
+##
+# All the `to_one_or_zero`, `to_y_or_n`, `to_yes_or_no`, `to_on_or_off`, and `to_true_or_false` methods accept the `:by` keyword.
+# `:to_ruby_bool` is the default value.
+# `:to_bool`, `:to_env_bool`, `:to_active_model_boolean_type`, `:blank?` and `:present?` are also available.
+#
+SemanticBoolean.to_one_or_zero(any_object)
+SemanticBoolean.to_y_or_n(any_object, by: :to_ruby_bool)
+SemanticBoolean.to_yes_or_no(any_object, by: :to_bool)
+SemanticBoolean.to_on_or_off(any_object, by: :to_env_bool)
+SemanticBoolean.to_true_or_false(any_object, by: :to_active_model_boolean_type)
+SemanticBoolean.to_one_or_zero(any_object, by: :blank?)
+SemanticBoolean.to_y_or_n(any_object, by: :present?)
+
+##
+# Also there is the `:unknown` keyword.
+# It allows to specify what should be returned when `object` is `nil`.
+#
+SemanticBoolean.to_one_or_zero(any_object, unknown: 127)
+SemanticBoolean.to_yes_or_no(any_object, by: :to_env_bool, unknown: "unavailable")
+```
+
+Check the [specs](https://github.com/marian13/semantic_boolean/blob/main/spec/lib/semantic_boolean_spec.rb) to see a comprehensive comparison of all Semantic Boolean methods.
+
+## Installation
+
+### Bundler
+
+Add the following line to your Gemfile:
+
+```ruby
+gem "semantic_boolean"
+```
+
+And then run:
+
+```bash
+bundle install
+```
+
+### Without Bundler
+
+Execute the command below:
+
+```bash
+gem install semantic_boolean
+```
+
+## Performance
+
+This gem is especially useful for one-time Ruby scripts, CLI applications, configuration parsers that are reading values from `ENV`, YAML files, etc.
+
+However, if you have a code snippet where performance is a requirement, prefer using the original implementations (if you need [blank?](https://github.com/rails/rails/blob/main/activesupport/lib/active_support/core_ext/object/blank.rb), [present?](https://github.com/rails/rails/blob/main/activesupport/lib/active_support/core_ext/object/blank.rb), or [to_active_model_boolean_type](https://github.com/rails/rails/blob/main/activemodel/lib/active_model/type/boolean.rb)) or dive into the [Semantic Boolean source](https://github.com/marian13/semantic_boolean/blob/main/lib/semantic_boolean.rb) to extract only the parts that your application can leverage the most effectively.
+
+## Credits
+
+To the CLI enthusiasts, who allow me to pass words, numbers, and shortcuts to the same shell commands options depending on my mood.
+
+```bash
+DEBUG=1
+SKIP_AUTH=no
+--verbose=y
+--tracking=off
+```
+
+To the Rails team. They made me a Ruby dev who can't live without Rails goodies in the non-Rails projects.

data/lib/semantic_boolean/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SemanticBoolean
+  VERSION = "1.0.0"
+end

data/lib/semantic_boolean.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+require_relative "semantic_boolean/version"
+
+require "set"
+
+# rubocop:disable Lint/BooleanSymbol
+module SemanticBoolean
+  class << self
+    ##
+    # Truthy values in `SemanticBoolean.to_env_bool` terms.
+    #
+    # @return [Array<String>]
+    #
+    TO_ENV_BOOL_TRUE_VALUES = ["t", "T", "true", "True", "TRUE", "on", "On", "ON", "y", "Y", "yes", "Yes", "YES"].freeze
+
+    ##
+    # Falsy values in `ActiveModel::Type::Boolean` terms.
+    #
+    # @return [Array<String>]
+    #
+    # @see https://github.com/rails/rails/blob/v8.0.2/activemodel/lib/active_model/type/boolean.rb#L15
+    #
+    TO_ACTIVE_MODEL_BOOLEAN_TYPE_FALSE_VALUES = [false, 0, "0", :"0", "f", :f, "F", :F, "false", :false, "FALSE", :FALSE, "off", :off, "OFF", :OFF].to_set.freeze
+
+    ##
+    # Regexp to match falsy string values in Rails `blank?` terms.
+    #
+    # @return [Regexp]
+    #
+    # @see https://github.com/rails/rails/blob/v8.0.2/activesupport/lib/active_support/core_ext/object/blank.rb#L136
+    #
+    ACTIVE_SUPPORT_CORE_EXT_BLANK_RE = /\A[[:space:]]*\z/
+
+    ##
+    # Cache of regexp objects to match falsy string values in Rails `blank?` terms with non-default encodings.
+    #
+    # @return [Hash]
+    #
+    # @see https://github.com/rails/rails/blob/v8.0.2/activesupport/lib/active_support/core_ext/object/blank.rb#L137
+    #
+    ACTIVE_SUPPORT_CORE_EXT_ENCODED_BLANKS = ::Hash.new do |h, enc|
+      h[enc] = ::Regexp.new(ACTIVE_SUPPORT_CORE_EXT_BLANK_RE.source.encode(enc), ACTIVE_SUPPORT_CORE_EXT_BLANK_RE.options | ::Regexp::FIXEDENCODING)
+    end
+
+    ##
+    # Returns `false` when `object` is `false` or `nil`.
+    # Returns `true` for all the other cases.
+    # Just like Ruby does in the control expressions.
+    #
+    # @param object [Object] Can be any type.
+    # @return [Boolean]
+    #
+    # @note If performance is a concern, prefer to use `!!` directly.
+    # @see https://docs.ruby-lang.org/en/3.4/syntax/control_expressions_rdoc.html
+    #
+    def to_ruby_bool(object)
+      !!object
+    end
+
+    ##
+    # A handy alias for `to_ruby_bool`.
+    #
+    # @return [Boolean]
+    #
+    alias_method :to_bool, :to_ruby_bool
+
+    if ::Gem::Version.create(::RUBY_VERSION) >= ::Gem::Version.create("2.6")
+      ##
+      # Converts `object` to a boolean by the following logic:
+      # - Converts `object` to a string by the `#to_s` method and checks whether it is one of `["t", "T", "true", "True", "TRUE", "on", "On", "ON", "y", "Y", "yes", "Yes", "YES"]`.
+      # - If yes, returns `true`, otherwise it converts `object` to an integer by `Kernel.Integer` and checks whether it is greater than zero.
+      # - If yes, returns `true`, otherwise returns `false`.
+      #
+      # @param object [Object] Can be any type.
+      # @return [Boolean]
+      #
+      def to_env_bool(object)
+        string = object.to_s
+
+        return false if string.empty?
+
+        return true if TO_ENV_BOOL_TRUE_VALUES.include?(string)
+
+        integer = ::Kernel.Integer(string, exception: false)
+
+        return false unless integer
+
+        integer > 0
+      rescue ::Encoding::CompatibilityError
+        false
+      end
+    else
+      ##
+      # Converts `object` to a boolean by the following logic:
+      # - Converts `object` to a string by the `#to_s` method and checks whether it is one of `["t", "T", "true", "True", "TRUE", "on", "On", "ON", "y", "Y", "yes", "Yes", "YES"]`.
+      # - If yes, returns `true`, otherwise it converts `object` to an integer by `Kernel.Integer` and checks whether it is greater than zero.
+      # - If yes, returns `true`, otherwise returns `false`.
+      #
+      # @param object [Object] Can be any type.
+      # @return [Boolean]
+      #
+      # rubocop:disable Lint/SuppressedExceptionInNumberConversion
+      def to_env_bool(object)
+        string = object.to_s
+
+        return false if string.empty?
+
+        return true if TO_ENV_BOOL_TRUE_VALUES.include?(string)
+
+        integer =
+          begin
+            ::Kernel.Integer(string)
+          rescue
+            nil
+          end
+
+        return false unless integer
+
+        integer > 0
+      rescue ::Encoding::CompatibilityError
+        false
+      end
+      # rubocop:enable Lint/SuppressedExceptionInNumberConversion
+    end
+
+    ##
+    # Converts `object` to boolean using exactly the same logic as `blank?` in Rails does (but with `Hash` instead of `Concurent::Map` for string encodings storage).
+    #
+    # @param object [Object] Can be any type.
+    # @return [Boolean]
+    #
+    # @note If performance is a concern, prefer to load Rails (or just `activesupport`) and use `blank?` directly.
+    # @see https://api.rubyonrails.org/classes/Object.html#method-i-blank-3F
+    # @see https://api.rubyonrails.org/classes/ActiveSupport/TimeWithZone.html#method-i-blank-3F
+    # @see https://api.rubyonrails.org/classes/ActiveRecord/Relation.html#method-i-blank-3F
+    #
+    def blank?(object)
+      return object.__send__(:blank?) if object.respond_to?(:blank?)
+
+      case object
+      when NilClass
+        true
+      when FalseClass
+        true
+      when TrueClass
+        false
+      when Array
+        object.empty?
+      when Hash
+        object.empty?
+      when Symbol
+        object.empty?
+      when String
+        object.empty? ||
+          begin
+            ACTIVE_SUPPORT_CORE_EXT_BLANK_RE.match?(object)
+          rescue ::Encoding::CompatibilityError
+            ACTIVE_SUPPORT_CORE_EXT_ENCODED_BLANKS[object.encoding].match?(object)
+          end
+      when Numeric
+        false
+      when Time
+        false
+      when Object
+        object.respond_to?(:empty?) ? !!object.empty? : false
+      else
+        object.__send__(:blank?)
+      end
+    end
+
+    ##
+    # Converts `object` to boolean using exactly the same logic as `present?` in Rails does (but with `Hash` instead of `Concurent::Map` for string encodings storage).
+    #
+    # @param object [Object] Can be any type.
+    # @return [Boolean]
+    #
+    # @note If performance is a concern, prefer to load Rails (or just `activesupport`) and use `present?` directly.
+    # @see https://api.rubyonrails.org/classes/Object.html#method-i-present-3F
+    #
+    def present?(object)
+      !blank?(object)
+    end
+
+    ##
+    # Converts `object` to boolean (or `nil`) using exactly the same logic as `ActiveModel::Type::Boolean.new.cast(object)` does.
+    #
+    # @param object [Object] Can be any type.
+    # @return [Boolean, nil]
+    #
+    # @note If performance is a concern, prefer to load Rails (or just `activemodel`) and use `ActiveModel::Type::Boolean.new.cast(object)` directly.
+    # @see https://api.rubyonrails.org/classes/ActiveModel/Type/Boolean.html
+    # @see https://github.com/rails/rails/blob/v8.0.2/activemodel/lib/active_model/type/boolean.rb#L39
+    #
+    def to_active_model_boolean_type(object)
+      (object == "") ? nil : !TO_ACTIVE_MODEL_BOOLEAN_TYPE_FALSE_VALUES.include?(object)
+    end
+
+    ##
+    # Converts `object` to `1` or `0`.
+    # Uses `to_ruby_bool` method under the hood.
+    # Accepts optional `:by` keyword to rely on a different method.
+    # Accepts optional `:unknown` keyword that specify what to return when `object` is `nil`.
+    #
+    # @param object [Object] Can be any type.
+    # @param by [Symbol, String].
+    # @param unknown [Object] Can be any type.
+    # @return [Integer]
+    #
+    # @example Call without the `:by` keyword.
+    #   SemanticBoolean.to_one_or_zero("")
+    #   # => 1
+    #
+    # @example Call with the `:by` keyword.
+    #   SemanticBoolean.to_one_or_zero("", by: :present?)
+    #   # => 0
+    #
+    # @example Call with the `:unknown` keyword.
+    #   SemanticBoolean.to_one_or_zero(nil, unknown: 127)
+    #   # => 127
+    #
+    def to_one_or_zero(object, by: :to_ruby_bool, unknown: false)
+      return unknown if object.nil?
+
+      public_send(by, object) ? 1 : 0
+    end
+
+    ##
+    # Converts `object` to `"y"` or `"n"`.
+    # Uses `to_ruby_bool` method under the hood.
+    # Accepts optional `:by` keyword to rely on a different method.
+    # Accepts optional `:unknown` keyword that specify what to return when `object` is `nil`.
+    #
+    # @param object [Object] Can be any type.
+    # @param by [Symbol, String].
+    # @param unknown [Object] Can be any type.
+    # @return [String]
+    #
+    # @example Call without the `:by` keyword.
+    #   SemanticBoolean.to_y_or_n("n")
+    #   # => "y"
+    #
+    # @example Call with the `:by` keyword.
+    #   SemanticBoolean.to_y_or_n("n", by: :to_env_bool)
+    #   # => "n"
+    #
+    # @example Call with the `:unknown` keyword.
+    #   SemanticBoolean.to_y_or_n(nil, unknown: "")
+    #   # => ""
+    #
+    def to_y_or_n(object, by: :to_ruby_bool, unknown: false)
+      return unknown if object.nil?
+
+      public_send(by, object) ? "y" : "n"
+    end
+
+    ##
+    # Converts `object` to `"yes"` or `"no"`.
+    # Uses `to_ruby_bool` method under the hood.
+    # Accepts optional `:by` keyword to rely on a different method.
+    # Accepts optional `:unknown` keyword that specify what to return when `object` is `nil`.
+    #
+    # @param object [Object] Can be any type.
+    # @param by [Symbol, String].
+    # @param unknown [Object] Can be any type.
+    # @return [String]
+    #
+    # @example Call without the `:by` keyword.
+    #   SemanticBoolean.to_yes_or_no([])
+    #   # => "yes"
+    #
+    # @example Call with the `:by` keyword.
+    #   SemanticBoolean.to_yes_or_no([], by: :present?)
+    #   # => "no"
+    #
+    # @example Call with the `:unknown` keyword.
+    #   SemanticBoolean.to_yes_or_no(nil, unknown: "unknown")
+    #   # => "unknown"
+    #
+    def to_yes_or_no(object, by: :to_ruby_bool, unknown: false)
+      return unknown if object.nil?
+
+      public_send(by, object) ? "yes" : "no"
+    end
+
+    ##
+    # Converts `object` to `"on"` or `"off"`.
+    # Uses `to_ruby_bool` method under the hood.
+    # Accepts optional `:by` keyword to rely on a different method.
+    # Accepts optional `:unknown` keyword that specify what to return when `object` is `nil`.
+    #
+    # @param object [Object] Can be any type.
+    # @param by [Symbol, String].
+    # @param unknown [Object] Can be any type.
+    # @return [String]
+    #
+    # @example Call without the `:by` keyword.
+    #   SemanticBoolean.to_on_or_off(false)
+    #   # => "off"
+    #
+    # @example Call with the `:by` keyword.
+    #   SemanticBoolean.to_yes_or_no(false, by: :blank?)
+    #   # => "on"
+    #
+    # @example Call with the `:unknown` keyword.
+    #   SemanticBoolean.to_on_or_off(nil, unknown: "unavailable")
+    #   # => "unavailable"
+    #
+    def to_on_or_off(object, by: :to_ruby_bool, unknown: false)
+      return unknown if object.nil?
+
+      public_send(by, object) ? "on" : "off"
+    end
+
+    ##
+    # Converts `object` to `true` or `false`.
+    # Uses `to_ruby_bool` method under the hood.
+    # Accepts optional `:by` keyword to rely on a different method.
+    # Accepts optional `:unknown` keyword that specify what to return when `object` is `nil`.
+    #
+    # @param object [Object] Can be any type.
+    # @param by [Symbol, String].
+    # @param unknown [Object] Can be any type.
+    # @return [String]
+    #
+    # @example Call without the `:by` keyword.
+    #   SemanticBoolean.to_on_or_off(false)
+    #   # => "off"
+    #
+    # @example Call with the `:by` keyword.
+    #   SemanticBoolean.to_yes_or_no(false, by: :blank?)
+    #   # => "on"
+    #
+    # @example Call with the `:unknown` keyword.
+    #   SemanticBoolean.to_on_or_off(nil, unknown: "unavailable")
+    #   # => "unavailable"
+    #
+    def to_true_or_false(object, by: :to_ruby_bool, unknown: false)
+      return unknown if object.nil?
+
+      public_send(by, object) ? true : false
+    end
+  end
+end
+# rubocop:enable Lint/BooleanSymbol

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: semantic_boolean
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Marian Kostyk
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: set
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Multiple ways to convert Ruby objects into booleans bundled in a single
+  gem.
+email:
+- mariankostyk13895@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/semantic_boolean.rb
+- lib/semantic_boolean/version.rb
+homepage: https://github.com/marian13/semantic_boolean
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/marian13/semantic_boolean
+  source_code_uri: https://github.com/marian13/semantic_boolean
+  changelog_uri: https://github.com/marian13/semantic_boolean/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Multiple ways to convert Ruby objects into booleans bundled in a single gem.
+test_files: []