forthic 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e71f6368dc2bcc817f0095a389740a6676005ab8ddb862cdef02f0e0910d09d
-  data.tar.gz: b408177ce893d5353aa00ce2a73698005c07e22e3d68a8ec6cade6032887a591
+  metadata.gz: edd1101930e744ff0289d9a71f7449645852a558c7f12b4f4b0fe8bb211278cd
+  data.tar.gz: ea53ba5d3f04fca67b2088debe870eba40e9c2b1bca04061095420d0b92de8cd
 SHA512:
-  metadata.gz: 2ffd692800bdf839d25a106c79bea485addaeabb7d2eafd5366a9d034927a642fed7b4ecb498e5f081016f5079077d3a4db4ba96eae113a8ce547024b4164736
-  data.tar.gz: b4ab0aec5f7b788873bbbc71761f5382f565864057101125919338c24453bdccdedbcf26f281dc5c46dee4a16fc7824a08516a52c9c318af91ab0f932a329f42
+  metadata.gz: 8f193bcb169fe8b7a7f59c27978b3c296b61e791199b6e4c9797eb10d671ff091416ac5e7fc6ecd42f7bf70955dbbbf237fa7c97e8434ea3abd41e13a4c861e9
+  data.tar.gz: 9bea9f3a03156019a3e3e23bf634c8988bd13180ec28faa4cb91d4256851c3cefbcd9928341e494e8f281a3f331bd4262d358c7fd1bb61db99c50e0983dcc13c

data/README.md

@@ -1,37 +1,337 @@
-# Forthic
+# Forthic Ruby Runtime
 
