wrapture 0.3.0 → 0.4.0

data/lib/wrapture/constant_spec.rb

@@ -1,6 +1,22 @@
+# SPDX-License-Identifier: Apache-2.0
+
 # frozen_string_literal: true
 
-require 'wrapture/normalize'
+#--
+# 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 description of a constant.
@@ -10,6 +26,8 @@ module Wrapture
     # will set missing keys to their default value (for example, an empty list
     # if no includes are given).
     def self.normalize_spec_hash(spec)
+      Comment.validate_doc(spec['doc']) if spec.key?('doc')
+
       normalized = spec.dup
 
       normalized['version'] = Wrapture.spec_version(spec)
@@ -26,8 +44,13 @@ module Wrapture
     # 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).
+    #
+    # The following keys are optional:
+    # doc:: a string containing the documentation for this constant
     def initialize(spec)
-      @spec = ConstantSpec.normalize_spec_hash spec
+      @spec = ConstantSpec.normalize_spec_hash(spec)
+      @doc = @spec.key?('doc') ? Comment.new(@spec['doc']) : nil
+      @type = TypeSpec.new(@spec['type'])
     end
 
     # A list of includes needed for the declaration of this constant.
@@ -40,9 +63,11 @@ module Wrapture
       @spec['includes'].dup
     end
 
-    # The declaration of this constant.
+    # Yields each line of the declaration of this constant, including any
+    # documentation.
     def declaration
-      "static const #{ClassSpec.typed_variable(@spec['type'], @spec['name'])}"
+      @doc&.format_as_doxygen(max_line_length: 76) { |line| yield line }
+      yield "static const #{@type.variable(@spec['name'])};"
     end
 
     # The definition of this constant.

data/lib/wrapture/constants.rb

@@ -2,6 +2,7 @@
 
 # frozen_string_literal: true
 
+#--
 # Copyright 2019-2020 Joel E. Anderson
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,6 +16,7 @@
 # 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.
@@ -26,7 +28,13 @@ module Wrapture
   # A string denoting the return value of a wrapped function call.
   RETURN_VALUE_KEYWORD = 'return-value'
 
+  # A string denoting a reference to the object a method is called on.
+  SELF_REFERENCE_KEYWORD = 'self-reference'
+
+  # A string denoting a reference to a template.
+  TEMPLATE_USE_KEYWORD = 'use-template'
+
   # A list of all keywords.
   KEYWORDS = [EQUIVALENT_STRUCT_KEYWORD, EQUIVALENT_POINTER_KEYWORD,
-              RETURN_VALUE_KEYWORD].freeze
+              RETURN_VALUE_KEYWORD, TEMPLATE_USE_KEYWORD].freeze
 end

