ruby-ladybug 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b1d33c54dd9d7ffa7c488fcbab32b251daf549ca772d3190a19bca475b17c84
+  data.tar.gz: 5c74689b9bbcff42b6c3c2a9bf0e89dbafab675966bf91c1a4326bc2231434c6
+SHA512:
+  metadata.gz: 67f33c1849dbe93cf15b0a6df16a8d232ce27319a570aa7fbbbcad3382fbffe0fee40e71984a9d5df63fa0df238826f2aefcd60e984611ec8d85609019511cb5
+  data.tar.gz: b1e8e192ed387249a6cf5a823caa2a4614ddbc0efbc06ab76de35ff48098b655a132739bda4b30b2f8fc9baab8623696f35b2ad16076eafe773e344574e5e345

data/History.md

@@ -0,0 +1,9 @@
+# Release History for ruby-ladybug
+
+---
+
+## v0.1.0 [2026-03-09] Michael Granger <ged@FaerieMUD.org>
+
+Renamed from "Kuzu" (which acquired and closed by Apple) and adjusted to
+bind against LadybugDB instead.
+

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2025 Michael Granger
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,250 @@
+# ruby-ladybug
+
+home
+: https://sr.ht/~ged/Ruby-Ladybug
+
+code
+: https://hg.sr.ht/~ged/Ruby-Ladybug
+
+github
+: https://github.com/ged/ruby-ladybug
+
+docs
+: https://deveiate.org/code/ruby-ladybug
+
+
+## Description
+
+A Ruby binding for the [LadybugDB](https://ladybugdb.com) embedded graph database.
+
+[![builds.sr.ht status](https://builds.sr.ht/~ged/Ruby-Ladybug.svg)](https://builds.sr.ht/~ged/Ruby-Ladybug?)
+
+
+### Creating A Database and Connecting To It
+
+To create an in-memory database:
+
+    database = Ladybug.database
+    # => #<Ladybug::Database:0x000000012917ec68 path:nil read-only:false>
+
+Or explicitly via an empty string:
+
+    database = Ladybug.database( '' )
+    # => #<Ladybug::Database:0x000000012144edb0 path:nil read-only:false>
+
+If you pass a non-empty string, it is assumed to be the path to a database:
+
+    database = Ladybug.database( 'path/to/mydb' )
+    # => #<Ladybug::Database:0x0000000121624d10 path:"path/to/mydb" read-only:false>
+
+There's also support for passing configuration options to the database
+handle as keyword arguments to the `.database` method:
+
+    database = Ladybug.database( 'mydb', read_only: true )
+    # => #<Ladybug::Database:0x00000001227aa5a8 path:"mydb" read-only:true>
+
+Once you have a Ladybug::Database object, you need a connection to actually use it:
+
+    conn = db.connect
+    # => #<Ladybug::Connection:0x0000000122a41f28 threads:16>
+
+
+### Querying
+
+There are two ways of running queries, immediate execution and via a prepared
+statement. Either method returns one or more results as Ladybug::Result objects.
+
+
+### Results
+
+The each result of a query in a query string is returned as a Ladybug::Result. If
+there are more than one queries in the query string, the Results will be
+chained together so they can be iterated over.
+
+Each tuple in a Result can be fetched using Ladybug::Result#next, which returns a
+Hash of the variables in the `RETURN` clause, keyed by the column name as a
+`String`:
+
+    res = conn.query( 'MATCH (a:User)-[f:Follows]->(b:User) RETURN a.name, b.name, f.since;' )
+    # => #<Ladybug::Result:0x00000001268449d8 success: true (4 tuples of 3 columns)>
+    res.next
+    # => {"a.name" => "Adam", "b.name" => "Karissa", "f.since" => 2020}
+    res.next
+    # => {"a.name" => "Adam", "b.name" => "Zhang", "f.since" => 2020}
+
+The value's type will be determined by the Ladybug datatype of that column of the
+result. See Ladybug::Result for a mapping of the types.
+
+If there are more tuples to fetch, Ladybug::Result#has_next? will return `true`:
+
+    res.has_next?
+    # => true
+    res.next
+    # => {"a.name" => "Karissa", "b.name" => "Zhang", "f.since" => 2021}
+    res.next
+    # => {"a.name" => "Zhang", "b.name" => "Noura", "f.since" => 2022}
+    res.has_next?
+    # => false
+    res.next
+    # => nil
+
+Ladybug::Result is also Enumerable, so you can `#each` over its tuples:
+
+    res.each
+    # => #<Enumerator: ...>
+    res.map do |tuple|
+        "%s has followed %s since %s" % tuple.values_at('a.name', 'b.name', 'f.since')
+    end
+    # => ["Adam has followed Karissa since 2020",
+    #     "Adam has followed Zhang since 2020",
+    #     "Karissa has followed Zhang since 2021",
+    #     "Zhang has followed Noura since 2022"]
+
+If the query string has more than one query in it, a separate Ladybug::Result is
+linked to the previous one, and can be fetched using Ladybug::Result#next_set.
+
+For example:
+
+    res = conn.query( <<~END_OF_QUERY )
+        MATCH (a:User)-[f:Follows]->(b:User)
+        RETURN a.name, b.name, f.since;
+        MATCH (u:User) RETURN *
+    END_OF_QUERY
+    # => #<Ladybug::Result:0x000000011e6faaf8 success: true (4 tuples of 3 columns)>
+    res.to_a
+    # => [{"a.name" => "Adam", "b.name" => "Karissa", "f.since" => 2020},
+    #     {"a.name" => "Adam", "b.name" => "Zhang", "f.since" => 2020},
+    #     {"a.name" => "Karissa", "b.name" => "Zhang", "f.since" => 2021},
+    #     {"a.name" => "Zhang", "b.name" => "Noura", "f.since" => 2022}]
+    res.has_next_set?
+    # => true
+    res2 = res.next_set
+    # => #<Ladybug::Result:0x000000011e338fa0 success: true (4 tuples of 1 columns)>
+    res2.to_a
+    # => [{"u" => #<Ladybug::Node:0x000000011e7553b8 @id=[0, 0], @label="User",
+    #       @properties={name: "Adam", age: 30}>},
+    #     {"u" => #<Ladybug::Node:0x000000011e7551b0 @id=[0, 1], @label="User",
+    #       @properties={name: "Karissa", age: 40}>},
+    #     {"u" => #<Ladybug::Node:0x000000011e755048 @id=[0, 2], @label="User",
+    #       @properties={name: "Zhang", age: 50}>},
+    #     {"u" => #<Ladybug::Node:0x000000011e754ee0 @id=[0, 3], @label="User",
+    #       @properties={name: "Noura", age: 25}>}]
+    res2.has_next_set?
+    # => false
+    res2.next_set
+    # => nil
+
+
+### Prepared Statements
+
+An alternative to using strings to query the database is to used *prepared statements*. These have a number of advantages, such as reusability and using parameters for queries instead of string interpolation.
+
+You can create a Ladybug::PreparedStatement by calling Ladybug::Connection#prepare, then execute it one or more times with parameters using Ladybug::PreparedStatement#execute:
+
+    stmt = conn.prepare( <<~END_OF_QUERY )
+      MATCH (a:User)-[f:Follows]->(b:User)
+      WHERE a.name = $name
+      RETURN a.name, b.name, f.since'
+    END_OF_QUERY
+    # => #<Ladybug::PreparedStatement:0x000000011e919b68>
+    res = stmt.execute( name: "Karissa" )
+    # => #<Ladybug::Result:0x000000011ee8df90 success: true (1 tuples of 3 columns)>
+    res.to_a
+    # => [{"a.name" => "Karissa", "b.name" => "Zhang", "f.since" => 2021}]
+
+
+### Result Memory Management
+
+Because of the way Ruby frees memory when it's shutting down (i.e., the order is indeterminate), Ladybug::Result objects may not be freed immediately when they go out of scope. To provide some way to manage this, the Ladybug::Result#finish call is provided as a way to explicitly destroy the underlying Ladybug data structure so the Result can be freed. Since this is somewhat inconvenient to manage, there are two forms of Ladybug::Connection#query and Ladybug::PreparedStatement#execute, one which returns a Result and a "bang" equivalent one which just returns success or failure. Additionally, passing a block to either method will yield the Result to the block and then immediately `finish` the Result for you and return the block's value.
+
+    query_string = 'MATCH (a:User)-[f:Follows]->(b:User) RETURN a.name, b.name, f.since'
+    conn.query!( query_string )
+    # => true
+    conn.query( query_string ) {|res| res.tuples }
+    # => [{"a.name" => "Adam", "b.name" => "Karissa", "f.since" => 2020},
+    #     {"a.name" => "Adam", "b.name" => "Zhang", "f.since" => 2020},
+    #     {"a.name" => "Karissa", "b.name" => "Zhang", "f.since" => 2021},
+    #     {"a.name" => "Zhang", "b.name" => "Noura", "f.since" => 2022}]
+
+    stmt = conn.prepare( "CREATE (:User {name: $name, age: $age})" )
+    # => #<Ladybug::PreparedStatement:0x000000010bc7cfe8>
+    stmt.execute!( name: 'David', age: 19 )
+    # => true
+    stmt.execute!( name: 'Agnes', age: 28 )
+    # => true
+
+
+## Examples
+
+    require 'Ladybug'
+
+    db = Ladybug.database
+    conn = db.connect
+    conn.run("CREATE NODE TABLE User(name STRING, age INT64, PRIMARY KEY (name))")
+    conn.run("CREATE NODE TABLE City(name STRING, population INT64, PRIMARY KEY (name))")
+    conn.run("CREATE REL TABLE Follows(FROM User TO User, since INT64)")
+    conn.run("CREATE REL TABLE LivesIn(FROM User TO City)")
+
+    # Load data.
+    conn.run("COPY User FROM \"user.csv\"")
+    conn.run("COPY City FROM \"city.csv\"")
+    conn.run("COPY Follows FROM \"follows.csv\"")
+    conn.run("COPY LivesIn FROM \"lives-in.csv\"")
+
+    # Execute a simple query.
+    result = conn.query("MATCH (a:User)-[f:Follows]->(b:User) RETURN a.name, f.since, b.name;")
+
+    # Output query result.
+    result.each do |tuple|
+        name, since, name2 = tuple.values_at( 'a.name', 'f.since', 'b.name' )
+        puts "%s follows %s since %lld", [ name, name2, since ]
+    end
+
+    result.finish
+
+
+## To-Do List
+
+- `UNION` result type.
+- `JSON` result type from the JSON extension
+- Better memory management for Ladybug::Results
+
+
+## Requirements
+
+- Ruby >= 3
+- LadybugDB >= 0.12
+
+
+## Install
+
+    $ gem install ruby-ladybug
+
+
+## Authors
+
+- Michael Granger <ged@FaerieMUD.org>
+
+
+## Copyright
+
+Copyright (c) 2025-2026 Michael Granger
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/ext/ladybug_ext/config.c

@@ -0,0 +1,318 @@
+/*
+ *  config.c - Ladybug::Config class
+ *
+ */
+
+#include "ladybug_ext.h"
+
+#define CHECK_CONFIG(self) ((lbug_system_config*)rb_check_typeddata((self), &rlbug_config_type))
+
+
+VALUE rlbug_cLadybugConfig;
+
+static const rb_data_type_t rlbug_config_type = {
+	.wrap_struct_name = "Ladybug::Config",
+	.function = {},
+	.data = NULL,
+};
+
+
+
+/*
+ * ::allocate function
+ */
+static VALUE
+rlbug_config_s_allocate( VALUE klass )
+{
+	return TypedData_Wrap_Struct( klass, &rlbug_config_type, NULL );
+}
+
+
+lbug_system_config *
+rlbug_get_config( VALUE obj )
+{
+	return CHECK_CONFIG( obj );
+}
+
+
+
+/*
+ * call-seq:
+ *    new()   -> config
+ *
+ * Create a Ladybug::Config with default values.
+ *
+ */
+static VALUE
+rlbug_config_initialize( VALUE self )
+{
+	lbug_system_config *ptr = CHECK_CONFIG( self );
+
+	if ( !ptr ) {
+		ptr = ALLOC( lbug_system_config );
+		lbug_system_config defaults = lbug_default_system_config();
+
+		ptr->buffer_pool_size     = defaults.buffer_pool_size;
+		ptr->max_num_threads      = defaults.max_num_threads;
+		ptr->enable_compression   = defaults.enable_compression;
+		ptr->read_only            = defaults.read_only;
+		ptr->max_db_size          = defaults.max_db_size;
+		ptr->auto_checkpoint      = defaults.auto_checkpoint;
+		ptr->checkpoint_threshold = defaults.checkpoint_threshold;
+
+		RTYPEDDATA_DATA( self ) = ptr;
+	} else {
+		rb_raise( rb_eRuntimeError, "cannot reinit config" );
+	}
+
+	rb_call_super( 0, 0 );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *   config.buffer_pool_size()  -> integer
+ *
+ * Return the buffer_pool_size config value.
+ */
+static VALUE
+rlbug_config_buffer_pool_size( VALUE self )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	return ULONG2NUM( config->buffer_pool_size );
+}
+
+
+/*
+ * call-seq:
+ *   config.max_num_threads()  -> integer
+ *
+ * Return the max_num_threads config value.
+ */
+static VALUE
+rlbug_config_max_num_threads( VALUE self )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	return ULONG2NUM( config->max_num_threads );
+}
+
+
+/*
+ * call-seq:
+ *   config.enable_compression()  -> true or false
+ *
+ * Return the enable_compression config value.
+ */
+static VALUE
+rlbug_config_enable_compression( VALUE self )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	return config->enable_compression ? Qtrue : Qfalse;
+}
+
+
+/*
+ * call-seq:
+ *   config.read_only()  -> true or false
+ *
+ * Return the read_only config value.
+ */
+static VALUE
+rlbug_config_read_only( VALUE self )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	return config->read_only ? Qtrue : Qfalse;
+}
+
+
+/*
+ * call-seq:
+ *   config.max_db_size()  -> integer
+ *
+ * Return the max_db_size config value.
+ */
+static VALUE
+rlbug_config_max_db_size( VALUE self )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	return ULONG2NUM( config->max_db_size );
+}
+
+
+/*
+ * call-seq:
+ *   config.auto_checkpoint()  -> true or false
+ *
+ * Return the auto_checkpoint config value.
+ */
+static VALUE
+rlbug_config_auto_checkpoint( VALUE self )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	return config->auto_checkpoint ? Qtrue : Qfalse;
+}
+
+
+/*
+ * call-seq:
+ *   config.checkpoint_threshold()  -> integer
+ *
+ * Return the checkpoint_threshold config value.
+ */
+static VALUE
+rlbug_config_checkpoint_threshold( VALUE self )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	return ULONG2NUM( config->checkpoint_threshold );
+}
+
+
+/*
+ * call-seq:
+ *   config.buffer_pool_size = integer
+ *
+ * Set the buffer_pool_size config value.
+ */
+static VALUE
+rlbug_config_buffer_pool_size_eq( VALUE self, VALUE value )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	config->buffer_pool_size = NUM2ULONG( value );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *   config.max_num_threads = integer
+ *
+ * Set the max_num_threads config value.
+ */
+static VALUE
+rlbug_config_max_num_threads_eq( VALUE self, VALUE value )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	config->max_num_threads = NUM2ULONG( value );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *   config.enable_compression = true or false
+ *
+ * Set the enable_compression config value.
+ */
+static VALUE
+rlbug_config_enable_compression_eq( VALUE self, VALUE value )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	config->enable_compression = RTEST( value );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *   config.read_only = true or false
+ *
+ * Set the read_only config value.
+ */
+static VALUE
+rlbug_config_read_only_eq( VALUE self, VALUE value )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	config->read_only = RTEST( value );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *   config.max_db_size = integer
+ *
+ * Set the max_db_size config value.
+ */
+static VALUE
+rlbug_config_max_db_size_eq( VALUE self, VALUE value )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	config->max_db_size = NUM2ULONG( value );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *   config.auto_checkpoint = true or false
+ *
+ * Set the auto_checkpoint config value.
+ */
+static VALUE
+rlbug_config_auto_checkpoint_eq( VALUE self, VALUE value )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	config->auto_checkpoint = RTEST( value );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *   config.checkpoint_threshold = integer
+ *
+ * Set the checkpoint_threshold config value.
+ */
+static VALUE
+rlbug_config_checkpoint_threshold_eq( VALUE self, VALUE value )
+{
+	lbug_system_config *config = CHECK_CONFIG( self );
+	config->checkpoint_threshold = NUM2ULONG( value );
+
+	return Qtrue;
+}
+
+
+
+/*
+ * Document-class: Ladybug::Config
+ */
+void
+rlbug_init_config( void )
+{
+#ifdef FOR_RDOC
+	rlbug_mLadybug = rb_define_module( "ladybug" );
+#endif
+
+	rlbug_cLadybugConfig = rb_define_class_under( rlbug_mLadybug, "Config", rb_cObject );
+
+	rb_define_alloc_func( rlbug_cLadybugConfig, rlbug_config_s_allocate );
+
+	rb_define_method( rlbug_cLadybugConfig, "initialize", rlbug_config_initialize, 0 );
+
+	rb_define_method( rlbug_cLadybugConfig, "buffer_pool_size", rlbug_config_buffer_pool_size, 0 );
+	rb_define_method( rlbug_cLadybugConfig, "max_num_threads", rlbug_config_max_num_threads, 0 );
+	rb_define_method( rlbug_cLadybugConfig, "enable_compression", rlbug_config_enable_compression, 0 );
+	rb_define_method( rlbug_cLadybugConfig, "read_only", rlbug_config_read_only, 0 );
+	rb_define_method( rlbug_cLadybugConfig, "max_db_size", rlbug_config_max_db_size, 0 );
+	rb_define_method( rlbug_cLadybugConfig, "auto_checkpoint", rlbug_config_auto_checkpoint, 0 );
+	rb_define_method( rlbug_cLadybugConfig, "checkpoint_threshold", rlbug_config_checkpoint_threshold, 0 );
+
+	rb_define_method( rlbug_cLadybugConfig, "buffer_pool_size=", rlbug_config_buffer_pool_size_eq, 1 );
+	rb_define_method( rlbug_cLadybugConfig, "max_num_threads=", rlbug_config_max_num_threads_eq, 1 );
+	rb_define_method( rlbug_cLadybugConfig, "enable_compression=", rlbug_config_enable_compression_eq, 1 );
+	rb_define_method( rlbug_cLadybugConfig, "read_only=", rlbug_config_read_only_eq, 1 );
+	rb_define_method( rlbug_cLadybugConfig, "max_db_size=", rlbug_config_max_db_size_eq, 1 );
+	rb_define_method( rlbug_cLadybugConfig, "auto_checkpoint=", rlbug_config_auto_checkpoint_eq, 1 );
+	rb_define_method( rlbug_cLadybugConfig, "checkpoint_threshold=", rlbug_config_checkpoint_threshold_eq, 1 );
+
+	rb_require( "ladybug/config" );
+}