flex-cartesian 0.1.8 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e92633e14160e43566c300b7e747f9f8cf742954652a442073ca44f7e0992ca3
-  data.tar.gz: c0a3ba79e43094b3c8325f23a9c37c8cf9f29a7fc4fb5bd20b34c514cef3e8d0
+  metadata.gz: 4b34c40aea1692a248f2f4ee506b8b7a5a66a8257f90b1f74a7613897f8047c4
+  data.tar.gz: 3fb4c691a65ebcda1f9606368f436ba1ebee56749dee9e27d04296884cfef26e
 SHA512:
-  metadata.gz: 1bd895985ea81a675c38e9feace76e9d3a6b0dca8502fe9065420695c66a75b8e1b4134b55a1144bf9082fe52a60f4c0812317f113ae486c0e739b6e55266bcd
-  data.tar.gz: 44edb599dff65eb233ef2bd87623cd0c4cf20ca1d5d9d6cb33dfbe504b8c852a3020374dae019efac8193b552590fd7a684637dac58efc7eb6b6de44117246b0
+  metadata.gz: 455053108bada48ae9b224879069cfe6e43fca419391e194f5b90dbaece0523ab7810eb471e1768814c17bc61f4952171493fb5c38283473d7798039f6b8b8dd
+  data.tar.gz: 63ebb02a0fb22162b67d17caf483ab2abc3499e9d072ddec3749124e82856d4bfcf3106fbe53b84fd927fe3b36279cb1b2103d75064d4a1cf393ab2f72912f38

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.9 - 2025-07-08
+### Fixed
+- Documentation
+
+### Added
+- Unified methods for import and export
+- JSON and YAML can be imported, not only exported
+- Functions can be removed
+- Minor changes in default values of named parameters
+
 ## 0.1.8 - 2025-07-07
 ### Fixed
 - Documentation

data/README.md

@@ -2,6 +2,8 @@
 
 **Ruby implementation of flexible and human-friendly operations on Cartesian products**  
 
+
+
 ## Features
 
 ✅ Named dimensions with arbitrary keys
@@ -10,18 +12,26 @@
 
 ✅ Functions over Cartesian vectors are decoupled from dimensionality
 
+✅ Define conditions on Cartesian combinations using `s.cond(:set) { |v| v.dim1 > v.dim2 } }` syntax
+
 ✅ Calculate over named dimensions using `s.cartesian { |v| puts "#{v.dim1} and #{v.dim2}" }` syntax
 
+✅ Add functions over dimensions using `s.add_function { |v| v.dim1 + v.dim2 }` syntax
+
 ✅ Lazy and eager evaluation
 
-✅ Progress bars for large Cartesian combinations  
+✅ Progress bars for large Cartesian combinations
+
+✅ Export of Cartesian space to Markdown or CSV
 
-✅ Export of Cartesian space to Markdown or CSV  
+✅ Import of Cartesian space from JSON or YAML
 
-✅ Import of dimension space from JSON or YAML  
+✅ Export of Cartesian space to Markdown or CSV
 
 ✅ Structured and colorized terminal output  
 
+
+
 ## Installation
 
 ```bash
@@ -30,53 +40,140 @@ gem build flex-cartesian.gemspec
 gem install flex-cartesian-*.gem
 ```
 