data/lib/wrapture/enum_spec.rb

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+#--
+# Copyright 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 description of an enumeration.
+  class EnumSpec
+    # Returns a normalized copy of a hash specification of an enumeration in
+    # place. See normalize_spec_hash! for details.
+    def self.normalize_spec_hash(spec)
+      normalize_spec_hash!(Marshal.load(Marshal.dump(spec)))
+    end
+
+    # Normalizes a hash specification of an enumeration in place. Normalization
+    # will remove duplicate entries in include lists and check for a name key.
+    def self.normalize_spec_hash!(spec)
+      unless spec.key?('name')
+        raise MissingSpecKey, 'a name is required for enumerations'
+      end
+
+      if spec.key?('elements')
+        unless spec['elements'].is_a?(Array)
+          raise InvalidSpecKey, 'the elements key must be an array'
+        end
+      else
+        raise MissingSpecKey, 'elements are required for enumerations'
+      end
+
+      spec['includes'] = Wrapture.normalize_includes(spec['includes'])
+      spec['elements'].each do |element|
+        element['includes'] = Wrapture.normalize_includes(element['includes'])
+      end
+
+      spec
+    end
+
+    # Creates an enumeration specification based on the provided hash spec.
+    def initialize(spec)
+      @spec = EnumSpec.normalize_spec_hash(spec)
+
+      @doc = Comment.new(@spec.fetch('doc', nil))
+    end
+
+    # Generates the wrapper definition file.
+    def generate_wrapper
+      filename = "#{@spec['name']}.hpp"
+
+      File.open(filename, 'w') do |file|
+        definition_contents do |line|
+          file.puts(line)
+        end
+      end
+
+      [filename]
+    end
+
+    # The name of the enumeration.
+    def name
+      @spec['name']
+    end
+
+    private
+
+    # Yields each line of the definition of the wrapper for this enum.
+    def definition_contents
+      indent = 0
+
+      yield "#ifndef #{header_guard}"
+      yield "#define #{header_guard}"
+      yield
+
+      definition_includes.each { |filename| yield "#include <#{filename}>" }
+      yield
+
+      if @spec.key?('namespace')
+        yield "namespace #{@spec['namespace']} {"
+        yield
+        indent += 2
+      end
+
+      @doc.format_as_doxygen(max_line_length: 76) do |line|
+        yield "#{' ' * indent}#{line}"
+      end
+
+      yield "#{' ' * indent}enum class #{name} {"
+      indent += 2
+
+      elements = @spec['elements']
+      elements[0...-1].each do |element|
+        element_doc(element) { |line| yield "#{' ' * indent}#{line}" }
+        element_definition(element) { |line| yield "#{' ' * indent}#{line}," }
+      end
+
+      element_doc(elements.last) { |line| yield "#{' ' * indent}#{line}" }
+      element_definition(elements.last) do |line|
+        yield "#{' ' * indent}#{line}"
+      end
+
+      indent -= 2
+      yield "#{' ' * indent}};"
+      yield
+      yield '}' if @spec.key?('namespace')
+      yield
+      yield "#endif /* #{header_guard} */"
+    end
+
+    # A list of the includes needed for the definition of the enumeration.
+    def definition_includes
+      includes = @spec['includes'].dup
+
+      @spec['elements'].each do |element|
+        includes.concat(element['includes'])
+      end
+
+      includes.uniq
+    end
+
+    # Yields each line of the definition of an element.
+    def element_definition(element)
+      if element.key?('value')
+        yield "#{element['name']} = #{element['value']}"
+      else
+        yield element['name']
+      end
+    end
+
+    # Yields each line of the documentation for an element.
+    def element_doc(element)
+      doc = Comment.new(element.fetch('doc', nil))
+      doc.format_as_doxygen(max_line_length: 74) { |line| yield line }
+    end
+
+    # The header guard for the enumeration.
+    def header_guard
+      "__#{@spec['name'].upcase}_HPP"
+    end
+  end
+end

data/lib/wrapture/errors.rb

@@ -2,7 +2,8 @@
 
 # frozen_string_literal: true
 
-# Copyright 2019 Joel E. Anderson
+#--
+# 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.
@@ -15,12 +16,29 @@
 # 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
 
+  # A documentation string is invalid.
+  class InvalidDoc < WraptureError
+    # Creates an InvalidDoc with the given message.
+    def initialize(message)
+      super(message)
+    end
+  end
+
+  # A template has been invoked in an unsupported way.
+  class InvalidTemplateUsage < WraptureError
+    # Creates an InvalidTemplateUsage with the given message.
+    def initialize(message)
+      super(message)
+    end
+  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
@@ -51,6 +69,14 @@ module Wrapture
   class NoNamespace < WraptureError
   end
 
+  # The spec cannot be defined due to missing information.
+  class UndefinableSpec < WraptureError
+    # Creates an UndefinableSpec with error +message+.
+    def initialize(message)
+      super(message)
+    end
+  end
+
   # The spec version is not supported by this version of Wrapture.
   class UnsupportedSpecVersion < WraptureError
   end

data/lib/wrapture/function_spec.rb

@@ -2,6 +2,7 @@
 
 # frozen_string_literal: true
 
+#--
 # Copyright 2019-2020 Joel E. Anderson
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,43 +16,38 @@
 # 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
+    # Returns a copy of the return type specification +spec+.
+    def self.normalize_return_hash(spec)
+      if spec.nil?
+        { 'type' => 'void', 'includes' => [] }
+      else
+        normalized = Marshal.load(Marshal.dump(spec))
+        Comment.validate_doc(spec['doc']) if spec.key?('doc')
+        normalized['type'] ||= 'void'
+        normalized['includes'] = Wrapture.normalize_includes(spec['includes'])
+        normalized
+      end
+    end
+
     # 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)
+      Comment.validate_doc(spec['doc']) if spec.key?('doc')
+
       normalized = spec.dup
-      param_types = {}
 
       normalized['version'] = Wrapture.spec_version(spec)
       normalized['virtual'] = Wrapture.normalize_boolean(spec, 'virtual')
-
-      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
-
-      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
+      normalized['params'] = ParamSpec.normalize_param_list(spec['params'])
+      normalized['return'] = normalize_return_hash(spec['return'])
 
       overload = Wrapture.normalize_boolean(normalized['return'], 'overloaded')
       normalized['return']['overloaded'] = overload
