rubyduino 0.1.1

data/vendor/spinel/benchmark/bm_tak.rb

@@ -0,0 +1,10 @@
+def tak(x, y, z)
+  if y < x
+    tak(tak(x - 1, y, z), tak(y - 1, z, x), tak(z - 1, x, y))
+  else
+    z
+  end
+end
+
+puts tak(18, 9, 0)
+puts "done"

data/vendor/spinel/benchmark/bm_tarai.rb

@@ -0,0 +1,10 @@
+def tarai(x, y, z)
+  if x <= y
+    y
+  else
+    tarai(tarai(x - 1, y, z), tarai(y - 1, z, x), tarai(z - 1, x, y))
+  end
+end
+
+puts tarai(12, 6, 0)
+puts "done"

data/vendor/spinel/benchmark/bm_template.rb

@@ -0,0 +1,50 @@
+# Simple template engine
+# Replaces {{key}} with values from a hash
+
+def render(template, vars)
+  result = ""
+  i = 0
+  while i < template.length
+    if i + 1 < template.length && template[i] == "{" && template[i + 1] == "{"
+      # Find closing }}
+      j = i + 2
+      while j + 1 < template.length
+        if template[j] == "}" && template[j + 1] == "}"
+          break
+        end
+        j = j + 1
+      end
+      key = template[i + 2, j - i - 2]
+      if vars.has_key?(key)
+        result = result + vars[key]
+      else
+        result = result + "{{" + key + "}}"
+      end
+      i = j + 2
+    else
+      result = result + template[i]
+      i = i + 1
+    end
+  end
+  result
+end
+
+# Test
+tmpl = "Hello {{name}}! You are {{age}} years old. Welcome to {{city}}."
+vars = {"name" => "Matz", "age" => "58", "city" => "Matsue"}
+puts render(tmpl, vars)
+
+tmpl2 = "{{greeting}} {{name}}, {{message}}"
+vars2 = {"greeting" => "Hi", "name" => "World", "message" => "how are you?"}
+puts render(tmpl2, vars2)
+
+# Missing key
+puts render("{{known}} and {{unknown}}", {"known" => "yes"})
+
+# Benchmark
+i = 0
+while i < 50000
+  render(tmpl, vars)
+  i = i + 1
+end
+puts "done"

data/vendor/spinel/benchmark/bm_throw.rb

@@ -0,0 +1,25 @@
+def foo
+  yield
+end
+
+def bar
+  foo { return 1 }
+end
+
+total = 0
+i = 0
+while i < 200000
+  total = total + bar
+  total = total + bar
+  total = total + bar
+  total = total + bar
+  total = total + bar
+  total = total + bar
+  total = total + bar
+  total = total + bar
+  total = total + bar
+  total = total + bar
+  i = i + 1
+end
+puts total
+puts "done"

data/vendor/spinel/benchmark/bm_wordfreq.rb

@@ -0,0 +1,43 @@
+# Word frequency counter using str_int_hash
+# Tests Hash, String, Array operations
+
+def gen_words(n)
+  words = ["the", "of", "and", "to", "in", "a", "is", "that", "for", "it",
+           "was", "on", "are", "be", "with", "as", "at", "by", "this", "from"]
+  result = []
+  seed = 42
+  i = 0
+  while i < n
+    seed = (seed * 1103515245 + 12345) % 2147483648
+    idx = seed / 107374182
+    result.push(words[idx])
+    i = i + 1
+  end
+  result
+end
+
+n = Integer(ARGV[0] || 10000)
+words = gen_words(n)
+
+freq = {}
+i = 0
+while i < words.length
+  w = words[i]
+  if freq.key?(w)
+    freq[w] = freq[w] + 1
+  else
+    freq[w] = 1
+  end
+  i = i + 1
+end
+
+# Sum all counts
+keys = freq.keys
+total = 0
+i = 0
+while i < keys.length
+  total = total + freq[keys[i]]
+  i = i + 1
+end
+puts total
+puts keys.length

data/vendor/spinel/docs/FFI.md

