wrapture 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb5e341af7e97543a1ee20d0a4d962f461372c5ef948de704c1508e346ca71c7
-  data.tar.gz: af4cf7f89111e459a866107ebc46823b81d6a4de0bbdd944a3b5294dc0ad9220
+  metadata.gz: 0a808f785d4a2a78afea58ed889d1b177f73dbd820206bd1d0ff55f0a9de1d16
+  data.tar.gz: 91197fff6cf5343c365b8f4ad3a2efdc913576355bc90a82c5040fa28442058b
 SHA512:
-  metadata.gz: 9a3e8e31db51f492ab179bc047de225cd7db2ceb7156c1734ce45929cbce325f38abd40d54637c87839d0b0cc2bbf41ec8cf491d128e0a61a01aaafa724c6ef3
-  data.tar.gz: eb13f2975a79f0caf669b3a72408e9af1c61155598ce516c43d406e2b95f3016550724e2efe35766da6ebec0695d8052c2fa9b2149cedad87d0c89eab7672e44
+  metadata.gz: 561bdb4547a1e4617bba11c99921b2b475e4e6178e58202b066f51e2e6fee89ce11b64408d33e73952869dcef1ac1e2c793295f1bb79ac9bdcbee0e6b9e4eb49
+  data.tar.gz: ed3a3e6b8a2062bc0938cd18253f9f90f64893a2cfc26b9b4fe0f043ca66e2806f75cc9acfc0054cf18e2a99f93cd1b6fd089561a91363f76bd4accc7cae22b5

data/bin/wrapture

@@ -1,7 +1,23 @@
 #!/usr/bin/env ruby
 
+# 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 'yaml'
 require 'wrapture'
 
@@ -10,8 +26,16 @@ scope = Wrapture::Scope.new
 ARGV.each do |spec_file|
   spec = YAML.load_file(spec_file)
 
-  spec['classes'].each do |class_spec|
-    Wrapture::ClassSpec.new(class_spec, scope: scope)
+  spec.fetch('templates', []).each do |temp_spec|
+    scope << Wrapture::TemplateSpec.new(temp_spec)
+  end
+
+  spec.fetch('classes', []).each do |class_spec|
+    scope.add_class_spec_hash(class_spec)
+  end
+
+  spec.fetch('enums', []).each do |enum_spec|
+    scope.add_enum_spec_hash(enum_spec)
   end
 end
 

data/lib/wrapture.rb

@@ -2,7 +2,7 @@
 
 # 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.
@@ -19,15 +19,20 @@
 # Classes and functions for generating language wrappers
 module Wrapture
   require 'wrapture/action_spec'
+  require 'wrapture/comment'
   require 'wrapture/constant_spec'
   require 'wrapture/constants'
   require 'wrapture/class_spec'
+  require 'wrapture/enum_spec'
   require 'wrapture/errors'
   require 'wrapture/function_spec'
   require 'wrapture/normalize'
   require 'wrapture/rule_spec'
+  require 'wrapture/param_spec'
   require 'wrapture/scope'
   require 'wrapture/struct_spec'
+  require 'wrapture/template_spec'
+  require 'wrapture/type_spec'
   require 'wrapture/version'
   require 'wrapture/wrapped_function_spec'
 end

data/lib/wrapture/action_spec.rb

@@ -2,6 +2,7 @@
 
 # frozen_string_literal: true
 
+#--
 # Copyright 2020 Joel E. Anderson
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,9 +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.
-
-require 'wrapture/constants'
-require 'wrapture/errors'
+#++
 
 module Wrapture
   # An action to take within a generated program.

data/lib/wrapture/class_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,11 +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.
-
-require 'wrapture/constant_spec'
-require 'wrapture/constants'
-require 'wrapture/function_spec'
-require 'wrapture/normalize'
+#++
 
 module Wrapture
   # A description of a class, including its constants, functions, and other
@@ -34,6 +31,9 @@ module Wrapture
     # it uses an unsupported version type, then an exception is raised.
     def self.normalize_spec_hash(spec)
       raise NoNamespace unless spec.key?('namespace')
+      raise MissingSpecKey, 'name key is required' unless spec.key?('name')
+
+      Comment.validate_doc(spec['doc']) if spec.key?('doc')
 
       normalized = spec.dup
       normalized.default = []
@@ -71,11 +71,6 @@ module Wrapture
       end
     end
 
-    # Returns a string of the variable with it's type, properly formatted.
-    def self.typed_variable(type, name)
-      "#{type}#{' ' unless type.end_with?('*')}#{name}"
-    end
-
     # The underlying struct of this class.
     attr_reader :struct
 