@@ -66,22 +62,55 @@ module Wrapture
     # params:: a list of parameter specifications
     # wrapped-function:: a hash describing the function to be wrapped
     #
+    # Each parameter specification must have a 'name' key with the name of the
+    # parameter and a 'type' key with its type. The type key may be ommitted
+    # if the name of the parameter is '...' in which case the generated function
+    # will be made variadic. It may optionally have an 'includes' key with
+    # includes that are required (for example to support the type) and/or a
+    # 'doc' key with documentation of the parameter.
+    #
+    # Only one parameter named '...' is allowed in a specification. If more than
+    # one is provided, then only the first encountered will be used. This
+    # parameter should also be last - if it is not, it will be moved to the end
+    # of the parameter list during normalization.
+    #
     # 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.
+    # list of includes that are needed for this function to compile. The wrapped
+    # function may be left out entirely, but the function will not be definable
+    # if this is the case.
     #
     # The following keys are optional:
-    # static:: set to true if this is a static function.
+    # doc:: a string containing the documentation for this function
+    # return:: a specification of the return value for this function
+    # static:: set to true if this is a static function
+    #
+    # The return specification may have either a 'type' key with the name of the
+    # type the function returns, and/or a 'doc' key with documentation on the
+    # return value itself. If neither of these is needed, then the return
+    # specification may simply be omitted.
+    #
+    # The 'type' key of the return spec may also be set to 'self-reference'
+    # which will have the function return a reference to the instance it was
+    # called on. Of course, this cannot be used from a function that is not a
+    # class method.
     def initialize(spec, owner = Scope.new, constructor: false,
                    destructor: false)
       @owner = owner
       @spec = FunctionSpec.normalize_spec_hash(spec)
-      @wrapped = WrappedFunctionSpec.new(spec['wrapped-function'])
+      @wrapped = if @spec.key?('wrapped-function')
+                   WrappedFunctionSpec.new(@spec['wrapped-function'])
+                 end
+      @params = ParamSpec.new_list(@spec['params'])
+      @return_type = TypeSpec.new(@spec['return']['type'])
       @constructor = constructor
       @destructor = destructor
     end
 
+    # A TypeSpec describing the return type of this function.
+    attr_reader :return_type
+
     # True if the function is a constructor, false otherwise.
     def constructor?
       @constructor
@@ -90,61 +119,89 @@ module Wrapture
     # A list of includes needed for the declaration of the function.
     def declaration_includes
       includes = @spec['return']['includes'].dup
-      includes.concat(param_includes)
+      @params.each { |param| includes.concat(param.includes) }
+      includes.concat(@return_type.includes)
       includes.uniq
     end
 
+    # True if this function can be defined.
+    def definable?
+      definable_check
+    rescue UndefinableSpec
+      false
+    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)
+      @params.each { |param| includes.concat(param.includes) }
+      includes.concat(@return_type.includes)
+      includes << 'stdarg.h' if variadic?
       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?
+    # The name of the function.
+    def name
+      @spec['name']
+    end
 
-      params = []
+    # A string with the parameter list for this function.
+    def param_list
+      ParamSpec.signature(@params, self)
+    end
 
-      @spec['params'].each do |param|
-        type = resolve_type(param['type'])
-        params << ClassSpec.typed_variable(type, param['name'])
+    # The name of the function with the class name, if it exists.
+    def qualified_name
+      if @owner.is_a?(ClassSpec)
+        "#{@owner.name}::#{name}"
+      else
+        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'] }
+      used_param = @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'])
+      elsif param_spec['value'] == '...'
+        'variadic_args'
+      elsif castable?(param_spec)
+        param_class = @owner.type(used_param.type)
+        param_class.cast(used_param.name,
+                         param_spec['type'],
+                         used_param.type)
       else
         param_spec['value']
       end
     end
 
+    # Calls return_expression on the return type of this function. +func_name+
+    # is passed to return_expression if provided.
+    def return_expression(func_name: name)
+      resolved_return.return_expression(self, func_name: func_name)
+    end
+
     # The signature of the function.
     def signature
-      "#{@spec['name']}( #{param_list} )"
+      "#{name}( #{param_list} )"
     end
 
-    # The declaration of the function.
+    # Yields each line of the declaration of the function, including any
+    # documentation.
     def declaration
-      return signature if @constructor || @destructor
+      doc.format_as_doxygen(max_line_length: 76) { |line| yield line }
+
+      if @constructor || @destructor
+        yield "#{signature};"
+        return
+      end
 
       modifier_prefix = if @spec['static']
                           'static '
