{"id":21094024,"url":"https://github.com/xord/rucy","last_synced_at":"2026-06-12T03:02:11.671Z","repository":{"id":28744897,"uuid":"32266726","full_name":"xord/rucy","owner":"xord","description":"A Ruby C++ Extension Helper Library","archived":false,"fork":false,"pushed_at":"2026-05-15T18:43:58.000Z","size":144,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-05-15T20:59:31.763Z","etag":null,"topics":["cpp","gem","ruby"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xord.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2015-03-15T15:10:10.000Z","updated_at":"2026-05-15T18:44:02.000Z","dependencies_parsed_at":"2023-11-11T18:29:36.288Z","dependency_job_id":"4105a0c7-9586-454c-a4bf-755f44b56477","html_url":"https://github.com/xord/rucy","commit_stats":null,"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/xord/rucy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xord%2Frucy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xord%2Frucy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xord%2Frucy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xord%2Frucy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xord","download_url":"https://codeload.github.com/xord/rucy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xord%2Frucy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34225409,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","gem","ruby"],"created_at":"2024-11-19T22:15:58.040Z","updated_at":"2026-06-12T03:02:11.661Z","avatar_url":"https://github.com/xord.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rucy - A Ruby C++ extension helper library\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/xord/rucy)\n![License](https://img.shields.io/github/license/xord/rucy)\n![Build Status](https://github.com/xord/rucy/actions/workflows/test.yml/badge.svg)\n![Gem Version](https://badge.fury.io/rb/rucy.svg)\n\n## ⚠️  Notice\n\nThis repository is a read-only mirror of our monorepo.\nWe do not accept pull requests or direct contributions here.\n\n### 🔄 Where to Contribute?\n\nAll development happens in our [xord/all](https://github.com/xord/all) monorepo, which contains all our main libraries.\nIf you'd like to contribute, please submit your changes there.\n\nFor more details, check out our [Contribution Guidelines](./CONTRIBUTING.md).\n\nThanks for your support! 🙌\n\n## 🚀 About\n\n**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.\n\nIt 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.\n\nLike 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.\n\n## 📋 Requirements\n\n- Ruby **3.0.0** or later\n- A C++ compiler with C++20 support\n- [Xot](https://rubygems.org/gems/xot) (declared as a runtime dependency)\n- Rake and test-unit (development only)\n\n## 📦 Installation\n\nAdd this line to your Gemfile:\n```ruby\ngem 'rucy'\n```\n\nThen install:\n```bash\n$ bundle install\n```\n\nOr install it directly:\n```bash\n$ gem install rucy\n```\n\nWhen 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.\n\n## 📚 What's Included\n\n### C++ headers (`include/rucy/`)\n\n| Header        | Provides                                                                                 |\n| ------------- | ---------------------------------------------------------------------------------------- |\n| `rucy.h`      | `Rucy::init()`, the `Rucy` module, and the error class hierarchy                         |\n| `ruby.h`      | A safe `\u003cruby.h\u003e` wrapper plus the `RubyValue` / `RubySymbol` typedefs                   |\n| `value.h`     | `Rucy::Value` — wraps `VALUE` with type predicates, conversions, and method calls        |\n| `module.h`    | `Rucy::Module` — `define_module`, `define_class`, `define_method`, ...                   |\n| `class.h`     | `Rucy::Class` — adds `define_alloc_func` on top of `Module`                              |\n| `function.h`  | `Rucy::call(\"method\", ...)`, `eval`, `protect` — invoke Ruby code with C++ exception safety |\n| `symbol.h`    | `Rucy::Symbol` plus the `RUCY_SYM`, `RUCY_SYM_Q`, `RUCY_SYM_B` macros                    |\n| `exception.h` | `RubyException`, `RubyJumpTag`, and `raise` / `*_error` throw helpers                    |\n| `extension.h` | Method definition macros (`RUCY_DEF0` ... `RUCY_DEFN`) and `VALUE` ↔ native converters   |\n\n### Method definition macros\n\n| Macro                        | Purpose                                                                 |\n| ---------------------------- | ----------------------------------------------------------------------- |\n| `RUCY_DEF0` ... `RUCY_DEF12` | Define a Ruby method that takes 0–12 arguments                          |\n| `RUCY_DEFN`                  | Define a variadic Ruby method (`int argc, const Value* argv`)           |\n| `RUCY_DEF_ALLOC`             | Define an allocator function for a class                                |\n| `RUCY_DEF_END`               | Close a method definition; converts C++ exceptions into Ruby exceptions |\n| `RUCY_TRY` / `RUCY_CATCH`    | Wrap any block of C++ code in Ruby-safe exception translation           |\n\n### Type conversion macros\n\n`RUCY_DECLARE_VALUE_FROM_TO` / `RUCY_DEFINE_VALUE_FROM_TO` (and the `WRAPPER` / `ARRAY` variants) generate `Rucy::value(...)` and `Rucy::value_to\u003cT\u003e(...)` overloads so you can move data between Ruby and a native class with one line of declaration plus one line of definition.\n\n### Ruby side (`lib/rucy/`)\n\n| Module            | Purpose                                                                                         |\n| ----------------- | ----------------------------------------------------------------------------------------------- |\n| `Rucy::Extension` | Path / name / version helpers, mirroring `Xot::Extension` for Rucy-based gems                   |\n| `Rucy::Rake`      | Rake DSL extensions used by `xord/*` gems (`build_native_library`, `build_ruby_extension`, ...) |\n\n### Tools (`bin/`)\n\n| Tool        | Purpose                                                                               |\n| ----------- | ------------------------------------------------------------------------------------- |\n| `rucy2rdoc` | Extract doc comments from C++ files using `RUCY_DEF*` macros into RDoc-friendly stubs |\n\n## 💡 Usage\n\n### A minimal extension\n\n```cpp\n// ext/hello/hello.cpp\n#include \u003crucy/rucy.h\u003e\n#include \u003crucy/extension.h\u003e\n\nusing namespace Rucy;\n\n/*\n  Returns a friendly greeting.\n*/\nRUCY_DEF1(greet, name)\n{\n    return value(Xot::String(\"hello, \") + name.c_str());\n}\nRUCY_DEF_END\n\nextern \"C\" void\nInit_hello ()\n{\n    RUCY_TRY\n\n    Module mHello = define_module(\"Hello\");\n    mHello.define_module_function(\"greet\", greet);\n\n    RUCY_CATCH\n}\n```\n\n```ruby\n# ext/hello/extconf.rb\nrequire 'rucy/extension'\nrequire 'mkmf'\n\n$INCFLAGS \u003c\u003c \" -I#{Xot::Extension.inc_dir} -I#{Rucy::Extension.inc_dir}\"\n$LDFLAGS  \u003c\u003c \" -L#{Xot::Extension.lib_dir} -L#{Rucy::Extension.lib_dir} -lxot -lrucy\"\n\ncreate_makefile 'hello/hello'\n```\n\n```ruby\n# Use it from Ruby\nrequire 'hello/hello'\nHello.greet 'world'   # =\u003e \"hello, world\"\n```\n\n### Exception-safe method bodies\n\nAnything 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:\n\n```cpp\nRUCY_DEF1(divide, n)\n{\n    if (n.as_i() == 0)\n        argument_error(__FILE__, __LINE__, \"divide by zero\");\n    return value(100 / n.as_i());\n}\nRUCY_DEF_END\n```\n\n### Calling Ruby from C++\n\n```cpp\nValue ary = eval(\"[1, 2, 3]\");\nValue n   = ary.call(\"sum\");    // =\u003e Value(6)\n```\n\nFor 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).\n\n## 🛠️ Development\n\n```bash\n$ rake lib    # build the native C++ library (librucy)\n$ rake ext    # build the test extension\n$ rake test   # run the test suite\n$ rake doc    # generate RDoc from C++ sources via rucy2rdoc\n$ rake       # default: builds the extension\n```\n\nSeveral 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.\n\n## 📜 License\n\n**Rucy** is licensed under the MIT License.\nSee the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxord%2Frucy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxord%2Frucy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxord%2Frucy/lists"}