json_logic_humanizable 0.0.1.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b3d6d686007b6c7b9677f087f792802a19756964a3b2b234da07765d3c2623f
+  data.tar.gz: 449bddb8f9471d7f8090f9c0be0a8331ee224de27b927b039224c060d5d0b60a
+SHA512:
+  metadata.gz: 5050c96999ce0016559b7a73f9b34ffef9b4bd2af8414b7145158c65536664c1a9c82d43439a1744167b41869c33cd150ece438abe654df6e70af75f5277ef66
+  data.tar.gz: 8b006202a2b17a4b48cbb08612a31b98d2e59c7adcfe9491c1ec6dd8f0e20f3a961e5804fb2ee0fe5cf6f1ab41f52f2d16841635600e789b6b39f661c21a6369

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.2.1 (2025-10-04)
+- Rename gem to `json_logic_humanizable`
+- Keep only Humanizable mixin and Expression class
+- Improve docs with payments example and configuration details

data/CONTRIBUTION.md

@@ -0,0 +1,28 @@
+# Contribution Guide
+
+**Contributions are very welcome!** Whether it's a small typo fix, a new operator label, a better example, or a larger refactor — your help makes this gem better. If you're unsure where to start, open an issue and we can figure it out together.
+
+## Setup
+- Ruby 2.7+
+- No runtime dependencies
+
+## How to contribute
+1. Fork the repo and create a branch from `main`
+2. Make your change (code, docs, or tests)
+3. Include examples for any new operators or pretty mappings
+4. Update `README.md` if public behavior changes
+5. Run your tests
+6. Open a Pull Request and describe:
+   - What changed and why
+   - Any breaking impacts
+   - Before/after output if applicable
+
+## Code style
+- Plain Ruby
+- Public API stays stable:
+  - `JsonLogic::Rule.new(logic).humanize`
+  - `JsonLogic::Humanizable` mixin + `humanize_json_logic`
+
+## Releases
+- Bump `lib/json_logic/version.rb` using SemVer
+- Update `CHANGELOG.md`

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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,139 @@
+
+
+# json_logic_humanizable
+
+**Translate JsonLogic rules into readable sentences**. Extension for [JsonLogic](https://jsonlogic.com/).
+
+
+## What
+
+This gem converts JsonLogic Rules into readable sentences. It is framework-agnostic.
+- A mixin for serializer/presenter classes.
+- A small wrapper for one-off translations.
+
+No dependencies. Works with a Ruby Hash or a Ruby Json string.
+
+## How
+
+Input: a JsonLogic rule (as a Hash or JSON string).
+Output: human-readable text that explains the JsonLogic Rule.
+
+Where this is useful:
+
+If you found this gem, you likely already know where to use it in your app — the abstract use case is simple: you want to read a rule as text (e.g., show it in the UI, preview it, or share it elsewhere).
+
+## Installation
+
+Add to your `Gemfile` if you need:
+
+```ruby
+gem "json_logic_humanizable"
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+## Examples
+
+
+### Easy – Quick Start
+```ruby
+logic = {
+  "and" => [
+    { ">=" => [ { "var" => "payment.amount" }, 50 ] },
+    { "in" => [ { "var" => "payment.currency" }, %w[EUR USD] ] }
+  ]
+}
+
+puts JsonLogic::Rule.new(logic).humanize
+```
+
+### Complex – With Config
+
+```ruby
+
+JsonLogic::Config.operators["in"] = "is one of"
+
+JsonLogic::Config.vars[/([^\.]+)$/] =  ->(m) { m[1].tr("_", " ").split.map(&:capitalize).join(" ") }
+
+logic = {
+  "and" => [
+    { ">=" => [ { "var" => "payment.amount" }, 50 ] },
+    { "fact" => "payment.currency", "operator" => "in", "value" => %w[EUR USD] },
+    {
+      "or" => [
+        { "in" => [ { "var" => "customer.country" }, %w[LT LV EE] ] },
+        { "==" => [ { "var" => "customer.vip" }, true ] }
+      ]
+    },
+    { "!" => { "==" => [ { "var" => "customer.blacklisted" }, true ] } },
+    { "<=" => [ { "var" => "risk.score" }, 300 ] },
+    { "fact" => "chargeback.history_count", "operator" => "<=", "value" => 1 }
+  ]
+}
+
+puts JsonLogic::Rule.new(logic).humanize
+```
+
+Example output:
+```
+Amount is greater than or equal to 50 AND Currency is one of ["EUR", "USD"] AND Country is one of LT, LV, EE OR Vip is equal to true AND NOT (Blacklisted is equal to true) AND Score is less than or equal to 300 AND History Count is less than or equal to 1
+```
+
+### Serializer example
+
+```ruby
+class RuleSerializer
+  include JsonLogic::Humanizable
+
+  attr_reader :condition
+  humanize_json_logic :condition
+
+  def initialize(condition)
+    @condition = condition
+  end
+end
+
+s = RuleSerializer.new({
+  "and" => [
+    { ">=" => [ { "var" => "payment.amount" }, 50 ] },
+    { "in" => [ { "var" => "payment.currency" }, %w[EUR USD] ] }
+  ]
+})
+
+# RuleSerializer includes methods:
+s.condition
+s.condition_human
+```
+
+## Configuration
+
+### Operators mapping
+
+Configure labels as you prefer:
+
+```ruby
+JsonLogic::Config.operators["in"]  = "is one of"
+JsonLogic::Config.operators["=="]  = "equals"
+JsonLogic::Config.operators[">="]  = "is at least"
+JsonLogic::Config.operators["!"]   = "NOT"
+JsonLogic::Config.operators["and"] = "AND"
+JsonLogic::Config.operators["or"]  = "OR"
+```
+
+### Variables mapping
+
+Each entry is `[pattern, replacement]` where `pattern` is a `Regexp` or exact `String`, and `replacement` is a `String` or `Proc`.
+
+```ruby
+JsonLogic::Config.vars[/([^\.]+)$/] =  ->(m) { m[1].tr("_", " ").split.map(&:capitalize).join(" ") }
+```
+
+This maps `payment.amount` → `Amount`, `customer.country` → `Country`, etc.
+
+## Links
+
+- JsonLogic site: https://jsonlogic.com/

data/lib/json_logic/config.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module JsonLogic
+  module Config
+    class << self
+      attr_accessor :vars, :operators
+    end
+  end
+
+  Config.vars = {}
+
+  Config.operators = {
+    "==" => "is equal to",
+    "!=" => "is not equal to",
+    ">"  => "is greater than",
+    "<"  => "is less than",
+    ">=" => "is greater than or equal to",
+    "<=" => "is less than or equal to",
+    "in" => "is in",
+    "!"  => "NOT",
+    "and"=> "AND",
+    "or" => "OR"
+  }
+end

data/lib/json_logic/humanizable.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module JsonLogic
+  module Humanizable
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def humanize_json_logic(*attrs, as: nil, suffix: "_human")
+        attrs.each do |attr|
+          method_name = (as || "#{attr}#{suffix}").to_sym
+          define_method(method_name) do
+            value = public_send(attr)
+            humanize_logic(value)
+          end
+        end
+      end
+    end
+
+    def humanize_logic(value)
+      return nil if value.nil?
+      obj = value.is_a?(String) ? parse_json(value) : value
+      explain(obj)
+    rescue JSON::ParserError
+      value
+    end
+
+    def humanize(value)
+      humanize_logic(value)
+    end
+
+    private
+
+    def parse_json(str)
+      require "json"
+      JSON.parse(str)
+    end
+
+    AND_OPERATORS   = %w[and all].freeze
+    OR_OPERATORS    = %w[or any].freeze
+    LOGIC_OPERATORS = (AND_OPERATORS + OR_OPERATORS).freeze
+    NOT_OPERATOR      = "!"
+    IN_OPERATOR       = "in"
+    VARIABLE_OPERATOR = "var"
+    FACT_OPERATOR     = "fact"
+
+    def explain(logic)
+      return logic.to_s unless logic.is_a?(Hash)
+      operator, operands = logic.first
+      operands ||= []
+      case operator
+      when *LOGIC_OPERATORS
+        joiner = label(normalize(operator))
+        operands.map { |operand| explain(operand) rescue operand.inspect }.join(" #{joiner} ")
+      when NOT_OPERATOR
+        "#{label(NOT_OPERATOR)} (#{explain(operands)})"
+      when IN_OPERATOR
+        variable, list = operands
+        "#{pretty(variable)} #{label(IN_OPERATOR)} #{Array(list).join(', ')}"
+      when VARIABLE_OPERATOR
+        pretty(operands)
+      when FACT_OPERATOR
+        "#{pretty(operands)} #{label(logic['operator'])} #{logic['value']}"
+      else
+        binary(operator, operands) || logic.inspect
+      end
+    end
+
+    def binary(operator, operands)
+      return unless valid_operands?(operands)
+      "#{pretty(operands.first)} #{label(operator)} #{operands[1]}"
+    end
+
+    def valid_operands?(operands)
+      operands.is_a?(Array) && operands.size == 2 && operands.first.is_a?(Hash) && operands.first[VARIABLE_OPERATOR]
+    end
+
+    def normalize(operator)
+      return "and" if AND_OPERATORS.include?(operator)
+      return "or"  if OR_OPERATORS.include?(operator)
+      operator
+    end
+
+    def pretty(expression)
+      extract_variable_name(expression).tap do |base|
+        Array(Config.vars).each do |pattern, replacement|
+          if pattern.is_a?(Regexp) ? (match = pattern.match(base)) : base == pattern.to_s
+            return replacement.is_a?(Proc) ? replacement.call(match || base) : replacement
+          end
+        end
+      end
+    end
+
+    def extract_variable_name(expression)
+      expression.is_a?(Hash) && expression[VARIABLE_OPERATOR] ? expression[VARIABLE_OPERATOR].to_s : expression.to_s
+    end
+
+    def label(operator)
+      Config.operators&.[](operator) || operator
+    end
+  end
+end

data/lib/json_logic/rule.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "humanizable"
+
+module JsonLogic
+  class Rule
+    include Humanizable
+
+    attr_reader :logic
+
+    def initialize(value)
+      @logic = value
+    end
+
+    humanize_json_logic :logic
+
+    def to_s
+      humanize_logic(@logic).to_s
+    end
+
+    def humanize
+      to_s
+    end
+
+    class << self
+      def call(value)
+        new(value).humanize
+      end
+      alias [] call
+      alias text call
+    end
+  end
+end

data/lib/json_logic/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JsonLogic
+  VERSION = "0.0.1.beta1"
+end

data/lib/json_logic.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "json_logic/version"
+require_relative "json_logic/config"
+require_relative "json_logic/humanizable"
+require_relative "json_logic/rule"

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: json_logic_humanizable
+version: !ruby/object:Gem::Version
+  version: 0.0.1.beta1
+platform: ruby
+authors:
+- Tavrel Kate
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-04 00:00:00.000000000 Z
+dependencies: []
+description: An extension over JsonLogic that translates Rules to human text via a
+  mixin and a small Rule wrapper.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTION.md
+- LICENSE
+- README.md
+- lib/json_logic.rb
+- lib/json_logic/config.rb
+- lib/json_logic/humanizable.rb
+- lib/json_logic/rule.rb
+- lib/json_logic/version.rb
+homepage:
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Translate JsonLogic rules into readable sentences.
+test_files: []