abachrome 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88fab17313d84aca8190acb8c108af84d1129ce9e240353e2afec2225fc5aa37
-  data.tar.gz: f98569f28bf4a1fa967f43bc8538de967e7dfa34f40f22749099b51b8b7512ac
+  metadata.gz: a33e1980f4b275bc95646259d6c71b01715d2a77f019828b2c05ea98b24826d8
+  data.tar.gz: 896c1479708b87a3862bc28bdbb1959aefc0bcb3619604980096f34ed7dd07e9
 SHA512:
-  metadata.gz: 1df4f29f6700b0488656b3a7c7dc22a1aa72cfab8d6a11cfc89363acd57488a39e9ded2d79f397c2727e7cbb5a2b203f41975cdbc891de3028435b3d40be1915
-  data.tar.gz: d31cb69b1412ab7e5c06349ce2e44b9b1ecf1324d2b862d26e19adbf496bfeeec0c1195382bf5f4092d0fe12407e4d9d9024c7fe1065e52b3b353f94e55a79a4
+  metadata.gz: e6923ce91856cf5261cc52613c1e6eacd70e0fb9c3f7a1a2fe4f248b04ea326530ca8e6b56e84f07d4cc7f663ed61fb469c35ab1247ca40f6efeeb22b28952c3
+  data.tar.gz: db5e02222ce2f664086a1deb5b2a4cf878c3e285c9053b652935b45688cac1d64286987b5bca0a02a0a8a884110996a2f071d283ac5df3b94f8d8722a620aef7

data/.envrc

@@ -0,0 +1,3 @@
+source_url "https://raw.githubusercontent.com/cachix/devenv/95f329d49a8a5289d31e0982652f7058a189bfca/direnvrc" "sha256-d+8cBpDfDBj41inrADaJt+bDWhOktwslgoP5YiGJ1v0="
+
+use devenv

data/README.md

@@ -2,6 +2,8 @@
 
 Abachrome is a Ruby gem for parsing, manipulating, and managing colors. It provides a robust set of tools for working with various color formats including hex, RGB, HSL, and named colors.
 
+![Abachrome Logo](logo.png)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -97,3 +99,11 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/durabl
 
 We'd like to thank the excellent Color.js and culori color libraries, which helped inspire this project and
 inform its design.
+
+# Commercial Support
+
+Commercial support for this tool is available from Durable Programming, LLC. You can find out more at [durableprogramming.com](https://durableprogramming.com/) or via email at [commercial@durableprogramming.com](mailto:commercial@durableprogramming.com).
+
+# Copyright
+
+Copyright 2025, Durable Programming LLC. All rights reserved.

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create do |t|
+
+  t.test_prelude = %(require "simplecov"; SimpleCov.start { add_filter %p }) % ['/test/']
+  t.test_globs = FileList["test/**/*_test.rb", 'test/**/test_*.rb']
+  t.framework = %(require "test/test_helper.rb")
+end
+
+
+task default: :test
+

data/devenv.lock

@@ -3,10 +3,10 @@
     "devenv": {
       "locked": {
         "dir": "src/modules",
-        "lastModified": 1739172804,
+        "lastModified": 1749202057,
         "owner": "cachix",
         "repo": "devenv",
-        "rev": "f8be0ed0141abab89cefb20d3d375740671fbee1",
+        "rev": "1c28c31f09f8a5ab134e1943b29b9d2f302cfbcd",
         "type": "github"
       },
       "original": {
@@ -19,10 +19,10 @@
     "flake-compat": {
       "flake": false,
       "locked": {
-        "lastModified": 1733328505,
+        "lastModified": 1747046372,
         "owner": "edolstra",
         "repo": "flake-compat",
-        "rev": "ff81ac966bb2cae68946d5ed5fc4994f96d0ffec",
+        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
         "type": "github"
       },
       "original": {
@@ -31,10 +31,63 @@
         "type": "github"
       }
     },
+    "flake-compat_2": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1747046372,
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "git-hooks": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "gitignore": "gitignore",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1747372754,
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "rev": "80479b6ec16fefd9c1db3ea13aeb038c60530f46",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "type": "github"
+      }
+    },
     "gitignore": {
       "inputs": {
         "nixpkgs": [
-          "pre-commit-hooks",
+          "git-hooks",
           "nixpkgs"
         ]
       },
@@ -53,10 +106,10 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1733477122,
+        "lastModified": 1746807397,
         "owner": "cachix",
         "repo": "devenv-nixpkgs",
-        "rev": "7bd9e84d0452f6d2e63b6e6da29fe73fac951857",
+        "rev": "c5208b594838ea8e6cca5997fbf784b7cca1ca90",
         "type": "github"
       },
       "original": {
@@ -66,32 +119,50 @@
         "type": "github"
       }
     },