@@ -89,14 +84,20 @@ module Wrapture
     # equivalent-struct:: a hash describing the struct this class wraps
     #
     # The following keys are optional:
+    # doc:: a string containing the documentation for this class
     # constructors:: a list of function specs that can create this class
     # destructor:: a function spec for the destructor of the class
     # functions:: a list of function specs
     # constants:: a list of constant specs
     def initialize(spec, scope: Scope.new)
-      @spec = ClassSpec.normalize_spec_hash(spec)
+      @spec = Marshal.load(Marshal.dump(spec))
+      TemplateSpec.replace_all_uses(@spec, *scope.templates)
+
+      @spec = ClassSpec.normalize_spec_hash(@spec)
 
-      @struct = StructSpec.new @spec[EQUIVALENT_STRUCT_KEYWORD]
+      @struct = if @spec.key?(EQUIVALENT_STRUCT_KEYWORD)
+                  StructSpec.new(@spec[EQUIVALENT_STRUCT_KEYWORD])
+                end
 
       @functions = @spec['constructors'].map do |constructor_spec|
         full_spec = constructor_spec.dup
@@ -121,32 +122,27 @@ module Wrapture
         ConstantSpec.new(constant_spec)
       end
 
+      @doc = @spec.key?('doc') ? Comment.new(@spec['doc']) : nil
+
       scope << self
       @scope = scope
     end
 
-    # Returns a cast of an instance of this class to the provided type, if
-    # possible.
-    def cast_to(name, type)
+    # Returns a cast of an instance of this class with the provided name to the
+    # specified type. Optionally the from parameter may hold the type of the
+    # instance, either a reference or a pointer.
+    def cast(instance, to, from = name)
+      member_access = from.pointer? ? '->' : '.'
+
       struct = "struct #{@struct.name}"
 
-      if [EQUIVALENT_STRUCT_KEYWORD, struct].include?(type)
-        equivalent_struct(name)
-      elsif [EQUIVALENT_POINTER_KEYWORD, "#{struct} *"].include?(type)
-        equivalent_struct_pointer(name)
+      if [EQUIVALENT_STRUCT_KEYWORD, struct].include?(to)
+        "#{'*' if pointer_wrapper?}#{instance}#{member_access}equivalent"
+      elsif [EQUIVALENT_POINTER_KEYWORD, "#{struct} *"].include?(to)
+        "#{'&' unless pointer_wrapper?}#{instance}#{member_access}equivalent"
       end
     end
 
-    # The equivalent struct of this class from an instance of it.
-    def equivalent_struct(instance_name)
-      "#{'*' if pointer_wrapper?}#{instance_name}.equivalent"
-    end
-
-    # A pointer to the equivalent struct of this class from an instance of it.
-    def equivalent_struct_pointer(instance_name)
-      "#{'&' unless pointer_wrapper?}#{instance_name}.equivalent"
-    end
-
     # Generates the wrapper class declaration and definition files.
     def generate_wrappers
       [generate_declaration_file, generate_definition_file]
@@ -163,7 +159,7 @@ module Wrapture
     # class cannot have any rules in its equivalent struct, or it will not be
     # overloaded.
     def overloads?(parent_spec)
-      return false unless parent_spec.struct.rules.empty?
+      return false unless parent_spec.struct&.rules&.empty?
 
       parent_spec.struct.name == struct_name &&
         parent_spec.name == parent_name &&
@@ -172,7 +168,12 @@ module Wrapture
 
     # The name of the parent of this class, or nil if there is no parent.
     def parent_name
-      @spec['parent']['name'] if @spec.key?('parent')
+      @spec['parent']['name'] if child?
+    end
+
+    # Determines if this class is a wrapper for a struct pointer or not.
+    def pointer_wrapper?
+      @spec['type'] == 'pointer'
     end
 
     # The name of the equivalent struct of this class.
@@ -208,6 +209,11 @@ module Wrapture
 
     private
 
+    # True if the class has a parent.
+    def child?
+      @spec.key?('parent')
+    end
+
     # Gives the content of the class declaration to a block, line by line.
     def declaration_contents
       yield "#ifndef #{header_guard}"
@@ -222,7 +228,8 @@ module Wrapture
       yield "namespace #{@spec['namespace']} {"
       yield
 
-      parent = if @spec.key?('parent')
+      documentation { |line| yield "  #{line}" }
+      parent = if child?
                  ": public #{parent_name} "
                else
                  ''
