libcall 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b45f825f6989bd4673b982435ce1bad8ff1b1785785118ffa66c8bdad84b1d7c
-  data.tar.gz: 9a60c1d6d69b2ff7e70a2884b6dfbc8e2b6099c87df40558559fdffffff5c65c
+  metadata.gz: db2f2234f00412d76e307fc12179b0a829953a08bd6aefa83d59bbab866e85f3
+  data.tar.gz: bb2cd9b42fb09fc6b6e5201ed98c16dae47258e9a1fb23ef76fc6a49efe17ab3
 SHA512:
-  metadata.gz: ed0cde569e1eea83480b744907d3397f6e7abae68b991993090312edc6ccf74d4cf973afbad2dd3402142eccf390a3f992cf2174ad016ea0009d5d8b91e104bd
-  data.tar.gz: 42571c69fd4e1487e17b592ec98afc321ed646e938d9d773a96c4e450f4762c9d49975f7de47a33ba5f747e2e2c1367da00d7a3233ff059a8ab5a70f43a3bb92
+  metadata.gz: 12bc58798f6130a316ba87e53a66d2806035a7fd8abbb6ba2fc71654d82e0f2210149152cf9876ca818a5241808a2c871021eca2c7264a2110cfe37199da2872
+  data.tar.gz: bb6f252e8a7a9aec0a353abec0ed9674b346bb1af3471768ca51fad040234024c6fc77b18a25d42c396a389a0063ac44c5675f54fa8bd66eed3b0c9055da8e34

data/README.md

@@ -23,13 +23,11 @@ libcall [OPTIONS] <LIBRARY> <FUNCTION> (TYPE VALUE)...
 ### Quick Examples
 
 ```sh
-# TYPE VALUE pairs
-libcall -lm -r f64 sqrt double 16
-# => 4.0
+libcall -lm sqrt double 16 -r double # => 4.0
+```
 
-# libc strlen
-libcall -lc strlen string "hello" -r usize
-# => 5
+```sh
+libcall -lc strlen string "hello" -r usize # => 5
 ```
 
 ### Argument Syntax
@@ -76,25 +74,51 @@ Library search:
 
 ### More Examples
 
+TYPE/VALUE pairs with `-r` before function
+
+```sh
+libcall -lm  -r double fabs double -5.5 # => 5.5
+```
+
+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
+Windows: calling C runtime functions
 
-# TYPE/VALUE pairs with -r after function
-libcall -lm fabs double -5.5 -r f64
-# => 5.5
+```powershell
+libcall msvcrt.dll sqrt double 16.0 -r f64 # => 4.0
+```
 
-# Windows: calling C runtime functions
-libcall msvcrt.dll sqrt double 16.0 -r f64
-# => 4.0
+Windows: accessing environment variables
 
-# Windows: accessing environment variables
+```powershell
 libcall msvcrt.dll getenv string "PATH" -r cstr
 ```
 
@@ -119,6 +143,8 @@ Also supported:
 - `cstr`: C string return (char\*)
 - `ptr`/`pointer`: void\* pointer
 
+See [type_map.rb](lib/libcall/type_map.rb) for all available type mappings.
+
 ## pkg-config Support
 
 Set `PKG_CONFIG_PATH` and use package names with `-l`:
@@ -160,6 +186,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(ARG,ARG,...){|a, b, ...| 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,int){|a,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*,void*){|pa,pb| int(pa) <=> int(pb) }' \
+	-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:

data/lib/libcall/caller.rb

@@ -18,6 +18,7 @@ module Libcall
       arg_types = []
       arg_values = []
       out_refs = []
+      closures = []
 
       arg_pairs.each_with_index do |(type_sym, value), idx|
         arg_types << TypeMap.to_fiddle_type(type_sym)
@@ -39,11 +40,47 @@ module Libcall
             base = type_sym[1]
             count = type_sym[2]
             ptr = TypeMap.allocate_array(base, count)
+            # Optional initializer values
+            if value
+              vals = Array(value)
+              raise Error, "Initializer length #{vals.length} does not match out array size #{count}" unless vals.length == count
+              TypeMap.write_array(ptr, base, vals)
+            end
             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
