flex-cartesian 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e92633e14160e43566c300b7e747f9f8cf742954652a442073ca44f7e0992ca3
-  data.tar.gz: c0a3ba79e43094b3c8325f23a9c37c8cf9f29a7fc4fb5bd20b34c514cef3e8d0
+  metadata.gz: 0b26211b52fac8e2a26ff5408d422e6ae328aefbd67d0a18ac07ef0404006c05
+  data.tar.gz: cf406e24632a26605b5002e91ddfdf63bddaeb0a361d2dbbab76f5514bfdec88
 SHA512:
-  metadata.gz: 1bd895985ea81a675c38e9feace76e9d3a6b0dca8502fe9065420695c66a75b8e1b4134b55a1144bf9082fe52a60f4c0812317f113ae486c0e739b6e55266bcd
-  data.tar.gz: 44edb599dff65eb233ef2bd87623cd0c4cf20ca1d5d9d6cb33dfbe504b8c852a3020374dae019efac8193b552590fd7a684637dac58efc7eb6b6de44117246b0
+  metadata.gz: 2cb31e4b65dba494aeac390ad1baee384c5eca90aeb67363cb374db4ba0c1e4b4d4f4dc6acac088642a751e9d7d4ee996b98c99abf49fdc98c615981c5c12663
+  data.tar.gz: 2b9c27d532a24430cbd21508d91d02d2f29172d9069eab75a8af5c60a2fb25936ff014de5ffc6c5a7df29e08d07de1b7272aefb6edbc907f60a96ae1e1520236

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
@@ -12,16 +14,22 @@
 
 ✅ 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 dimension space from JSON or YAML  
+✅ Import of Cartesian space from JSON or YAML
+
+✅ Export of Cartesian space to Markdown or CSV
 
 ✅ Structured and colorized terminal output  
 
+
+
 ## Installation
 
 ```bash
@@ -30,53 +38,103 @@ 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
+
+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)
+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
+
+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)
+
+
+
+# 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 dimenstions, it ignores functions"
+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 +174,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,22 +246,36 @@ 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: true) }
+s.cartesian { |v| v.output(colorize: true, align: false) }
 ```
 
 ## License

data/lib/flex-cartesian.rb

@@ -5,7 +5,7 @@ require 'json'
 require 'yaml'
 
 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 })
@@ -35,6 +35,10 @@ class FlexCartesian
     @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)
@@ -90,7 +94,7 @@ end
     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 +127,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.1.9
 platform: ruby
 authors:
 - Yury Rassokhin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-06 00:00:00.000000000 Z
+date: 2025-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colorize
@@ -53,9 +53,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.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 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: []