-    "pre-commit-hooks": {
+    "nixpkgs-ruby": {
       "inputs": {
-        "flake-compat": "flake-compat",
-        "gitignore": "gitignore",
+        "flake-compat": "flake-compat_2",
+        "flake-utils": "flake-utils",
         "nixpkgs": [
           "nixpkgs"
         ]
       },
       "locked": {
-        "lastModified": 1737465171,
-        "owner": "cachix",
-        "repo": "pre-commit-hooks.nix",
-        "rev": "9364dc02281ce2d37a1f55b6e51f7c0f65a75f17",
+        "lastModified": 1747288354,
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "rev": "5d7598f3059fff0cbd0dc4756f9d87f8cb7f3f7c",
         "type": "github"
       },
       "original": {
-        "owner": "cachix",
-        "repo": "pre-commit-hooks.nix",
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
         "type": "github"
       }
     },
     "root": {
       "inputs": {
         "devenv": "devenv",
+        "git-hooks": "git-hooks",
         "nixpkgs": "nixpkgs",
-        "pre-commit-hooks": "pre-commit-hooks"
+        "nixpkgs-ruby": "nixpkgs-ruby",
+        "pre-commit-hooks": [
+          "git-hooks"
+        ]
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
       }
     }
   },

data/devenv.nix

@@ -5,9 +5,10 @@
   env.GREET = "devenv";
 
   # https://devenv.sh/packages/
-  packages = [ pkgs.git pkgs.ncurses pkgs.asciinema pkgs.asciinema-agg];
+  packages = [ pkgs.git];
 
 	languages.ruby.enable = true;
+	languages.ruby.version = "3.3.2";
 
   languages.javascript.enable = true;
   languages.javascript.npm.enable = true;

data/devenv.yaml

@@ -1,15 +1,8 @@
-# yaml-language-server: $schema=https://devenv.sh/devenv.schema.json
 inputs:
   nixpkgs:
     url: github:cachix/devenv-nixpkgs/rolling
-
-# If you're using non-OSS software, you can set allowUnfree to true.
-# allowUnfree: true
-
-# If you're willing to use a package that's vulnerable
-# permittedInsecurePackages:
-#  - "openssl-1.1.1w"
-
-# If you have more than one devenv you can merge them
-#imports:
-# - ./backend
+  nixpkgs-ruby:
+    url: github:bobvanderlinden/nixpkgs-ruby
+    inputs:
+      nixpkgs:
+        follows: nixpkgs

data/lib/abachrome/abc_decimal.rb

@@ -1,4 +1,17 @@
-# frozen_string_literal: true
+# Abachrome::AbcDecimal - High-precision decimal arithmetic for color calculations
+#
+# This class provides a wrapper around Ruby's BigDecimal to ensure consistent precision
+# across color space conversions and calculations. It handles the precision requirements
+# needed for accurate color manipulation while providing a convenient interface that
+# supports standard arithmetic operations and type coercion.
+#
+# The class is designed to work seamlessly with Ruby's numeric types while maintaining
+# the high precision necessary for color science calculations. It includes methods for
+# conversion between different numeric representations and implements the full set of
+# comparison and arithmetic operators.
+#
+# Default precision can be configured via the ABC_DECIMAL_PRECISION environment variable,
+# falling back to 24 significant digits if not specified.
 
 require "bigdecimal"
 require "forwardable"
@@ -10,8 +23,17 @@ module Abachrome
 
     attr_accessor :value, :precision
 
-    def_delegators :@value, :to_i, :to_f, :zero?, :nonzero?
-
+    def_delegators :@value, :to_i, :zero?, :nonzero?, :finite?
+
+    # Initializes a new AbcDecimal object with the specified value and precision.
+    # 
+    # @param value [AbcDecimal, BigDecimal, Rational, #to_s] The numeric value to represent.
+    # If an AbcDecimal is provided, its internal value is used.
+    # If a BigDecimal or Rational is provided, it's used directly.
+    # Otherwise, the value is converted to a string and parsed as a BigDecimal.
+    # @param precision [Integer] The decimal precision to use (number of significant digits).
+    # Defaults to DEFAULT_PRECISION.
+    # @return [AbcDecimal] A new AbcDecimal instance.
     def initialize(value, precision = DEFAULT_PRECISION)
       @precision = precision
       @value = case value