-A Forthic interpreter that runs within Ruby.
+**A Ruby runtime for [Forthic](https://github.com/forthix/forthic)** - *the* stack-based, concatenative language for composable transformations.
+
+Use Forthic to wrap your Ruby code within composable words, leveraging categorical principles for clean, powerful abstractions.
+
+**[Forthic Parent Documentation](https://github.com/forthix/forthic)** | **[Getting Started](#getting-started)** | **[Examples](examples/)** | **[API Docs](docs/)**
+
+---
+
+## What is Forthic?
+
+Forthic enables **categorical coding** - a way to solve problems by viewing them in terms of transformation rather than computation. This Ruby runtime lets you:
+
+1. **Wrap existing code** with simple decorators
+2. **Compose transformations** cleanly using stack-based operations
+3. **Build powerful abstractions** from simple primitives
+
+See the [Forthic repository](https://github.com/forthix/forthic) for philosophy, core concepts, and why categorical coding matters.
+
+---
+
+## Quick Example
+
+### Create a Module
+
+```ruby
+require 'forthic'
+
+class AnalyticsModule < Forthic::Decorators::DecoratedModule
+  def initialize
+    super("analytics")
+  end
+
+  word :AVERAGE, "( numbers -- avg )", "Calculate average"
+  def AVERAGE(numbers)
+    numbers.sum.to_f / numbers.length
+  end
+
+  word :FILTER_OUTLIERS, "( numbers stdDevs -- filtered )", "Filter outliers beyond N std devs"
+  def FILTER_OUTLIERS(numbers, std_devs)
+    mean = AVERAGE(numbers)
+    std_dev = Math.sqrt(numbers.map { |n| (n - mean) ** 2 }.sum / numbers.length)
+    threshold = std_dev * std_devs
+    numbers.select { |n| (n - mean).abs <= threshold }
+  end
+end
+```
+
+### Use It
+
+```ruby
+require 'forthic'
+
+interp = Forthic::Interpreter.new
+interp.register_module(AnalyticsModule.new)
+
+interp.run(%{
+  ["analytics"] USE-MODULES
+
+  [1 2 3 100 4 5] 2 FILTER-OUTLIERS AVERAGE
+})
+
+result = interp.stack_pop  # Clean average without outliers
+```
+
+---
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Add to your Gemfile:
+
+```ruby
+gem 'forthic'
+```
+
+Then install:
 
 ```bash
-bundle add forthic
+bundle install
+```
+
+---
+
+## Getting Started
+
+### Basic Usage
+
+```ruby
+require 'forthic'
+
+interp = Forthic::Interpreter.new
+
+# Execute Forthic code
+interp.run(%{
+  [1 2 3 4 5] "2 *" MAP  # Double each element
+})
+
+result = interp.stack_pop  # [2, 4, 6, 8, 10]
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### Creating Your First Module
+
+```ruby
+require 'forthic'
+
+class MyModule < Forthic::Decorators::DecoratedModule
+  def initialize
+    super("mymodule")
+  end
+
+  word :PROCESS, "( data -- result )", "Process data your way"
+  def PROCESS(data)
+    # Wrap your existing Ruby code
+    my_existing_function(data)
+  end
+end
+
+# Register and use
+interp = Forthic::Interpreter.new
+interp.register_module(MyModule.new)
+
+interp.run(%{
+  ["mymodule"] USE-MODULES
+  SOME-DATA PROCESS
+})
+```
+
+See [examples/README.md](examples/README.md) for detailed tutorials and examples.
+
+---
+
+## Features
+
+### Standard Library
+
+The Ruby runtime includes comprehensive standard modules:
+
+- **array** - MAP, SELECT, SORT, GROUP-BY, ZIP, REDUCE, FLATTEN (30+ operations)
+- **record** - REC@, <REC, MERGE, KEYS, VALUES, INVERT-KEYS
+- **string** - SPLIT, JOIN, UPPERCASE, LOWERCASE, TRIM, REPLACE
+- **math** - +, -, *, /, ROUND, ABS, MIN, MAX, AVERAGE
+- **datetime** - >DATE, >DATETIME, ADD-DAYS, FORMAT, DIFF-DAYS
+- **json** - >JSON, JSON>, JSON-PRETTIFY
+- **boolean** - ==, <, >, AND, OR, NOT, IN
+
+See [docs/modules/](docs/modules/) for complete reference.
+
+### Easy Module Creation
+
+The decorator system makes wrapping code trivial:
+
+```ruby
+word :MY_WORD, "( input -- output )", "Description"
+def MY_WORD(input)
+  your_logic(input)
+end
+```
+
+### Ruby Integration
+
+- Full Ruby compatibility (Ruby 2.7+)
+- Works with Rails applications
+- Synchronous execution model
+- Native Ruby error handling
+
+---
+
+## Documentation
+
+### This Runtime
+- **[Module API Reference](docs/modules/)** - Standard library documentation
+- **[Examples](examples/)** - Working code samples
+
+### Core Forthic Concepts
+- **[Main Forthic Docs](https://github.com/forthix/forthic)** - Philosophy, language guide
+- **[Why Forthic?](https://github.com/forthix/forthic/blob/main/docs/why-forthic.md)** - Motivation and core principles
+- **[Category Theory](https://github.com/forthix/forthic/blob/main/docs/language/category-theory.md)** - Mathematical foundations
+- **[Building Modules](https://github.com/forthix/forthic/blob/main/docs/tutorials/building-modules.md)** - Module creation patterns
+
+---
+
+## Examples
+
+See the [examples/](examples/) directory for working code samples including:
+- Basic usage patterns
+- Custom module creation
+- Multi-runtime execution
+- Rails integration
+
+---
+
+## Building
 
 ```bash
-gem install forthic
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rspec
+
+# Run only unit tests
+bundle exec rspec spec/unit/
+
+# Run only integration tests
+bundle exec rspec spec/integration/
+
+# Generate documentation
+bundle exec rake docs
 ```
 
-## Usage
+---
+
+## Multi-Runtime Execution
 
-Here's a basic example of how to use the Forthic interpreter:
+Call code from other language runtimes seamlessly - use Python's pandas from Ruby, or TypeScript's JavaScript libraries from Ruby.
+
+### Quick Example
 
 ```ruby
 require 'forthic'
+require 'forthic/grpc/client'
+require 'forthic/grpc/remote_runtime_module'
 
 interp = Forthic::Interpreter.new
-interp.run("[1 2 3] '8 *' MAP")
-puts interp.stack_pop
 
-# Output:
-#
-# [ 8, 16, 24 ]
+# Register the remote runtime module
+remote_runtime = Forthic::Grpc::RemoteRuntimeModule.new
+interp.register_module(remote_runtime)
+
+interp.run(%{
+  # Connect to Python runtime
+  "localhost:50051" CONNECT-RUNTIME
+
+  # Load Python pandas module
+  ["pandas"] USE-PY-MODULES
+
+  # Now use Python pandas from Ruby!
+  [
+    [ [.name "Alice"] [.age 30] ] REC
+    [ [.name "Bob"]   [.age 25] ] REC
+  ] DF-FROM-RECORDS
+})
+```
+
+### Approaches
+
+- **gRPC** - Ruby ↔ Python ↔ TypeScript (fast, server-to-server)
+- **WebSocket** - Browser ↔ Rails (ActionCable, client-server)
+
+### Learn More
+
+📖 **[Complete Multi-Runtime Documentation](docs/multi-runtime/)**
+
+- **[Overview](docs/multi-runtime/)** - When and how to use multi-runtime
+- **[gRPC Setup](docs/multi-runtime/grpc.md)** - Server and client configuration
+- **[WebSocket Setup](docs/multi-runtime/websocket.md)** - Browser-compatible communication
+- **[Configuration](docs/multi-runtime/configuration.md)** - YAML config and connection management
+- **[Examples](examples/)** - Working code samples
+
+**Runtime Status:** ✅ TypeScript, Python, Ruby | 🚧 Rust | 📋 Java, .NET
+
+---
+
+## Project Structure
+
 ```
+forthic-rb/
+├── lib/forthic/          # Core library code
+│   ├── decorators/       # Decorator system for modules and words
+│   ├── modules/          # Standard library modules
+│   │   └── standard/     # Standard modules (array, string, math, etc.)
+│   ├── grpc/             # gRPC client/server for multi-runtime
+│   ├── websocket/        # WebSocket/ActionCable support
+│   ├── interpreter.rb    # Main interpreter implementation
+│   ├── module.rb         # Module and word classes
+│   ├── tokenizer.rb      # Lexical analysis
+│   └── errors.rb         # Error classes
+├── spec/                 # Test suite
+│   ├── unit/             # Unit tests
+│   └── integration/      # Integration tests
+├── scripts/              # Utility scripts
+│   └── generate_docs.rb  # Documentation generator
+├── protos/               # Protocol buffer definitions
+│   └── v1/               # Version 1 of gRPC protocol
+└── docs/                 # Generated documentation (created by rake docs)
+```
+
+---
+
+## Cross-Runtime Compatibility
+
+This Ruby implementation maintains compatibility with:
+- **forthic-ts** (TypeScript/JavaScript)
+- **forthic-py** (Python)
+- **forthic-rs** (Rust, in progress)
+
+All runtimes share the same test suite and language semantics to ensure consistent behavior across platforms.
+
+---
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/linkedin/forthic.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines, or refer to the main [Forthic contributing guide](https://github.com/forthix/forthic/blob/main/CONTRIBUTING.md).
+
+When adding new words or modules:
+
+1. Use the decorator system (`word` or `direct_word`)
+2. Include stack effect notation: `( input -- output )`
+3. Provide clear descriptions
+4. Add corresponding tests in `spec/`
+5. Regenerate documentation: `bundle exec rake docs`
+
+---
+
+## Community
+
+- **Main Repository:** [forthix/forthic](https://github.com/forthix/forthic)
+- **Issues:** [Report issues](https://github.com/forthix/forthic-rb/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/forthix/forthic/discussions)
+- **Examples:** [Real-world applications](examples/)
+
+---
+
+## License
+
+[BSD-2-Clause License](LICENSE) - Copyright 2024 LinkedIn Corporation. Copyright 2025 Forthix LLC.
+
+---
+
+## Related
+
+- **[Forthic (main repo)](https://github.com/forthix/forthic)** - Core documentation and concepts
+
+---
+
+**Forthic**: Wrap. Compose. Abstract.

data/Rakefile

@@ -1,14 +1,43 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "minitest/test_task"
+require 'rspec/core/rake_task'
 
-Minitest::TestTask.create
+RSpec::Core::RakeTask.new(:spec)
 
-require "standard/rake"
+task default: :spec
 
-task default: %i[test standard]
+desc 'Generate documentation from module decorators'
+task :docs do
+  ruby 'scripts/generate_docs.rb'
+end
 
-task :guard do
-  sh "bundle exec guard"
-end
+desc 'Run all tests'
+task test: :spec
+
+desc 'Run unit tests only'
+task :test_unit do
+  sh 'bundle exec rspec spec/unit'
+end
+
+desc 'Run integration tests only'
+task :test_integration do
+  sh 'bundle exec rspec spec/integration'
+end
+
+desc 'Generate gRPC protobuf code from .proto file'
+task :generate_grpc do
+  proto_file = 'protos/v1/forthic_runtime.proto'
+  proto_dir = 'protos/v1'
+  output_dir = 'lib/forthic/grpc'
+
+  # Create output directory if it doesn't exist
+  FileUtils.mkdir_p(output_dir)
+
+  # Generate Ruby protobuf code from v1 proto
+  sh "grpc_tools_ruby_protoc -I #{proto_dir} " \
+     "--ruby_out=#{output_dir} " \
+     "--grpc_out=#{output_dir} " \
+     "#{proto_file}"
+
+  puts "✓ Generated protobuf code from #{proto_file}"
+end

data/lib/forthic/decorators/docs.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'word'
+require 'json'
+
+module Forthic
+  module Decorators
+    # Generate markdown documentation for a module
+    #
+    # @param mod [DecoratedModule] The module to document
+    # @return [String] Markdown-formatted documentation
+    def self.generate_module_docs(mod)
+      docs = mod.get_word_docs
+      md = "# #{mod.get_name} Module\n\n"
+
+      if docs.empty?
+        md += "*No documented words*\n"
+        return md
+      end
+
+      # Sort alphabetically by name
+      docs.sort_by! { |doc| doc[:name] }
+
+      docs.each do |doc|
+        md += "## #{doc[:name]}\n\n"
+        md += "**Stack Effect**: `#{doc[:stack_effect]}`\n\n"
+        md += "#{doc[:description]}\n\n" if doc[:description] && !doc[:description].empty?
+      end
+
+      md
+    end
+
+    # Generate JSON documentation for multiple modules
+    #
+    # @param modules [Array<DecoratedModule>] The modules to document
+    # @return [Array<Hash>] Array of module documentation hashes
+    def self.generate_docs_json(modules)
+      modules.map do |mod|
+        {
+          name: mod.get_name,
+          words: mod.get_word_docs
+        }
+      end
+    end
+
+    # Generate full stdlib documentation
+    #
+    # @param interp [StandardInterpreter] The interpreter with stdlib loaded
+    # @return [String] Markdown-formatted stdlib documentation
+    def self.generate_stdlib_docs(interp)
+      module_names = [
+        "core", "array", "record", "string", "datetime",
+        "math", "boolean", "json", "utility"
+      ]
+
+      md = "# Forthic Standard Library\n\n"
+
+      module_names.each do |module_name|
+        mod = interp.get_app_module.find_module(module_name)
+        if mod && mod.is_a?(DecoratedModule)
+          md += generate_module_docs(mod)
+          md += "\n---\n\n"
+        end
+      end
+
+      md
+    end
+  end
+end