@@ -0,0 +1,198 @@
+# Spinel FFI
+
+Call C functions from Spinel Ruby programs. No extension compiler, no
+`require "ffi"`: declarations go straight into the source and the AOT
+compiler generates direct C call sites with the right externs and
+linker flags.
+
+## Example
+
+```ruby
+module LibC
+  ffi_func :strlen, [:str], :size_t
+  ffi_func :getpid, [],     :int
+end
+
+puts LibC.strlen("hello, world")   # 12
+puts LibC.getpid
+```
+
+Compile and run:
+
+```sh
+./spinel prog.rb && ./prog
+```
+
+`libc` and `libm` are always linked; anything else needs `ffi_lib`.
+
+## DSL reference
+
+All FFI declarations go inside a `module` body. The module name becomes
+the namespace for the functions (`RAY.InitWindow`, `LibC.strlen`, …).
+
+### `ffi_lib "name"`
+
+Declares that this module needs `-lname` on the link command line. May
+appear multiple times per module.
+
+```ruby
+module SQL
+  ffi_lib "sqlite3"
+end
+```
+
+### `ffi_cflags "..."`
+
+Declares cflags (include dirs, defines, link-search paths) needed for
+this module's externs. Rarely needed — externs use standard C types
+only, so headers don't have to be included in the generated code — but
+useful when a library is installed somewhere non-standard.
+
+```ruby
+ffi_cflags "-I/usr/local/include"
+ffi_cflags "-Wl,-rpath,/usr/local/lib"
+```
+
+### `ffi_func :name, [arg_types], ret_type`
+
+Declares a C function callable as `Module.name(...)`.
+
+```ruby
+ffi_func :sqlite3_open,        [:str, :ptr],                   :int
+ffi_func :sqlite3_close,       [:ptr],                         :int
+ffi_func :sqlite3_exec,        [:ptr, :str, :ptr, :ptr, :ptr], :int
+ffi_func :sqlite3_errmsg,      [:ptr],                         :str
+```
+
+Recognized type specs:
+
+| spec | C type | Spinel type |
+|---|---|---|
+| `:int` | `int` | `int` |
+| `:uint32` | `uint32_t` | `int` |
+| `:int32` | `int32_t` | `int` |
+| `:uint16` | `uint16_t` | `int` |
+| `:int16` | `int16_t` | `int` |
+| `:uint8` | `uint8_t` | `int` |
+| `:int8` | `int8_t` | `int` |
+| `:size_t` | `size_t` | `int` |
+| `:long` | `long` | `int` |
+| `:float` | `float` | `float` |
+| `:double` | `double` | `float` |
+| `:bool` | `int` | `bool` |
+| `:str` | `const char *` | `string` |
+| `:ptr` | `void *` | `ptr` |
+| `:void` | `void` | `void` (return only) |
+
+All integer types collapse to `mrb_int` (int64) inside Spinel and are
+cast to the declared C type at the call boundary. Floats collapse to
+`double` the same way.
+
+### `ffi_const :NAME, <int>`
+
+Declares an integer constant accessible as `Module::NAME`. Pure
+convenience — the value is inlined at use sites like any other Ruby
+integer constant.
+
+```ruby
+ffi_const :SQLITE_OK,   0
+ffi_const :SQLITE_ROW,  100
+ffi_const :SQLITE_DONE, 101
+```
+
+### `ffi_buffer :name, <size>`
+
+Declares a static `size`-byte buffer, accessible as `Module.name`
+returning a `:ptr`. Useful as scratch space or as an out-parameter for
+functions like sqlite3's `sqlite3_open`, which writes the database
+handle into a caller-supplied `sqlite3 **`.
+
+```ruby
+ffi_buffer :db_out, 8
+SQL.sqlite3_open(":memory:", SQL.db_out)
+db = SQL.read_ptr(SQL.db_out)  # the actual sqlite3 *
+```
+
+Lifetime: static. The buffer lives for the whole program.
+
+### `ffi_read_u32 :name, <offset>` / `ffi_read_i32` / `ffi_read_ptr`
+
+Declares a field reader: `Module.name(buf)` returns the value at
+`offset` bytes into `buf`. Handy for poking into C structs when you
+only need a few fields, or for reading back what a C function wrote
+into a buffer you handed it.
+
+```ruby
+# sqlite3_open(path, ppDb) writes the new db handle into *ppDb.
+# Pull the pointer out of our scratch buffer at offset 0.
+ffi_read_ptr :read_ptr, 0
+
+db = SQL.read_ptr(SQL.db_out)
+```
+
+No `ffi_write_*` in the MVP — the assumption is that a C function is
+the one writing into the buffer; Ruby just reads back.
+
+## Pointer semantics
+
+`:ptr` maps to C `void *`. Values of this type are **not GC-tracked**:
+the Spinel garbage collector never follows them and never frees them.
+Foreign memory is the user's responsibility.
+
+Two consequences worth knowing:
+
+1. **Call destroy functions explicitly.** Nothing calls `sqlite3_close`,
+   `sqlite3_finalize`, or `free()` for you.
+2. **Strings passed into C are only valid for the duration of the
+   call.** Spinel strings are GC-managed; if a C function stashes the
+   pointer somewhere and the string becomes unreachable afterward, a
+   later GC cycle will free it out from under the C code. If you need
+   a string to outlive the call, copy it into an `ffi_buffer` first.
+
+`ptr` values compare equal to `nil` when the pointer is NULL:
+
+```ruby
+db = SQL.read_ptr(SQL.db_out)
+if db == nil
+  puts "could not open database"
+end
+```
+
+## Link-flag plumbing
+
+The codegen emits marker comments into the generated C:
+
+```c
+/* SPINEL_LINK: -lsqlite3 */
+/* SPINEL_CFLAGS: -I/usr/local/include */
+```
+
+The `spinel` wrapper script scrapes these with `sed` and appends them
+to the `cc` invocation. If you want to override (e.g. static linking or
+a custom lib path), use `-c` to stop at C and drive the linker yourself.
+
+## Limitations
+
+The MVP covers scalars, strings, opaque pointers, integer constants,
+raw byte buffers, and simple struct-field reads. Not supported yet:
+
+- **No struct declarations.** Use `ffi_buffer` + `ffi_read_*` for the
+  handful of fields you need.
+- **No callbacks / Ruby-to-C function pointers.**
+- **No variadic C functions** (`printf(...)`). Use Spinel's built-in
+  `printf` if you want formatted output.
+- **No `ffi_write_*`** — can't write struct fields from Ruby. Pass a
+  buffer to a C function that writes it for you.
+- **Pointers can't enter polymorphic values.** Don't put a `:ptr` into
+  a `poly_array` or a generic `Hash`; keep them as plain locals or
+  wrap them in a class with a `ptr`-typed ivar.
+
+## Examples
+
+Runnable examples live under `examples/ffi/`:
+
+- `examples/ffi/libm/`     — libc / libm smoke (cos, sqrt, pow, strlen, getpid)
+- `examples/ffi/sqlite/`   — blog system (posts, tags, comments) on sqlite3
+
+Each subdirectory has a `README.md` with build instructions and the
+required system packages.

