json-logic-rb-humanizable 0.0.1.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4585919e62954c6b514f1e0fc49d5791f67c862371ff6af1a39c3c42b6f11360
+  data.tar.gz: ad6b47848ed5f066b84158563ba1cb24dab8276557f918b0db42634775aa10ea
+SHA512:
+  metadata.gz: 20713639565afa699738180627be24bc56d123401235acaf1d45864944652514f6190d74ecc6e0cc08941069837d6d8a66f88f2c36107392a725189d10014be7
+  data.tar.gz: 99e961177dafc594b9ce1a1eff29f65e1448af5b7434bda7c7a307a78104d12045c7cd766e376c1458df8ae92c734215286586f37bbb5e1892bd2e520f7e4f95

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## 0.0.1 (2025-10-05)
+- First stable release

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,162 @@
+
+# json-logic-rb-humanizable
+
+Translate [JsonLogic](https://jsonlogic.com/) rules into readable sentences. Extension for [JsonLogic](https://jsonlogic.com/).
+
+⚙️ Zero deps · 🛠️ Configurable · 🧩 Mixin + Wrapper
+
+[![Gem Version](https://img.shields.io/gem/v/json_logic_humanizable.svg)](https://rubygems.org/gems/json_logic_humanizable) [![Docs](https://img.shields.io/badge/docs-rubydoc.info-blue)](https://www.rubydoc.info/gems/json_logic_humanizable) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+
+
+## What
+
+This gem converts JsonLogic Rules into readable sentences.
+- A mixin for serializer/presenter classes.
+- A small wrapper for one-off translations.
+
+No dependencies. Works with a Ruby Hash.
+
+## How
+
+Config => operators map + variables map
+Input  => JsonLogic Rule (Hash)
+Output => human-readable sentence
+
+
+
+## Where
+
+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
+
+### Plain Ruby
+```bash
+gem install json_logic_humanizable
+```
+
+### Rails (Bundler)
+Add to your `Gemfile` if you need:
+
+```ruby
+gem "json_logic_humanizable"
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+Configuration (if needed)
+```ruby
+# config/initializers/json_logic.rb
+
+require "json_logic"
+
+# Configuration
+```
+
+## Examples
+
+
+### Easy – Quick Start
+```ruby
+logic = {
+  "and" => [
+    { ">=" => [ { "var" => "payment.amount" }, 50 ] },
+    { "in" => [ { "var" => "payment.currency" }, %w[EUR USD] ] }
+  ]
+}
+
+puts JsonLogic::Rule.new(logic).humanize
+```
+
+Example output:
+```
+payment.amount is greater than or equal to 50 AND payment.currency is in EUR, USD
+```
+
+### 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] }
+  ]
+}
+
+puts JsonLogic::Rule.new(logic).humanize
+```
+
+Example output:
+```
+Amount is greater than or equal to 50 AND Currency is one of ["EUR", "USD"]
+```
+
+### Mixin – Humanizable in serializers
+
+```ruby
+class RuleSerializer
+  include JsonLogic::Humanizable
+
+  attr_reader :json_logic
+
+  def initialize(json_logic)
+    @json_logic = json_logic
+  end
+
+   def condition
+      humanize_logic(json_logic)
+   end
+end
+
+s = RuleSerializer.new({
+  "and" => [
+    { ">=" => [ { "var" => "payment.amount" }, 50 ] },
+    { "in" => [ { "var" => "payment.currency" }, %w[EUR USD] ] }
+  ]
+})
+
+puts s.condition
+```
+Example output:
+```
+payment.amount is greater than or equal to 50 AND payment.currency is in EUR, USD
+```
+
+## 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 key  – **pattern**,  value – **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)
+    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,56 @@
+--- !ruby/object:Gem::Specification
+name: json-logic-rb-humanizable
+version: !ruby/object:Gem::Version
+  version: 0.0.1.beta1
+platform: ruby
+authors:
+- Tavrel Kate
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-06 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
+- 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: https://github.com/tavrelkate/json_logic_humanizable
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://www.rubydoc.info/gems/json_logic_humanizable
+  homepage_uri: https://github.com/tavrelkate/json_logic_humanizable
+  source_code_uri: https://github.com/tavrelkate/json_logic_humanizable
+  changelog_uri: https://github.com/tavrelkate/json_logic_humanizable/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/tavrelkate/json_logic_humanizable/issues
+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: []