+
+
 ## Usage
 
 ```ruby
+#!/usr/bin/ruby
+
 require 'flex-cartesian'
 
-# Define a Cartesian space with named dimensions:
+
+
+# BASIC CONCEPTS
+
+# 1. Cartesian object is a set of combinations of values of dimansions.
+# 2. Dimensions always have names.
+
+puts "\nDefine named dimensions"
 example = {
   dim1: [1, 2],
   dim2: ['x', 'y'],
   dim3: [true, false]
 }
+
+puts "\nCreate Cartesian space"
 s = FlexCartesian.new(example)
 
-# Iterate over all combinations and calculate function on each combination:
-s.cartesian { |v| puts "#{v.dim1}-#{v.dim2}" if v.dim3 }
+def do_something(v)
+  # do something here on vector v and its components 
+end
 
-# Get number of Cartesian combinations:
-puts "Total size: #{s.size}"
 
-# Convert Cartesian space to array of combinations
-array = s.to_a(limit: 3)
-puts array.inspect
 
-def do_something(v)
-end
+# ITERATION OVER CARTESIAN SPACE
 
-# Display progress bar (useful for large Cartesian spaces)
+# 3. Iterator is dimensionality-agnostic, that is, has a vector syntax that hides dimensions under the hood.
+#    This keeps foundational code intact, and isolates modifications in the iterator body 'do_something'.
+# 4. For efficiency on VERY largse Cartesian spaces, there are
+#    a). lazy evaluation of each combination
+#    b). progress bar to track time-consuming calculations.
+
+puts "\nIterate over all Cartesian combinations and execute action (dimensionality-agnostic style)"
+s.cartesian { |v| do_something(v) }
+
+puts "\nIterate over all Cartesian combinations and execute action (dimensionality-aware style)"
+s.cartesian { |v| puts "#{v.dim1} & #{v.dim2}" if v.dim3 }
+
+puts "\nIterate and display progress bar (useful for large Cartesian spaces)"
 s.progress_each { |v| do_something(v) }
 
-# Print Cartesian space as table
-s.output(align: true)
+puts "\nIterate in lLazy mode, without materializing entire Cartesian product in memory"
+s.cartesian(lazy: true).take(2).each { |v| do_something(v) }
 
-# Lazy evaluation without materializing entire Cartesian product in memory:
-s.cartesian(lazy: true).take(2).each { |v| puts v.inspect }
 
-# Load from JSON or YAML
-File.write('example.json', JSON.pretty_generate(example))
-s = FlexCartesian.from_json('example.json')
+
+# FUNCTIONS ON CARTESIAN SPACE
+
+# 5. A function is a virtual dimension that is calculated based on a vector of base dimensions.
+#    You can think of a function as a scalar field defined on Cartesian space.
+# 6. Functions are printed as virtual dimensions in .output method.
+# 7. However, functions remains virtual construct, and their values can't be referenced by name
+#    (unlike regular dimensions). Also, functions do not add to .size of Cartesian space.
+
+puts "\nAdd function 'triple'"
+puts "Note: function is visualized in .output as a new dimension"
+s.add_function(:triple) { |v| v.dim1 * 3 + (v.dim3 ? 1: 0) }
+# Note: however, function remains a virtual construct, and it cannot be referenced by name
+s.output
+
+puts "\Add and then remove function 'test'"
+s.add_function(:test) { |v| v.dim3.to_i }
+s.remove_function(:test)
+
+
+
+# CONDITIONS ON CARTESIAN SPACE
+
+# 8. A condition is a logical restriction of allowed combitnations for Cartesian space.
+# 9. Using conditions, you can take a slice of Cartesian space.
+#    In particular, you can reflect semantical dependency of dimensional values.
+
+puts "Build Cartesian space that includes only odd values of 'dim1' dimension"
+s.cond(:set) { |v| v.dim1.odd? }
+puts "print all the conditions in format 'index | condition '"
+s.cond
+puts "Test the condition: print the updated Cartesian space"
+s.output
+puts "Test the condition: check the updated size of Cartesian space"
+puts "New size: #{s.size}"
+puts "Clear condition #0"
+s.cond(:unset, index: 0)
+puts "Clear all conditions"
+s.cond(:clear)
+puts "Restored size without conditions: #{s.size}"
+
+
+
+# PRINT
+
+puts "\nPrint Cartesian space as plain table, all functions included"
 s.output
 
-# Export to Markdown
-s.output(format: :markdown, align: true)
+puts "\nPrint Cartesian space as Markdown"
+s.output(format: :markdown)
 
-# Export to CSV
+puts "\nPrint Cartesian space as CSV"
 s.output(format: :csv)
+
+
+
+# IMPORT / EXPORT
+
+puts "\nImport Cartesian space from JSON (similar method for YAML)"
+File.write('example.json', JSON.pretty_generate(example))
+puts "\nNote: after import, all assigned functions will calculate again, and they appear in the output"
+s.import('example.json').output
+
+puts "\nExport Cartesian space to YAML (similar method for JSON)"
+s.export('example.yaml', format: :yaml)
+
+
+
+# UTILITIES
+
+puts "\nGet number of Cartesian combinations"
+puts "Note: .size counts only dimensions, it ignores virtual constructs (functions, conditions, etc.)"
+puts "Total size of Cartesian space: #{s.size}"
+
+puts "\nPartially converting Cartesian space to array:"
+array = s.to_a(limit: 3)
+puts array.inspect
 ```
 