data/vendor/spinel/examples/ffi/libm/README.md

@@ -0,0 +1,24 @@
+# libc / libm FFI demo
+
+Calls a handful of libc and libm functions directly. libc and libm are
+linked into every Spinel binary by default, so no `ffi_lib` declaration
+is needed for these.
+
+## Build & run
+
+From the repo root:
+
+```sh
+./spinel examples/ffi/libm/libm.rb
+./libm
+```
+
+Expected output:
+
+```
+1
+4
+1024
+12
+pid > 0: true
+```

data/vendor/spinel/examples/ffi/libm/libm.rb

@@ -0,0 +1,17 @@
+module LibM
+  ffi_func :cos,  [:double], :double
+  ffi_func :sin,  [:double], :double
+  ffi_func :sqrt, [:double], :double
+  ffi_func :pow,  [:double, :double], :double
+end
+
+module LibC
+  ffi_func :strlen, [:str], :size_t
+  ffi_func :getpid, [],     :int
+end
+
+puts LibM.cos(0.0).to_i
+puts LibM.sqrt(16.0).to_i
+puts LibM.pow(2.0, 10.0).to_i
+puts LibC.strlen("hello, world")
+puts "pid > 0: " + (LibC.getpid > 0).to_s

data/vendor/spinel/examples/ffi/sqlite/README.md

