implement struct overloading for python

Implements the overloaded struct example for the Python wrapper.

docs/examples/overloaded_struct/security_system.h

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /*
- * Copyright 2019 Joel E. Anderson
+ * Copyright 2019-2024 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.
@@ -23,6 +23,10 @@
 #define GLASS_BREAK_EVENT 2
 #define CAMERA_EVENT 3
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 struct event {
   int code;
   void *data;
@@ -61,4 +65,8 @@ print_glass_break_event( const struct event *ev );
 void
 print_motion_event( const struct event *ev );
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif

docs/examples/overloaded_struct/security_system.yml

@@ -1,7 +1,8 @@
 version: "0.3.0"
 classes:
   - name: "SecurityEvent"
-    namespace: "security_system"
+    namespace: "home_automation"
+    libraries: "security_system"
     equivalent-struct:
       name: "event"
       includes: "security_system.h"
@@ -33,6 +34,8 @@ classes:
         wrapped-function:
           name: "get_next_event"
           includes: "security_system.h"
+          return:
+            type: "equivalent-struct-pointer"
       - name: "Print"
         virtual: true
         wrapped-function:
@@ -41,10 +44,10 @@ classes:
           params:
             - value: "equivalent-struct-pointer"
   - name: "CameraEvent"
-    namespace: "security_system"
+    namespace: "home_automation"
+    libraries: "security_system"
     parent:
       name: "SecurityEvent"
-      includes: "SecurityEvent.hpp"
     equivalent-struct:
       name: "event"
       includes: "security_system.h"
@@ -68,10 +71,10 @@ classes:
           params:
             - value: "equivalent-struct-pointer"
   - name: "GlassBreakEvent"
-    namespace: "security_system"
+    namespace: "home_automation"
+    libraries: "security_system"
     parent:
       name: "SecurityEvent"
-      includes: "SecurityEvent.hpp"
     equivalent-struct:
       name: "event"
       includes: "security_system.h"
@@ -95,10 +98,10 @@ classes:
           params:
             - value: "equivalent-struct-pointer"
   - name: "MotionEvent"
-    namespace: "security_system"
+    namespace: "home_automation"
+    libraries: "security_system"
     parent:
       name: "SecurityEvent"
-      includes: "SecurityEvent.hpp"
     equivalent-struct:
       name: "event"
       includes: "security_system.h"

docs/examples/overloaded_struct/event_usage.cpp → docs/examples/overloaded_struct/security_system_usage.cpp

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /*
- * Copyright 2019 Joel E. Anderson
+ * Copyright 2019-2024 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,7 +19,7 @@
 #include <cstdlib>
 #include <SecurityEvent.hpp>
 
-using namespace security_system;
+using namespace home_automation;
 
 int
 main( int argc, char **argv ) {

docs/examples/overloaded_struct/security_system_usage.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Copyright 2024 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.
+
+import home_automation
+
+for i in range(5):
+    home_automation.SecurityEvent.NextEvent().Print()

lib/wrapture/class_spec.rb

@@ -169,6 +169,11 @@ def child?
       @spec.key?('parent')
     end
 
+    # A list of constructor functions for the class.
+    def constructors
+      @functions.select(&:constructor?)
+    end
+
     # A list of includes needed for the declaration of the class.
     def declaration_includes
       includes = @spec['includes'].dup
@@ -200,11 +205,14 @@ def definition_includes
         includes.concat(const.definition_includes)
       end
 
-      includes.concat(factory_definition_includes)
-
       includes.uniq
     end
 
+    # The destructor function for the class, or nil if there isn't one.
+    def destructor
+      @functions.select(&:destructor?).first
+    end
+
     # Calls the given block for each line of the class documentation.
     def documentation(&block)
       @doc&.format_as_doxygen(max_line_length: 78) { |line| block.call(line) }
@@ -237,6 +245,15 @@ def libraries
       @functions.flat_map(&:libraries).concat(@spec['libraries'])
     end
 
+    # An array of methods of the class. This is a subset of the list of
+    # functions without the constructors and destructors.
+    #
+    # Named with a specs suffix to avoid conflicts with Ruby's "methods"
+    # instance method.
+    def method_specs
+      @functions.select { |spec| !spec.constructor? && !spec.destructor? }
+    end
+
     # The name of the class.
     def name
       @spec['name']
@@ -301,12 +318,5 @@ def type(type)
     def type?(type)
       @scope.type?(type)
     end
-
-    private
-
-    # A list of the includes needed for the factory function definition.
-    def factory_definition_includes
-      @scope.overloads(self).map { |overload| "#{overload.name}.hpp" }
-    end
   end
 end

lib/wrapture/cpp_wrapper.rb

@@ -409,7 +409,8 @@ def declare_class
     # Gives each line of the declaration of the given ConstantSpec.
     def declare_constant(constant_spec, &block)
       constant_spec.doc&.format_as_doxygen(max_line_length: 76, &block)
-      yield "static const #{constant_spec.type.variable(constant_spec.name)};"
+      variable = type_variable(constant_spec.type, constant_spec.name)
+      yield "static const #{variable};"
     end
 
     # Gives each line of the declaration of a FunctionSpec to the provided
@@ -543,7 +544,14 @@ def define_function
 
     # A list of includes needed for the definition of the class.
     def definition_includes
-      @spec.definition_includes.concat(common_includes(@spec))
+      includes = @spec.definition_includes
+      includes.concat(common_includes(@spec))
+
+      @spec.scope.overloads(@spec).map do |overload|
+        includes.append("#{overload.name}.hpp")
+      end
+
+      includes
     end
 
     # The definition of an enum element.
@@ -577,6 +585,9 @@ def equivalent_member_field(field_name)
     end
 
     # A spec hash for a factory constructor for this class.
+    #
+    # A factory constructor creates an instance of a class based on a struct
+    # that is overloaded.
     def factory_constructor_hash
       factory_lines = []
       line_prefix = ''
@@ -605,7 +616,7 @@ def function_declaration_param_list(func_spec)
         'void'
       else
         func_spec.params.map do |param|
-          sig = param.type.resolve(func_spec).variable(param.name)
+          sig = type_variable(param.type.resolve(func_spec), param.name)
 
           if param.default_value?
             sig += ' = '
@@ -629,15 +640,15 @@ def function_declaration_signature(func_spec)
         "#{func_spec.name}( #{function_declaration_param_list(func_spec)} )"
       else
         return_type = func_spec.resolved_return
-        return_type.return_expression(func_spec, func_name: func_spec.name)
+        return_expression(return_type, func_spec, func_name: func_spec.name)
       end
     end
 
     # The parameter list for the function definition.
     def function_definition_param_list(func_spec)
       if func_spec.params?
         func_spec.params.map do |param|
-          param.type.resolve(func_spec).variable(param.name)
+          type_variable(param.type.resolve(func_spec), param.name)
         end.join(', ')
       else
         'void'
@@ -651,7 +662,7 @@ def function_definition_signature(func_spec)
         "#{func_name}( #{function_definition_param_list(func_spec)} )"
       else
         return_type = func_spec.resolved_return
-        return_type.return_expression(func_spec, func_name: func_name)
+        return_expression(return_type, func_spec, func_name: func_name)
       end
     end
 
@@ -661,7 +672,7 @@ def function_locals(spec)
 
       if spec.capture_return?
         wrapped_type = spec.resolve_type(spec.wrapped.return_val_type)
-        yield "#{wrapped_type.variable('return_val')};"
+        yield "#{type_variable(wrapped_type, 'return_val')};"
       end
     end
 
@@ -735,8 +746,34 @@ def return_cast(value)
       elsif @spec.return_overloaded?
         "new#{@spec.return_type.name.chomp('*').strip} ( #{value} )"
       else
-        @spec.resolved_return.cast_expression(value)
+        return_type = @spec.resolved_return
+        "( #{type_variable(return_type)} )( #{value} )"
+      end
+    end
+
+    # A string with a declaration of FunctionSpec +func+ with the given type as
+    # the return value. +func_name+ can be provided to override the function
+    # name, for example if a class name needs to be included.
+    def return_expression(type_spec, func_spec, func_name: func_spec.name)
+      name_part = String.new(func_name || '')
+      param_part = String.new
+      ret_part = String.new(type_spec.name || '')
+
+      current_type = type_spec
+      while current_type.function?
+        name_part.prepend('( *')
+
+        current_func = current_type.function
+        param_list = function_definition_param_list(current_func)
+        param_part.concat(" )( #{param_list} )")
+
+        current_type = current_func.resolved_return
+        ret_part = current_type.name
       end
+
+      ret_part << ' ' unless current_type.pointer?
+      param_list = function_definition_param_list(func_spec)
+      "#{ret_part}#{name_part}( #{param_list} )#{param_part}"
     end
 
     # The return statement used in this function's definition.
@@ -777,6 +814,23 @@ def this_struct_pointer
       "#{'&' unless @spec.owner.pointer_wrapper?}this->equivalent"
     end
 
+    # A string with a declaration of a variable named +var_name+ of this type.
+    # If +var_name+ is nil then this will simply be a type declaration.
+    def type_variable(type_spec, var_name = nil)
+      if type_spec.variadic?
+        '...'
+      elsif type_spec.function?
+        func_spec = type_spec.function
+        func_name = "( *#{var_name} )"
+        return_expression(func_spec.resolved_return, func_spec,
+                          func_name: func_name)
+      elsif var_name.nil?
+        type_spec.name
+      else
+        "#{type_spec.name}#{' ' unless type_spec.pointer?}#{var_name}"
+      end
+    end
+
     # The expression containing the call to the underlying wrapped function.
     def wrapped_call_expression
       call = @spec.wrapped.call_from(self)

lib/wrapture/function_spec.rb

@@ -255,9 +255,9 @@ def optional_params
     end
 
     # A string with the parameter list for this function.
-    def param_list
-      ParamSpec.signature(@params, self)
-    end
+    # def param_list
+    #   ParamSpec.signature(@params, self)
+    # end
 
     # An array of the names of the function params.
     def param_names
@@ -318,12 +318,6 @@ def returns_call_directly?
         !@wrapped.error_check?
     end
 
-    # The signature of the function. +func_name+ can be used to override the
-    # function name if needed, for example if a class name qualifier is needed.
-    def signature(func_name: name)
-      "#{func_name}( #{param_list} )"
-    end
-
     # True if the function is static.
     def static?
       @spec['static']

lib/wrapture/param_spec.rb

@@ -130,24 +130,24 @@ def name
     # The parameter type and name, suitable for use in a function signature or
     # declaration. +owner+ must be the FunctionSpec that the parameter belongs
     # to.
-    def signature(owner)
-      sig = @type.resolve(owner).variable(name)
-
-      if @spec.key?('default-value')
-        default_value = @spec['default-value']
-
-        sig += ' = '
-        sig += if @spec['type'] == 'const char *'
-                 "\"#{default_value}\""
-               elsif @spec['type'].end_with?('char')
-                 "'#{default_value}'"
-               else
-                 default_value.to_s
-               end
-      end
-
-      sig
-    end
+    # def signature(owner)
+    #   sig = @type.resolve(owner).variable(name)
+
+    #   if @spec.key?('default-value')
+    #     default_value = @spec['default-value']
+
+    #     sig += ' = '
+    #     sig += if @spec['type'] == 'const char *'
+    #              "\"#{default_value}\""
+    #            elsif @spec['type'].end_with?('char')
+    #              "'#{default_value}'"
+    #            else
+    #              default_value.to_s
+    #            end
+    #   end
+
+    #   sig
+    # end
 
     # True if this parameter is variadic (the name is equal to '...').
     def variadic?