@@ -233,23 +240,25 @@ module Wrapture
 
       yield unless @constants.empty?
       @constants.each do |const|
-        yield "    #{const.declaration};"
+        const.declaration { |line| yield "    #{line}" }
       end
 
       yield
-      yield "    #{@struct.declaration equivalent_name};"
+      equivalent_member_declaration { |line| yield "    #{line}" }
       yield
 
       member_constructor_declaration { |line| yield "    #{line}" }
 
       pointer_constructor_declaration { |line| yield "    #{line}" }
 
-      yield "    #{struct_constructor_signature};" unless pointer_wrapper?
+      unless !@struct || pointer_wrapper?
+        yield "    #{struct_constructor_signature};"
+      end
 
       overload_declaration { |line| yield "    #{line}" }
 
       @functions.each do |func|
-        yield "    #{func.declaration};"
+        func.declaration { |line| yield "    #{line}" }
       end
 
       yield '  };' # end of class
@@ -263,7 +272,7 @@ module Wrapture
     def declaration_includes
       includes = @spec['includes'].dup
 
-      includes.concat(@struct.includes)
+      includes.concat(@struct.includes) if @struct
 
       @functions.each do |func|
         includes.concat(func.declaration_includes)
@@ -273,7 +282,7 @@ module Wrapture
         includes.concat(const.declaration_includes)
       end
 
-      includes.concat(@spec['parent']['includes']) if @spec.key?('parent')
+      includes.concat(@spec['parent']['includes']) if child?
 
       includes.uniq
     end
@@ -296,7 +305,7 @@ module Wrapture
 
       pointer_constructor_definition { |line| yield "  #{line}" }
 
-      unless pointer_wrapper?
+      unless pointer_wrapper? || !@struct
         yield
         yield "  #{@spec['name']}::#{struct_constructor_signature} {"
 
@@ -313,7 +322,7 @@ module Wrapture
       @functions.each do |func|
         yield
 
-        func.definition(@spec['name']) do |def_line|
+        func.definition do |def_line|
           yield "  #{def_line}"
         end
       end
@@ -341,6 +350,29 @@ module Wrapture
       includes.uniq
     end
 
+    # Yields the class documentation one line at a time.
+    def documentation
+      @doc&.format_as_doxygen(max_line_length: 78) { |line| yield line }
+    end
+
+    # Yields the declaration of the equivalent member if this class has one.
+    #
+    # A class might not have an equivalent member if it is able to use the
+    # parent class's, for example if the child class wraps the same struct.
+    def equivalent_member_declaration
+      return unless @struct
+
+      if child?
+        parent_spec = @scope.type(TypeSpec.new(parent_name))
+        member_reusable = !parent_spec.nil? &&
+                          parent_spec.struct_name == @struct.name &&
+                          parent_spec.pointer_wrapper? == pointer_wrapper?
+        return if member_reusable
+      end
+
+      yield "#{@struct.declaration(equivalent_name)};"
+    end
+
     # Gives the name of the equivalent struct.
     def equivalent_name
       "#{'*' if pointer_wrapper?}equivalent"
@@ -380,7 +412,7 @@ module Wrapture
     # Yields the declaration of the member constructor for a class. This will be
     # empty if the wrapped struct is a pointer wrapper.
     def member_constructor_declaration
-      return unless @struct.members?
+      return unless @struct&.members?
 
       yield "#{@spec['name']}( #{@struct.member_list_with_defaults} );"
     end
@@ -388,7 +420,7 @@ module Wrapture
     # Yields the definition of the member constructor for a class. This will be
     # empty if the wrapped struct is a pointer wrapper.
     def member_constructor_definition
-      return unless @struct.members?
+      return unless @struct&.members?
 
       yield "#{@spec['name']}::#{@spec['name']}( #{@struct.member_list} ) {"
 
@@ -440,9 +472,12 @@ module Wrapture
 
     # Yields the declaration of the pointer constructor for a class.
     #
-    # If there is already a constructor provided with this signature, then this
-    # function will return with no output.
+    # If this class does not have an equivalent struct, or if there is already
+    # a constructor defined with this signature, then this function will return
+    # with no output.
     def pointer_constructor_declaration
+      return unless @struct
+
       signature_prefix = "#{@spec['name']}( #{@struct.pointer_declaration('')}"
       return if @functions.any? do |func|
         func.constructor? && func.signature.start_with?(signature_prefix)
@@ -453,21 +488,25 @@ module Wrapture
 
     # Yields the definition of the pointer constructor for a class.
     #
