libcall 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d33e4ff88ea0b7f5200165a946f7a146cf0a1d4781d6fd5583d4ccdf3ec17dcf
+  data.tar.gz: 24d91124d8f8207fca38aabadab15cced21106e649755130180d248491e03eb0
+SHA512:
+  metadata.gz: b79e721348b381ca177f8662ced2a942f7a34b65102a9dc3e8e852ad726c3501e48fadc311f63b7a86eab3113b2081e20c78de1dbbe4b58f2b6249d8541329fc
+  data.tar.gz: 9924983519f2f36b5930edab9ae607419eba0199ad6c3aa7a0707ea06006be7512a3d2b1087985e711eeefc928f4d287f23159ba80df240b130acd16cffcfa12

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 kojix2
+
+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,107 @@
+# libcall
+
+[![test](https://github.com/kojix2/libcall/actions/workflows/main.yml/badge.svg)](https://github.com/kojix2/libcall/actions/workflows/main.yml)
+[![Lines of Code](https://img.shields.io/endpoint?url=https%3A%2F%2Ftokei.kojix2.net%2Fbadge%2Fgithub%2Fkojix2%2Flibcall%2Flines)](https://tokei.kojix2.net/github/kojix2/libcall)
+
+Call C functions in shared libraries from the command line.
+
+## Installation
+
+```sh
+gem install libcall
+```
+
+## Usage
+
+```sh
+libcall [OPTIONS] <LIBRARY> <FUNCTION> [ARGS...]
+```
+
+### Quick Examples
+
+```sh
+# Math function with type suffix
+libcall -lm sqrt 16.0f64 -r f64
+# => 4.0
+
+# Custom library
+libcall ./mylib.so add 10i32 20i32 -r i32
+# => 30
+```
+
+### Type Syntax
+
+Use Rust-style type suffixes:
+
+- Integers: `42i32`, `100u64`, `255u8`
+- Floats: `3.14f64`, `2.5f32`
+- Strings: `"hello"`
+
+### Options
+
+- `-l LIBRARY` - library name (searches standard paths)
+- `-L PATH` - add library search path
+- `-r TYPE` - return type (void, i32, f64, cstr, ptr)
+- `--dry-run` - validate without executing
+- `--json` - JSON output
+- `--verbose` - detailed info
+- `-h, --help` - show help
+- `-v, --version` - show version
+
+### More Examples
+
+```sh
+# JSON output
+libcall --json -lm sqrt 9.0f64 -r f64
+
+# Dry run
+libcall --dry-run ./mylib.so test 42i32 -r void
+
+# Using -L and -l (like gcc)
+libcall -lmylib -L./build add 10i32 20i32 -r i32
+```
+
+## Type Reference
+
+| Suffix | Type            | Range/Note         |
+| ------ | --------------- | ------------------ |
+| `i8`   | signed 8-bit    | -128 to 127        |
+| `u8`   | unsigned 8-bit  | 0 to 255           |
+| `i16`  | signed 16-bit   | -32768 to 32767    |
+| `u16`  | unsigned 16-bit | 0 to 65535         |
+| `i32`  | signed 32-bit   | standard int       |
+| `u32`  | unsigned 32-bit | unsigned int       |
+| `i64`  | signed 64-bit   | long long          |
+| `u64`  | unsigned 64-bit | unsigned long long |
+| `f32`  | 32-bit float    | single precision   |
+| `f64`  | 64-bit float    | double precision   |
+
+## pkg-config Support
+
+Set `PKG_CONFIG_PATH` and use package names with `-l`:
+
+```sh
+PKG_CONFIG_PATH=/path/to/pkgconfig libcall -lmypackage func 42i32 -r i32
+```
+
+## Warning
+
+FFI calls are inherently unsafe. You must:
+
+- Provide correct function signatures
+- Match argument types exactly
+- Handle memory correctly
+- Understand ABI compatibility
+
+Incorrect usage can crash your program.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/exe/libcall

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'libcall'
+
+Libcall::CLI.new(ARGV).run

data/lib/libcall/caller.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'fiddle'
+
+module Libcall
+  class Caller
+    attr_reader :lib_path, :func_name, :return_type, :args
+
+    def initialize(lib_path, func_name, args: [], return_type: :void)
+      @lib_path = lib_path
+      @func_name = func_name
+      @return_type = return_type
+      @args = args
+    end
+
+    def call
+      arg_types = []
+      arg_values = []
+
+      args.each do |arg|
+        type_sym, value = Parser.parse_arg(arg)
+        arg_types << Parser.fiddle_type(type_sym)
+        arg_values << value
+      end
+
+      ret_type = Parser.fiddle_type(return_type)
+
+      handle = Fiddle.dlopen(lib_path)
+      func_ptr = handle[func_name]
+      func = Fiddle::Function.new(func_ptr, arg_types, ret_type)
+
+      result = func.call(*arg_values)
+
+      format_result(result, return_type)
+    rescue Fiddle::DLError => e
+      raise Error, "Failed to load library or function: #{e.message}"
+    end
+
+    private
+
+    def format_result(result, type)
+      case type
+      when :void
+        nil
+      when :string, :cstr
+        addr = result.to_i
+        return '(null)' if addr.zero?
+
+        begin
+          Fiddle::Pointer.new(addr).to_s
+        rescue StandardError
+          format('0x%x', addr)
+        end
+      when :float, :double
+        result.to_f
+      when :voidp, :ptr
+        format('0x%x', result.to_i)
+      else
+        result
+      end
+    end
+  end
+end

data/lib/libcall/cli.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'json'
+
+module Libcall
+  class CLI
+    def initialize(argv)
+      @argv = argv
+      @options = {
+        dry_run: false,
+        json: false,
+        verbose: false,
+        return_type: :void,
+        lib: nil,
+        lib_name: nil,
+        lib_paths: []
+      }
+    end
+
+    def run
+      parse_options!
+
+      if @argv.empty?
+        puts @parser.help
+        exit 1
+      end
+
+      # Resolve library path
+      if @options[:lib_name]
+        finder = LibraryFinder.new(lib_paths: @options[:lib_paths])
+        lib_path = finder.find(@options[:lib_name])
+      else
+        lib_path = @options[:lib] || @argv.shift
+      end
+
+      func_name = @argv.shift
+      args = @argv
+
+      if lib_path.nil? || func_name.nil?
+        warn 'Error: Missing required arguments'
+        warn 'Usage: libcall <LIBRARY> <FUNCTION> [ARGS...]'
+        exit 1
+      end
+
+      if @options[:verbose]
+        warn "Library: #{lib_path}"
+        warn "Function: #{func_name}"
+        warn "Arguments: #{args.inspect}"
+        warn "Return type: #{@options[:return_type]}"
+      end
+
+      if @options[:dry_run]
+        dry_run_info(lib_path, func_name, args)
+      else
+        execute_call(lib_path, func_name, args)
+      end
+    rescue Error => e
+      warn "Error: #{e.message}"
+      exit 1
+    rescue StandardError => e
+      warn "Unexpected error: #{e.message}"
+      warn e.backtrace if @options[:verbose]
+      exit 1
+    end
+
+    private
+
+    def parse_options!
+      @parser = OptionParser.new do |opts|
+        opts.banner = <<~BANNER
+          Usage: libcall [OPTIONS] <LIBRARY> <FUNCTION> [ARGS...]
+
+          Call C functions in shared libraries from the command line.
+
+          Examples:
+            libcall /lib/libm.so.6 sqrt 16.0f64 -r f64
+            libcall -lm sqrt 16.0f64 -r f64
+            libcall -lsum -L. add 10i32 20i32 -r i32
+            libcall --dry-run ./mylib.so test 42u64 -r void
+
+          Options:
+        BANNER
+
+        opts.on('--dry-run', 'Validate arguments without executing') do
+          @options[:dry_run] = true
+        end
+
+        opts.on('--json', 'Output result as JSON') do
+          @options[:json] = true
+        end
+
+        opts.on('--verbose', 'Show detailed information') do
+          @options[:verbose] = true
+        end
+
+        opts.on('-l', '--lib LIBRARY', 'Library name (searches in standard paths)') do |lib|
+          @options[:lib_name] = lib
+        end
+
+        opts.on('-L', '--lib-path PATH', 'Add library search path') do |path|
+          @options[:lib_paths] << path
+        end
+
+        opts.on('-r', '--ret TYPE', 'Return type (void, i32, f64, cstr, etc.)') do |type|
+          @options[:return_type] = Parser.parse_return_type(type)
+        end
+
+        opts.on('-h', '--help', 'Show help') do
+          puts opts
+          exit
+        end
+
+        opts.on('-v', '--version', 'Show version') do
+          puts "libcall #{Libcall::VERSION}"
+          exit
+        end
+      end
+
+      @parser.permute!(@argv)
+    end
+
+    def dry_run_info(lib_path, func_name, args)
+      info = {
+        library: lib_path,
+        function: func_name,
+        arguments: [],
+        return_type: @options[:return_type].to_s
+      }
+
+      args.each_with_index do |arg, i|
+        type_sym, value = Parser.parse_arg(arg)
+        info[:arguments] << {
+          index: i,
+          raw: arg,
+          type: type_sym.to_s,
+          value: value
+        }
+      end
+
+      if @options[:json]
+        puts JSON.pretty_generate(info)
+      else
+        puts "Library:  #{info[:library]}"
+        puts "Function: #{info[:function]}"
+        puts "Return:   #{info[:return_type]}"
+        unless info[:arguments].empty?
+          puts 'Arguments:'
+          info[:arguments].each do |arg|
+            puts "  [#{arg[:index]}] #{arg[:raw]} => #{arg[:type]} (#{arg[:value].inspect})"
+          end
+        end
+      end
+    end
+
+    def execute_call(lib_path, func_name, args)
+      caller = Caller.new(
+        lib_path,
+        func_name,
+        args: args,
+        return_type: @options[:return_type]
+      )
+
+      result = caller.call
+
+      if @options[:json]
+        output = {
+          library: lib_path,
+          function: func_name,
+          return_type: @options[:return_type].to_s,
+          result: result
+        }
+        puts JSON.pretty_generate(output, allow_nan: true)
+      else
+        puts result unless result.nil?
+      end
+    end
+  end
+end

data/lib/libcall/library_finder.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'fiddle'
+
+begin
+  require 'pkg-config'
+rescue LoadError
+  # pkg-config is optional
+end
+
+module Libcall
+  class LibraryFinder
+    def initialize(lib_paths: [])
+      @lib_paths = lib_paths
+      @default_paths = default_library_paths
+    end
+
+    # Find library by name (e.g., "m" -> "/lib/x86_64-linux-gnu/libm.so.6")
+    def find(lib_name)
+      # If it's a path, return as-is
+      return File.expand_path(lib_name) if lib_name.include?('/') || lib_name.include?('\\')
+      return File.expand_path(lib_name) if File.file?(lib_name)
+
+      search_paths = @lib_paths + @default_paths
+
+      if defined?(PKGConfig)
+        pkg_exists = if PKGConfig.respond_to?(:exist?)
+                       PKGConfig.exist?(lib_name)
+                     else
+                       PKGConfig.respond_to?(:have_package) ? PKGConfig.have_package(lib_name) : false
+                     end
+
+        if pkg_exists
+          lib_dirs = if PKGConfig.respond_to?(:libs_only_L)
+                       PKGConfig.libs_only_L(lib_name).to_s.split.map { |p| p.start_with?('-L') ? p[2..] : p }
+                     else
+                       PKGConfig.libs(lib_name).to_s.split.select { |t| t.start_with?('-L') }.map { |t| t[2..] }
+                     end
+          lib_names = if PKGConfig.respond_to?(:libs_only_l)
+                        PKGConfig.libs_only_l(lib_name).to_s.split.map { |l| l.start_with?('-l') ? l[2..] : l }
+                      else
+                        PKGConfig.libs(lib_name).to_s.split.select { |t| t.start_with?('-l') }.map { |t| t[2..] }
+                      end
+
+          search_paths = lib_dirs + search_paths
+
+          # Attempt to resolve any of the advertised libs from the package
+          lib_names.each do |lname|
+            resolved = resolve_by_name_in_paths(lname, search_paths)
+            return resolved if resolved
+          end
+        end
+      end
+
+      # Try resolving the provided name using standard conventions
+      resolved = resolve_by_name_in_paths(lib_name, search_paths)
+      return resolved if resolved
+
+      raise Error, "Library not found: #{lib_name} (searched in: #{search_paths.join(', ')})"
+    end
+
+    private
+
+    def default_library_paths
+      paths = []
+
+      # Standard library paths
+      paths << '/lib'
+      paths << '/usr/lib'
+      paths << '/usr/local/lib'
+
+      # Architecture-specific paths
+      if RUBY_PLATFORM =~ /x86_64/
+        paths << '/lib/x86_64-linux-gnu'
+        paths << '/usr/lib/x86_64-linux-gnu'
+      elsif RUBY_PLATFORM =~ /aarch64|arm64/
+        paths << '/lib/aarch64-linux-gnu'
+        paths << '/usr/lib/aarch64-linux-gnu'
+      end
+
+      # macOS paths
+      if RUBY_PLATFORM =~ /darwin/
+        paths << '/usr/local/lib'
+        paths << '/opt/homebrew/lib'
+      end
+
+      # LD_LIBRARY_PATH
+      paths.concat(ENV['LD_LIBRARY_PATH'].split(':')) if ENV['LD_LIBRARY_PATH']
+
+      # DYLD_LIBRARY_PATH (macOS)
+      paths.concat(ENV['DYLD_LIBRARY_PATH'].split(':')) if ENV['DYLD_LIBRARY_PATH']
+
+      paths.select { |p| Dir.exist?(p) }
+    end
+
+    def resolve_by_name_in_paths(lib_name, search_paths)
+      # Try direct name first (e.g., "libm.so")
+      search_paths.each do |path|
+        full_path = File.join(path, lib_name)
+        return File.expand_path(full_path) if File.file?(full_path)
+      end
+
+      # Try with lib prefix and common extensions
+      extensions = ['', '.so', '.dylib', '.dll']
+      prefixes = lib_name.start_with?('lib') ? [''] : ['lib']
+
+      prefixes.each do |prefix|
+        extensions.each do |ext|
+          name = "#{prefix}#{lib_name}#{ext}"
+          search_paths.each do |path|
+            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.)
+            next if ext.empty?
+
+            pattern = File.join(path, "#{name}.*")
+            matches = Dir.glob(pattern).select { |f| File.file?(f) }
+            return File.expand_path(matches.first) unless matches.empty?
+          end
+        end
+      end
+
+      nil
+    end
+  end
+end

data/lib/libcall/parser.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Libcall
+  class Parser
+    TYPE_MAP = {
+      'i8' => :char,
+      'u8' => :uchar,
+      'i16' => :short,
+      'u16' => :ushort,
+      'i32' => :int,
+      'u32' => :uint,
+      'i64' => :long_long,
+      'u64' => :ulong_long,
+      'isize' => :long,
+      'usize' => :ulong,
+      'f32' => :float,
+      'f64' => :double,
+      'cstr' => :string,
+      'ptr' => :voidp,
+      'void' => :void,
+      'int' => :int,
+      'uint' => :uint,
+      'long' => :long,
+      'ulong' => :ulong,
+      'float' => :float,
+      'double' => :double,
+      'char' => :char,
+      'str' => :string
+    }.freeze
+
+    def self.parse_arg(arg)
+      return [:string, ''] if arg.empty?
+
+      if (arg.start_with?('"') && arg.end_with?('"')) ||
+         (arg.start_with?("'") && arg.end_with?("'"))
+        return [:string, arg[1...-1]]
+      end
+
+      if arg =~ /^([-+]?(?:\d+\.?\d*|\d*\.\d+))([a-z]\d+|[a-z]+)$/i
+        value_str = ::Regexp.last_match(1)
+        type_str = ::Regexp.last_match(2)
+
+        type_sym = TYPE_MAP[type_str]
+        raise Error, "Unknown type suffix: #{type_str}" unless type_sym
+
+        value = if %i[float double].include?(type_sym)
+                  value_str.to_f
+                else
+                  value_str.to_i
+                end
+
+        return [type_sym, value]
+      end
+
+      if arg =~ /^[-+]?\d+$/
+        [:int, arg.to_i]
+      elsif arg =~ /^[-+]?(?:\d+\.\d*|\d*\.\d+)$/
+        [:double, arg.to_f]
+      else
+        raise Error, "Cannot parse argument: #{arg}"
+      end
+    end
+
+    def self.parse_return_type(type_str)
+      return :void if type_str.nil? || type_str.empty? || type_str == 'void'
+
+      type_sym = TYPE_MAP[type_str]
+      raise Error, "Unknown return type: #{type_str}" unless type_sym
+
+      type_sym
+    end
+
+    def self.parse_signature(sig)
+      raise Error, "Invalid signature format: #{sig}" unless sig =~ /^([a-z]\w*)\((.*)\)$/i
+
+      ret_type = parse_return_type(::Regexp.last_match(1))
+      arg_types = ::Regexp.last_match(2).split(',').map(&:strip).reject(&:empty?).map do |t|
+        TYPE_MAP[t] or raise Error, "Unknown type in signature: #{t}"
+      end
+      [ret_type, arg_types]
+    end
+
+    def self.fiddle_type(type_sym)
+      case type_sym
+      when :void then Fiddle::TYPE_VOID
+      when :char then Fiddle::TYPE_CHAR
+      when :uchar then Fiddle::TYPE_UCHAR
+      when :short then Fiddle::TYPE_SHORT
+      when :ushort then Fiddle::TYPE_USHORT
+      when :int, :uint then Fiddle::TYPE_INT
+      when :long, :ulong then Fiddle::TYPE_LONG
+      when :long_long, :ulong_long then Fiddle::TYPE_LONG_LONG
+      when :float then Fiddle::TYPE_FLOAT
+      when :double then Fiddle::TYPE_DOUBLE
+      when :voidp, :string then Fiddle::TYPE_VOIDP
+      else
+        raise Error, "Unknown Fiddle type: #{type_sym}"
+      end
+    end
+  end
+end

data/lib/libcall/version.rb

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

data/lib/libcall.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'libcall/version'
+require_relative 'libcall/parser'
+require_relative 'libcall/library_finder'
+require_relative 'libcall/caller'
+require_relative 'libcall/cli'
+
+module Libcall
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: libcall
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- kojix2
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pkg-config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+email: 2xijok@gmail.com
+executables:
+- libcall
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/libcall
+- lib/libcall.rb
+- lib/libcall/caller.rb
+- lib/libcall/cli.rb
+- lib/libcall/library_finder.rb
+- lib/libcall/parser.rb
+- lib/libcall/version.rb
+homepage: https://github.com/kojix2/libcall
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Call functions in shared libraries directly from the CLI
+test_files: []