zproject_ruby.gsl

#   Generate minimal Ruby language bindings.
#
#   These are not meant to be idiomatic, but to provide a minimal platform
#   of FFI function bindings on which to base idiomatic Ruby classes.
#
#   This is a code generator built using the iMatix GSL code generation
#   language. See https://github.com/imatix/gsl for details.
#
#   Copyright (c) the Contributors as noted in the AUTHORS file.
#   This file is part of zproject.
#
#   This Source Code Form is subject to the terms of the Mozilla Public
#   License, v. 2.0. If a copy of the MPL was not distributed with this
#   file, You can obtain one at http://mozilla.org/MPL/2.0/.

register_target ("ruby", "Ruby binding")

#   Target provides name space isolation for its functions
function target_ruby

# Work out Ruby name based on container.name and and set it as
# container.ruby_name.
function sanitize_ruby_container_name(container)
    my.container.ruby_name = "$(my.container.name:c)"

    # Replace default value from resolve_c_container().
    if my.container.ruby_name = "_"
        my.container.ruby_name = my.container.variadic ?? "args" ? "result"
    endif

    # Sanitize if it matches a Ruby keyword.

    # Ruby keywords. The only keyword not listed here is 'defined?', but that
    # won't be possible because of the 'c' pretty-print modifier above.
    my.ruby_keywords_regexp = "^(BEGIN|END|__ENCODING__|__END__|__FILE__|__LINE__|alias|and|begin|break|case|class|def|do|else|elsif|end|ensure|false|for|if|in|module|next|nil|not|or|redo|rescue|retry|return|self|super|then|true|undef|unless|until|when|while|yield)$"

    if regexp.match (my.ruby_keywords_regexp, my.container.ruby_name)
        my.container.ruby_name += "_"
    endif
endfunction

function resolve_ruby_container (container)
    sanitize_ruby_container_name(my.container)

    # Defaults
    my.container.ruby_ffi_type = ":pointer"
    my.container.ruby_doc_type = "::FFI::Pointer, #to_ptr"

    # All C types should be transformed to a type name recognized by FFI.
    # To handle more C types, add support for them here.
    if my.container.variadic
        my.container.ruby_doc_type = "Array<Object>"
        my.container.ruby_ffi_type = ":varargs"
    elsif my.container.c_type = "void"
        my.container.ruby_doc_type = "void"
        my.container.ruby_ffi_type = ":void"
    elsif my.container.c_type = "size_t"
        my.container.ruby_doc_type = "Integer, #to_int, #to_i"
        my.container.ruby_ffi_type = ":size_t"
        my.container.coerce_to_c = "Integer($(my.container.ruby_name:))"
    elsif my.container.c_type = "int"
        my.container.ruby_doc_type = "Integer, #to_int, #to_i"
        my.container.ruby_ffi_type = ":int"
        my.container.coerce_to_c = "Integer($(my.container.ruby_name:))"
    elsif regexp.match ("^(uint[0-9]+)_t$", my.container.c_type, match)
        my.container.ruby_doc_type = "Integer, #to_int, #to_i"
        my.container.ruby_ffi_type = ":$(match:)"
        my.container.coerce_to_c = "Integer($(my.container.ruby_name:))"
    elsif my.container.c_type = "float"
        my.container.ruby_doc_type = "Float, #to_f"
        my.container.ruby_ffi_type = ":float"
        my.container.coerce_to_c = "Float($(my.container.ruby_name:))"
    elsif my.container.c_type = "double"
        my.container.ruby_doc_type = "Float, #to_f"
        my.container.ruby_ffi_type = ":double"
        my.container.coerce_to_c = "Float($(my.container.ruby_name:))"
    elsif my.container.c_type = "bool"
        my.container.ruby_doc_type = "Boolean"
        my.container.ruby_ffi_type = ":bool"
        my.container.coerce_to_c = "!(0==$(my.container.ruby_name:)||!$(my.container.ruby_name:)) # boolean"
    elsif my.container.c_type = "const char *"
        my.container.ruby_doc_type = "String, #to_s, nil"
        my.container.ruby_ffi_type = ":string"
    elsif my.container.c_type = "char *"
        if my.container.fresh
            my.container.ruby_doc_return_type = "::FFI::AutoPointer"
            # if it's a fresh string that we have to free() when done with it,
            # wrap pointer in an FFI::AutoPointer
            my.container.coerce_to_ruby = "::FFI::AutoPointer.new($(my.container.ruby_name:), LibC.method(:free))"
        endif
    elsif my.container.c_type = "byte"
        my.container.ruby_doc_type = "Integer, #to_int, #to_i"
        my.container.ruby_ffi_type = ":char"
        my.container.coerce_to_c = "Integer($(my.container.ruby_name:))"
    elsif my.container.c_type = "SOCKET"
        my.container.ruby_doc_type = "Integer or FFI::Pointer"
        my.container.ruby_ffi_type = "(::FFI::Platform.unix? ? :int : :uint64)" # support for Unix & Win64
    elsif count (project.class, defined (class.RubyName) & (my.container.type = class.c_name))
        for project.class where (defined (class.RubyName) & (my.container.type = class.c_name))
            if my.container.by_reference
                if defined (my.container.destructor_self)
                    my.container.coerce_to_c = "__ptr_give_ref"
                else
                    my.container.ruby_doc_type = "#__ptr_give_ref"
                    my.container.coerce_to_c = "$(my.container.ruby_name:).__ptr_give_ref"
                endif
            else
                my.container.ruby_doc_type = "$(class.RubyName:), #__ptr"
                my.container.coerce_to_c = "$(my.container.ruby_name:).__ptr if $(my.container.ruby_name:)"
                my.container.coerce_to_ruby = "$(class.RubyName:).__new $(my.container.ruby_name:), "
                my.container.coerce_to_ruby += my.container.fresh ?? "true" ? "false"
            endif
        endfor
    endif
