crystalruby 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db2722469a6d98fb5696b55dd0980337db19ce92fde42b4c1c023cfa6fd877d0
-  data.tar.gz: a2914be29451a124cca3dcdd83173e8f4713c5e1dbd1121c1c4179e6e8a55ea6
+  metadata.gz: 46edf2cddbf8fc124cca7cab14a4c3d745fcf88b9a841468cdbc7f2fc517187a
+  data.tar.gz: c350e0049aff5d88f8326314e0a70fbe57ea3866dcdf247010a0c1c64f656899
 SHA512:
-  metadata.gz: 9253f9b6b953021570fb31ee958e4ca2c798d3e586d5be8da59d5f26b895f1bce22672bbb1c0c14322732d61d9c4fe780d6833d9410d9e16732683862fd3330f
-  data.tar.gz: d14edd179ed85907f90038b303f409a6c3868b2cf2bbfd60695350886d67ee5bf9d98b2ee3e1d05421e3d55b9b3ce155f7d9b0d04d2c6bee0165f36e1598abc7
+  metadata.gz: 54ca6d542370d360f1f48959e4edf5a4308985d8e952317e2780b980c068674cb56c257c9d8241d0fc929bb152ca9960a8c7397f90c08725acf9bd268f794842
+  data.tar.gz: 303d6c379501dcf8966dd3941f2e667f35efeec67b24eb68bf2965abee06e5afa4b631c7b23e7493e4a3e088f650bd5a85271ae2bedb18b7a0120ca4c4bc605c

data/README.md

@@ -1,6 +1,6 @@
-# CrystalRuby
+# crystalruby
 
-Crystal Ruby is a gem that allows you to write Crystal code, inlined in Ruby. All you need is a modern crystal compiler installed on your system.
+`crystalruby` is a gem that allows you to write Crystal code, inlined in Ruby. All you need is a modern crystal compiler installed on your system.
 
 You can then turn simple methods into Crystal methods as easily as demonstrated below:
 
@@ -169,6 +169,60 @@ Remember to require these installed shards after installing them. E.g. inside `.
 
 You can edit the default paths for crystal source and library files from within the `./crystalruby.yaml` config file.
 
+### Wrapping Crystal code in Ruby
+
+Sometimes you may want to wrap a Crystal method in Ruby, so that you can use Ruby before the Crystal code to prepare arguments, or after the Crystal code, to apply transformations to the result. A real-life example of this might be an ActionController method, where you might want to use Ruby to parse the request, perform auth etc., and then use Crystal to perform some heavy computation, before returning the result from Ruby.
+To do this, you simply pass a block to the `crystalize` method, which will serve as the Ruby entry point to the function. From within this block, you can invoke `super` to call the Crystal method, and then apply any Ruby transformations to the result.
+
+```ruby
+module MyModule
+  crystalize [a: :int32, b: :int32] => :int32 do |a, b|
+    # In this example, we perform automated conversion to integers inside Ruby.
+    # Then add 1 to the result of the Crystal method.
+    result = super(a.to_i, b.to_i)
+    result + 1
+  end
+  def add(a, b)
+    a + b
+  end
+end
+
+MyModule.add("1", "2")
+```
+
+### Release Builds
+
+You can control whether CrystalRuby builds in debug or release mode by setting following config option
+
+```ruby
+CrystalRuby.configure do |config|
+  config.debug = false
+end
+```
+
+By default, Crystal code is only JIT compiled. In production, you likely want to compile the Crystal code ahead of time. To do this, you can create a dedicated file which
+
+- Preloads all files Ruby code with embedded crystal
+- Forces compilation.
+
+E.g.
+
+```ruby
+# E.g. crystalruby_build.rb
+require "crystalruby"
+
+CrystalRuby.configure do |config|
+  config.debug = false
+end
+
+require_relative "foo"
+require_relative "bar"
+
+CrystalRuby.compile!
+```
+
+Then you can run this file as part of your build step, to ensure all Crystal code is compiled ahead of time.
+
 ### Troubleshooting
 
 The logic to detect when to JIT recompile is not robust and can end up in an inconsistent state. To remedy this it is useful to clear out all generated assets and build from scratch.
@@ -179,6 +233,26 @@ To do this execute:
 bundle exec crystalruby clean
 ```
 
