libcall 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b45f825f6989bd4673b982435ce1bad8ff1b1785785118ffa66c8bdad84b1d7c
-  data.tar.gz: 9a60c1d6d69b2ff7e70a2884b6dfbc8e2b6099c87df40558559fdffffff5c65c
+  metadata.gz: 6d3e1c356b60aca8356cd319a9c31619850cb4cbee3275d94f04bc0f3d18b422
+  data.tar.gz: 75ebf8ecc71c6d38f34c4b1f1b6be809e95cc2d5f24cba21755cbf3455ccd9fb
 SHA512:
-  metadata.gz: ed0cde569e1eea83480b744907d3397f6e7abae68b991993090312edc6ccf74d4cf973afbad2dd3402142eccf390a3f992cf2174ad016ea0009d5d8b91e104bd
-  data.tar.gz: 42571c69fd4e1487e17b592ec98afc321ed646e938d9d773a96c4e450f4762c9d49975f7de47a33ba5f747e2e2c1367da00d7a3233ff059a8ab5a70f43a3bb92
+  metadata.gz: fcebbe2dd033a7392ee4bc5b5efed51e5352f6cc1a1dee9aa33751e9833703a6574853265698851548c1b1cda17fad437f450f6058b2a664b7b599c049b44e48
+  data.tar.gz: f3f36070e3aec368a843d72851c88bc25e86a8f04bc23e4950e92e0eda46a23a8980d25598c697069c093f3083b0476d2f6bd1d082ec2dc46e64dd1af661fe6e

data/README.md

@@ -12,50 +12,20 @@ Call C functions in shared libraries from the command line.
 gem install libcall
 ```
 
-**Windows**: Supports DLLs (e.g., `msvcrt.dll`, `kernel32.dll`). Searches in System32, PATH, and MSYS2/MinGW directories. For building custom DLLs, RubyInstaller with DevKit is recommended.
-
-## Usage
-
-```sh
-libcall [OPTIONS] <LIBRARY> <FUNCTION> (TYPE VALUE)...
-```
-
 ### Quick Examples
 
 ```sh
-# TYPE VALUE pairs
-libcall -lm -r f64 sqrt double 16
-# => 4.0
-
-# libc strlen
-libcall -lc strlen string "hello" -r usize
-# => 5
+libcall -lm sqrt double 16 -r double # => 4.0
 ```
 
-### Argument Syntax
-
-Pass arguments as TYPE VALUE pairs (single-token suffix style has been removed):
-
-- Examples: `int 10`, `double -3.14`, `string "hello"`
-- Negative values are safe (not treated as options): `int -23`
-
-Pointers and null:
-
-- Use `ptr` (or `pointer`) to pass raw addresses as integers
-- Use `null`, `nil`, `NULL`, or `0` to pass a null pointer
-
 ```sh
-# Pass a null pointer to a function taking const char*
-libcall -ltest str_length ptr null -r i32
-# => 0
+libcall -lc strlen string "hello" -r usize # => 5
 ```
 
-End of options `--`:
-
-- Use `--` to stop option parsing if a value starts with `-`
+## Usage
 
 ```sh
-libcall -lc getenv string -- -r -r cstr
+libcall [OPTIONS] <LIBRARY> <FUNCTION> (TYPE VALUE)...
 ```
 
 ### Options
@@ -76,48 +46,119 @@ Library search:
 
 ### More Examples
 
+Output parameter with libm
+
+```sh
+libcall -lm modf double -3.14 out:double -r f64
+# Result: -0.14000000000000012
+# Output parameters:
+#   [1] double = -3.0
+```
+
+JSON output
+
 ```sh
-# JSON output
 libcall --json -lm sqrt double 9.0 -r f64
+# {
+#   "library": "/lib/x86_64-linux-gnu/libm.so",
+#   "function": "sqrt",
+#   "return_type": "double",
+#   "result": 3.0
+# }
+```
+
+Dry run
 
-# Dry run
+```sh
 libcall --dry-run -lc getpid -r int