endfunction

function resolve_ruby_method (method)
    my.method.ruby_name = "$(my.method.name:c)"
    for my.method.argument
        resolve_ruby_container (argument)
    endfor
    for my.method.return as ret
        resolve_ruby_container (ret)
    endfor
endfunction

# The line that attaches the function to the project's FFI module
# like: attach_function my_project_method, [:pointer], :int, **opts
function ruby_ffi_attach_definition(method)
    my.attach_definition = "attach_function :$(class.c_name)_$(method.c_name:), ["
    if !my.method.singleton
        my.attach_definition += ":pointer"
        if count (my.method.argument)
            my.attach_definition += ", "
        endif
    endif
    for my.method.argument
        my.attach_definition += "$(argument.ruby_ffi_type:)"
        if !last ()
            my.attach_definition += ", "
        endif
    endfor
    my.attach_definition += "], $(method->return.ruby_ffi_type:), **opts"
    return my.attach_definition
endfunction


# Ruby code that warns about unavailable function and creates a placeholder
# function that just raises NotImplementedError with a helpful message.
.macro ruby_unimplemented_method_definition(method)
        if $VERBOSE || $DEBUG
          warn "The $(method.STATE) function $(class.c_name:)_$(method.name:c)()" +
            " is not provided by the installed $(project.name:) library."
        end
        def self.$(class.c_name:)_$(method.c_name:)(*)
.       if method.state = 'draft'
          raise NotImplementedError, "compile $(project.name:) with --enable-drafts"
.       else
          raise NotImplementedError, "update your code or downgrade the $(project.name:) library"
.       endif
        end
.endmacro

# Returns the Ruby method call without arguments,
# like: ::MyProject::FFI.my_class_my_method
function ruby_method_call_without_arguments(method)
    # must not contain newline at the end
    my.call = "::$(project.RubyName:)::FFI.$(class.c_name:)_$(my.method.c_name:)"
    return my.call