@@ -26,6 +48,13 @@ module Abachrome
                end
     end
 
+    # Returns a string representation of the decimal value.
+    # 
+    # This method converts the internal value to a String, using a fixed-point
+    # notation format. If the internal value is a Rational, it's first converted
+    # to a BigDecimal with the configured precision before string conversion.
+    # 
+    # @return [String] The decimal value as a string in fixed-point notation
     def to_s
       if @value.is_a?(Rational)
         BigDecimal(@value, precision).to_s("F")
@@ -34,55 +63,127 @@ module Abachrome
       end
     end
 
+    # Converts the decimal value to a floating-point number.
+    # 
+    # @return [Float] the floating-point representation of the AbcDecimal value
     def to_f
       @value.to_f
     end
 
+    # Creates a new AbcDecimal from a string representation of a number.
+    # 
+    # @param str [String] The string representation of a number to convert to an AbcDecimal
+    # @param precision [Integer] The precision to use for the decimal value (number of significant digits after the decimal point). Defaults to DEFAULT_PRECISION
+    # @return [AbcDecimal] A new AbcDecimal instance initialized with the given string value and precision
     def self.from_string(str, precision = DEFAULT_PRECISION)
       new(str, precision)
     end
 
+    # Creates a new AbcDecimal from a Rational number.
+    # 
+    # @param rational [Rational] The rational number to convert to an AbcDecimal
+    # @param precision [Integer] The precision to use for the decimal representation, defaults to DEFAULT_PRECISION
+    # @return [AbcDecimal] A new AbcDecimal instance with the value of the given rational number
     def self.from_rational(rational, precision = DEFAULT_PRECISION)
       new(rational, precision)
     end
 
+    # Creates a new AbcDecimal instance from a float value.
+    # 
+    # @param float [Float] The floating point number to convert to an AbcDecimal
+    # @param precision [Integer] The precision to use for the decimal representation (default: DEFAULT_PRECISION)
+    # @return [AbcDecimal] A new AbcDecimal instance representing the given float value
     def self.from_float(float, precision = DEFAULT_PRECISION)
       new(float, precision)
     end
 
+    # Creates a new AbcDecimal from an integer value.
+    # 
+    # @param integer [Integer] The integer value to convert to an AbcDecimal
+    # @param precision [Integer] The precision to use for the decimal, defaults to DEFAULT_PRECISION
+    # @return [AbcDecimal] A new AbcDecimal instance with the specified integer value and precision
     def self.from_integer(integer, precision = DEFAULT_PRECISION)
       new(integer, precision)
     end
 
+    # # Addition operation
+    # #
+    # # Adds another value to this decimal.
+    # #
+    # # @param other [AbcDecimal, Numeric] The value to add. If not an AbcDecimal,
+    # #   it will be converted to one.
+    # # @return [AbcDecimal] A new AbcDecimal instance with the sum of the two values
     def +(other)
       other_value = other.is_a?(AbcDecimal) ? other.value : AbcDecimal(other).value
       self.class.new(@value + other_value)
     end
 
+    # Subtracts another numeric value from this AbcDecimal.
+    # 
+    # @param other [AbcDecimal, Numeric] The value to subtract from this AbcDecimal.
+    # @return [AbcDecimal] A new AbcDecimal representing the result of the subtraction.
     def -(other)
       other_value = other.is_a?(AbcDecimal) ? other.value : AbcDecimal(other).value
       self.class.new(@value - other_value)
     end
 
+    # Multiplies this AbcDecimal by another value.
+    # 
+    # @param other [Object] The value to multiply by. If not an AbcDecimal, it will be converted to one.
+    # @return [AbcDecimal] A new AbcDecimal instance representing the product of this decimal and the other value.
+    # @example
+    # dec1 = AbcDecimal.new(5)
+    # dec2 = AbcDecimal.new(2)
+    # result = dec1 * dec2 # => AbcDecimal representing 10
+    # 
+    # # With a non-AbcDecimal value
+    # result = dec1 * 3 # => AbcDecimal representing 15
     def *(other)
       other_value = other.is_a?(AbcDecimal) ? other.value : AbcDecimal(other).value
       self.class.new(@value * other_value)
     end
 
