rayzer 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d2d485235aff6865bd30482c32ffb45f1d4fb51ca8ecc49f4514edd774453aa
+  data.tar.gz: 6d01f1423c71f9ebe81e259fefc8db44bbc1795cd139abc2729992d52cf22c14
+SHA512:
+  metadata.gz: 37213df3a9af6cdc3e3c75850644a89abba0991f1bcf95ab3c899193811137162d2f240de63723b70ec9aeb3dd50ed0062728cbea1385de7545c60d1b01da6af
+  data.tar.gz: cc974c31a04788be0206123bddeacfef55e11d92836264609e564ce430d2832383787b1ca47ced170cfa4faf8457f1e8f1a22c261b8fe9501387c6176c7be5ad

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.0.1] - 2025-11-17
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 NullFluxKevin
+
+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,35 @@
+# Rayzer
+
+A razor sharp layout engine for rectangular areas.
+
+Use constraints such as fixed length, minimum length, percentage, ratio, and maximum length to divide a rectangular area into a tree of nested rows and columns.
+
+
+## Usage
+
+See `usage_example.rb`.
+
+For full specs, read the tests.
+
+TODO: more on usage
+
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/rayzer/constraint.rb

@@ -0,0 +1,111 @@
+module Rayzer
+  class Constraint
+    # zero or one <=, >=, %, or :
+    # (?<=) is a look ahead assertion, if matches < or >, then check for =
+    # followed by digits
+    # then optionally followed by a decimal point "." and digits
+    @parse_arg_format_regex = /^([<>]?(?<=[<>])=|[%:])?\d+(.\d+)?$/
+    
+    FIXED = :fixed
+    MINIMUM = :minimum
+    MAXIMUM = :maximum
+    PERCENTAGE = :percentage
+    RATIO = :ratio
+
+    # define factory class methods such as Constraint.fixed(value)
+    constants.each do |constraint_type|
+      define_singleton_method(constraint_type.downcase) do |value|
+        new(const_get(constraint_type), value)
+      end
+    end
+
+
+    attr_reader :type, :value
+
+
+    def initialize(type, value)
+      raise ArgumentError, "Negative constraint value: #{value}" if value.negative?
+      @type = type
+      @value = value
+    end
+
+
+    # This intends to provide a concise api for things that accepts constraints
+    # 
+    # Usage:
+    #  To get a fixed constraint, pass:        30, "30", or :"30"
+    #  To get a minimum constraint, pass:      ">=30", or :">=30"
+    #  To get a percentage constraint, pass:   "30%", :"30%", "%30", :"%30" 
+    #  To get a ratio constraint, pass:        ":30", or :":30"
+    #  To get a maximum constraint, pass:      "<=30", or :"<=30"
+    # 
+    # 
+    # API Usage Example:
+    #   constraints = %i[ 3 20% <=10 >=5 :3 ] # or use %w
+    #   constraints << Constraint.fixed(1)
+    # 
+    #   some_method(args)
+    #  
+    #   def some_method(args)
+    #     constraints = args.map { |arg| Constraint.parse arg )
+    #     ...
+    #   end
+    # 
+    def self.parse(arg)
+
+      is_of_valid_type = [Integer, Float, String, Symbol, self].any?{ |cls| arg.instance_of? cls }
+
+      unless is_of_valid_type
+        raise ArgumentError,
+          "Cannot parse: #{arg}. Constraint.parse only accepts: Constraint, Integer, Float, Symbol and String of valid format" 
+      end
+
+      return arg.dup if arg.instance_of? self
+      
+      if [Integer, Float].include? arg.class
+        return fixed arg
+      end
+
+      # I'm not making the regexp any more complex with look ahead assertion for checking % at the end only if the arg starts with a digit.
+      if arg[-1] == "%"
+        arg = "%" + arg[...-1]
+      end
+
+      raise ArgumentError, "Invalid argument format in: #{arg}" unless arg =~ @parse_arg_format_regex
+
+      if arg[0] =~ /\d/
+        value = parse_number arg
+        return fixed value
+      end
+
+      case arg[0]
+        when ">"
+          value = parse_number arg[2..] # 2 == '>='.size
+          minimum value
+        when "%"
+          value = parse_number arg[1..]
+          percentage value
+        when "<"
+          value = parse_number arg[2..] # 2 == '<='.size
+          maximum value
+        when ":"
+          value = parse_number arg[1..]
+          ratio value
+      end
+    end
+    
+
+    def ==(other)
+      (@type == other.type) && (@value == other.value)
+    end
+
+
+    private
+      def self.parse_number(arg)
+        arg = arg.to_s
+        arg.include?(".") ? arg.to_f : arg.to_i
+      end
+
+  end # end of class
+
+end # end of module

data/lib/rayzer/distributor.rb