endfunction

# The arguments passed to the inner method call,
# like: arg1, arg2, args*
#
# If it's a singleton method, or the class method of a polymorphic method, make
# sure to set self_p first (before the call).
function ruby_method_call_arguments(method)
    my.args = ""
    if !my.method.singleton
        my.args += "self_p"
        if count(my.method.argument)
            my.args += ", "
        endif
    endif
    for my.method.argument
        my.args += argument.variadic ?? "*" ? ""
        my.args += argument.ruby_name
        if !last ()
            my.args += ", "
        endif
    endfor
    return my.args
endfunction

function ruby_method_signature_arguments(method)
    my.args = ""
    for my.method.argument
        if !(my.method.is_destructor & first())
            my.args += argument.variadic ?? "*" ? ""
            my.args += argument.ruby_name
            if !last ()
                my.args += ", "
            endif
        endif
    endfor
    return my.args
endfunction

# The first line of the monomorphic method definition (either class or instance method)
# like: def my_method(arg1, arg2)
#   or: def self.my_method(arg1, arg2)
function ruby_monomorphic_method_signature(method)
    my.def_line = ""
    if my.method.singleton & !my.method.is_destructor
        my.def_line += "self."
    endif
    my.def_line += "$(my.method.c_name:)($(ruby_method_signature_arguments(my.method)))"
    return my.def_line
endfunction

# Ruby methods, which take a pointer to the receiving object,
# like: def self.my_method(self_p, arg1, arg2)
function ruby_polymorphic_method_signature(method)
    my.def_line = "self.$(my.method.c_name:)(self_p"
    my.def_line += count(my.method.argument) ?? ", " ? ""
    my.def_line += ruby_method_signature_arguments(my.method)
    my.def_line += ")"
    return my.def_line
endfunction

function ruby_doc_return_type (method)
    if defined(my.method->return.ruby_doc_return_type)
        return my.method->return.ruby_doc_return_type
    endif

    if defined(string.locate (my.method->return.ruby_doc_type, ","))
        # turn "Integer, #to_int, #to_i" into "Integer"
        return string.prefix (my.method->return.ruby_doc_type, ",")
    else
        return my.method->return.ruby_doc_type
    endif
endfunction

function ruby_doc_arg_description (argument)
    if my.argument.variadic
      return " see https://github.com/ffi/ffi/wiki/examples#using-varargs"
    else
      return ""
    endif
endfunction

function resolve_ruby_class (class)
    for my.class.constructor as method
        resolve_ruby_method (method)
    endfor
    for my.class.destructor as method
        resolve_ruby_method (method)
    endfor
    for my.class.method
        resolve_ruby_method (method)
    endfor
    for my.class.callback_type as method
        resolve_ruby_method (method)
    endfor
endfunction

.macro generate_ruby_binding
.directory.create ("bindings/ruby/lib/$(project.name:c)/ffi")
.output "bindings/ruby/lib/$(project.name:c)/ffi/version.rb"
$(project.GENERATED_WARNING_HEADER:)

module $(project.RubyName:)
  module FFI
    VERSION = '$(project->version.major).$(project->version.minor).$(project->version.patch)'
  end
end

$(project.GENERATED_WARNING_HEADER:)
.#
.output "bindings/ruby/lib/$(project.name:c)/ffi.rb"
$(project.GENERATED_WARNING_HEADER:)

require 'ffi'
require_relative 'ffi/version'