+## Design Goals
+
+`crystalruby`'s primary purpose is provide ergonomic access to Crystal from Ruby, over FFI.
+For simple usage, advanced knowledge of Crystal should not be required.
+
+However, the abstraction it provides should remain simple, transparent, and easy to hack on and it should not preclude users from supplementing its capabilities with a more direct integration using ffi primtives.
+
+It should support escape hatches to allow it to coexist with code that performs a more direct [FFI](https://github.com/ffi/ffi) integration to implement advanced functionality not supported by `crystalruby`.
+
+The library is currently in its infancy. Planned additions are:
+
+- Replace existing checksum process, with one that combines results of inline and external crystal to more accurately detect when recompilation is necessary.
+- Support for automatic serialization of nested data structures (holding _ONLY_ primitives), using JSON as our serialization protocol (prioritizing portability over raw serialization performance. JSON generation and parsing is bundled into the stdlib in both languages).
+- Simple mixin/concern that utilises `FFI::Struct` for bi-directional passing of Ruby objects and Crystal objects (by value).
+- Install command to generate a sample build script, and supports build command (which simply verifies then invokes this script)
+- Call Ruby from Crystal using FFI callbacks (implement `.expose_to_crystal`)
+- Support long-lived synchronized objects (through use of synchronized memory arena to prevent GC).
+- Support for passing `crystalruby` types by reference (need to contend with GC).
+- Explore mechanisms to safely expose true parallelism using [FFI over Ractors](https://github.com/ffi/ffi/wiki/Ractors)
+
 ## Installation
 
 To get started, add this line to your application's Gemfile:
@@ -199,7 +273,7 @@ Or install it yourself as:
 $ gem install crystalruby
 ```
 
-Crystal Ruby requires some basic initialization options inside a crystalruby.yaml file in the root of your project.
+`crystalruby` requires some basic initialization options inside a crystalruby.yaml file in the root of your project.
 You can run `crystalruby init` to generate a configuration file with sane defaults.
 
 ```bash
@@ -221,7 +295,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/crystalruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/crystalruby/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/wouterken/crystalruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/wouterken/crystalruby/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -229,4 +303,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Crystalruby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/crystalruby/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the `crystalruby` project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/wouterken/crystalruby/blob/master/CODE_OF_CONDUCT.md).

data/crystalruby.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = "Embed Crystal code directly in Ruby."
   spec.homepage = "https://github.com/wouterken/crystalruby"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.0.0"
+  spec.required_ruby_version = ">= 2.7.2"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
@@ -32,10 +32,10 @@ Gem::Specification.new do |spec|
 
   # Uncomment to register a new dependency of your gem
   # spec.add_dependency "example-gem", "~> 1.0"
-  spec.add_dependency 'ffi'
-  spec.add_dependency 'digest'
-  spec.add_dependency 'fileutils'
-  spec.add_dependency 'method_source'
+  spec.add_dependency "digest"
+  spec.add_dependency "ffi"
+  spec.add_dependency "fileutils"
+  spec.add_dependency "method_source"
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html
 end

data/lib/crystalruby/config.rb

@@ -1,5 +1,5 @@
-require 'singleton'
-require 'yaml'
+require "singleton"
+require "yaml"
 
 module CrystalRuby
   def self.config
@@ -14,10 +14,11 @@ module CrystalRuby
     def initialize
       # Set default configuration options
       @debug = true
-      if File.exist?("crystalruby.yaml")
-        @crystal_src_dir, @crystal_lib_dir, @crystal_main_file, @crystal_lib_name =
-        YAML.safe_load_file("crystalruby.yaml").values_at("crystal_src_dir","crystal_lib_dir","crystal_main_file", "crystal_lib_name")
-      end
+      return unless File.exist?("crystalruby.yaml")
+
+      @crystal_src_dir, @crystal_lib_dir, @crystal_main_file, @crystal_lib_name =
+        YAML.safe_load(IO.read("crystalruby.yaml")).values_at("crystal_src_dir", "crystal_lib_dir", "crystal_main_file",
+                                                              "crystal_lib_name")
     end
   end
 

data/lib/crystalruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Crystalruby
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/crystalruby.rb

@@ -1,33 +1,20 @@
-require 'ffi'
-require 'digest'
-require 'fileutils'
-require 'method_source'
+require "ffi"
+require "digest"
+require "fileutils"
+require "method_source"
 require_relative "crystalruby/config"
 require_relative "crystalruby/version"
 require_relative "crystalruby/typemaps"
-# TODO
-# Shards
-# Object methods
-# Fix bigint issues
-# * Initialize Crystal project
-# * Clear build artifacts
-# * Add config file
-# * Set release flag (Changes build target locations)
-# Struct Conversions
-# Classes
-# Test Nesting
-
 
 module CrystalRuby
-
   # Define a method to set the @crystalize proc if it doesn't already exist
-  def crystalize(type=:src, **options, &block)
+  def crystalize(type = :src, **options, &block)
     (args,), returns = options.first
     args ||= {}
-    raise "Arguments should be of the form name: :type. Got #{args}" unless args.kind_of?(Hash)
-    @crystalize_next = {raw: type.to_sym == :raw, args:, returns:, block: }
-  end
+    raise "Arguments should be of the form name: :type. Got #{args}" unless args.is_a?(Hash)
 
+    @crystalize_next = { raw: type.to_sym == :raw, args: args, returns: returns, block: block }
+  end
 
   def method_added(method_name)
     if @crystalize_next
@@ -42,7 +29,6 @@ module CrystalRuby
   end
 
   def attach_crystalized_method(method_name)
-
     CrystalRuby.instantiate_crystal_ruby! unless CrystalRuby.instantiated?
 
     function_body = instance_method(method_name).source.lines[
@@ -59,12 +45,14 @@ module CrystalRuby
       extend FFI::Library
       ffi_lib "#{config.crystal_lib_dir}/#{config.crystal_lib_name}"
       attach_function "#{method_name}", fname, args.map(&:last), returns
-      attach_function 'init!', 'init', [], :void
-      [singleton_class, self].each do |receiver|
-        receiver.prepend(Module.new do
-          define_method(method_name, &block)
-        end)
-      end if block
+      attach_function "init!", "init", [], :void
+      if block
+        [singleton_class, self].each do |receiver|
+          receiver.prepend(Module.new do
+            define_method(method_name, &block)
+          end)
+        end
+      end
 
       init!
     end
@@ -82,21 +70,20 @@ module CrystalRuby
 
   module_function
 
-
   def build_function(owner, name, args, returns, body)
     fnname = "#{owner.name.downcase}_#{name}"
     args ||= {}
     string_conversions = args.select { |_k, v| v.eql?(:string) }.keys
     function_body = <<~CRYSTAL
       module #{owner.name}
-        def self.#{name}(#{args.map { |k, v| "#{k} : #{native_type(v)}" }.join(',')}) : #{native_type(returns)}
+        def self.#{name}(#{args.map { |k, v| "#{k} : #{native_type(v)}" }.join(",")}) : #{native_type(returns)}
           #{body}
         end
       end
 
-      fun #{fnname}(#{args.map { |k, v| "_#{k}: #{lib_type(v)}" }.join(',')}): #{lib_type(returns)}
+      fun #{fnname}(#{args.map { |k, v| "_#{k}: #{lib_type(v)}" }.join(",")}): #{lib_type(returns)}
         #{args.map { |k, v| "#{k} = #{convert_to_native_type("_#{k}", v)}" }.join("\n\t")}
-        #{convert_to_return_type("#{owner.name}.#{name}(#{args.keys.map { |k| "#{k}" }.join(',')})", returns)}
+        #{convert_to_return_type("#{owner.name}.#{name}(#{args.keys.map { |k| "#{k}" }.join(",")})", returns)}
       end
     CRYSTAL
 
@@ -123,22 +110,27 @@ module CrystalRuby
   end
 
   def self.instantiate_crystal_ruby!
-    raise "Crystal executable not found. Please ensure Crystal is installed and in your PATH." unless system("which crystal > /dev/null 2>&1")
+    unless system("which crystal > /dev/null 2>&1")
+      raise "Crystal executable not found. Please ensure Crystal is installed and in your PATH."
+    end
+
     @instantiated = true
     %w[crystal_lib_dir crystal_main_file crystal_src_dir crystal_lib_name].each do |config_key|
-      raise "Missing config option `#{config_key}`. \nProvide this inside crystalruby.yaml (run `bundle exec crystalruby init` to generate this file with detaults)" unless config.send(config_key)
+      unless config.send(config_key)
+        raise "Missing config option `#{config_key}`. \nProvide this inside crystalruby.yaml (run `bundle exec crystalruby init` to generate this file with detaults)"
+      end
     end
     FileUtils.mkdir_p "#{config.crystal_src_dir}/generated"
     FileUtils.mkdir_p "#{config.crystal_lib_dir}"
     unless File.exist?("#{config.crystal_src_dir}/#{config.crystal_main_file}")
       IO.write("#{config.crystal_src_dir}/#{config.crystal_main_file}", "require \"./generated/index\"\n")
     end
-    unless File.exist?("#{config.crystal_src_dir}/shard.yml")
-      IO.write("#{config.crystal_src_dir}/shard.yml", <<~CRYSTAL)
+    return if File.exist?("#{config.crystal_src_dir}/shard.yml")
+
+    IO.write("#{config.crystal_src_dir}/shard.yml", <<~CRYSTAL)
       name: src
       version: 0.1.0
-      CRYSTAL
-    end
+    CRYSTAL
   end
 
   def self.instantiated?
@@ -155,13 +147,14 @@ module CrystalRuby
 
   def self.compile!
     return unless @block_store
+
     index_content = <<~CRYSTAL
-    FAKE_ARG = "crystal"
-    fun init(): Void
-      GC.init
-      ptr = FAKE_ARG.to_unsafe
-      LibCrystalMain.__crystal_main(1, pointerof(ptr))
-    end
+      FAKE_ARG = "crystal"
+      fun init(): Void
+        GC.init
+        ptr = FAKE_ARG.to_unsafe
+        LibCrystalMain.__crystal_main(1, pointerof(ptr))
+      end
     CRYSTAL
 
     index_content += @block_store.map do |function|
@@ -175,14 +168,16 @@ module CrystalRuby
     begin
       lib_target = "#{Dir.pwd}/#{config.crystal_lib_dir}/#{config.crystal_lib_name}"
       Dir.chdir(config.crystal_src_dir) do
-        config.debug ?
-          `crystal build -o #{lib_target} #{config.crystal_main_file}` :
+        if config.debug
+          `crystal build -o #{lib_target} #{config.crystal_main_file}`
+        else
           `crystal build --release --no-debug -o #{lib_target} #{config.crystal_main_file}`
+        end
       end
 
       @compiled = true
     rescue StandardError => e
-      puts 'Error compiling crystal code'
+      puts "Error compiling crystal code"
       puts e
       File.delete("#{config.crystal_src_dir}/generated/index.cr")
     end
@@ -198,7 +193,7 @@ module CrystalRuby
   def self.write_function(owner, name:, body:, &compile_callback)
     @compiled = File.exist?("#{config.crystal_src_dir}/generated/index.cr") unless defined?(@compiled)
     @block_store ||= []
-    @block_store << {owner: owner, name: name, body: body, compile_callback: compile_callback}
+    @block_store << { owner: owner, name: name, body: body, compile_callback: compile_callback }
     FileUtils.mkdir_p("#{config.crystal_src_dir}/generated")
     existing = Dir.glob("#{config.crystal_src_dir}/generated/**/*.cr")
     @block_store.each do |function|

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: crystalruby
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Wouter Coppieters
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-07 00:00:00.000000000 Z
+date: 2024-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: ffi
+  name: digest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -25,7 +25,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: digest
+  name: ffi
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -103,7 +103,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 2.7.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="