@@ -0,0 +1,126 @@
+# Constraint Priority:
+#   fixed = minimum > percentage > ratio > maximum
+# 
+# If there is still a remaining when every constraint is satisfied:
+#   If there is a minimum constraint, then the remaining is added to the result of the first minimum constraint.
+#   Otherwise:
+#     If used distribute, the remaining is added to the end of the returned array
+#     If used distribute!, raise an exception.
+
+module Rayzer
+  module Distributor
+    refine Numeric do
+
+      def distribute(*constraints)
+        _distribute(constraints, false)
+      end # end of distribute method 
+
+
+      def distribute!(*constraints)
+        # raises if the value is not completely distributed
+        _distribute(constraints, true)
+      end # end of distribute! method 
+
+
+      private 
+        def _distribute(args, raise_if_has_remaining)
+          raise ArgumentError, "Can not distribute non-real value #{self}" unless [Integer, Float].include? self.class
+
+          raise ArgumentError, "Can not distribute non-positive value #{self}" unless self.positive?
+
+          constraints = args.map { |arg| Constraint.parse arg }
+
+          remaining = self
+          parts = Array.new(constraints.size) { 0 }
+          first_min_index = nil
+
+          total_percentage = 0
+          percentages = []
+
+          total_ratio = 0
+          ratios = []
+
+          maximums = []
+
+
+          constraints.each.with_index do |cons, i|
+            case cons.type
+              when Constraint::FIXED, Constraint::MINIMUM
+                parts[i] = cons.value
+                remaining -= cons.value
+                raise ArgumentError, "Sum of required constraints exceeds #{self}" if remaining < 0
+
+                if cons.type == Constraint::MINIMUM
+                  first_min_index = i if first_min_index.nil?
+                end
+
+              when Constraint::PERCENTAGE
+                total_percentage += cons.value
+                raise ArgumentError, "Sum of percentage constraints exceeds 100" if total_percentage > 100
+
+                percentages << [i, cons.value]
+
+              when Constraint::RATIO
+                total_ratio += cons.value
+                ratios << [i, cons.value]
+
+              when Constraint::MAXIMUM
+                maximums << [i, cons.value]
+            end
+          end
+
+
+          unless remaining.zero? or total_percentage.zero?
+            percentages.each do |i, percentage|
+              parts[i] = percentage * 0.01 * remaining
+            end
+
+            remaining = (1 - total_percentage * 0.01) * remaining
+          end
+
+
+          unless remaining.zero? or total_ratio.zero?
+            value_per_ratio = remaining.fdiv total_ratio
+
+            ratios.each do |i, ratio|
+              parts[i] = ratio * value_per_ratio
+            end
+
+            remaining = 0
+          end
+
+
+          maximums.each do |i, value|
+            if value < remaining
+              parts[i] = value 
+              remaining -= value
+            else
+              parts[i] = remaining
+              remaining = 0
+              break
+            end
+          end
+
+
+          unless remaining.zero?
+            unless first_min_index.nil?
+              parts[first_min_index] += remaining
+              return parts
+            end
+
+            raise "Incomplete distribution of #{self}, remaining #{remaining}" if raise_if_has_remaining
+
+            parts << remaining
+          end
+
+          
+          parts
+        end # end of _distribute method 
+
+      # end of private
+
+    end # end of refinement
+
+  end # end of Distributor
+
+end # end of Rayzer

data/lib/rayzer/layout.rb

@@ -0,0 +1,141 @@
+require_relative 'distributor'
+
+
+module Rayzer
+  class Layout
+    class RemainingSpaceError < ArgumentError; end
+
+    using Distributor
+
+    COLUMN_CONTAINER = :column_container
+    ROW_CONTAINER = :row_container
+    LEAF = :leaf
+
+    attr_reader :x, :y, :width, :height, :parent, :children, :type
+
+
+    def initialize(x, y, width, height, parent=nil)
+      @x = x
+      @y = y
+      @width = width
+      @height = height
+      @parent = parent
+      @children = []
+      @type = LEAF
+    end
+
+
+    def root?
+      @parent.nil?
+    end
+
+
+    def leaf?
+      @type == LEAF
+    end
+
+    def rect
+      [@x, @y, @width, @height]
+    end
+
+
+    def split_to_rows(constraints, names=nil, &block)
+      heights = @height.distribute(*constraints)
+      curr_y = @y
+      @children = heights.map do |h|
+        row = self.class.new(@x, curr_y, @width, h, self)
+        curr_y += h
+        row
+      end
+
+      constraints_size = constraints.size
+      add_named_layout_instance_vars names, constraints_size
+      add_remaining_instance_var constraints_size
+
+      @type = ROW_CONTAINER
+      yield @children if block_given?
+      @children
+    end
+
+
+    def split_to_cols(constraints, names=nil, &block)
+      widths = @width.distribute(*constraints)
+
+      curr_x = @x
+
+      @children = widths.map do |w|
+        col = self.class.new(curr_x, @y, w, @height, self)
+        curr_x += w
+        col
+      end
+
+      constraints_size = constraints.size
+
+      add_named_layout_instance_vars names, constraints_size
+      add_remaining_instance_var constraints_size
+
+      @type = COLUMN_CONTAINER
+      yield @children if block_given?
+      @children
+    end
+
+
+    def split_to_cols!(constraints, names=nil, &block)
+      split_to_cols(constraints, names, &block)
+      raise RemainingSpaceError if instance_variable_defined? :@remaining
+      @children
+    end
+
+
+    def split_to_rows!(constraints, names=nil, &block)
+      split_to_rows(constraints, names, &block)
+      raise RemainingSpaceError if instance_variable_defined? :@remaining
+      @children
+    end
+
+
+    def ==(other)
+      # should require parent and children equality?
+      return false unless @x == other.x
+      return false unless @y == other.y
+      return false unless @width == other.width
+      return false unless @height == other.height
+      true
+    end
+
+
+  private
+    def add_named_layout_instance_vars(names, constraints_size)
+      unless names.nil?
+        if names.is_a? Array
+          raise ArgumentError, "Size of names and size of constraints mismatch" unless names.size == constraints_size
+
+          names.each.with_index do |name, i|
+            next if name.nil?
+            instance_variable_set "@#{name}", @children[i]
+            define_singleton_method(name) { instance_variable_get "@#{name}" }
+          end
+
+        elsif names.is_a? Hash
+          names.each do |i, name|
+            instance_variable_set "@#{name}", @children.fetch(i)
+            define_singleton_method(name) { instance_variable_get "@#{name}" }
+          end
+
+        else
+          raise ArgumentError, "Invalid type for arg: names. Expecting Array or Hash"
+        end
+      end
+    end
+
+
+    def add_remaining_instance_var(constraints_size)
+      if @children.size - constraints_size == 1
+        instance_variable_set :@remaining, @children[-1]
+        define_singleton_method(:remaining) { instance_variable_get :@remaining }
+      end
+    end
+
+
+  end # end of layout
+end # end of Rayzer