+    # Divides this decimal by another value.
+    # 
+    # @param other [Numeric, AbcDecimal] The divisor, which can be an AbcDecimal instance or any numeric value
+    # @return [AbcDecimal] A new AbcDecimal representing the result of the division
+    # @example
+    # decimal = AbcDecimal.new(10)
+    # result = decimal / 2
+    # # => AbcDecimal.new(5)
     def /(other)
       other_value = other.is_a?(AbcDecimal) ? other.value : AbcDecimal(other).value
       self.class.new(@value / other_value)
     end
 
+    # Performs modulo operation with another value.
+    # 
+    # @param other [Numeric, AbcDecimal] The divisor for the modulo operation
+    # @return [AbcDecimal] A new AbcDecimal containing the remainder after division
     def %(other)
       other_value = other.is_a?(AbcDecimal) ? other.value : AbcDecimal(other).value
       self.class.new(@value % other_value)
     end
 
+    # Constrains the value to be between the specified minimum and maximum values.
+    # 
+    # @param min [Numeric, AbcDecimal] The minimum value to clamp to
+    # @param max [Numeric, AbcDecimal] The maximum value to clamp to
+    # @return [AbcDecimal] A new AbcDecimal within the specified range
+    # @example
+    # AbcDecimal(5).clamp(0, 10)   # => 5
+    # AbcDecimal(15).clamp(0, 10)  # => 10
+    # AbcDecimal(-5).clamp(0, 10)  # => 0
     def clamp(min,max)
       @value.clamp(AbcDecimal(min),AbcDecimal(max))
     end
 
+    # Raises self to the power of another value.
+    # This method handles different input types, including Rational values and
+    # other AbcDecimal instances.
+    # 
+    # @param other [Numeric, Rational, AbcDecimal] The exponent to raise this value to
+    # @return [AbcDecimal] A new AbcDecimal representing self raised to the power of other
     def **(other)
       if other.is_a?(Rational)
         self.class.new(@value**other)
@@ -92,58 +193,137 @@ module Abachrome
       end
     end
 
+    # Allows for mixed arithmetic operations between AbcDecimal and other numeric types.
+    # 
+    # @param other [Numeric] The other number to be coerced into an AbcDecimal object
+    # @return [Array<AbcDecimal>] A two-element array containing the coerced value and self,
+    # allowing Ruby to perform arithmetic operations with mixed types
     def coerce(other)
       [self.class.new(other), self]
     end
 
+    # Returns a string representation of the decimal value for inspection purposes.
+    # This method returns a formatted string that includes the class name and
+    # the string representation of the decimal value itself.
+    # 
+    # @return [String] A string in the format "ClassName('value')"
     def inspect
       "#{self.class}('#{self}')"
     end
 
+    # Compares this decimal value with another value for equality.
+    # Attempts to convert the other value to an AbcDecimal if it isn't one already.
+    # 
+    # @param other [Object] The value to compare against this AbcDecimal
+    # @return [Boolean] True if the values are equal, false otherwise
     def ==(other)
       @value == (other.is_a?(AbcDecimal) ? other.value : AbcDecimal(other).value)
     end
 
+    # Compares this AbcDecimal instance with another AbcDecimal or a value that can be
+    # converted to an AbcDecimal.
+    # 
+    # @param other [Object] The value to compare with this AbcDecimal.
+    # If not an AbcDecimal, it will be converted using AbcDecimal().
+    # @return [Integer, nil] Returns -1 if self is less than other,
+    # 0 if they are equal,
+    # 1 if self is greater than other,
+    # or nil if the comparison is not possible.
     def <=>(other)
       @value <=> (other.is_a?(AbcDecimal) ? other.value : AbcDecimal(other).value)
     end
 
+    # Compares this decimal with another value.
+    # 
+    # @param other [Object] The value to compare with. Can be an AbcDecimal or any value
+    # convertible to AbcDecimal
+    # @return [Boolean] true if this decimal is greater than the other value, false otherwise
     def >(other)
       @value > (other.is_a?(AbcDecimal) ? other.value : AbcDecimal(other).value)
     end
 
+    # Compares this decimal value with another value.
+    # 
+    # @param other [Object] The value to compare against. If not an AbcDecimal,
+    # it will be converted to one.
+    # @return [Boolean] true if this decimal is greater than or equal to the other value,
+    # false otherwise.
     def >=(other)
       @value >= (other.is_a?(AbcDecimal) ? other.value : AbcDecimal(other).value)
     end
 