module $(project.RubyName:)
  module FFI
    module LibC
      extend ::FFI::Library
      ffi_lib ::FFI::Platform::LIBC
      attach_function :free, [ :pointer ], :void, blocking: true
    end

    extend ::FFI::Library

    def self.available?
      @available
    end

    begin
      lib_name = '$(project.libname)'
      lib_dirs = ['/usr/local/lib', '/opt/local/lib', '/usr/lib64']
      env_name = "#{lib_name.upcase}_PATH"
      lib_dirs = [*ENV[env_name].split(':'), *lib_dirs] if ENV[env_name]
      lib_paths = lib_dirs.map { |path| "#{path}/#{lib_name}.#{::FFI::Platform::LIBSUFFIX}" }
      ffi_lib lib_paths + [lib_name]
      @available = true
    rescue LoadError
      warn ""
      warn "WARNING: ::$(project.RubyName:)::FFI is not available without $(project.libname)."
      warn ""
      @available = false
    end

    if available?
      opts = {
        blocking: true  # only necessary on MRI to deal with the GIL.
      }
.for class where defined (class.api) & class.private = "0"

.for constructor as method
.  if method.state = 'draft' | method.state = 'deprecated'
      begin # $(method.STATE) method
        $(ruby_ffi_attach_definition (method))
      rescue ::FFI::NotFoundError
.       ruby_unimplemented_method_definition (method)
      end
.  else
      $(ruby_ffi_attach_definition (method))
.  endif
.endfor
.for destructor as method
.  if method.state = 'draft' | method.state = 'deprecated'
      begin # $(method.STATE) method
        $(ruby_ffi_attach_definition (method))
      rescue ::FFI::NotFoundError
.       ruby_unimplemented_method_definition (method)
      end
.  else
      $(ruby_ffi_attach_definition (method))
.  endif
.endfor
.for method
.  if method.state = 'draft' | method.state = 'deprecated'
      begin # $(method.STATE) method
        $(ruby_ffi_attach_definition (method))
      rescue ::FFI::NotFoundError
.       ruby_unimplemented_method_definition (method)
      end
.  else
      $(ruby_ffi_attach_definition (method))
.  endif
.endfor

      require_relative 'ffi/$(class.ruby_require:)'
.endfor
    end
  end
end

$(project.GENERATED_WARNING_HEADER:)
.#
.for class where defined (class.api) & class.private = "0"
.output "bindings/ruby/lib/$(project.name:c)/ffi/$(class.ruby_require:).rb"
$(project.GENERATED_WARNING_HEADER:)

module $(project.RubyName:)
  module FFI

    # $(class.description:no,block)
    # @note This class is 100% generated using zproject.
.    # TODO: extract boilerplate into a reusable module
    class $(class.RubyName:)
.for class.constant
      # $(constant.description:no,block)
      $(CONSTANT.NAME:c) = $(constant.value)

.endfor
      # Raised when one tries to use an instance of {$(class.RubyName:)} after
      # the internal pointer to the native object has been nullified.
      class DestroyedError < RuntimeError; end

      # Boilerplate for self pointer, initializer, and finalizer
      class << self
        alias :__new :new
      end
      # Attaches the pointer _ptr_ to this instance and defines a finalizer for
      # it if necessary.
      # @param ptr [::FFI::Pointer]
      # @param finalize [Boolean]
      def initialize(ptr, finalize = true)
        @ptr = ptr
        if @ptr.null?
.          # TODO: extract to method #attach_native(ptr)
          @ptr = nil # Remove null pointers so we don't have to test for them.
        elsif finalize
          @finalizer = self.class.create_finalizer_for @ptr
          ObjectSpace.define_finalizer self, @finalizer
        end
      end
.for class.destructor where count (destructor.argument) = 1
.   if first ()
.       class.has_ruby_finalizer = 1
      # @param ptr [::FFI::Pointer]
      # @return [Proc]
      def self.create_finalizer_for(ptr)
        Proc.new do
          ptr_ptr = ::FFI::MemoryPointer.new :pointer
          ptr_ptr.write_pointer ptr
          ::$(project.RubyName:)::FFI.$(class.c_name)_$(destructor.c_name) ptr_ptr
        end
      end