@@ -0,0 +1,73 @@
+# SQLite3 FFI demo — toy blog
+
+A self-contained blog (posts, tags, comments) running on top of
+SQLite3 via Spinel's FFI. Demonstrates:
+
+- Open / close a database
+- DDL via `sqlite3_exec`
+- INSERT with `last_insert_rowid` follow-up
+- Many-to-many joins (post_tags)
+- SELECT with `prepare_v2` / `step` / `finalize` and `column_int` /
+  `column_text`
+- `:ptr` out-params (`sqlite3 **`, `sqlite3_stmt **`) read back via
+  `ffi_buffer` + `ffi_read_ptr`
+
+## Setup
+
+You need SQLite3 development headers and a linker stub:
+
+```sh
+# Debian / Ubuntu / WSL
+sudo apt install libsqlite3-dev
+
+# Fedora
+sudo dnf install sqlite-devel
+
+# macOS (Homebrew)
+brew install sqlite
+```
+
+Spinel's `ffi_lib "sqlite3"` becomes `-lsqlite3` at link time, so the
+runtime library (`libsqlite3.so`/`.dylib`) needs to be on the loader's
+search path.
+
+## Build & run
+
+From the repo root:
+
+```sh
+./spinel examples/ffi/sqlite/blog.rb
+./blog
+```
+
+Expected output:
+
+```
+Posts (with comment + tag counts):
+  [1] Spinel learns to call C  (2 comments, 3 tags)
+  [2] Tasting o'tea  (1 comments, 2 tags)
+  [3] Hashes vs SymIntHash  (1 comments, 2 tags)
+
+Posts tagged 'spinel':
+  - Spinel learns to call C
+  - Hashes vs SymIntHash
+
+Comments on the FFI post:
+  alice: Wonderful — does it work with libcurl too?
+  bob: I tried sqlite3 myself; the bindings are tidy.
+```
+
+## Files
+
+- `sqlite3_lib.rb` — minimal FFI bindings + a `Sql.q` helper that
+  escapes single quotes for inline string literals.
+- `blog.rb` — the demo program.
+
+## Notes
+
+The demo uses inline-quoted SQL with `Sql.q` for escaping, not bound
+parameters. The reason: `sqlite3_bind_text`'s last argument is a
+destructor callback (the `SQLITE_TRANSIENT` sentinel is `(void *)-1`),
+and the MVP FFI can't yet construct a `:ptr` from a sentinel integer.
+For real applications you'd write a tiny C helper that wraps `bind_text`
+with `SQLITE_TRANSIENT` baked in and link it alongside.

data/vendor/spinel/examples/ffi/sqlite/blog.rb