+        elsif type_sym == :callback
+          spec = value
+          unless spec.is_a?(Hash) && spec[:kind] == :callback
+            raise Error, 'Invalid callback value; expected func signature and block'
+          end
+
+          ret_ty = TypeMap.to_fiddle_type(spec[:ret])
+          arg_tys = spec[:args].map { |a| TypeMap.to_fiddle_type(a) }
+          # Build Ruby proc from block source, e.g., "{|a,b| a+b}"
+          # Evaluate proc in a helper context so DSL methods are available
+          ctx = Object.new.extend(Libcall::Fiddley::DSL)
+          begin
+            ruby_proc = ctx.instance_eval("proc #{spec[:block]}", __FILE__, __LINE__)
+          rescue SyntaxError => e
+            raise Error, "Invalid Ruby block for callback: #{e.message}"
+          end
+          closure = Fiddle::Closure::BlockCaller.new(ret_ty, arg_tys) do |*cb_args|
+            # Convert pointer-typed args to Fiddle::Pointer for convenience
+            cooked = cb_args.each_with_index.map do |v, i|
+              at = spec[:args][i]
+              if at == :voidp
+                Fiddle::Pointer.new(v)
+              else
+                v
+              end
+            end
+            ruby_proc.call(*cooked)
+          end
+          closures << closure # keep alive during call
+          arg_values << closure
         else
           arg_values << value
         end

data/lib/libcall/cli.rb

@@ -156,8 +156,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,156 @@
+# 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
+
+      # Native size_t pack template and size
+      SIZET_PACK = (Fiddle::SIZEOF_VOIDP == Fiddle::SIZEOF_LONG ? 'L!' : 'Q')
+
+      # Return size in bytes for a given type symbol.
+      # Falls back to pointer size for :pointer and :voidp.
+      def sizeof(type)
+        return Fiddle::SIZEOF_SIZE_T if type == :size_t
+        return Fiddle::SIZEOF_VOIDP if %i[pointer voidp].include?(type)
+
+        # Delegate to Libcall::TypeMap when possible
+        Libcall::TypeMap.sizeof(type)
+      rescue StandardError
+        raise Libcall::Error, "unknown type for sizeof: #{type}"
+      end
+
+      # Convert a type symbol to a Fiddle type constant.
+      def to_fiddle_type(type)
+        return Fiddle::TYPE_SIZE_T if type == :size_t
+        return Fiddle::TYPE_VOIDP if %i[pointer voidp].include?(type)
+
+        Libcall::TypeMap.to_fiddle_type(type)
+      rescue StandardError
+        raise Libcall::Error, "unknown type for to_fiddle_type: #{type}"
+      end
+
+      # Pack template for array values of given base type.
+      def array_pack_template(type)
+        return SIZET_PACK if type == :size_t
+
+        # Use TypeMap's packing for standard types
+        Libcall::TypeMap.pack_template(type)
+      rescue StandardError
+        # For generic pointers/addresses, use native unsigned pointer width
+        return 'J' if %i[pointer voidp].include?(type)
+
+        raise Libcall::Error, "Unsupported array base type: #{type}"
+      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/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,32 @@ 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 = m[1].strip
+        args_s = m[2].strip
+        block_src = m[3]
+
+        ret_sym = TypeMap.lookup(ret_s)
+        raise Error, "Unknown callback return type: #{ret_s}" unless ret_sym
+
+        arg_syms = if args_s.empty?
+                     []
+                   else
+                     args_s.split(',').map(&:strip).map do |a|
+                       sym = TypeMap.lookup(a)
+                       raise Error, "Unknown callback arg type: #{a}" unless sym
+
+                       sym
+                     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,6 +121,9 @@ 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
       when :void then Fiddle::TYPE_VOID
       when :char then Fiddle::TYPE_CHAR
@@ -167,6 +195,11 @@ module Libcall
       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)

data/lib/libcall/version.rb

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

data/lib/libcall.rb

@@ -5,6 +5,7 @@ require_relative 'libcall/parser'
 require_relative 'libcall/library_finder'
 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.3
 platform: ruby
 authors:
 - kojix2
@@ -49,6 +49,7 @@ files:
 - lib/libcall.rb
 - lib/libcall/caller.rb
 - lib/libcall/cli.rb
+- lib/libcall/fiddley.rb
 - lib/libcall/library_finder.rb
 - lib/libcall/parser.rb
 - lib/libcall/platform.rb
@@ -72,7 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Call functions in shared libraries directly from the CLI
 test_files: []