ruby-FFI-utilities 0.1.0

data/README.md

@@ -0,0 +1,90 @@
+# Ruby FFI::Utilities
+
+[![Build Status](https://travis-ci.org/nicb/ruby-FFI-utilities.svg?branch=master)](https://travis-ci.org/nicb/ruby-FFI-utilities)
+[![Code Climate](https://codeclimate.com/github/nicb/ruby-FFI-utilities/badges/gpa.svg)](https://codeclimate.com/github/nicb/ruby-FFI-utilities)
+[![Test Coverage](https://codeclimate.com/github/nicb/ruby-FFI-utilities/badges/coverage.svg)](https://codeclimate.com/github/nicb/ruby-FFI-utilities/coverage)
+[![Issue Count](https://codeclimate.com/github/nicb/ruby-FFI-utilities/badges/issue_count.svg)](https://codeclimate.com/github/nicb/ruby-FFI-utilities)
+
+Utilities for the `FFI` (*Foreign Function Interface*) library for Ruby
+
+## Description
+
+The `FFI` library is fantastic in many ways. Sometimes we wish to have some
+extra features to be added upon request. We put these features in this
+`FFI::Utilities` library.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby-FFI-utilities'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ruby-FFI-utilities
+
+## Implemented Utilities
+
+Currently implemented utility functions are:
+
+* `set_args(array_of_string_arguments)` - transforms a `ruby` string array
+  into an array suitable to be passed to a `C` function that accepts a `char *[]` argument
+* `set_string(const char *string)` - transforms a `ruby` string
+  into a string pointer suitable to be passed to a `C` function that accepts a
+  `const char *` or a `char *` argument
+
+There are also two wrappers for `FFI::Struct` and `FFI::ManagedStruct`,
+respectively called `FFI::Utilities::Struct` and
+`FFI::Utilities::ManagedStruct. These two wrappers implement some features,
+such as:
+
+* attribute accessors
+* attribute `char` accessors, which implement single `char` type access to
+  data structures (separated from usual attribute accessors because `ruby`
+  does not make a difference between single-char and multiple-char `String`s
+* private `new` method
+* public `create(*args) [{ |this, *args| ... }]` method, which substitutes `new`
+* `struct_initialize(*args)` private function which mimicks the functionality
+  of `initialize` but gets called by `create`
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/ruby-FFI-utilities/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+  GNU GENERAL PUBLIC LICENSE
+  Version 2, June 1991
+
+  Ruby FFI Utilities
+  Copyright (C) 2015 Nicola Bernardini
+
+  This program is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License along
+  with this program; if not, write to the Free Software Foundation, Inc.,
+  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

data/Rakefile

@@ -0,0 +1,21 @@
+require "bundler/gem_tasks"
+
+begin
+  require 'byebug'
+  require 'rspec/core/rake_task'
+  
+  #
+  # FIXME: we need to set the ruby options to -W0 to silence the warnings connected
+  # to the reassignement of the RUBY_PLATFORM constant value for testing purposes
+  #
+  RSpec::Core::RakeTask.new(:spec => 'fixtures:C:build') { |t| t.ruby_opts = '-W0' }
+rescue LoadError
+  # no rspec available
+end
+
+task :default => :spec
+
+#
+# Load all other rake tasks that reside in lib/tasks
+#
+Dir.glob(File.expand_path(File.join('..', 'lib', 'tasks', '**', '*.rake'), __FILE__)).each { |f| load f }

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'FFI/utilities'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require 'pry'
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/FFI/utilities.rb

@@ -0,0 +1,17 @@
+require 'ffi'
+
+module FFI
+  module Utilities
+    PATH = File.expand_path(File.join('..', 'utilities'), __FILE__)
+  end
+end
+
+%w(
+  version
+  deprecated
+  suffixes
+  set_argv
+  set_string
+  struct_extensions
+  struct
+).each { |f| require File.join(FFI::Utilities::PATH, f) }

data/lib/FFI/utilities/deprecated.rb

@@ -0,0 +1,15 @@
+module FFI
+
+  module Utilities
+
+    class << self
+
+      def deprecated(msg)
+        $stderr.puts("WARNING: DEPRECATED: #{msg}. This will soon be removed from sources")
+      end
+
+    end
+
+  end
+
+end

data/lib/FFI/utilities/set_argv.rb

@@ -0,0 +1,28 @@
+module FFI
+
+  module Utilities
+
+    class << self
+
+      #
+      # <tt>set_argv(array_of_strings)</tt>
+      #
+      # creates the appropriate +FFI::MemoryPointer+ out of a +ruby+ array of
+      # strings
+      #
+      def set_argv(array_of_strings)
+        str_array = []
+        array_of_strings.each { |str| str_array << FFI::MemoryPointer.from_string(str) }
+        str_array << nil
+      
+        res = FFI::MemoryPointer.new(:pointer, str_array.size)
+        str_array.each_with_index { |p, i| res[i].put_pointer(0,  p) }
+      
+        res
+      end
+
+    end
+
+  end
+
+end

data/lib/FFI/utilities/set_string.rb

@@ -0,0 +1,21 @@
+module FFI
+
+  module Utilities
+
+    class << self
+
+      #
+      # <tt>set_string(str)</tt>
+      #
+      # creates the appropriate +FFI::MemoryPointer+ from a +ruby+ string
+      # passed as argument
+      #
+      def set_string(str)
+        FFI::MemoryPointer.from_string(str)
+      end
+
+    end
+
+  end
+
+end

data/lib/FFI/utilities/struct.rb

@@ -0,0 +1,30 @@
+module FFI
+  module Utilities
+    #
+    # <tt>FFI::Utilities::Struct</tt> and <tt>FFI::Utilities::ManagedStruct</tt>
+    # *may not* be called with the +new+ method (because it is +private+ in
+    # these classes. Users may use the <tt>create(*args) { |args| ...  }</tt>
+    # method and block for initialization purposes
+    #
+    class Struct < FFI::Struct
+
+      include FFI::Utilities::StructExtensions
+
+      private_class_method :new
+
+      private :struct_initialize
+
+    end
+
+    class ManagedStruct < FFI::ManagedStruct
+
+      include FFI::Utilities::StructExtensions
+
+      private_class_method :new
+
+      private :struct_initialize
+
+    end
+
+  end
+end

data/lib/FFI/utilities/struct_extensions.rb

@@ -0,0 +1,156 @@
+module FFI
+  module Utilities
+
+    module StructExtensions
+
+      class NoLayout < StandardError; end
+      class NotALayoutMember < StandardError; end
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+
+        #
+        # <tt>create(*args) [{ |this_object, args| ... }]</tt>
+        #
+        # does all the necessary FFI memory housekeeping for data structures
+        # and then passes a pointer to self and its arguments to a block.
+        #
+        # Also, this method may be overridden in subclasses and then called
+        # with <tt>super()</tt> if necessary.
+        #
+        def create(*args)
+          mp = FFI::MemoryPointer.new(self.size, 1)
+          p  = FFI::Pointer.new(mp)
+          this_self = new(p)
+          this_self.send(:struct_initialize, *args)
+          yield(this_self, *args) if block_given?
+          this_self
+        end
+
+        def cast_pointer(p)
+          raise ArgumentError, 'bad pointer' unless p.kind_of?(FFI::MemoryPointer)
+          new(p)
+        end
+
+        #
+        # +attr_reader+, +attr_writer+, +attr_accessor+
+        # +attr_char_reader, +attr_char_writer+, +attr_char_accessor+
+        #
+        # Two basic sets of read/write methods are created, because we have to
+        # differentiate whether we want to be able to convert to/from a single
+        # +char+ (which +ruby+ will treat as a String object +C+ treats
+        # differently)
+        #
+        def attr_reader(*m)
+          method = 'read'
+          m.flatten.each { |a| common_read_eval(a, method) }
+        end
+
+        def attr_writer(*m)
+          method = 'write'
+          m.flatten.each { |a| common_write_eval(a, method) }
+        end
+
+        def attr_accessor(*m)
+          attr_reader(*m)
+          attr_writer(*m)
+        end
+
+        def attr_char_reader(*m)
+          method = 'read_char'
+          m.flatten.each { |a| common_read_eval(a, method) }
+        end
+
+        def attr_char_writer(*m)
+          method = 'write_char'
+          m.flatten.each { |a| common_write_eval(a, method) }
+        end
+
+        def attr_char_accessor(*m)
+          attr_char_reader(*m)
+          attr_char_writer(*m)
+        end
+
+      private
+
+        def common_read_eval(m, method)
+          rms = "def #{m}(); #{method}_attribute(:#{m}); end"
+          class_eval(rms) if exists_in_layout?(m)
+        end
+
+        def common_write_eval(m, method)
+          wms = "def #{m}=(val); #{method}_attribute(:#{m}, val); end"
+          class_eval(wms) if exists_in_layout?(m)
+        end
+
+        def exists_in_layout?(m)
+          raise NoLayout, "No layout for class #{self.name}" unless self.layout
+          raise NotALayoutMember, "method #{m} is not a layout member in class #{self.name}" unless self.layout.members.include?(m)
+          true
+        end
+
+      end
+
+      def read_attribute(attr)
+        self[attr]
+      end
+
+      #
+      # <tt>write_attribute(attr, val)</tt>
+      #
+      # writes +val+ into property +attr+. Care is taken to manage strings
+      # properly, even tough there seems to be a general suggestion that
+      # assigning strings is a Bad Thing (tm)
+      #
+      def write_attribute(attr, val)
+        if self.class.layout[attr].type == FFI::Type::Builtin::STRING
+          pos = offset_of(attr)
+          sp = val.nil? ? FFI::MemoryPointer::NULL : FFI::MemoryPointer.from_string(val)
+          self.pointer.put_pointer(pos, sp)
+        else
+          self[attr] = val
+        end
+        self[attr]
+      end
+
+      def read_char_attribute(attr)
+        self[attr].chr
+      end
+
+      def write_char_attribute(attr, val)
+        self[attr] = val.each_byte.map { |b| b }.first.to_i
+        read_char_attribute(attr)
+      end
+
+    private
+
+      #
+      # <tt>struct_initialize(*args)</tt>
+      #
+      # the +struct_initialize+ private method can be overridden by 
+      # subclasses just like the +initialize+ method can, and it will be
+      # called by the <tt>create(*args)</tt> method just +new+ calls
+      # the +initialize+ method.
+      #
+      # *PLEASE NOTE*: the +initialize+ method cannot be used as usual,
+      # (just like +new+ cannot be used) because <tt>new()</tt> is used
+      # by FFI to memory initialization - so don't use it unless you
+      # *really* know what you are doing.
+      #
+      # The classes using this mixin should make this method +private+,
+      # just as +initialize+ is.
+      # 
+      def struct_initialize(*args)
+        #
+        # this is supposed to be overridden and as such it is empty
+        #
+      end
+
+    end
+
+  end
+
+end

data/lib/FFI/utilities/suffixes.rb

@@ -0,0 +1,38 @@
+module FFI
+
+  module Utilities
+
+    class UnknownPlatform < StandardError
+      def initialize(msg)
+        ext_msg = [msg, "unknown platform #{RUBY_PLATFORM}"].join(': ')
+        super(ext_msg)
+      end
+    end
+
+    class << self
+
+      def library_suffix
+        deprecated("use the FFI.manage_library_name() method instead")
+        res = case RUBY_PLATFORM
+              when /linux/i then '.so'
+              when /darwin/i then '.dylib'
+              when /windows/i then '.dll'
+              else raise UnknownPlatform.new('library_suffix')
+        end
+      end
+
+      def object_suffix
+        res = case RUBY_PLATFORM
+              when /linux/i then '.o'
+              when /darwin/i then '.o'
+              when /windows/i then '.obj'
+              else raise UnknownPlatform.new('object_suffix')
+        end
+      end
+
+    end
+
+  end
+
+end
+