@@ -0,0 +1,185 @@
+require_relative "sqlite3_lib"
+
+# A toy blog: posts, tags (many-to-many), comments. Demonstrates
+# create / insert / select with a few joins on top of the bare-metal
+# Spinel SQLite FFI bindings.
+
+class Blog
+  def initialize(path)
+    rc = SQL.sqlite3_open(path, SQL.db_out)
+    if rc != SQL::OK
+      puts "sqlite3_open failed: " + rc.to_s
+      exit(1)
+    end
+    @db = SQL.read_ptr(SQL.db_out)
+  end
+
+  def close
+    SQL.sqlite3_close(@db)
+    @db = nil
+  end
+
+  # Run a statement that returns no rows (DDL, INSERT/UPDATE/DELETE).
+  def exec(sql)
+    rc = SQL.sqlite3_exec(@db, sql, nil, nil, nil)
+    if rc != SQL::OK
+      puts "exec failed (" + rc.to_s + "): " + SQL.sqlite3_errmsg(@db)
+      puts "  sql: " + sql
+      exit(1)
+    end
+  end
+
+  def last_id
+    SQL.sqlite3_last_insert_rowid(@db)
+  end
+
+  # Prepare and step through a SELECT, returning the resulting stmt
+  # pointer. Caller is responsible for finalizing.
+  def prepare(sql)
+    rc = SQL.sqlite3_prepare_v2(@db, sql, -1, SQL.stmt_out, nil)
+    if rc != SQL::OK
+      puts "prepare failed (" + rc.to_s + "): " + SQL.sqlite3_errmsg(@db)
+      puts "  sql: " + sql
+      exit(1)
+    end
+    SQL.read_ptr(SQL.stmt_out)
+  end
+
+  def db
+    @db
+  end
+end
+
+# Convenience wrappers — keep call sites readable.
+def step?(stmt)
+  SQL.sqlite3_step(stmt) == SQL::ROW
+end
+
+def col_text(stmt, i)
+  s = SQL.sqlite3_column_text(stmt, i)
+  if s == nil
+    return ""
+  end
+  # Copy out — the buffer is invalidated by the next step / finalize.
+  s + ""
+end
+
+def col_int(stmt, i)
+  SQL.sqlite3_column_int(stmt, i)
+end
+
+def finalize(stmt)
+  SQL.sqlite3_finalize(stmt)
+end
+
+# Look up the id of a tag by name (creating it on the fly if missing).
+def upsert_tag(blog, name)
+  blog.exec("INSERT OR IGNORE INTO tags (name) VALUES ('" + Sql.q(name) + "')")
+  stmt = blog.prepare("SELECT id FROM tags WHERE name = '" + Sql.q(name) + "'")
+  tid = 0
+  if step?(stmt)
+    tid = col_int(stmt, 0)
+  end
+  finalize(stmt)
+  tid
+end
+
+def add_post(blog, title, body, tag_names)
+  blog.exec("INSERT INTO posts (title, body) VALUES ('" +
+            Sql.q(title) + "', '" + Sql.q(body) + "')")
+  pid = blog.last_id
+  tag_names.each { |t|
+    tid = upsert_tag(blog, t)
+    blog.exec("INSERT INTO post_tags (post_id, tag_id) VALUES (" +
+              pid.to_s + ", " + tid.to_s + ")")
+  }
+  pid
+end
+
+def add_comment(blog, post_id, author, body)
+  blog.exec("INSERT INTO comments (post_id, author, body) VALUES (" +
+            post_id.to_s + ", '" + Sql.q(author) + "', '" + Sql.q(body) + "')")
+end
+
+# ---- Demo ----
+
+# Use an in-memory database so each run starts fresh and we don't
+# have to worry about cleaning up.
+blog = Blog.new(":memory:")
+
+blog.exec(
+  "CREATE TABLE posts (" +
+    "id INTEGER PRIMARY KEY AUTOINCREMENT, " +
+    "title TEXT NOT NULL, " +
+    "body TEXT NOT NULL)")
+blog.exec(
+  "CREATE TABLE tags (" +
+    "id INTEGER PRIMARY KEY AUTOINCREMENT, " +
+    "name TEXT NOT NULL UNIQUE)")
+blog.exec(
+  "CREATE TABLE post_tags (" +
+    "post_id INTEGER NOT NULL, " +
+    "tag_id  INTEGER NOT NULL, " +
+    "PRIMARY KEY (post_id, tag_id))")
+blog.exec(
+  "CREATE TABLE comments (" +
+    "id INTEGER PRIMARY KEY AUTOINCREMENT, " +
+    "post_id INTEGER NOT NULL, " +
+    "author TEXT NOT NULL, " +
+    "body TEXT NOT NULL)")
+
+p1 = add_post(blog,
+  "Spinel learns to call C",
+  "Today the AOT compiler grew an FFI. Now we can drive sqlite3 directly.",
+  ["spinel", "ffi", "sqlite"])
+
+p2 = add_post(blog,
+  "Tasting o'tea",
+  "She said it's the best Earl Grey in London.",
+  ["food", "off-topic"])
+
+p3 = add_post(blog,
+  "Hashes vs SymIntHash",
+  "Symbol-keyed hashes get a dedicated type with no string hashing.",
+  ["spinel", "perf"])
+
+add_comment(blog, p1, "alice", "Wonderful — does it work with libcurl too?")
+add_comment(blog, p1, "bob",   "I tried sqlite3 myself; the bindings are tidy.")
+add_comment(blog, p2, "carol", "Where's the shop?")
+add_comment(blog, p3, "dave",  "Nice; the symbol path is hot in our app.")
+
+puts "Posts (with comment + tag counts):"
+stmt = blog.prepare(
+  "SELECT p.id, p.title, " +
+    "(SELECT COUNT(*) FROM comments WHERE post_id = p.id) AS n_comments, " +
+    "(SELECT COUNT(*) FROM post_tags WHERE post_id = p.id) AS n_tags " +
+    "FROM posts p ORDER BY p.id")
+while step?(stmt)
+  puts "  [" + col_int(stmt, 0).to_s + "] " + col_text(stmt, 1) +
+       "  (" + col_int(stmt, 2).to_s + " comments, " +
+       col_int(stmt, 3).to_s + " tags)"
+end
+finalize(stmt)
+
+puts ""
+puts "Posts tagged 'spinel':"
+stmt = blog.prepare(
+  "SELECT p.title FROM posts p " +
+    "JOIN post_tags pt ON pt.post_id = p.id " +
+    "JOIN tags t ON t.id = pt.tag_id " +
+    "WHERE t.name = 'spinel' ORDER BY p.id")
+while step?(stmt)
+  puts "  - " + col_text(stmt, 0)
+end
+finalize(stmt)
+
+puts ""
+puts "Comments on the FFI post:"
+stmt = blog.prepare(
+  "SELECT author, body FROM comments WHERE post_id = " + p1.to_s + " ORDER BY id")
+while step?(stmt)
+  puts "  " + col_text(stmt, 0) + ": " + col_text(stmt, 1)
+end
+finalize(stmt)
+
+blog.close