@@ -153,39 +210,72 @@ module Wrapture
                         else
                           ''
                         end
-      "#{modifier_prefix}#{@spec['return']['type']} #{signature}"
+
+      yield "#{modifier_prefix}#{return_expression};"
     end
 
-    # Gives the definition of the function to a block, line by line.
-    def definition(class_name)
-      yield "#{return_prefix}#{class_name}::#{signature} {"
+    # Gives the definition of the function in a block, line by line.
+    def definition
+      definable_check
 
-      if @wrapped.error_check?
-        yield "  #{@wrapped.return_val_type} return_val;"
-        yield
-      end
+      yield "#{return_expression(func_name: qualified_name)} {"
 
-      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};"
+      locals { |declaration| yield "  #{declaration}" }
+
+      yield "  va_start( variadic_args, #{@params[-2].name} );" if variadic?
 
       if @wrapped.error_check?
+        yield
+        yield "  #{wrapped_call_expression};"
         yield
         @wrapped.error_check { |line| yield "  #{line}" }
+      else
+        yield "  #{wrapped_call_expression};"
       end
 
+      yield '  va_end( variadic_args );' if variadic?
+
+      yield '  return *this;' if @return_type.self?
+
       yield '}'
     end
 
+    # A Comment holding the function documentation.
+    def doc
+      comment = String.new
+      comment << @spec['doc'] if @spec.key?('doc')
+
+      @params
+        .reject { |param| param.doc.empty? }
+        .each { |param| comment << "\n\n" << param.doc.text }
+
+      if @spec['return'].key?('doc')
+        comment << "\n\n@return " << @spec['return']['doc']
+      end
+
+      Comment.new(comment)
+    end
+
+    # A resolved type, given a TypeSpec +type+. Resolved types will not have any
+    # keywords like +equivalent-struct+, which will be resolved to their
+    # effective type.
+    def resolve_type(type)
+      if type.equivalent_struct?
+        TypeSpec.new("struct #{@owner.struct_name}")
+      elsif type.equivalent_pointer?
+        TypeSpec.new("struct #{@owner.struct_name} *")
+      elsif type.self?
+        TypeSpec.new("#{@owner.name}&")
+      else
+        type
+      end
+    end
+
+    # True if the function is variadic.
+    def variadic?
+      @params.last&.variadic?
+    end
+
     # True if the function is virtual.
     def virtual?
       @spec['virtual']
@@ -193,26 +283,35 @@ module Wrapture
 
     private
 
-    # A list of includes needed for the parameters of the function.
-    def param_includes
-      includes = []
+    # The resolved type of the return type.
+    def resolved_return
+      @return_type.resolve(self)
+    end
 
-      @spec['params'].each do |param_spec|
-        includes.concat(param_spec['includes'])
-      end
+    # True if the provided wrapped param spec can be cast to when used in this
+    # function.
+    def castable?(wrapped_param)
+      param = @params.find { |p| p.name == wrapped_param['value'] }
 
-      includes
+      !param.nil? &&
+        !wrapped_param['type'].nil? &&
+        @owner.type?(param.type)
     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
+    # Raises an exception if this function cannot be defined as is. Returns
+    # true otherwise.
+    def definable_check
+      if @wrapped.nil?
+        raise UndefinableSpec, 'no wrapped function was specified'
       end
+
+      true
+    end
+
+    # Yields a declaration of each local variable used by the function.
+    def locals
+      yield 'va_list variadic_args;' if variadic?
+      yield "#{@wrapped.return_val_type} return_val;" if @wrapped.error_check?
     end
 
     # The function to use to create the return value of the function.
@@ -226,20 +325,25 @@ module Wrapture
       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
+    # True if the function returns the result of the wrapped function call.
+    def returns_call_result?
+      !@constructor && !@destructor &&
+        !%w[void self-reference].include?(@spec['return']['type'])
     end
 
-    # True if the function returns a value.
-    def returns_value?
-      !@constructor && !@destructor && @spec['return']['type'] != 'void'
+    # The expression containing the call to the underlying wrapped function.
+    def wrapped_call_expression
+      call = @wrapped.call_from(self)
+
+      if @constructor
+        "this->equivalent = #{call}"
+      elsif @wrapped.error_check?
+        "return_val = #{call}"
+      elsif returns_call_result?
+        "return #{return_cast(call)}"
+      else
+        call
+      end
     end
   end
 end