+# Library:  /lib/x86_64-linux-gnu/libc.so
+# Function: getpid
+# Return:   int
+```
 
-# Output parameter with libm
-libcall -lm modf double -3.14 out:double -r f64
+## Type Reference
 
-# TYPE/VALUE pairs with -r after function
-libcall -lm fabs double -5.5 -r f64
-# => 5.5
+libcall supports multiple naming conventions for types, making it easy to work with C libraries.
 
-# Windows: calling C runtime functions
-libcall msvcrt.dll sqrt double 16.0 -r f64
-# => 4.0
+### Integer Types
 
-# Windows: accessing environment variables
-libcall msvcrt.dll getenv string "PATH" -r cstr
+| Short (Rust-like) | C Standard                 | C99/stdint.h           | Size               |
+| ----------------- | -------------------------- | ---------------------- | ------------------ |
+| `i8` / `u8`       | `char` / `uchar`           | `int8_t` / `uint8_t`   | 1 byte             |
+| `i16` / `u16`     | `short` / `ushort`         | `int16_t` / `uint16_t` | 2 bytes            |
+| `i32` / `u32`     | `int` / `uint`             | `int32_t` / `uint32_t` | 4 bytes            |
+| `i64` / `u64`     | `long_long` / `ulong_long` | `int64_t` / `uint64_t` | 8 bytes            |
+| `isize` / `usize` | `long` / `ulong`           | `ssize_t` / `size_t`   | platform-dependent |
+
+**Alternative names**: You can use any of these:
+
+- C-style: `char`, `short`, `int`, `long`, `unsigned_int`, etc.
+- stdint-style: `int8`, `int16`, `int32`, `int64`, `uint8`, `uint16`, etc.
+- With `_t` suffix: `int8_t`, `uint8_t`, `int32_t`, `size_t`, etc.
+
+### Floating Point Types
+
+| Short | C Standard | Alternative | Size    |
+| ----- | ---------- | ----------- | ------- |
+| `f32` | `float`    | `float32`   | 4 bytes |
+| `f64` | `double`   | `float64`   | 8 bytes |
+
+### Pointer Types
+
+| Type                        | Description              | Usage                          |
+| --------------------------- | ------------------------ | ------------------------------ |
+| `ptr` / `pointer` / `voidp` | Generic pointer (void\*) | For arbitrary memory addresses |
+| `string` / `cstr` / `str`   | C string (char\*)        | For passing/returning strings  |
+
+**Null pointer values**: Use `null`, `NULL`, `nil`, or `0` to pass a null pointer.
+
+### Special Types
+
+| Type                     | Description                 | Alternative names    |
+| ------------------------ | --------------------------- | -------------------- |
+| `void`                   | No value (return type only) | —                    |
+| `size_t`                 | Platform size type          | `usize` (unsigned)   |
+| `ssize_t`                | Signed size type            | `isize` (signed)     |
+| `intptr_t` / `uintptr_t` | Pointer-sized integer       | `intptr` / `uintptr` |
+| `ptrdiff_t`              | Pointer difference type     | —                    |
+| `bool`                   | Boolean (as int)            | —                    |
+
+### Output Parameters
+
+Prefix any type with `out:` to create an output parameter:
+
+```sh
+out:int       # Output integer pointer (int*)
+out:double    # Output double pointer (double*)
+out:string    # Output string pointer (char**)
 ```
 
-## Type Reference
+### Array Types
+
+| Syntax        | Description                   | Example              |
+| ------------- | ----------------------------- | -------------------- |
+| `TYPE[]`      | Input array                   | `int[] 1,2,3,4,5`    |
+| `out:TYPE[N]` | Output array of N elements    | `out:int[10]`        |
+| `out:TYPE[N]` | Output array with initializer | `out:int[4] 4,3,2,1` |
 
-| Short (suffix) | Formal (C)                          | Note/Range         |
-| -------------- | ----------------------------------- | ------------------ |
-| `i8`           | `char` (≈ `int8_t`)                 | -128 to 127        |
-| `u8`           | `unsigned char` (≈ `uint8_t`)       | 0 to 255           |
-| `i16`          | `short` (≈ `int16_t`)               | -32768 to 32767    |
-| `u16`          | `unsigned short` (≈ `uint16_t`)     | 0 to 65535         |
-| `i32`          | `int` (≈ `int32_t`)                 | typical 32-bit int |
-| `u32`          | `unsigned int` (≈ `uint32_t`)       | unsigned 32-bit    |
-| `i64`          | `long long` (≈ `int64_t`)           | 64-bit             |
-| `u64`          | `unsigned long long` (≈ `uint64_t`) | 64-bit             |
-| `f32`          | `float`                             | single precision   |
-| `f64`          | `double`                            | double precision   |
-
-Also supported:
-
-- `string`: C string argument (char\*)
-- `cstr`: C string return (char\*)
-- `ptr`/`pointer`: void\* pointer
+### Callback Types
+
+| Keyword    | Description                 | Example                          |
+| ---------- | --------------------------- | -------------------------------- |
+| `func`     | Function pointer (callback) | `func 'int(int a,int b){ a+b }'` |
+| `callback` | Alias for `func`            | Same as above                    |
+
+### Argument Syntax
+
+Pass arguments as TYPE VALUE pairs:
+
+```sh
+libcall -lm sqrt double 16.0 -r f64
+libcall -lc strlen string "hello" -r usize
+```
+
+- Null pointers: Use `null`, `NULL`, `nil`, or `0`
+- Negative numbers work as expected (e.g., `double -3.14`)
 
 ## pkg-config Support
 
@@ -160,6 +201,42 @@ libcall -lc getrandom out:uchar[16] size_t 16 uint 0 -r long
 libcall -lSystem arc4random_buf out:uchar[16] size_t 16 -r void
 ```
 