data/vendor/spinel/examples/ffi/sqlite/sqlite3_lib.rb

@@ -0,0 +1,46 @@
+# Minimal SQLite3 FFI bindings for Spinel.
+#
+# Only the surface area the blog demo needs:
+#   - open / close
+#   - exec for DDL + INSERT/UPDATE/DELETE
+#   - prepare_v2 / step / finalize + column accessors for SELECT
+#
+# Strings are passed inline into SQL; bind_text would also work but
+# requires the SQLITE_TRANSIENT destructor sentinel which the Spinel FFI
+# can't construct as a `:ptr` value yet. For string columns we escape
+# single quotes ourselves (`Sql.q`).
+module SQL
+  ffi_lib "sqlite3"
+
+  ffi_const :OK,   0
+  ffi_const :ROW,  100
+  ffi_const :DONE, 101
+
+  # Core API.
+  ffi_func :sqlite3_open,              [:str, :ptr],                          :int
+  ffi_func :sqlite3_close,             [:ptr],                                :int
+  ffi_func :sqlite3_exec,              [:ptr, :str, :ptr, :ptr, :ptr],        :int
+  ffi_func :sqlite3_prepare_v2,        [:ptr, :str, :int, :ptr, :ptr],        :int
+  ffi_func :sqlite3_step,              [:ptr],                                :int
+  ffi_func :sqlite3_finalize,          [:ptr],                                :int
+  ffi_func :sqlite3_column_int,        [:ptr, :int],                          :int
+  ffi_func :sqlite3_column_text,       [:ptr, :int],                          :str
+  ffi_func :sqlite3_column_count,      [:ptr],                                :int
+  ffi_func :sqlite3_errmsg,            [:ptr],                                :str
+  ffi_func :sqlite3_last_insert_rowid, [:ptr],                                :long
+  ffi_func :sqlite3_changes,           [:ptr],                                :int
+
+  # Out-params — sqlite3_open writes the db handle here, prepare_v2
+  # writes the stmt handle.
+  ffi_buffer :db_out,   8
+  ffi_buffer :stmt_out, 8
+  ffi_read_ptr :read_ptr, 0
+end
+
+# Tiny helper module. Quote-escapes single quotes for inline SQL —
+# good enough for the demo's well-known input strings.
+module Sql
+  def self.q(s)
+    s.gsub("'", "''")
+  end
+end