.   endif
.endfor
.if !defined (class.has_ruby_finalizer)
.# TODO: just raise an ImplicitDestroyError
      # @return [Proc]
      def self.create_finalizer_for(ptr)
        Proc.new do
          "WARNING: "\\
          "Objects of type #{self} cannot be destroyed implicitly. "\\
          "Please call the correct destroy method with the relevant arguments."
        end
      end
.endif
      # @return [Boolean]
      def null?
        !@ptr or @ptr.null?
      end
      # Return internal pointer
      # @return [::FFI::Pointer]
      def __ptr
        raise DestroyedError unless @ptr
        @ptr
      end
      # So external Libraries can just pass the Object to a FFI function which expects a :pointer
      alias_method :to_ptr, :__ptr
      # Nullify internal pointer and return pointer pointer.
      # @note This detaches the current instance from the native object
      #   and thus makes it unusable.
      # @return [::FFI::MemoryPointer] the pointer pointing to a pointer
      #   pointing to the native object
      def __ptr_give_ref
        raise DestroyedError unless @ptr
        ptr_ptr = ::FFI::MemoryPointer.new :pointer
        ptr_ptr.write_pointer @ptr
        __undef_finalizer if @finalizer
        @ptr = nil
        ptr_ptr
      end
      # Undefines the finalizer for this object.
      # @note Only use this if you need to and can guarantee that the native
      #   object will be freed by other means.
      # @return [void]
      def __undef_finalizer
        ObjectSpace.undefine_finalizer self
        @finalizer = nil
      end
.for callback_type

      # Create a new callback of the following type:
      # $(callback_type.description:no,block)
      #     $(c_callback_typedef (callback_type):no,block)
      #
      # @note WARNING: If your Ruby code doesn't retain a reference to the
      #   FFI::Function object after passing it to a C function call,
      #   it may be garbage collected while C still holds the pointer,
      #   potentially resulting in a segmentation fault.
      def self.$(callback_type.name)
        ::FFI::Function.new $(callback_type->return.ruby_ffi_type:), [\
.   for callback_type.argument
$(argument.ruby_ffi_type:)\
.       if !last ()
, \
.       endif
.   endfor
], blocking: true do \|\
.   for callback_type.argument
$(argument.ruby_name)\
.       if !last ()
, \
.       endif
.   endfor
\|
.   for callback_type.argument where defined (argument.coerce_to_ruby)
          $(argument.ruby_name) = $(argument.coerce_to_ruby:)
.   endfor
          result = yield \
.   for callback_type.argument
$(argument.ruby_name)\
.       if !last ()
, \
.       endif
.   endfor

.if defined (callback_type->return.coerce_to_c)
          result = $(callback_type->return.coerce_to_c:)
.endif
          result
        end
      end
.endfor
.for constructor as method

      # $(method.description:no,block)
.for method.argument
      # @param $(argument.ruby_name:) [$(argument.ruby_doc_type:)]
.endfor
      # @return [$(project.RubyName:)::$(class.RubyName:)]
      def $(ruby_monomorphic_method_signature(method))
.for method.argument where defined (argument.coerce_to_c)
        $(argument.ruby_name:) = $(argument.coerce_to_c:)
.endfor
        ptr = $(ruby_method_call_without_arguments(method))($(ruby_method_call_arguments(method)))
        __new ptr
      end
.endfor
.for destructor as method

      # $(method.description:no,block)
      #
      # @return [void]
      def $(ruby_monomorphic_method_signature(method))
        return unless @ptr
.for method.argument where defined (argument.coerce_to_c)
        $(argument.ruby_name:) = $(argument.coerce_to_c:)
.endfor
        result = $(ruby_method_call_without_arguments(method))($(ruby_method_call_arguments(method)))
.if defined (method->return.coerce_to_ruby)
        result = $(method->return.coerce_to_ruby:)
.endif
        result
      end
.endfor
.for method

      # $(method.description:no,block)
      #