+## Callbacks (experimental)
+
+Pass a C function pointer via a Ruby callback. Use `func` or `callback` with a quoted spec:
+
+- Syntax: `func 'RET(TYPE name, TYPE name, ...){ ruby_code }'` (alias: `callback ...`)
+- Inside the block, helper methods from `Libcall::Fiddley::DSL` are available:
+  - `int(ptr)`, `double(ptr)`, `cstr(ptr)` read values from pointers
+  - `read(:type, ptr)` reads any supported type; `ptr(addr)` makes a pointer
+
+Quick examples
+
+```sh
+# Fixture function: int32_t apply_i32(int32_t, int32_t, int32_t (*)(int32_t,int32_t))
+libcall -ltest -L test/fixtures/libtest/build apply_i32 \
+	int 3 int 5 \
+	func 'int(int a,int b){ a + b }' \
+	-r i32
+# => 8
+```
+
+```sh
+# libc qsort: sort 4 ints ascending; use out:int[4] with an initializer so the result prints
+libcall -lc qsort \
+	out:int[4] 4,2,3,1 \
+	size_t 4 \
+	size_t 4 \
+	callback 'int(void* a, void* b){ int(a) <=> int(b) }' \
+	-r void
+# Output parameters:
+#   [0] int[4] = [1, 2, 3, 4]
+```
+
+Notes
+
+- Match the C signature exactly (types and arity). Blocks run in-process; exceptions abort the call.
+
 ## Warning
 
 FFI calls are inherently unsafe. You must:
@@ -171,6 +248,22 @@ FFI calls are inherently unsafe. You must:
 
 Incorrect usage can crash your program.
 
+## Windows Support
+
+Supports DLLs (e.g., `msvcrt.dll`, `kernel32.dll`). Searches in System32, PATH, and MSYS2/MinGW directories. For building custom DLLs, RubyInstaller with DevKit is recommended.
+
+### Windows Examples
+
+```powershell
+# Calling C runtime functions
+libcall msvcrt.dll sqrt double 16.0 -r f64 # => 4.0
+```
+
+```powershell
+# Accessing environment variables
+libcall msvcrt.dll getenv string "PATH" -r cstr
+```
+
 ## Development
 
 ```sh

data/lib/libcall/argument_processor.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Libcall
+  # Processes argument pairs for FFI calls
+  class ArgumentProcessor
+    # Value object to hold processed arguments
+    ProcessedArguments = Struct.new(
+      :arg_types,
+      :arg_values,
+      :out_refs,
+      :closures,
+      keyword_init: true
+    )
+
+    def initialize(arg_pairs)
+      @arg_pairs = arg_pairs
+    end
+
+    def process
+      arg_types = []
+      arg_values = []
+      out_refs = []
+      closures = []
+
+      @arg_pairs.each_with_index do |(type_sym, value), idx|
+        if type_sym.is_a?(Array)
+          process_complex_type(type_sym, value, idx, arg_types, arg_values, out_refs)
+        elsif type_sym == :callback
+          process_callback(value, arg_types, arg_values, closures)
+        else
+          arg_types << TypeMap.to_fiddle_type(type_sym)
+          arg_values << value
+        end
+      end
+
+      ProcessedArguments.new(
+        arg_types: arg_types,
+        arg_values: arg_values,
+        out_refs: out_refs,
+        closures: closures
+      )
+    end
+
+    private
+
+    def process_complex_type(type_sym, value, idx, arg_types, arg_values, out_refs)
+      case type_sym.first
+      when :out
+        process_output_pointer(type_sym, idx, arg_types, arg_values, out_refs)
+      when :array
+        process_input_array(type_sym, value, arg_types, arg_values)
+      when :out_array
+        process_output_array(type_sym, value, idx, arg_types, arg_values, out_refs)
+      else
+        raise Error, "Unknown array/output form: #{type_sym.inspect}"
+      end
+    end
+
+    def process_output_pointer(type_sym, idx, arg_types, arg_values, out_refs)
+      inner = type_sym[1]
+      ptr = TypeMap.allocate_output_pointer(inner)
+      out_refs << { index: idx, kind: :out, type: inner, ptr: ptr }
+      arg_types << TypeMap.to_fiddle_type(type_sym)
+      arg_values << ptr.to_i
+    end
+
+    def process_input_array(type_sym, value, arg_types, arg_values)
+      base = type_sym[1]
+      values = Array(value)
+      ptr = TypeMap.allocate_array(base, values.length)
+      TypeMap.write_array(ptr, base, values)
+      arg_types << TypeMap.to_fiddle_type(type_sym)
+      arg_values << ptr.to_i
+    end
+
+    def process_output_array(type_sym, value, idx, arg_types, arg_values, out_refs)
+      base = type_sym[1]
+      count = type_sym[2]
+      ptr = TypeMap.allocate_array(base, count)
+
+      # Optional initializer values
+      if value
+        vals = Array(value)
+        unless vals.length == count
+          raise Error,
+                "Initializer length #{vals.length} does not match out array size #{count}"
+        end
+
+        TypeMap.write_array(ptr, base, vals)
+      end
+
+      out_refs << { index: idx, kind: :out_array, base: base, count: count, ptr: ptr }
+      arg_types << TypeMap.to_fiddle_type(type_sym)
+      arg_values << ptr.to_i
+    end
+
+    def process_callback(value, arg_types, arg_values, closures)
+      closure = CallbackHandler.create(value)
+      closures << closure # keep alive during call
+      arg_types << TypeMap.to_fiddle_type(:callback)
+      arg_values << closure
+    end
+  end
+end

data/lib/libcall/callback_handler.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'fiddle'
+
+module Libcall
+  # Handles callback function pointer creation for FFI calls
+  class CallbackHandler
+    attr_reader :spec
+
+    def self.create(spec)
+      new(spec).create_closure
+    end
+
+    def initialize(spec)
+      @spec = spec
+      validate_spec!
+    end
+
+    def create_closure
+      ret_ty = TypeMap.to_fiddle_type(@spec[:ret])
+      arg_tys = @spec[:args].map { |a| TypeMap.to_fiddle_type(a) }
+      ruby_proc = build_proc
+
+      Fiddle::Closure::BlockCaller.new(ret_ty, arg_tys) do |*cb_args|
+        cooked_args = cook_arguments(cb_args)
+        ruby_proc.call(*cooked_args)
+      end
+    end
+
+    private
+
+    def validate_spec!
+      return if @spec.is_a?(Hash) && @spec[:kind] == :callback
+
+      raise Error, 'Invalid callback value; expected func signature and block'
+    end
+
+    def build_proc
+      ctx = Object.new.extend(Fiddley::DSL)
+      ctx.instance_eval("proc #{@spec[:block]}", __FILE__, __LINE__)
+    rescue SyntaxError => e
+      raise Error, "Invalid Ruby block for callback: #{e.message}"
+    end
+
+    def cook_arguments(cb_args)
+      cb_args.each_with_index.map do |v, i|
+        at = @spec[:args][i]
+        at == :voidp ? Fiddle::Pointer.new(v) : v
+      end
+    end
+  end
+end

data/lib/libcall/caller.rb

@@ -15,53 +15,17 @@ module Libcall
     end
 
     def call
-      arg_types = []
-      arg_values = []
-      out_refs = []
+      processor = ArgumentProcessor.new(arg_pairs)
+      processed = processor.process
 
-      arg_pairs.each_with_index do |(type_sym, value), idx|
-        arg_types << TypeMap.to_fiddle_type(type_sym)
-
-        if type_sym.is_a?(Array)
-          case type_sym.first
-          when :out
-            inner = type_sym[1]
-            ptr = TypeMap.allocate_output_pointer(inner)
-            out_refs << { index: idx, kind: :out, type: inner, ptr: ptr }
-            arg_values << ptr.to_i
-          when :array
-            base = type_sym[1]
-            values = Array(value)
-            ptr = TypeMap.allocate_array(base, values.length)
-            TypeMap.write_array(ptr, base, values)
-            arg_values << ptr.to_i
-          when :out_array
-            base = type_sym[1]
-            count = type_sym[2]
-            ptr = TypeMap.allocate_array(base, count)
-            out_refs << { index: idx, kind: :out_array, base: base, count: count, ptr: ptr }
-            arg_values << ptr.to_i
-          else
-            raise Error, "Unknown array/output form: #{type_sym.inspect}"
-          end
-        else
-          arg_values << value
-        end
-      end
-
-      ret_type = TypeMap.to_fiddle_type(return_type)
-
-      handle = Fiddle.dlopen(lib_path)
-      func_ptr = handle[func_name]
-      func = Fiddle::Function.new(func_ptr, arg_types, ret_type)
-
-      raw_result = func.call(*arg_values)
+      raw_result = execute_function(processed)
       formatted_result = format_result(raw_result, return_type)
 
-      if out_refs.empty?
+      output_reader = OutputReader.new(processed.out_refs)
+      if output_reader.empty?
         formatted_result
       else
-        { result: formatted_result, outputs: read_output_values(out_refs) }
+        { result: formatted_result, outputs: output_reader.read }
       end
     rescue Fiddle::DLError => e
       raise Error, "Failed to load library or function: #{e.message}"
@@ -69,6 +33,14 @@ module Libcall
 
     private
 
+    def execute_function(processed)
+      handle = Fiddle.dlopen(lib_path)
+      func_ptr = handle[func_name]
+      ret_type = TypeMap.to_fiddle_type(return_type)
+      func = Fiddle::Function.new(func_ptr, processed.arg_types, ret_type)
+      func.call(*processed.arg_values)
+    end
+
     def format_result(result, type)
       case type
       when :void
@@ -90,22 +62,5 @@ module Libcall
         result
       end
     end
-
-    def read_output_values(out_refs)
-      out_refs.map do |ref|
-        case ref[:kind]
-        when :out
-          value = TypeMap.read_output_pointer(ref[:ptr], ref[:type])
-          { index: ref[:index], type: ref[:type].to_s, value: value }
-        when :out_array
-          base = ref[:base]
-          count = ref[:count]
-          values = TypeMap.read_array(ref[:ptr], base, count)
-          { index: ref[:index], type: "#{base}[#{count}]", value: values }
-        else
-          raise Error, "Unknown out reference kind: #{ref[:kind]}"
-        end
-      end
-    end
   end
 end

data/lib/libcall/cli.rb

@@ -85,6 +85,11 @@ module Libcall
                  end
 
       <<~BANNER
+
+        Program: libcall (Call C functions from the command line)
+        Version: #{Libcall::VERSION}
+        Source:  https://github.com/kojix2/libcall
+
         Usage: libcall [OPTIONS] <LIBRARY> <FUNCTION> (TYPE VALUE)...
 
         Call C functions in shared libraries from the command line.
@@ -95,14 +100,14 @@ module Libcall
           #{examples.lines.map { |line| line.chomp }.join("\n  ")}
 
         Options:
-          -l, --lib LIBRARY        Library name to search for (e.g., -lm for libm)
-          -L, --lib-path PATH      Add directory to library search path
-          -r, --ret TYPE           Return type (default: void)
-              --dry-run            Show what would be executed without calling
-              --json               Output result in JSON format
-              --verbose            Show detailed information
-          -h, --help               Show this help message
-          -v, --version            Show version information
+          -l, --lib LIBRARY    Library name to search for (e.g., -lm for libm)
+          -L, --lib-path PATH  Add directory to library search path
+          -r, --ret TYPE       Return type (default: void)
+              --dry-run        Show what would be executed without calling
+              --json           Output result in JSON format
+              --verbose        Show detailed information
+          -h, --help           Show this help message
+          -v, --version        Show version information
       BANNER
     end
 
@@ -156,8 +161,17 @@ module Libcall
         type_sym = Parser.parse_type(type_tok)
 
         # TYPE that represents an output pointer/array does not require a value
+        # For out:TYPE[N], allow an optional comma-separated initializer list right after the type.
         if type_sym.is_a?(Array) && %i[out out_array].include?(type_sym.first)
-          arg_pairs << [type_sym, nil]
+          if type_sym.first == :out_array && i < argv.length && argv[i].include?(',')
+            init_tok = argv[i]
+            i += 1
+            base = type_sym[1]
+            values = Parser.coerce_value([:array, base], init_tok)
+            arg_pairs << [type_sym, values]
+          else
+            arg_pairs << [type_sym, nil]
+          end
           next
         end
 

data/lib/libcall/fiddley.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+# A tiny helper layer inspired by fiddley (BSD-2-Clause) to offer
+# convenient, DSL-friendly utilities on top of Ruby's Fiddle.
+# This is intentionally small and tailored for libcall use-cases.
+
+require 'fiddle'
+
+module Libcall
+  module Fiddley
+    # Small helper methods intended for use inside callback blocks
+    module DSL
+      module_function
+
+      def ptr(x)
+        Fiddle::Pointer.new(Integer(x))
+      end
+
+      def read(type, p)
+        t = type.is_a?(Symbol) ? type : type.to_s
+        t_sym = Libcall::TypeMap.lookup(t) || (type.is_a?(Symbol) ? type : nil)
+        raise Libcall::Error, "unknown read type: #{type}" unless t_sym
+
+        pp = p.is_a?(Fiddle::Pointer) ? p : Fiddle::Pointer.new(Integer(p))
+        Libcall::TypeMap.read_output_pointer(pp, t_sym)
+      end
+
+      # Typed short-hands
+      def char(p) = read(:char, p)
+      def uchar(p) = read(:uchar, p)
+      def short(p) = read(:short, p)
+      def ushort(p) = read(:ushort, p)
+      def int(p) = read(:int, p)
+      def uint(p) = read(:uint, p)
+      def long(p) = read(:long, p)
+      def ulong(p) = read(:ulong, p)
+      def long_long(p) = read(:long_long, p)
+      def ulong_long(p) = read(:ulong_long, p)
+      def float(p) = read(:float, p)
+      def double(p) = read(:double, p)
+      def cstr(p) = read(:string, p)
+    end
+
+    module Utils
+      module_function
+
+      # Return size in bytes for a given type symbol.
+
+      def sizeof(type)
+        Libcall::TypeMap.sizeof(type)
+      rescue StandardError => e
+        raise Libcall::Error, "unknown type for sizeof: #{type} (#{e.message})"
+      end
+
+      # Convert a type symbol to a Fiddle type constant.
+      def to_fiddle_type(type)
+        Libcall::TypeMap.to_fiddle_type(type)
+      rescue StandardError => e
+        raise Libcall::Error, "unknown type for to_fiddle_type: #{type} (#{e.message})"
+      end
+
+      # Pack template for array values of given base type.
+      def array_pack_template(type)
+        Libcall::TypeMap.pack_template(type)
+      rescue StandardError => e
+        raise Libcall::Error, "Unsupported array base type: #{type} (#{e.message})"
+      end
+
+      # Convert Ruby array of numbers to a binary string for the given type
+      def array2str(type, array)
+        array.pack("#{array_pack_template(type)}*")
+      end
+
+      # Convert binary string to Ruby array of the given type
+      def str2array(type, str)
+        str.unpack("#{array_pack_template(type)}*")
+      end
+    end
+
+    # Minimal memory buffer wrapper to make building args/arrays convenient
+    class MemoryPointer
+      attr_reader :size
+
+      def initialize(type, count = 1)
+        @type = type
+        @size = Utils.sizeof(type) * count
+        @ptr = Fiddle::Pointer.malloc(@size)
+      end
+
+      def to_ptr
+        @ptr
+      end
+
+      def address
+        @ptr.to_i
+      end
+
+      def write_array(type, values)
+        data = Utils.array2str(type, Array(values))
+        @ptr[0, data.bytesize] = data
+        self
+      end
+
+      def read_array(type, count)
+        bytes = Utils.sizeof(type) * count
+        Utils.str2array(type, @ptr[0, bytes])
+      end
+
+      def put_bytes(offset, str)
+        @ptr[offset, str.bytesize] = str
+      end
+
+      def write_bytes(str)
+        put_bytes(0, str)
+      end
+
+      def get_bytes(offset, len)
+        @ptr[offset, len]
+      end
+
+      def read_bytes(len)
+        get_bytes(0, len)
+      end
+
+      # Return Fiddle::Pointer stored at this pointer (read void*)
+      def read_pointer
+        to_ptr.ptr
+      end
+    end
+
+    # Wrap Fiddle::Closure::BlockCaller with friendlier type mapping
+    class Function < Fiddle::Closure::BlockCaller
+      def initialize(ret, params, &blk)
+        r = Utils.to_fiddle_type(ret)
+        p = Array(params).map { |t| Utils.to_fiddle_type(t) }
+        super(r, p, &blk)
+      end
+    end
+  end
+end

data/lib/libcall/library_finder.rb

@@ -19,6 +19,9 @@ module Libcall
 
     # Find library by name (e.g., "m" -> "/lib/x86_64-linux-gnu/libm.so.6")
     def find(lib_name)
+      # Normalize "-lfoo" style if passed as is (harmless if not present)
+      lib_name = lib_name.sub(/\A-l/, '')
+
       # If it's a path, return as-is
       return File.expand_path(lib_name) if path_like?(lib_name)
 
@@ -52,6 +55,30 @@ module Libcall
       resolved = resolve_by_name_in_paths(lib_name, search_paths)
       return resolved if resolved
 
+      # On macOS, try common library naming conventions for dyld shared cache
+      # (e.g., libSystem.B.dylib exists in cache but not on filesystem)
+      if Platform.darwin?
+        prefixes = lib_name.start_with?('lib') ? [''] : ['lib', '']
+        extensions = Platform.library_extensions
+
+        prefixes.product(extensions).each do |prefix, ext|
+          candidates = [
+            "#{prefix}#{lib_name}#{ext}",
+            "#{prefix}#{lib_name}.B#{ext}",  # Common pattern: libSystem.B.dylib
+            "#{prefix}#{lib_name}.A#{ext}"   # Also try .A variant
+          ]
+
+          candidates.each do |candidate|
+            # Test if dyld can resolve this name
+
+            Fiddle.dlopen(candidate)
+            return candidate # Return the name itself, let Fiddle resolve it
+          rescue Fiddle::DLError
+            next
+          end
+        end
+      end
+
       raise Error, "Library not found: #{lib_name} (searched in: #{search_paths.join(', ')})"
     end
 
@@ -134,11 +161,20 @@ module Libcall
         full_path = File.join(path, name)
         return File.expand_path(full_path) if File.file?(full_path)
 
-        # Check for versioned libraries (libm.so.6, etc.)
+        # Check for versioned libraries:
+        # - Linux: libm.so.6 => "#{name}.*"
+        # - macOS: libSystem.B.dylib, libcrypto.3.dylib => "#{prefix}#{lib_name}.*#{ext}"
         next if ext.empty?
 
-        matches = Dir.glob(File.join(path, "#{name}.*")).select { |f| File.file?(f) }
-        return File.expand_path(matches.first) unless matches.empty?
+        patterns = [
+          File.join(path, "#{name}.*"),
+          File.join(path, "#{prefix}#{lib_name}.*#{ext}")
+        ]
+
+        patterns.each do |pattern|
+          matches = Dir.glob(pattern).select { |f| File.file?(f) }
+          return File.expand_path(matches.first) unless matches.empty?
+        end
       end
 
       nil

data/lib/libcall/output_reader.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Libcall
+  # Handles reading output parameters after FFI calls
+  class OutputReader
+    def initialize(out_refs)
+      @out_refs = out_refs
+    end
+
+    def read
+      @out_refs.map do |ref|
+        case ref[:kind]
+        when :out
+          read_single_output(ref)
+        when :out_array
+          read_array_output(ref)
+        else
+          raise Error, "Unknown out reference kind: #{ref[:kind]}"
+        end
+      end
+    end
+
+    def empty?
+      @out_refs.empty?
+    end
+
+    private
+
+    def read_single_output(ref)
+      value = TypeMap.read_output_pointer(ref[:ptr], ref[:type])
+      { index: ref[:index], type: ref[:type].to_s, value: value }
+    end
+
+    def read_array_output(ref)
+      values = TypeMap.read_array(ref[:ptr], ref[:base], ref[:count])
+      {
+        index: ref[:index],
+        type: "#{ref[:base]}[#{ref[:count]}]",
+        value: values
+      }
+    end
+  end
+end

data/lib/libcall/parser.rb

@@ -7,6 +7,9 @@ module Libcall
   class Parser
     # Pair-only API helpers
     def self.parse_type(type_str)
+      # Callback function pointer: func/callback 'ret(arg,...) { |...| ... }'
+      return :callback if %w[func callback].include?(type_str)
+
       # Output array spec: out:TYPE[N]
       if type_str.start_with?('out:') && type_str.match(/^out:(.+)\[(\d+)\]$/)
         base = Regexp.last_match(1)
@@ -51,6 +54,52 @@ module Libcall
     end
 
     def self.coerce_value(type_sym, token)
+      # Callback value: signature + Ruby block
+      if type_sym == :callback
+        src = strip_quotes(token.to_s)
+        m = src.match(/\A\s*([^(\s]+)\s*\(([^)]*)\)\s*(\{.*\})\s*\z/m)
+        raise Error, "Invalid callback spec: #{src}" unless m
+
+        ret_s, args_s, block_src = m.captures.map(&:strip)
+        if block_src =~ /\{\s*\|/
+          raise Error,
+                'Explicit block parameters are not supported; name your C args and omit block params (e.g., int(int a,int b){a+b})'
+        end
+
+        ret_sym = TypeMap.lookup(ret_s)
+        raise Error, "Unknown callback return type: #{ret_s}" unless ret_sym
+
+        pairs = if args_s.empty?
+                  []
+                else
+                  args_s.split(',').map do |raw|
+                    # Normalize pointer syntax: "void *a", "void * a", "void*a" → "void* a"
+                    normalized = raw.strip.gsub(/\s*\*\s*/, '* ').strip
+
+                    if (mm = normalized.match(/\A(.+?)\s+([A-Za-z_][A-Za-z0-9_]*)\z/))
+                      type_part = mm[1].strip
+                      name_part = mm[2]
+                    else
+                      type_part = normalized
+                      name_part = nil
+                    end
+                    sym = TypeMap.lookup(type_part)
+                    raise Error, "Unknown callback arg type: #{raw.strip}" unless sym
+
+                    [sym, name_part]
+                  end
+                end
+
+        arg_syms = pairs.map(&:first)
+        names_with_nils = pairs.map(&:last)
+        if !names_with_nils.empty? && names_with_nils.all?
+          block_src = block_src.sub(/\{\s*/) do
+            "{|#{names_with_nils.join(',')}| "
+          end
+        end
+
+        return { kind: :callback, ret: ret_sym, args: arg_syms, block: block_src }
+      end
       # Input array values: comma-separated
       if type_sym.is_a?(Array) && type_sym.first == :array
         base = type_sym[1]

data/lib/libcall/type_map.rb

@@ -27,6 +27,7 @@ module Libcall
       'void' => :void,
       # Common C type names
       'char' => :char,
+      'uchar' => :uchar,
       'short' => :short,
       'ushort' => :ushort,
       'int' => :int,
@@ -35,6 +36,21 @@ module Libcall
       'ulong' => :ulong,
       'float' => :float,
       'double' => :double,
+      # C-style pointer aliases
+      'void*' => :voidp,
+      'const void*' => :voidp,
+      'const_void*' => :voidp,
+      'const_voidp' => :voidp,
+      # Underscored variants
+      'unsigned_char' => :uchar,
+      'unsigned_short' => :ushort,
+      'unsigned_int' => :uint,
+      'unsigned_long' => :ulong,
+      'long_long' => :long_long,
+      'unsigned_long_long' => :ulong_long,
+      # Short aliases
+      'unsigned' => :uint,
+      'signed' => :int,
       # Extended type names (stdint-like)
       'int8' => :char,
       'uint8' => :uchar,
@@ -46,6 +62,15 @@ module Libcall
       'uint64' => :ulong_long,
       'float32' => :float,
       'float64' => :double,
+      # C99/C11 standard types with _t suffix
+      'int8_t' => :char,
+      'uint8_t' => :uchar,
+      'int16_t' => :short,
+      'uint16_t' => :ushort,
+      'int32_t' => :int,
+      'uint32_t' => :uint,
+      'int64_t' => :long_long,
+      'uint64_t' => :ulong_long,
       # Size and pointer-sized integers
       'size_t' => :ulong,
       'ssize_t' => :long,
@@ -96,18 +121,32 @@ module Libcall
         return Fiddle::TYPE_VOIDP if %i[out array out_array].include?(tag)
       end
 
+      # Callback function pointers are passed as void*
+      return Fiddle::TYPE_VOIDP if type_sym == :callback
+
       case type_sym
+      # Void type
       when :void then Fiddle::TYPE_VOID
+      # Integer types (8-bit)
       when :char then Fiddle::TYPE_CHAR
       when :uchar then Fiddle::TYPE_UCHAR
+      # Integer types (16-bit)
       when :short then Fiddle::TYPE_SHORT
       when :ushort then Fiddle::TYPE_USHORT
+      # Integer types (32-bit)
       when :int, :uint then Fiddle::TYPE_INT
+      # Integer types (platform-dependent)
       when :long, :ulong then Fiddle::TYPE_LONG
+      # Integer types (64-bit)
       when :long_long, :ulong_long then Fiddle::TYPE_LONG_LONG
+      # Floating point types
       when :float then Fiddle::TYPE_FLOAT
       when :double then Fiddle::TYPE_DOUBLE
-      when :voidp, :string then Fiddle::TYPE_VOIDP
+      # Pointer types
+      when :voidp, :pointer then Fiddle::TYPE_VOIDP
+      when :string then Fiddle::TYPE_VOIDP
+      # Special types
+      when :size_t then Fiddle::TYPE_SIZE_T
       else
         raise Error, "Unknown Fiddle type: #{type_sym}"
       end
@@ -116,14 +155,23 @@ module Libcall
     # Get the size in bytes for a type symbol
     def self.sizeof(type_sym)
       case type_sym
+      # Integer types (8-bit)
       when :char, :uchar then Fiddle::SIZEOF_CHAR
+      # Integer types (16-bit)
       when :short, :ushort then Fiddle::SIZEOF_SHORT
+      # Integer types (32-bit)
       when :int, :uint then Fiddle::SIZEOF_INT
+      # Integer types (platform-dependent)
       when :long, :ulong then Fiddle::SIZEOF_LONG
+      # Integer types (64-bit)
       when :long_long, :ulong_long then Fiddle::SIZEOF_LONG_LONG
+      # Floating point types
       when :float then Fiddle::SIZEOF_FLOAT
       when :double then Fiddle::SIZEOF_DOUBLE
-      when :voidp, :string then Fiddle::SIZEOF_VOIDP
+      # Pointer types
+      when :voidp, :pointer, :string then Fiddle::SIZEOF_VOIDP
+      # Special types
+      when :size_t then Fiddle::SIZEOF_SIZE_T
       else
         raise Error, "Cannot get size for type: #{type_sym}"
       end
@@ -140,18 +188,26 @@ module Libcall
     # Read value from output pointer
     def self.read_output_pointer(ptr, type_sym)
       case type_sym
+      # Integer types (8-bit)
       when :char then ptr[0, Fiddle::SIZEOF_CHAR].unpack1('c')
       when :uchar then ptr[0, Fiddle::SIZEOF_CHAR].unpack1('C')
+      # Integer types (16-bit)
       when :short then ptr[0, Fiddle::SIZEOF_SHORT].unpack1('s')
       when :ushort then ptr[0, Fiddle::SIZEOF_SHORT].unpack1('S')
+      # Integer types (32-bit)
       when :int then ptr[0, Fiddle::SIZEOF_INT].unpack1('i')
       when :uint then ptr[0, Fiddle::SIZEOF_INT].unpack1('I')
+      # Integer types (platform-dependent)
       when :long then ptr[0, Fiddle::SIZEOF_LONG].unpack1('l!')
       when :ulong then ptr[0, Fiddle::SIZEOF_LONG].unpack1('L!')
+      # Integer types (64-bit)
       when :long_long then ptr[0, Fiddle::SIZEOF_LONG_LONG].unpack1('q')
       when :ulong_long then ptr[0, Fiddle::SIZEOF_LONG_LONG].unpack1('Q')
+      # Floating point types
       when :float then ptr[0, Fiddle::SIZEOF_FLOAT].unpack1('f')
       when :double then ptr[0, Fiddle::SIZEOF_DOUBLE].unpack1('d')
+      # Pointer types
+      when :voidp then format('0x%x', ptr[0, Fiddle::SIZEOF_VOIDP].unpack1('J'))
       when :string
         addr = ptr[0, Fiddle::SIZEOF_VOIDP].unpack1('J')
         return '(null)' if addr.zero?
@@ -161,12 +217,16 @@ module Libcall
         rescue StandardError
           format('0x%x', addr)
         end
-      when :voidp then format('0x%x', ptr[0, Fiddle::SIZEOF_VOIDP].unpack1('J'))
       else
         raise Error, "Cannot read output value for type: #{type_sym}"
       end
     end
 
+    # Read a single scalar value at address (helper for callbacks)
+    def self.read_scalar(ptr, type_sym)
+      read_output_pointer(ptr, type_sym)
+    end
+
     # Allocate memory for an array of base type and count elements
     def self.allocate_array(base_type, count)
       Fiddle::Pointer.malloc(sizeof(base_type) * count)
@@ -189,18 +249,28 @@ module Libcall
 
     def self.pack_template(base_type)
       case base_type
+      # Integer types (8-bit)
       when :char then 'c'
       when :uchar then 'C'
+      # Integer types (16-bit)
       when :short then 's'
       when :ushort then 'S'
+      # Integer types (32-bit)
       when :int then 'i'
       when :uint then 'I'
+      # Integer types (platform-dependent)
       when :long then 'l!'
       when :ulong then 'L!'
+      # Integer types (64-bit)
       when :long_long then 'q'
       when :ulong_long then 'Q'
+      # Floating point types
       when :float then 'f'
       when :double then 'd'
+      # Pointer types
+      when :pointer, :voidp then 'J'
+      # Special types
+      when :size_t then (Fiddle::SIZEOF_VOIDP == Fiddle::SIZEOF_LONG ? 'L!' : 'Q')
       else
         raise Error, "Unsupported array base type: #{base_type}"
       end

data/lib/libcall/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Libcall
-  VERSION = '0.0.2'
+  VERSION = '0.0.4'
 end

data/lib/libcall.rb

@@ -3,8 +3,12 @@
 require_relative 'libcall/version'
 require_relative 'libcall/parser'
 require_relative 'libcall/library_finder'
+require_relative 'libcall/callback_handler'
+require_relative 'libcall/output_reader'
+require_relative 'libcall/argument_processor'
 require_relative 'libcall/caller'
 require_relative 'libcall/cli'
+require_relative 'libcall/fiddley'
 
 module Libcall
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libcall
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - kojix2
@@ -47,9 +47,13 @@ files:
 - README.md
 - exe/libcall
 - lib/libcall.rb
+- lib/libcall/argument_processor.rb
+- lib/libcall/callback_handler.rb
 - lib/libcall/caller.rb
 - lib/libcall/cli.rb
+- lib/libcall/fiddley.rb
 - lib/libcall/library_finder.rb
+- lib/libcall/output_reader.rb
 - lib/libcall/parser.rb
 - lib/libcall/platform.rb
 - lib/libcall/type_map.rb