+    # Compares this decimal with another value.
+    # 
+    # @param other [Object] The value to compare with. Will be coerced to AbcDecimal if not already an instance.
+    # @return [Boolean] true if this decimal is less than the other value, false otherwise.
+    # @example
+    # dec1 = AbcDecimal.new(1.5)
+    # dec2 = AbcDecimal.new(2.0)
+    # dec1 < dec2 #=> true
+    # dec1 < 2.0  #=> true
     def <(other)
       @value < (other.is_a?(AbcDecimal) ? other.value : AbcDecimal(other).value)
     end
 
+    # Compares this AbcDecimal with another value.
+    # 
+    # @param other [AbcDecimal, Numeric] The value to compare with. If not an AbcDecimal,
+    # it will be converted to one.
+    # @return [Boolean] true if this AbcDecimal is less than or equal to the other value,
+    # false otherwise.
     def <=(other)
       @value <= (other.is_a?(AbcDecimal) ? other.value : AbcDecimal(other).value)
     end
 
-    def clamp(*args)
-      AbcDecimal(@value.clamp(*args))
-    end
-
+    # @overload round(*args)
+    # Rounds this decimal to a specified precision.
+    # 
+    # @param args [Array] Arguments to be passed to BigDecimal#round. Can include
+    # the number of decimal places to round to and the rounding mode.
+    # @return [AbcDecimal] A new AbcDecimal instance with the rounded value
+    # @example Round to 2 decimal places
+    # decimal = AbcDecimal(3.14159)
+    # decimal.round(2) #=> 3.14
+    # @example Round with specific rounding mode
+    # decimal = AbcDecimal(3.5)
+    # decimal.round(0, half: :up) #=> 4
     def round(*args)
       AbcDecimal(@value.round(*args))
     end
 
+    # Returns the absolute value (magnitude) of the decimal number.
+    # 
+    # Wraps BigDecimal#abs to ensure return values are properly converted to AbcDecimal.
+    # 
+    # @param args [Array] Optional arguments to pass to BigDecimal#abs
+    # @return [AbcDecimal] The absolute value of the decimal number
     def abs(*args)
       AbcDecimal(@value.abs(*args))
     end
 
+    # Returns the square root of the AbcDecimal value.
+    # Calculates the square root by using Ruby's built-in Math.sqrt function
+    # and converting the result back to an AbcDecimal.
+    # 
+    # @return [AbcDecimal] A new AbcDecimal representing the square root of the value
     def sqrt
       AbcDecimal(Math.sqrt(@value))
     end
 
+    # Returns true if the internal value is negative, false otherwise.
+    # 
+    # @return [Boolean] true if the value is negative, false otherwise
     def negative?
       @value.negative?
     end
 
+    # Calculates the arctangent of y/x using the signs of the arguments to determine the quadrant.
+    # Unlike the standard Math.atan2, this method accepts AbcDecimal objects or any values
+    # that can be converted to AbcDecimal.
+    # 
+    # @param y [AbcDecimal, Numeric] The y coordinate
+    # @param x [AbcDecimal, Numeric] The x coordinate
+    # @return [AbcDecimal] The angle in radians between the positive x-axis and the ray to the point (x,y)
     def self.atan2(y, x)
       y_value = y.is_a?(AbcDecimal) ? y.value : AbcDecimal(y).value
       x_value = x.is_a?(AbcDecimal) ? x.value : AbcDecimal(x).value
@@ -152,10 +332,24 @@ module Abachrome
   end
 end
 
+# Creates a new AbcDecimal instance.
+# 
+# This is a convenience method that allows creating AbcDecimal objects
+# without explicitly referencing the Abachrome namespace.
+# 
+# @param args [Array] Arguments to pass to the AbcDecimal constructor
+# @return [Abachrome::AbcDecimal] A new AbcDecimal instance
 def AbcDecimal(*args)
   Abachrome::AbcDecimal.new(*args)
 end
 
+# Creates a new AbcDecimal instance.
+# 
+# @param args [Array] Arguments to pass to AbcDecimal.new
+# @return [Abachrome::AbcDecimal] A new AbcDecimal instance
+# @example
+# AD(3.14) # => #<Abachrome::AbcDecimal:0x... @value=3.14>
+# AD("2.718") # => #<Abachrome::AbcDecimal:0x... @value=2.718>
 def AD(*args)
   Abachrome::AbcDecimal.new(*args)
 end