xot 0.3.12 → 0.3.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95e3e82cc5f95bba59970fbe97e36e28e4f2a454e4cd4e1faf0ecf4ef1937be7
-  data.tar.gz: 84f576eaa74fbd89e6f029a31ab1fdccf3b59fc64ce4d574191051d445736047
+  metadata.gz: 9b42a573c90d9544aae23f3fe0768c88205bea55ca9279b68e794fd6067d7671
+  data.tar.gz: 4f3c4072b4c446d4b2afa46226df1f8e2101717951f274913b4a2ed81ae8dc39
 SHA512:
-  metadata.gz: ade52d927ea1a92a9a63dfa73ad98caf2868415accf4b0691328eced45aefe7bda9e9beead0ea3cf0329316f46635c7e7af1330b9a3fd2402bec2da8c05fb6a6
-  data.tar.gz: 783a40a3f5dfc1b4ce49eb578713ea74c0e1d7062b6b784914f208c1b02f20bbd89531c9ec965b1bebe194e587bbdc5d0da6c6b53606c8b5421d025e60a49c01
+  metadata.gz: 0c98011d4d8e0b8a8f31365af23d52ce1f170abacd1edbc8b704cbf098da6e4f174f41e24a54d819e7816499fd801c9a09ef33283cefaad127e443fff9cacb0c
+  data.tar.gz: 1c73c446d67a45360c08b4db4f6de67a5330d1d320f4cc8fd5badf5f1758391b35dbbb2d74e49c529dacbf3c876c438e787153827630f3c6e29b5da409383eb0

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 @@
 # xot 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
 
 - Add hint_memory_usage callback for external memory GC integration

data/README.md