.for method.argument
      # @param $(argument.ruby_name:) [$(argument.ruby_doc_type:)]$(ruby_doc_arg_description (argument):)
.endfor
      # @return [$(ruby_doc_return_type (method):)]
      def $(ruby_monomorphic_method_signature(method))
.if !method.singleton
        raise DestroyedError unless @ptr
.# we do this so actuall FFI call of monomorphic and polymorphic methods is the same
        self_p = @ptr
.endif
.for method.argument where defined (argument.coerce_to_c)
        $(argument.ruby_name:) = $(argument.coerce_to_c:)
.endfor
        result = $(ruby_method_call_without_arguments(method))($(ruby_method_call_arguments(method)))
.if defined (method->return.coerce_to_ruby)
        result = $(method->return.coerce_to_ruby:)
.endif
        result
      end
.if method.polymorphic & !method.singleton # only methods that aren't already singletons
.#
.# NOTE: polymorphic methods will result in 2 Ruby methods:
.# * a normal instance method (already produced above)
.# * a class ("singleton") method, which takes a polymorphic reference

      # $(method.description:no,block)
      #
      # This is the polymorphic version of #$(method.ruby_name:).
      #
      # @param self_p [$(project.RubyName:)::$(class.RubyName:), #__ptr, ::FFI::Pointer, nil]
      #   object reference to use this method on
.for method.argument
      # @param $(argument.ruby_name:) [$(argument.ruby_doc_type:)]$(ruby_doc_arg_description (argument):)
.endfor
      # @return [$(ruby_doc_return_type (method):)]
      def $(ruby_polymorphic_method_signature(method))
        self_p = self_p.__ptr if self_p.respond_to?(:__ptr)
.for method.argument where defined (argument.coerce_to_c)
        $(argument.ruby_name:) = $(argument.coerce_to_c:)
.endfor
        result = $(ruby_method_call_without_arguments(method))($(ruby_method_call_arguments(method)))
.if defined (method->return.coerce_to_ruby)
        result = $(method->return.coerce_to_ruby:)
.endif
        result
      end
.endif
.endfor
    end
  end
end

$(project.GENERATED_WARNING_HEADER:)
.endfor
.#
.if !file.exists ("bindings/ruby/Rakefile")
.output "bindings/ruby/Rakefile"

require 'rspec/core/rake_task'

task :default => :test

# Run tests.
RSpec::Core::RakeTask.new :test do |c|
end
.else
.   echo "NOT regenerating an existing bindings/ruby/Rakefile file; you might want to move yours out of the way and re-generate the project again to get updated settings"
.endif
.#
.directory.create ("bindings/ruby/spec")
.if !file.exists ("bindings/ruby/spec/spec_helper.rb")
.output "bindings/ruby/spec/spec_helper.rb"

require '$(project.name)/ffi'

RSpec.configure do |c|
  # Enable 'should' syntax
  c.expect_with(:rspec) { |c| c.syntax = [:should, :expect] }
  c.mock_with(:rspec)   { |c| c.syntax = [:should, :expect] }
end
.else
.   echo "NOT regenerating an existing bindings/ruby/spec/spec_helper.rb file; you might want to move yours out of the way and re-generate the project again to get updated settings"
.endif
.#
.output "bindings/ruby/spec/ffi_spec.rb"
$(project.GENERATED_WARNING_HEADER:)

require 'spec_helper'

describe ::$(project.RubyName:)::FFI do
  it { should be }
end

$(project.GENERATED_WARNING_HEADER:)
.endmacro

    project.RubyName = "$(project.name:Pascal)"
    for class where defined (class.api) & class.private = "0"
        class.ruby_require = string.replace (class.c_name, "$(project.name)_|")
        class.RubyName = "$(class.ruby_require:Pascal)"
    endfor
    for class where defined (class.api) & class.private = "0"
        resolve_ruby_class (class)
    endfor
    generate_ruby_binding ()
endfunction