+
+
 ## API Overview
 
 ### Initialization
@@ -116,6 +213,33 @@ s.cartesian { |v| puts "#{v.dim1} - #{v.dim2}" }
 
 ---
 
+### Add / Remove Functions
+```ruby
+add_function(name, &block)
+remove_function(name)
+```
+- `name`: symbol — the name of the virtual dimension (e.g. `:label`)
+- `block`: a function that receives each vector and returns a computed value
+
+Functions show up in `.output` like additional (virtual) dimensions.
+
+Example:
+```ruby
+s = FlexCartesian.new( { dim1: [1, 2], dim2: ['A', 'B'] } )
+s.add_function(:increment) { |v| v.dim1 + 1 }
+
+s.output(format: :markdown)
+# | dim1 | dim2 | increment |
+# |------|------|--------|
+# | 1    | "A"  | 2    |
+# | 1    | "B"  | 2    |
+# ...
+```
+
+> Note: functions are virtual — they are not part of the base dimensions, but they integrate seamlessly in output.
+
+---
+
 ### Count Total Combinations
 ```ruby
 size(dims = nil) → Integer
@@ -161,24 +285,55 @@ Markdown example:
 
 ---
 
-### Load from JSON or YAML
+### Import from JSON or YAML
+```ruby
+import('file.json',
+  format: :json) # or :yaml
+```
+
+Obsolete import methods:
+```ruby
+s.from_json("file.json")
+s.from_yaml("file.yaml")
+```
+
+---
+
+### Export from JSON or YAML
 ```ruby
-FlexCartesian.from_json("file.json")
-FlexCartesian.from_yaml("file.yaml")
+export('file.json',
+  format: :json) # or :yaml
 ```
 
 ---
 
-### Output from Vectors
+### Print Cartesian Space
 Each yielded combination is a `Struct` extended with:
 ```ruby
-output(separator: " | ", colorize: false, align: false)
+output(separator: " | ", colorize: false, align: true)
+```
+Example:
+```ruby
+s.cartesian { |v| v.output(colorize: true, align: false) }
 ```
+
+---
+
+### Conditions on Cartesian Space
+cond(command = :print, # or :set, :unset, :clear
+     index: nil, # index of a conditions to unset
+     &block # defintiion of the condition to set
+     )
 Example:
 ```ruby