@@ -1,4 +1,4 @@
-# Xot - Some useful utility classes and functions
+# Xot - Shared utility classes and functions for C++ and Ruby
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/xord/xot)
 ![License](https://img.shields.io/github/license/xord/xot)
@@ -21,20 +21,29 @@ Thanks for your support! 🙌
 
 ## 🚀 About
 
-**Xot** is a small utility library that was extracted for internal use to provide basic helper classes and functions across our own Ruby gems.
+**Xot** is the foundational utility layer used by every other library in the `xord/*` family — Rucy, Beeps, Rays, Reflex, Processing, RubySketch, and Reight.
 
-It’s not intended for general public use, but rather serves as a simple collection of utilities to make our own development process more efficient and consistent.
+It is split into two layers that ship in a single gem:
 
-Feel free to explore, but please note that it’s not actively maintained or intended for broad adoption.
+- **C++ headers and library** (`include/xot/`, `src/`) — building blocks such as reference counting, the pimpl idiom, non-copyable base, plus thin wrappers for strings, time, exceptions, and debug output. These are linked into the native extensions of the other `xord/*` gems.
+- **Ruby helpers** (`lib/xot/`) — small meta-programming mixins (`Hookable`, `Inspectable`, accessor builders, ...), bit-flag utilities, and shared Rake / test scaffolding used by our gems.
+
+Xot exists primarily to keep these patterns consistent across our own projects. It is not designed as a general-purpose dependency, and its API is not promised to be stable for outside use. You are welcome to read 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 (Clang on macOS / iOS, GCC or MSVC on Linux / Windows)
+- [Rake](https://rubygems.org/gems/rake) and [test-unit](https://rubygems.org/gems/test-unit) (development only)
 
 ## 📦 Installation
 
 Add this line to your Gemfile:
 ```ruby
-$ gem 'xot'
+gem 'xot'
 ```
 
-Then, install gem:
+Then install:
 ```bash
 $ bundle install
 ```
@@ -44,6 +53,145 @@ Or install it directly:
 $ gem install xot
 ```
 
+When installed via `gem install`, the C++ headers under `include/xot/` are placed inside the gem directory so that other `xord/*` extensions can locate them at build time (via `Xot::Extension.inc_dir`).
+
+## 📚 What's Included
+
+### C++ headers (`include/xot/`)
+
+| Header           | Provides                                                                 |
+| ---------------- | ------------------------------------------------------------------------ |
+| `defs.h`         | Type aliases (`uint`, `ushort`, `ulong`, `schar`, `longlong`, ...)       |
+| `noncopyable.h`  | `Xot::NonCopyable` — base class that disables copy and assignment        |
+| `ref.h`          | `Xot::RefCountable<>` and `Xot::Ref<T>` — intrusive reference counting   |
+| `pimpl.h`        | `Xot::PImpl<T>` / `Xot::PSharedImpl<T>` — pimpl idiom on top of smart ptrs |
+| `string.h`       | `Xot::String` (extends `std::string`), `stringf`, `split`, `to_s`         |
+| `time.h`         | `Xot::time()` (seconds since epoch, double), `Xot::sleep(seconds)`        |
+| `exception.h`    | `XotError` hierarchy and `xot_error` / `argument_error` / ... throw helpers |
+| `debug.h`        | `Xot::dout` / `doutln` — printf-style debug output (no-op in release)     |
+| `util.h`         | Bit / flag helpers, `random`, `deg2rad`, `rad2deg`, memory-usage hints   |
+| `windows.h`      | Win32 helpers used by other libraries                                    |
+
+### Ruby modules (`lib/xot/`)
+
+| Module / class              | Purpose                                                                 |
+| --------------------------- | ----------------------------------------------------------------------- |
+| `Xot::Hookable`             | Attach `on_*` hook methods, or `before` / `after` wrappers around an existing method, on a single object |
+| `Xot::Inspectable`          | Compact default `inspect` (class + object_id only) — safe under circular references |
+| `Xot::BitFlag`              | Build symbolic bit-flag sets and convert between symbols and bitmasks   |
+| `Xot::BitFlagAccessor`      | Class-level accessor generator backed by a `BitFlag`                    |
+| `Xot::BitUtil`              | Bit manipulation helpers (`bit(n)`, etc.)                               |
+| `Xot::BlockUtil`            | `instance_eval`-or-block-call dispatching                               |
+| `Xot::ConstSymbolAccessor`  | Define accessors that translate symbols to module constants             |
+| `Xot::UniversalAccessor`    | Single-method getter / setter (`obj.x` reads, `obj.x value` writes)     |
+| `Xot::Setter`               | Bulk attribute setter mixin                                             |
+| `Xot::Invoker`              | Helper for invoking methods / blocks safely                             |
+| `Xot::Util`                 | Misc Ruby utilities                                                     |
+| `Xot::Extension`            | Path / name / version helpers used by every `xord/*` gem's build script |
+| `Xot::Rake`                 | Rake DSL (`default_tasks`, `build_native_library`, `build_ruby_extension`, `test_ruby_extension`, `build_ruby_gem`, ...) |
+| `Xot::Test`                 | Test-unit helpers                                                       |
+
+## 💡 Usage
+
+### C++ — reference counting
+
+```cpp
+#include <xot/ref.h>
+
+class Thing : public Xot::RefCountable<>
+{
+    protected:
+        ~Thing () = default;   // destructor is protected; Ref<> handles deletion
+};
+
+Xot::Ref<Thing> a = new Thing;   // refcount = 1
+{
+    Xot::Ref<Thing> b = a;       // refcount = 2
+}                                // refcount = 1
+// when `a` goes out of scope, refcount = 0 and the object is deleted
+```
+
+### C++ — pimpl
+
+```cpp
+#include <xot/pimpl.h>
+
+// in the header
+class Widget
+{
+    public:
+        Widget ();
+        int value () const;
+    private:
+        struct Data;
+        Xot::PImpl<Data> self;
+};
+
+// in the .cpp
+struct Widget::Data { int n = 42; };
+Widget::Widget () {}
+int Widget::value () const { return self->n; }
+```
+
+### Ruby — `BitFlag`
+
+```ruby
+require 'xot/bit_flag'
+
+flags = Xot::BitFlag.new(read: 0x1, write: 0x2, exec: 0x4)
+mask  = flags.symbols2bits(:read, :exec)   # => 5
+flags.bits2symbols(mask)                   # => [:read, :exec]
+```
+
+### Ruby — `Hookable`
+
+```ruby
+require 'xot/hookable'
+
+class Greeter
+  include Xot::Hookable
+  def greet(name) = "hello, #{name}"
+end
+
+g = Greeter.new
+g.before(:greet) {|name| puts "about to greet #{name}" }
+g.greet 'world'
+# => about to greet world
+# => "hello, world"
+
+# `on` creates a brand-new on_* method instead of wrapping an existing one
+g.on(:click) {|x, y| puts "clicked at #{x}, #{y}" }
+g.on_click 1, 2
+```
+
+### Ruby — `UniversalAccessor`
+
+```ruby
+require 'xot/universal_accessor'
+
+class Box
+  attr_accessor :width
+  universal_accessor :width
+end
+
+box = Box.new
+box.width 10    # writes
+box.width       # => 10 (reads)
+```
+
+## 🛠️ Development
+
+Xot uses a shared Rakefile pattern. From the gem root:
+
+```bash
+$ rake lib    # build the native C++ library (libxot)
+$ rake ext    # build the Ruby C extension
+$ rake test   # run the test suite (test/test_*.rb)
+$ rake       # default: builds the extension
+```
+
+In the [`xord/all`](https://github.com/xord/all) monorepo you can also scope by module, e.g. `rake xot test`.
+
 ## 📜 License
 
 **Xot** is licensed under the MIT License.

data/VERSION

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xot
 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: []
 description: This library include some useful utility classes and functions for development
   with C++.