rucy 0.3.12 → 0.3.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1729a91940f9162509a18696813859a374ccb82c4af989b4c782e6015e394fa
-  data.tar.gz: 645ee9505dc9178bd1aa77093f44566290e05dac58ca5d20d62193e0d7a5c0d3
+  metadata.gz: e00e91444fff75c3bcce95970122b74ed7b90cfd25fa624c39135e9edd25bc94
+  data.tar.gz: f97ce5707abc53840eb150f0d04914cf017ee806bb9561e4310647c2f933b3ee
 SHA512:
-  metadata.gz: 2995825674988de7587c353785c032f15e974e5074412497b448fd6ac0450d0450dc4a0951b805e80ef58c66d47c92546e88da36127c4cbd0693c768b94e0b57
-  data.tar.gz: b7fbe367adbbcfd7de8dc7176f488a776451dbfb9658ac9c3f6a7b857aa3327cfcf5713f26b9bae709a4a3eb746c124917cb926da8df77ef728fe6701c9c1ba6
+  metadata.gz: b5309d718c81ea92139084d38894b099fb511f9fae0e9da1387740046136e1da8cc054a8ebadbc1353e430ec738264c5bba92c7e9f51ea9f9b7b8701a5b25be3
+  data.tar.gz: fcfd31e82f5c3abb5e13bcf827540fb87a5e32dcafad5f77d4fea15e0285658b6ccd2db2e0170c828e65f1480975c05390b63d93515bc0260f0266acaf892f82

data/.github/workflows/release-gem.yml

@@ -36,23 +36,9 @@ jobs:
           echo path=$(ruby -e 'print Dir.glob("*.gem").first') >> $GITHUB_OUTPUT
 
       - name: create github release
-        id: release
-        uses: actions/create-release@v1
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          tag_name: ${{ github.ref }}
-          release_name: ${{ github.ref }}
-
-      - name: upload to github release
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: ${{ steps.release.outputs.upload_url }}
-          asset_path: ./${{ steps.gem.outputs.path }}
-          asset_name:   ${{ steps.gem.outputs.path }}
-          asset_content_type: application/zip
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: ruby -I.github/workflows -rutils -e 'release(*ARGV)' ./${{ steps.gem.outputs.path }}
 
       - name: upload to rubygems
         env:

data/ChangeLog.md

@@ -1,6 +1,12 @@
 # rucy ChangeLog
 
 
+## [v0.3.13] - 2026-05-17
+
+- Rewrite README.md
+- CI: Migrate release-gem.yml from actions/create-release to gh release create
+
+
 ## [v0.3.12] - 2026-05-10
 
 - Migrate to TypedData API for Ruby 4.x compatibility

data/README.md