-    # If there is already a constructor provided with this signature, then this
-    # function will return with no output.
+    # If this class has no equivalent struct, or if there is already a
+    # constructor provided with this signature, then this function will return
+    # with no output.
     #
     # If this is a pointer wrapper class, then the constructor will simply set
-    # the underlying pointer to the provied one, and return the new object.
+    # the underlying pointer to the provided one, and return the new object.
     #
     # If this is a struct wrapper class, then a constructor will be created that
     # sets each member of the wrapped struct to the provided value.
     def pointer_constructor_definition
+      return unless @struct
+
       signature_prefix = "#{@spec['name']}( #{@struct.pointer_declaration('')}"
       return if @functions.any? do |func|
         func.constructor? && func.signature.start_with?(signature_prefix)
       end
 
-      yield "#{@spec['name']}::#{pointer_constructor_signature} {"
+      initializer = pointer_constructor_initializer
+      yield "#{@spec['name']}::#{pointer_constructor_signature} #{initializer}{"
 
       if pointer_wrapper?
         yield '  this->equivalent = equivalent;'
@@ -481,16 +520,25 @@ module Wrapture
       yield '}'
     end
 
+    # The initializer for the pointer constructor, if one is available, or an
+    # empty string if not.
+    def pointer_constructor_initializer
+      if pointer_wrapper? && child?
+        parent_spec = @scope.type(TypeSpec.new(parent_name))
+        parent_usable = !parent_spec.nil? &&
+                        parent_spec.pointer_wrapper? &&
+                        parent_spec.struct_name == @struct.name
+        return ": #{parent_name}( equivalent ) " if parent_usable
+      end
+
+      ''
+    end
+
     # The signature of the constructor given an equivalent strucct pointer.
     def pointer_constructor_signature
       "#{@spec['name']}( #{@struct.pointer_declaration 'equivalent'} )"
     end
 
-    # Determines if this class is a wrapper for a struct pointer or not.
-    def pointer_wrapper?
-      @spec['type'] == 'pointer'
-    end
-
     # The signature of the constructor given an equivalent struct type.
     def struct_constructor_signature
       "#{@spec['name']}( #{@struct.declaration 'equivalent'} )"

data/lib/wrapture/comment.rb

@@ -0,0 +1,106 @@
+# 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 comment that can be inserted in generated source code.
+  #
+  # Comments are primarily used to insert documentation about generated code for
+  # documentation generation tools such as Doxygen.
+  class Comment
+    # Validates a doc string.
+    def self.validate_doc(doc)
+      raise InvalidDoc, 'a doc must be a string' unless doc.is_a?(String)
+    end
+
+    # The raw text of the comment.
+    attr_reader :text
+
+    # Creates a comment from a string. If the provided string is nil, then an
+    # empty string is used.
+    def initialize(comment = '')
+      @text = comment.nil? ? '' : comment
+    end
+
+    # True if this comment is empty, false otherwise.
+    def empty?
+      @text.empty?
+    end
+
+    # Yields each line of the comment formatted as specified.
+    def format(line_prefix: '// ', first_line: nil, last_line: nil,
+               max_line_length: 80)
+      return if @text.empty?
+
+      yield first_line if first_line
+
+      paragraphs(max_line_length - line_prefix.length) do |line|
+        yield "#{line_prefix}#{line}".rstrip
+      end
+
+      yield last_line if last_line
+    end
+
+    # Yields each line of the comment formatted using Doxygen style.
+    def format_as_doxygen(max_line_length: 80)
+      format(line_prefix: ' * ', first_line: '/**',
+             last_line: ' */', max_line_length: max_line_length) do |line|
+        yield line
+      end
+    end
+
+    private
+
+    # Yields the comment converted into paragraph-style blocks.
+    #
+    # Consecutive lines with text are concatenated together to the maximum line
+    # length, regardless of the original line length in the comment. One or more
+    # empty lines are written as a single empty line, separating paragraphs.
+    #
+    # Yielded lines may have trailing spaces, which are not considered part of
+    # the maximum length. The caller must strip these off.
+    def paragraphs(line_length)
+      running_line = String.new
+      newline_mode = true
+      @text.each_line do |line|
+        if line.strip.empty?
+          unless newline_mode
+            yield running_line
+            yield ''
+            running_line.clear
+            newline_mode = true
+          end
+        else
+          newline_mode = false
+        end
+
+        line.scan(/\S+/) do |word|
+          if running_line.length + word.length > line_length
+            yield running_line
+            running_line = word + ' '
+          else
+            running_line << word << ' '
+          end
+        end
+      end
+
+      yield running_line
+    end
+  end
+end