data/lib/rayzer/version.rb

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

data/lib/rayzer.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "rayzer/version"
+require_relative "rayzer/constraint"
+require_relative "rayzer/distributor"
+require_relative "rayzer/layout"

data/releasing_new_version.md

@@ -0,0 +1,6 @@
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+

data/sig/rayzer.rbs

@@ -0,0 +1,4 @@
+module Rayzer
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/usage_example.rb

@@ -0,0 +1,48 @@
+require "rayzer"
+
+x = 0
+y = 0
+width = 100
+height = 100
+
+# Create a new top-level layout
+root = Rayzer::Layout.new(x, y, width, height)
+
+# Create 3 sections with fixed length 10, minimum length 0 and another fixed length 10.
+sections = %w[ 10 >=0 10 ]
+
+# You can optionally name the sections. If given a name, the section can be accessed with the reader of the same name.
+section_names = %w[ header main footer ]
+
+# Split_to_* returns the children as well also yields them to the block for further partition if a block is given.
+root.split_to_rows!(sections, section_names) do |header, main, footer|
+
+  # Percentage constraint
+  constraints = %w[ 30% ]
+ 
+  # If there is remaining space after all constraints are satisfied, split_to_* appends the remaining to the children, whereas the bang version raises Rayzer::Layout::RemainingSpaceError.
+  # 
+  # The remaining is also accessable using the remaining method.
+  #
+  # When no names are given, you can only access them using the children attr_reader later
+  main.split_to_cols(constraints) do |sidebar, remaining|
+
+    # Ratio constraints
+    rows = %i[:1 :3 :1]
+
+    # If you only want to access some inner layout by name, use a hash with index as the key and a symbol or name as value.
+    row_names = { 1 => :content }
+
+    remaining.split_to_rows!(rows, row_names)
+  end
+end
+
+
+p root.header.rect                       # [0, 0, 100, 10]   
+p root.main.rect                         # [0, 10, 100, 80]      
+p root.footer.rect                       # [0, 90, 100, 10]      
+p root.main.children[0].rect             # [0, 10, 30.0, 80]            
+p root.main.remaining.rect               # [30.0, 10, 70.0, 80]      
+p root.main.remaining.children[0].rect   # [30.0, 10, 70.0, 16.0]        
+p root.main.remaining.content.rect       # [30.0, 26.0, 70.0, 48.0]      
+p root.main.remaining.children[2].rect   # [30.0, 74.0, 70.0, 16.0]           

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: rayzer
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- NullFluxKevin
+bindir: exe
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies: []
+description: This Gem allows you to use constraints such as fixed length, minimum
+  length, percentage, ratio, and maximum length to divide a rectangular space into
+  a tree of nested rows and columns.
+email:
+- null_flux_kevin@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/rayzer.rb
+- lib/rayzer/constraint.rb
+- lib/rayzer/distributor.rb
+- lib/rayzer/layout.rb
+- lib/rayzer/version.rb
+- releasing_new_version.md
+- sig/rayzer.rbs
+- usage_example.rb
+homepage: https://github.com/NullFluxKevin/rayzer
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/NullFluxKevin/rayzer
+  source_code_uri: https://github.com/NullFluxKevin/rayzer
+  changelog_uri: https://github.com/NullFluxKevin/rayzer/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.6
+specification_version: 4
+summary: A constraint-based layout engine for rectangular areas.
+test_files: []