ffi-enum-generator 0.1.0

data/README.md

@@ -0,0 +1,91 @@
+Enums in C are weird.  They like `#define` constant, with delusions of being
+a "real type".  Behind the scenes, however, they're just a number.  And
+there's no guarantee that the number won't change.
+
+FFI comes with a neat "constant generator", that will avoid the problem of
+constants changing by getting the constant values out of the source code, at
+runtime.  This is great, but enums have exactly the same problem as
+`#define`d constants, and the constant generator doesn't work on enums.  So,
+I adapted the `FFI::ConstGenerator` code into this handy-dandy enum
+generator.  As a bonus, since you often want to be able to refer to enum
+values as constants, you can turn all the symbols in an enum into constants
+on a module.
+
+
+# Installation
+
+It's a gem:
+
+    gem install ffi-constant-generator
+
+If you're the sturdy type that likes to run from git:
+
+    rake build; gem install pkg/ffi-enum-generator-<whatever>.gem
+
+Or, if you've eschewed the convenience of Rubygems, then you presumably know
+what to do already.
+
+
+# Usage
+
+To generate an enum, use the `generate_enum` method in your
+`FFI::Library`-using class:
+
+    require 'ffi/enum_generator'
+
+    class MyFFI
+      extend ::FFI::Library
+      ffi_lib "foo.so"
+
+      generate_enum :foo_bar_opts do |eg|
+        # The enum is defined in here, so we need to know that so we can
+        # get the values
+        eg.include "foo/bar.h"
+
+        eg.symbol("FOO_BAR_FROB",   "FROB")
+        eg.symbol("FOO_BAR_BAZ",    "BAZ")
+        eg.symbol("FOO_BAR_WOMBAT", "WOMBAT")
+      end
+    end
+
+This will create an enum named `:foo_bar_opts`, with the symbols `:FROB`,
+`:BAZ`, and `:WOMBAT` with values equal to the C enum's values for
+`FOO_BAR_FROB`, `FOO_BAR_BAZ`, and `FOO_BAR_WOMBAT`, respectively.  If you
+leave off the second argument to `eg.symbol`, the symbols in your enum will
+be the same as the original names, but since anyone sane namespaces their
+enum values with prefixes, it's rare that you'll want to do that.
+
+Once your enum is generated, you can use it in exactly the same way as you
+would any other typed enum.  You can refer to it in your `attach_function`
+calls:
+
+    class MyFFI
+      attach_function :frobber,
+                      [:pointer, :foo_bar_opts],
+                      :int
+    end
+
+Or retrieve it at will using `MyFFI.enum_type`:
+
+    puts "foo_bar_opts[:wombat] is #{MyFFI.enum_type(:foo_bar_opts)[:WOMBAT]}"
+
+Since going through all that rigamarole is a lot of typing, and not very
+Rubyesque, you can set all the enum symbols up as constants on a module,
+like so:
+
+    module FooBarOpts; end
+
+    MyFFI.enum_type(:foo_bar_opts).set_consts(FooBarOpts)
+
+    puts "foo_bar_opts[:wombat] is #{FooBarOpts::WOMBAT}"
+
+Neat, huh?
+
+
+# Contributing
+
+Bug reports should be sent to the [Github issue
+tracker](https://github.com/mpalmer/ffi-enum-generator/issues), or
+[e-mailed](mailto:theshed+ffi-enum-generator@hezmatt.org).  Patches can be
+sent as a Github pull request, or
+[e-mailed](mailto:theshed+ffi-enum-generator@hezmatt.org).

data/lib/ffi/enum_generator.rb

@@ -0,0 +1,150 @@
+require 'tempfile'
+require 'open3'
+
+module FFI
+	module Library
+		# Generate an `FFI::Enum` from C enum values
+		#
+		# @example A simple example for a days-of-the-week enum
+		#
+		#  # C:
+		#  enum {
+		#    SUNDAY,    # Automatically given the value '0'
+		#    MONDAY,
+		#    TUESDAY,
+		#    WEDNESDAY,
+		#    THURSDAY,
+		#    FRIDAY,
+		#    SATURDAY
+		#  }
+		#
+		#  # Ruby:
+		#  enum = FFI::EnumGenerator(:weekdays) do |gen|
+		#    gen.symbol(:MONDAY)
+		#    gen.symbol('TUESDAY')
+		#    gen.symbol(:WEDNESDAY, :WED)  # this enum value's symbol will be :WED
+		#    gen.symbol(:THURSDAY),
+		#    gen.symbol(:FRIDAY)
+		#  end
+		#
+		#  enum.class       # => FFI::Enum
+		#  enum[:MONDAY]    # => 1
+		#  enum[:TUESDAY]   # => 2
+		#  enum[:WED]       # => 3
+		#  enum[:WEDNESDAY] # => nil
+		#  enum[:ohai]      # => nil
+		#
+		# @note Specifying a symbol that isn't known, will cause assplosions.
+		#   Specifying a symbol that isn't an enum value may work, but is not
+		#   guaranteed to continue to work.
+		#
+		# @param name [#to_s] The name of the enum to create.
+		#
+		# @return [FFI::Enum] The newly-created enum.
+		#
+		# @yieldparam gen [FFI::EnumGenerator] The generator is passed to the
+		#   block, so you can use {FFI::EnumGenerator#include} and
+		#   {FFI::EnumGenerator#symbol} to define the enum before it is
+		#   generated.
+		#
+		def generate_enum(name, &blk)
+			enum name, ::FFI::EnumGenerator.new(&blk).generate
+		end
+	end
+
+	class EnumGenerator
+		# Creates a new enum generator.
+		#
+		# You probably don't want to instantiate one of these directly.  Take
+		# a look at {FFI::Library.generate_enum} instead.
+		#
+		def initialize
+			@includes = ["stdio.h"]
+			@enum_symbols = {}
+
+			yield self if block_given?
+		end
+
+		# Add a symbolic value to the enum.
+		#
+		# @param name [#to_s] The name of the enum value to lookup.
+		#
+		# @param ruby_name [#to_sym] The name that the enum value will have
+		#   inside the Ruby enum.  This is useful to remove namespacing
+		#   prefixes that are unnecessary in Ruby, or to make the symbols more
+		#   pleasing to the eye (camel-casing, for instance).
+		#
+		def symbol(name, ruby_name = nil)
+			ruby_name ||= name
+			@enum_symbols[name] = ruby_name
+		end
+
+		# Add additional C include file(s) to use to lookup the enum values.
+		#
+		# You should use this method to add the `.h` files needed to fully
+		# define the enum(s) you wish to extract values from.
+		#
+		# @param i [List<String>, Array<String>] The additional file(s) to
+		#   include.
+		#
+		# @return [Array<String>] The complete array of included files.
+		#
+		def include(*i)
+			@includes += i.flatten
+		end
+
+		# Generate an array of enum symbols and values.
+		#
+		# You probably don't ever want to call this yourself.  We use it to
+		# feed the enum creation code.
+		#
+		# @return [Array] Alternating symbols and values for the new enum.
+		#
+		def generate
+			binary = File.join Dir.tmpdir, "rb_ffi_enum_gen_bin_#{Process.pid}"
+
+			Tempfile.open("#{@name}.enum_generator") do |f|
+				@includes.each do |inc|
+					f.puts "#include <#{inc}>"
+				end
+				f.puts "\nint main(void)\n{"
+
+				@enum_symbols.each do |name, ruby_name|
+					f.puts <<-EOF.gsub(/^\t{6}/, '')
+						printf("#{ruby_name} %d\\n", #{name});
+					EOF
+				end
+
+				f.puts "\n\treturn 0;\n}"
+				f.flush
+
+				output = `gcc -x c -Wall -Werror #{f.path} -o #{binary} 2>&1`
+
+				unless $?.success? then
+					output = output.split("\n").map { |l| "\t#{l}" }.join "\n"
+					raise "Compilation error generating constants #{@prefix}:\n#{output}"
+				end
+			end
+
+			output = `#{binary}`
+			File.unlink(binary + (FFI::Platform.windows? ? ".exe" : ""))
+			output.split("\n").inject([]) do |a, l|
+				l =~ /^(\S+)\s(.*)$/
+				a += [$1.to_sym, Integer($2)]
+			end
+		end
+	end
+
+	class Enum
+		# Set constants on the given module for each symbol in this enum
+		#
+		# This will blow up if a constant of the same name is already defined
+		# on `mod`, so you probably don't want to do that.
+		#
+		# @param mod [Module] The module upon which the constants will be set.
+		#
+		def set_consts(mod)
+			symbols.each { |s| mod.const_set(s, self[s]) }
+		end
+	end
+end

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification
+name: ffi-enum-generator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Matt Palmer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: git-version-bump
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: github-release
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- lib/ffi/enum_generator.rb
+- README.md
+homepage: http://theshed.hezmatt.org/ffi-enum-generator
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -4477082046855175583
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -4477082046855175583
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Generate values for FFI enums directly
+test_files: []
+has_rdoc: