wrapture 0.2.2 → 0.3.0

data/lib/wrapture/constant_spec.rb

@@ -1,34 +1,51 @@
 # frozen_string_literal: true
 
+require 'wrapture/normalize'
+
 module Wrapture
-  ##
   # A description of a constant.
   class ConstantSpec
+    # Normalizes a hash specification of a constant. Normalization will check
+    # for things like invalid keys, duplicate entries in include lists, and
+    # will set missing keys to their default value (for example, an empty list
+    # if no includes are given).
     def self.normalize_spec_hash(spec)
-      normalized_spec = spec.dup
+      normalized = spec.dup
 
-      normalized_spec['includes'] ||= []
-      normalized_spec['includes'].uniq!
+      normalized['version'] = Wrapture.spec_version(spec)
+      normalized['includes'] = Wrapture.normalize_includes spec['includes']
 
-      normalized_spec
+      normalized
     end
 
+    # Creates a constant spec based on the provided hash spec
+    #
+    # The hash must have the following keys:
+    # name:: the name of the constant
+    # type:: the type of the constant
+    # value:: the value to assign to the constant
+    # includes::  a list of includes that need to be added in order for this
+    # constant to be valid (for example, includes for the type and value).
     def initialize(spec)
       @spec = ConstantSpec.normalize_spec_hash spec
     end
 
+    # A list of includes needed for the declaration of this constant.
     def declaration_includes
       @spec['includes'].dup
     end
 
+    # A list of includes needed for the definition of this constant.
     def definition_includes
       @spec['includes'].dup
     end
 
+    # The declaration of this constant.
     def declaration
       "static const #{ClassSpec.typed_variable(@spec['type'], @spec['name'])}"
     end
 
+    # The definition of this constant.
     def definition(class_name)
       expanded_name = "#{class_name}::#{@spec['name']}"
       "const #{@spec['type']} #{expanded_name} = #{@spec['value']}"

data/lib/wrapture/constants.rb

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+# Copyright 2019-2020 Joel E. Anderson
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Wrapture
+  # A string denoting an equivalent struct type or value.
+  EQUIVALENT_STRUCT_KEYWORD = 'equivalent-struct'
+
+  # A string denoting a pointer to an equivalent struct type or value.
+  EQUIVALENT_POINTER_KEYWORD = 'equivalent-struct-pointer'
+
+  # A string denoting the return value of a wrapped function call.
+  RETURN_VALUE_KEYWORD = 'return-value'
+
+  # A list of all keywords.
+  KEYWORDS = [EQUIVALENT_STRUCT_KEYWORD, EQUIVALENT_POINTER_KEYWORD,
+              RETURN_VALUE_KEYWORD].freeze
+end

data/lib/wrapture/errors.rb

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+# Copyright 2019 Joel E. Anderson
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Wrapture
+  # An error from the Wrapture library
+  class WraptureError < StandardError
+  end
+
+  # The spec has a key that is not valid.
+  class InvalidSpecKey < WraptureError
+    # Creates an InvalidSpecKey with the given message. A list of valid values
+    # may optionally be passed to +valid_keys+ which will be added to the end
+    # of the message.
+    def initialize(message, valid_keys: [])
+      complete_message = message.dup
+
+      unless valid_keys.empty?
+        complete_message << ' (valid values are \''
+        complete_message << valid_keys.join('\', \'')
+        complete_message << '\')'
+      end
+
+      super(complete_message)
+    end
+  end
+
+  # The spec is missing a key that is required.
+  class MissingSpecKey < WraptureError
+    # Creates a MissingSpecKey with the given message.
+    def initialize(message)
+      super(message)
+    end
+  end
+
+  # Missing a namespace in the class spec
+  class NoNamespace < WraptureError
+  end
+
+  # The spec version is not supported by this version of Wrapture.
+  class UnsupportedSpecVersion < WraptureError
+  end
+end

data/lib/wrapture/function_spec.rb

@@ -1,74 +1,245 @@
+# SPDX-License-Identifier: Apache-2.0
+
 # frozen_string_literal: true
 
+# Copyright 2019-2020 Joel E. Anderson
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'wrapture/constants'
+require 'wrapture/errors'
+require 'wrapture/scope'
+require 'wrapture/wrapped_function_spec'
+
 module Wrapture
-  ##
   # A description of a function to be generated, including details about the
   # underlying implementation.
   class FunctionSpec
+    # Normalizes a hash specification of a function. Normalization will check
+    # for things like invalid keys, duplicate entries in include lists, and will
+    # set missing keys to their default values (for example, an empty list if no
+    # includes are given).
     def self.normalize_spec_hash(spec)
-      normalized_spec = spec.dup
+      normalized = spec.dup
+      param_types = {}
 
-      normalized_spec['params'] ||= []
-      normalized_spec['wrapped-function']['params'] ||= []
-      normalized_spec['wrapped-function']['includes'] ||= []
+      normalized['version'] = Wrapture.spec_version(spec)
+      normalized['virtual'] = Wrapture.normalize_boolean(spec, 'virtual')
 
-      if normalized_spec['return'].nil?
-        normalized_spec['return'] = {}
-        normalized_spec['return']['type'] = 'void'
+      normalized['params'] ||= []
+      normalized['params'].each do |param_spec|
+        param_types[param_spec['name']] = param_spec['type']
+        includes = Wrapture.normalize_includes(param_spec['includes'])
+        param_spec['includes'] = includes
       end
 
-      normalized_spec['return']['includes'] ||= []
-
-      normalized_spec
-    end
-
-    def self.param_list(spec)
-      return 'void' if spec['params'].empty?
-
-      params = []
-
-      spec['params'].each do |param|
-        params << ClassSpec.typed_variable(param['type'], param['name'])
+      if normalized['return'].nil?
+        normalized['return'] = {}
+        normalized['return']['type'] = 'void'
+        normalized['return']['includes'] = []
+      else
+        normalized['return']['type'] ||= 'void'
+        includes = Wrapture.normalize_includes(spec['return']['includes'])
+        normalized['return']['includes'] = includes
       end
 
-      params.join ', '
+      overload = Wrapture.normalize_boolean(normalized['return'], 'overloaded')
+      normalized['return']['overloaded'] = overload
+
+      normalized
     end
 
-    def initialize(spec, owner)
+    # Creates a function spec based on the provided function spec.
+    #
+    # The hash must have the following keys:
+    # name:: the name of the function
+    # params:: a list of parameter specifications
+    # wrapped-function:: a hash describing the function to be wrapped
+    #
+    # The wrapped-function must have a 'name' key with the name of the function,
+    # and a 'params' key with a list of parameters (each a hash with a 'name'
+    # and 'type' key). Optionally, it may also include an 'includes' key with a
+    # list of includes that are needed for this function to compile.
+    #
+    # The following keys are optional:
+    # static:: set to true if this is a static function.
+    def initialize(spec, owner = Scope.new, constructor: false,
+                   destructor: false)
       @owner = owner
       @spec = FunctionSpec.normalize_spec_hash(spec)
+      @wrapped = WrappedFunctionSpec.new(spec['wrapped-function'])
+      @constructor = constructor
+      @destructor = destructor
     end
 
-    def declaration_includes
-      @spec['return']['includes'].dup
+    # True if the function is a constructor, false otherwise.
+    def constructor?
+      @constructor
     end
 
-    def definition_includes
+    # A list of includes needed for the declaration of the function.
+    def declaration_includes
       includes = @spec['return']['includes'].dup
-      includes.concat @spec['wrapped-function']['includes']
+      includes.concat(param_includes)
+      includes.uniq
+    end
 
+    # A list of includes needed for the definition of the function.
+    def definition_includes
+      includes = @wrapped.includes
+      includes.concat(@spec['return']['includes'])
+      includes.concat(param_includes)
       includes.uniq
     end
 
+    # A comma-separated list of parameters and resolved types fit for use in a
+    # function signature or declaration.
+    def param_list
+      return 'void' if @spec['params'].empty?
+
+      params = []
+
+      @spec['params'].each do |param|
+        type = resolve_type(param['type'])
+        params << ClassSpec.typed_variable(type, param['name'])
+      end
+
+      params.join(', ')
+    end
+
+    # Gives an expression for calling a given parameter within this function.
+    # Equivalent structs and pointers are resolved, as well as casts between
+    # types if they are known within the scope of this function.
+    def resolve_wrapped_param(param_spec)
+      used_param = @spec['params'].find { |p| p['name'] == param_spec['value'] }
+
+      if param_spec['value'] == EQUIVALENT_STRUCT_KEYWORD
+        @owner.this_struct
+      elsif param_spec['value'] == EQUIVALENT_POINTER_KEYWORD
+        @owner.this_struct_pointer
+      elsif used_param &&
+            @owner.type?(used_param['type']) &&
+            !param_spec['type'].nil?
+        param_class = @owner.type(used_param['type'])
+        param_class.cast_to(used_param['name'], param_spec['type'])
+      else
+        param_spec['value']
+      end
+    end
+
+    # The signature of the function.
     def signature
-      "#{@spec['name']}( #{FunctionSpec.param_list @spec} )"
+      "#{@spec['name']}( #{param_list} )"
     end
 
+    # The declaration of the function.
     def declaration
-      modifier_prefix = @spec['static'] ? 'static ' : ''
+      return signature if @constructor || @destructor
+
+      modifier_prefix = if @spec['static']
+                          'static '
+                        elsif virtual?
+                          'virtual '
+                        else
+                          ''
+                        end
       "#{modifier_prefix}#{@spec['return']['type']} #{signature}"
     end
 
+    # Gives the definition of the function to a block, line by line.
     def definition(class_name)
-      return_type = @spec['return']['type']
-      yield "#{return_type} #{class_name}::#{signature} {"
-
-      wrapped_call = String.new
-      wrapped_call << "return #{return_type} ( " unless return_type == 'void'
-      wrapped_call << @owner.function_call(@spec['wrapped-function'])
-      wrapped_call << ' )' unless return_type == 'void'
-      yield "  #{wrapped_call};"
+      yield "#{return_prefix}#{class_name}::#{signature} {"
+
+      if @wrapped.error_check?
+        yield "  #{@wrapped.return_val_type} return_val;"
+        yield
+      end
+
+      call = @wrapped.call_from(self)
+      call_line = if @constructor
+                    "this->equivalent = #{call}"
+                  elsif @wrapped.error_check?
+                    "return_val = #{call}"
+                  elsif returns_value?
+                    "return #{return_cast(call)}"
+                  else
+                    call
+                  end
+
+      yield "  #{call_line};"
+
+      if @wrapped.error_check?
+        yield
+        @wrapped.error_check { |line| yield "  #{line}" }
+      end
+
       yield '}'
     end
+
+    # True if the function is virtual.
+    def virtual?
+      @spec['virtual']
+    end
+
+    private
+
+    # A list of includes needed for the parameters of the function.
+    def param_includes
+      includes = []
+
+      @spec['params'].each do |param_spec|
+        includes.concat(param_spec['includes'])
+      end
+
+      includes
+    end
+
+    # A resolved type name.
+    def resolve_type(type)
+      if type == EQUIVALENT_STRUCT_KEYWORD
+        "struct #{@owner.struct_name}"
+      elsif type == EQUIVALENT_POINTER_KEYWORD
+        "struct #{@owner.struct_name} *"
+      else
+        type
+      end
+    end
+
+    # The function to use to create the return value of the function.
+    def return_cast(value)
+      if @spec['return']['type'] == @wrapped.return_val_type
+        value
+      elsif @spec['return']['overloaded']
+        "new#{@spec['return']['type'].chomp('*').strip} ( #{value} )"
+      else
+        "#{@spec['return']['type']} ( #{value} )"
+      end
+    end
+
+    # The return type prefix to use for the function definition.
+    def return_prefix
+      if @constructor || @destructor
+        ''
+      elsif @spec['return']['type'].end_with?('*')
+        @spec['return']['type']
+      else
+        "#{@spec['return']['type']} "
+      end
+    end
+
+    # True if the function returns a value.
+    def returns_value?
+      !@constructor && !@destructor && @spec['return']['type'] != 'void'
+    end
   end
 end

data/lib/wrapture/normalize.rb

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+# Copyright 2019 Joel E. Anderson
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'wrapture/version'
+
+module Wrapture
+  # Normalizes a spec key to be boolean, raising an error if it is not. Keys
+  # that are not present are defaulted to false.
+  def self.normalize_boolean(spec, key)
+    is_boolean = [true, false].include?(spec[key])
+    error_msg = "'#{key}' key may only be true or false"
+    raise(InvalidSpecKey, error_msg) unless !spec.key?(key) || is_boolean
+
+    spec.key?(key) && spec[key]
+  end
+
+  # Normalizes an include list for an element. A single string will be converted
+  # into an array containing the single string, and a nil will be converted to
+  # an empty array.
+  def self.normalize_includes(includes)
+    if includes.nil?
+      []
+    elsif includes.is_a? String
+      [includes]
+    else
+      includes.uniq
+    end
+  end
+
+  # Returns the spec version for the provided spec. If the version is not
+  # provided in the spec, the newest version that the spec is compliant with
+  # will be returned instead.
+  #
+  # If this spec uses a version unsupported by this version of Wrapture or the
+  # spec is otherwise invalid, an exception is raised.
+  def self.spec_version(spec)
+    if spec.key?('version') && !Wrapture.supports_version?(spec['version'])
+      raise UnsupportedSpecVersion
+    end
+
+    if spec.key?('version')
+      spec['version']
+    else
+      Wrapture::VERSION
+    end
+  end
+end