-s.cartesian { |v| v.output(colorize: true, align: true) }
+s.cond(:set) { |v| v.dim1 > v.dim3 }
+s.cond # defaults to s.cond(:print) and shows all the conditions in the form 'index | definition'
+s.cond(:unset, 0) # remove previously set condition
+s.cond(:clear) # remove all conditions, if any
 ```
 
+
+
 ## License
 
 This project is licensed under the terms of the GNU General Public License v3.0.  

data/lib/flex-cartesian.rb

@@ -3,9 +3,10 @@ require 'progressbar'
 require 'colorize'
 require 'json'
 require 'yaml'
+require 'method_source'
 
 module FlexOutput
-  def output(separator: " | ", colorize: false, align: false)
+  def output(separator: " | ", colorize: false, align: true)
     return puts "(empty struct)" unless respond_to?(:members) && respond_to?(:values)
 
     values_list = members.zip(values.map { |v| v.inspect })
@@ -27,14 +28,39 @@ class FlexCartesian
 
   def initialize(dimensions = nil)
     @dimensions = dimensions
+    @conditions = []
     @derived = {}
   end
 
+  def cond(command = :print, index: nil, &block)
+    case command
+    when :set
+      raise ArgumentError, "Block required" unless block_given?
+      @conditions << block
+      self
+    when :unset
+      raise ArgumentError, "Index of the condition required" unless index
+      @conditions.delete_at(index)
+    when :clear 
+      @conditions.clear
+      self
+    when :print 
+      return if @conditions.empty?
+      @conditions.each_with_index { |cond, idx| puts "#{idx} | #{cond.source.gsub(/^.*?\s/, '')}" }
+    else
+      raise ArgumentError, "unknown condition command: #{command}"
+    end
+  end
+
   def add_function(name, &block)
     raise ArgumentError, "Block required" unless block_given?
     @derived[name.to_sym] = block
   end
 
+  def remove_function(name)
+    @derived.delete(name.to_sym)
+  end
+
   def cartesian(dims = nil, lazy: false)
   dimensions = dims || @dimensions
   return nil unless dimensions.is_a?(Hash)
@@ -57,18 +83,26 @@ class FlexCartesian
       struct_instance.define_singleton_method(name) { block.call(struct_instance) }
     end
 
+  next if @conditions.any? { |cond| !cond.call(struct_instance) }
+
     yield struct_instance
   end
 end
 
-  def size(dims = nil)
-    dimensions = dims || @dimensions
-    return 0 unless dimensions.is_a?(Hash)
-
-    values = dimensions.values.map { |dim| dim.is_a?(Enumerable) ? dim.to_a : [dim] }
-    return 0 if values.any?(&:empty?)
-
-    values.map(&:size).inject(1, :*)
+  def size
+    return 0 unless @dimensions.is_a?(Hash)
+    if @conditions.empty?
+      values = @dimensions.values.map { |dim| dim.is_a?(Enumerable) ? dim.to_a : [dim] }
+      return 0 if values.any?(&:empty?)
+      values.map(&:size).inject(1, :*)
+    else
+      size = 0
+      cartesian do |v|
+        next if @conditions.any? { |cond| !cond.call(v) }
+        size += 1
+      end
+      size
+    end
   end
 
   def to_a(limit: nil)
@@ -80,17 +114,16 @@ end
     result
   end
 
-  def progress_each(dims = nil, lazy: false, title: "Processing")
-    total = size(dims)
-    bar = ProgressBar.create(title: title, total: total, format: '%t [%B] %p%% %e')
+  def progress_each(lazy: false, title: "Processing")
+    bar = ProgressBar.create(title: title, total: size, format: '%t [%B] %p%% %e')
 
-    cartesian(dims, lazy: lazy) do |v|
+    cartesian(@dimensions, lazy: lazy) do |v|
       yield v
       bar.increment
     end
   end
 
-  def output(separator: " | ", colorize: false, align: false, format: :plain, limit: nil)
+  def output(separator: " | ", colorize: false, align: true, format: :plain, limit: nil)
   rows = []
   cartesian do |v|
     rows << v
@@ -123,14 +156,42 @@ end
   end
 end
 
-  def self.from_json(path)
+def import(path, format: :json)
+  data = case format
+  when :json
+    JSON.parse(File.read(path), symbolize_names: true)
+  when :yaml
+    YAML.safe_load(File.read(path), symbolize_names: true)
+  else
+    raise ArgumentError, "Unsupported format: #{format}. Only :json and :yaml are supported."
+  end
+
+  raise TypeError, "Expected parsed data to be a Hash" unless data.is_a?(Hash)
+
+  @dimensions = data
+  self
+end
+
+def export(path, format: :json)
+  case format
+  when :json
+    File.write(path, JSON.pretty_generate(@dimensions))
+  when :yaml
+    File.write(path, YAML.dump(@dimensions))
+  else
+    raise ArgumentError, "Unsupported format: #{format}. Only :json and :yaml are supported."
+  end
+end
+
+
+  def from_json(path)
     data = JSON.parse(File.read(path), symbolize_names: true)
-    new(data)
+    @dimensions = data
   end
 
-  def self.from_yaml(path)
+  def from_yaml(path)
     data = YAML.safe_load(File.read(path), symbolize_names: true)
-    new(data)
+    @dimensions = data
   end
 
 private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flex-cartesian
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: '0.2'
 platform: ruby
 authors:
 - Yury Rassokhin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-06 00:00:00.000000000 Z
+date: 2025-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colorize
@@ -52,10 +52,24 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: method_source
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: 'Flexible and human-friendly Cartesian product enumerator for Ruby. Supports
-  calculated functions, dimension-agnostic iterators, named dimensions, tabular output,
-  lazy/eager evaluation, progress bar, JSON/YAML loading, and export to Markdown/CSV.
-  Code example: https://github.com/Yuri-Rassokhin/flex-cartesian/blob/main/README.md#usage'
+  functions and conditions on cartesian, dimensionality-agnostic/dimensionality-aware
+  iterators, named dimensions, tabular output, lazy/eager evaluation, progress bar,
+  import from JSON/YAML, and export to Markdown/CSV. Code example: https://github.com/Yuri-Rassokhin/flex-cartesian/blob/main/README.md#usage'
 email:
 - yuri.rassokhin@gmail.com
 executables: []