@@ -1,4 +1,4 @@
-# Rucy - A Ruby C++ Extension Helper Library
+# Rucy - A Ruby C++ extension helper library
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/xord/rucy)
 ![License](https://img.shields.io/github/license/xord/rucy)
@@ -21,19 +21,27 @@ Thanks for your support! 🙌
 
 ## 🚀 About
 
-**Rucy** helps you to develop Ruby C extension library with few useful classes.
+**Rucy** is a thin C++ layer on top of Ruby's C API. It reduces the boilerplate involved in writing a Ruby extension in C++ by wrapping `VALUE`, providing exception-safe method definitions, and converting between native types and Ruby values.
 
-* Wrap VALUE for easy handling.
-* Exception safe (Rucy/C++).
+It is used by the native extensions in the `xord/*` family — [Beeps](https://github.com/xord/beeps), [Rays](https://github.com/xord/rays), and [Reflex](https://github.com/xord/reflex). It depends on [Xot](https://github.com/xord/xot) for low-level utilities such as reference counting, the pimpl idiom, and the string / exception classes.
+
+Like Xot, Rucy exists primarily for our own gems. The API is stable enough for us to build on, but it is not a general-purpose extension framework — feel free to read it and learn from it, but pin a specific version if you depend on it directly.
+
+## 📋 Requirements
+
+- Ruby **3.0.0** or later
+- A C++ compiler with C++20 support
+- [Xot](https://rubygems.org/gems/xot) (declared as a runtime dependency)
+- Rake and test-unit (development only)
 
 ## 📦 Installation
 
 Add this line to your Gemfile:
 ```ruby
-$ gem 'rucy'
+gem 'rucy'
 ```
 
-Then, install gem:
+Then install:
 ```bash
 $ bundle install
 ```
@@ -43,11 +51,134 @@ Or install it directly:
 $ gem install rucy
 ```
 
-And then, write C++ source like ext/rucy/tester.cpp.
+When linking against Rucy from your own extension, point `extconf.rb` at the gem's `include/` and `lib/` directories — `Rucy::Extension.inc_dir` and `Rucy::Extension.lib_dir` return the right paths.
+
+## 📚 What's Included
+
+### C++ headers (`include/rucy/`)
+
+| Header        | Provides                                                                                 |
+| ------------- | ---------------------------------------------------------------------------------------- |
+| `rucy.h`      | `Rucy::init()`, the `Rucy` module, and the error class hierarchy                         |
+| `ruby.h`      | A safe `<ruby.h>` wrapper plus the `RubyValue` / `RubySymbol` typedefs                   |
+| `value.h`     | `Rucy::Value` — wraps `VALUE` with type predicates, conversions, and method calls        |
+| `module.h`    | `Rucy::Module` — `define_module`, `define_class`, `define_method`, ...                   |
+| `class.h`     | `Rucy::Class` — adds `define_alloc_func` on top of `Module`                              |
+| `function.h`  | `Rucy::call("method", ...)`, `eval`, `protect` — invoke Ruby code with C++ exception safety |
+| `symbol.h`    | `Rucy::Symbol` plus the `RUCY_SYM`, `RUCY_SYM_Q`, `RUCY_SYM_B` macros                    |
+| `exception.h` | `RubyException`, `RubyJumpTag`, and `raise` / `*_error` throw helpers                    |
+| `extension.h` | Method definition macros (`RUCY_DEF0` ... `RUCY_DEFN`) and `VALUE` ↔ native converters   |
+
+### Method definition macros
+
+| Macro                        | Purpose                                                                 |
+| ---------------------------- | ----------------------------------------------------------------------- |
+| `RUCY_DEF0` ... `RUCY_DEF12` | Define a Ruby method that takes 0–12 arguments                          |
+| `RUCY_DEFN`                  | Define a variadic Ruby method (`int argc, const Value* argv`)           |
+| `RUCY_DEF_ALLOC`             | Define an allocator function for a class                                |
+| `RUCY_DEF_END`               | Close a method definition; converts C++ exceptions into Ruby exceptions |
+| `RUCY_TRY` / `RUCY_CATCH`    | Wrap any block of C++ code in Ruby-safe exception translation           |
+
+### Type conversion macros
+
+`RUCY_DECLARE_VALUE_FROM_TO` / `RUCY_DEFINE_VALUE_FROM_TO` (and the `WRAPPER` / `ARRAY` variants) generate `Rucy::value(...)` and `Rucy::value_to<T>(...)` overloads so you can move data between Ruby and a native class with one line of declaration plus one line of definition.
+
+### Ruby side (`lib/rucy/`)
+
+| Module            | Purpose                                                                                         |
+| ----------------- | ----------------------------------------------------------------------------------------------- |
+| `Rucy::Extension` | Path / name / version helpers, mirroring `Xot::Extension` for Rucy-based gems                   |
+| `Rucy::Rake`      | Rake DSL extensions used by `xord/*` gems (`build_native_library`, `build_ruby_extension`, ...) |
+
+### Tools (`bin/`)
+
+| Tool        | Purpose                                                                               |
+| ----------- | ------------------------------------------------------------------------------------- |
+| `rucy2rdoc` | Extract doc comments from C++ files using `RUCY_DEF*` macros into RDoc-friendly stubs |
+
+## 💡 Usage
+
+### A minimal extension
+
+```cpp
+// ext/hello/hello.cpp
+#include <rucy/rucy.h>
+#include <rucy/extension.h>
+
+using namespace Rucy;
+
+/*
+  Returns a friendly greeting.
+*/
+RUCY_DEF1(greet, name)
+{
+    return value(Xot::String("hello, ") + name.c_str());
+}
+RUCY_DEF_END
+
+extern "C" void
+Init_hello ()
+{
+    RUCY_TRY
+
+    Module mHello = define_module("Hello");
+    mHello.define_module_function("greet", greet);
+
+    RUCY_CATCH
+}
+```
+
+```ruby
+# ext/hello/extconf.rb
+require 'rucy/extension'
+require 'mkmf'
+
+$INCFLAGS << " -I#{Xot::Extension.inc_dir} -I#{Rucy::Extension.inc_dir}"
+$LDFLAGS  << " -L#{Xot::Extension.lib_dir} -L#{Rucy::Extension.lib_dir} -lxot -lrucy"
+
+create_makefile 'hello/hello'
+```
+
+```ruby
+# Use it from Ruby
+require 'hello/hello'
+Hello.greet 'world'   # => "hello, world"
+```
+
+### Exception-safe method bodies
 
-## 💡 Examples
+Anything you throw inside a `RUCY_DEF*` body — `Rucy::RubyException`, `std::exception`, `Xot::XotError`, or even a `const char*` — is caught by `RUCY_DEF_END` and re-raised as the corresponding Ruby exception. You can also raise directly:
+
+```cpp
+RUCY_DEF1(divide, n)
+{
+    if (n.as_i() == 0)
+        argument_error(__FILE__, __LINE__, "divide by zero");
+    return value(100 / n.as_i());
+}
+RUCY_DEF_END
+```
+
+### Calling Ruby from C++
+
+```cpp
+Value ary = eval("[1, 2, 3]");
+Value n   = ary.call("sum");    // => Value(6)
+```
+
+For more examples, see `ext/rucy/tester.cpp` (used by the test suite) and the native extensions in [Beeps](https://github.com/xord/beeps), [Rays](https://github.com/xord/rays), and [Reflex](https://github.com/xord/reflex).
+
+## 🛠️ Development
+
+```bash
+$ rake lib    # build the native C++ library (librucy)
+$ rake ext    # build the test extension
+$ rake test   # run the test suite
+$ rake doc    # generate RDoc from C++ sources via rucy2rdoc
+$ rake       # default: builds the extension
+```
 
-See ext/rucy/tester.cpp.
+Several headers and sources are ERB templates (`*.erb`) expanded automatically at build time. `NPARAM_MAX = 12` in the Rakefile auto-generates `RUCY_DEF0` ... `RUCY_DEF12` and the matching overloads of `call`, `protect`, and friends.
 
 ## 📜 License
 

data/VERSION

@@ -1 +1 @@
-0.3.12
+0.3.13

data/rucy.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |s|
   s.platform              = Gem::Platform::RUBY
   s.required_ruby_version = '>= 3.0.0'
 
-  s.add_dependency 'xot', '~> 0.3.12'
+  s.add_dependency 'xot', '~> 0.3.13'
 
   s.files            = `git ls-files`.split $/
   s.executables      = s.files.grep(%r{^bin/}) {|f| File.basename f}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rucy
 version: !ruby/object:Gem::Version
-  version: 0.3.12
+  version: 0.3.13
 platform: ruby
 authors:
 - xordog
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-09 00:00:00.000000000 Z
+date: 2026-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: xot
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.12
+        version: 0.3.13
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.12
+        version: 0.3.13
 description: This library helps you to develop Ruby Extension by C++.
 email: xordog@gmail.com
 executables: