rice 4.7.1 → 4.9.0

data/bin/rice-doc.rb

@@ -13,67 +13,74 @@ module Rice
 	# Generates Mkdocs for a Rice extension
 	#
 	# == Usage
-	# rice-doc [options] <rice_extension_library>
+	# rice-doc [options] <config_file>
 	#
 	# Options:
-	#    -o, --output=path                Output directory
-	#    -v, --version                    Show version (1.1.0)
+	#    -v, --version                    Show version
 	#    -h, --help                       Show help message
 
 	class Cmd
-		# :enddoc:
 		attr_accessor :options
 
 		def option_parser
 			OptionParser.new do |opts|
 				opts.banner = "rice-doc #{Rice::VERSION}\n" +
-											"Usage: rice-doc [options] <rice_extension_library_path>"
+											"Usage: rice-doc [options] <config_file.yaml>"
 
 				opts.separator ""
 				opts.separator "Options:"
 
-				opts.on('-o path', '--output=path',
-								'Output generated mkdoc files to the specified directory') do |dir|
-					options.output = File.expand_path(dir)
-				end
-
-				opts.on_tail("-v version", "--version", "Show version (#{Rice::VERSION})") do
-					puts "ruby_prof " + Rice::VERSION
+				opts.on_tail("-v", "--version", "Show version (#{Rice::VERSION})") do
+					puts "rice-doc " + Rice::VERSION
 					exit
 				end
 
 				opts.on_tail("-h", "--help", "Show help message") do
 					puts opts
+					puts ""
+					puts "Config file format (YAML):"
+					puts "  extension: path/to/extension.so"
+					puts "  output: ./docs/api"
+					puts "  resolvers:"
+					puts "    Std:"
+					puts "      type: cppreference"
+					puts "    MyNamespace:"
+					puts "      type: doxygen"
+					puts "      root: https://example.com/docs"
+					puts "      tagfile: https://example.com/docs/tagfile.xml"
+					puts "      type_mappings:"
+					puts "        - pattern: \"^enum\\\\s*\""
+					puts "          replacement: \"\""
+					puts "      method_mappings:"
+					puts "        MyNamespace::MyClass:"
+					puts "          ruby_method: cppMethod"
+					puts ""
+					puts "Note: Ruby core types are automatically linked to docs.ruby-lang.org"
 					exit
 				end
 			end
 		end
 
 		def parse_args
-			@options = Struct.new(:exec, :extension, :output).new
-			options.extension = nil
-			options.output = nil
+			@options = Struct.new(:config_file).new
+			options.config_file = nil
+
+			self.option_parser.parse! ARGV
 
-			# Make sure the user specified at least one file
-			if ARGV.length < 1 and not options.exec
+			if ARGV.length < 1
 				puts self.option_parser
 				puts ""
-				puts "Must specify a rice extension"
+				puts "Must specify a config file"
 				exit(-1)
 			end
 
-			self.option_parser.parse! ARGV
+			options.config_file = ARGV.shift
 
-			if options.output.nil?
-				puts "Must specify an output directory with -o/--output option"
+			unless File.exist?(options.config_file)
+				puts "Config file not found: #{options.config_file}"
 				exit(-1)
-			elsif !Dir.exist?(options.output)
-				puts "Creating output directory '#{options.output}'"
-				Dir.mkdir(options.output)
 			end
 
-			options.extension = ARGV.shift
-
 			options
 		rescue OptionParser::InvalidOption, OptionParser::InvalidArgument, OptionParser::MissingArgument => e
 			puts self.option_parser
@@ -87,125 +94,35 @@ end
 cmd = Rice::Cmd.new
 options = cmd.parse_args
 
+# Load configuration
+config = Rice::Doc::Config.new(options.config_file)
+
+# Validate configuration
+if config.extension.nil?
+	puts "Config file must specify 'extension'"
+	exit(-1)
+end
+
+if config.output.nil?
+	puts "Config file must specify 'output'"
+	exit(-1)
+end
+
+# Create output directory if needed
+unless Dir.exist?(config.output)
+	puts "Creating output directory '#{config.output}'"
+	FileUtils.mkdir_p(config.output)
+end
+
+# Add the extension directory the path in case it ships with extra libraries
+ENV["PATH"] = "#{File.dirname(config.extension)}#{File::PATH_SEPARATOR}#{ENV["PATH"]}"
 # Load the extension
-require options.extension
+require config.extension
 
 # Get modules and classes
 modules = Rice::Registries.instance.modules.modules
 klasses = Rice::Registries.instance.types.klasses
 
-# Doxygen documentation
-doxygen_root = "https://docs.opencv.org/4.x"
-doxygen_index = "https://docs.opencv.org/4.x/opencv.tag"
-#doxygen_index = "c:/Users/cfis/Downloads/opencv.tag"
-type_mappings = {/^enum\s*/i => '',
-								 /^union\s*/i => '',
-								 /<.*>/ => '',
-								 '::debug_build_guard' => ''}
-
-method_mappings = {'Cv' => {'agast' => 'AGAST',
-														'approx_poly_dp' => 'approxPolyDP',
-														'calc_optical_flow_pyr_lk' => 'calcOpticalFlowPyrLK',
-														'calibrate_camera_ro' => 'calibrateCameraRO',
-														'cam_shift' => 'CamShift',
-														'compose_rt' => 'composeRT',
-														'compute_ecc' => 'computeECC',
-														'create_clahe' => 'createCLAHE',
-														'current_ui_framework' => 'currentUIFramework',
-														'create_align_mtb' => 'createAlignMTB',
-														'create_background_subtractor_knn' => 'createBackgroundSubtractorKNN',
-														'create_background_subtractor_mog2' => 'createBackgroundSubtractorMOG2',
-														'denoise_tvl1' => 'denoise_TVL1',
-														'emd' => 'EMD',
-														'estimate_affine_2d' => 'estimateAffine2D',
-														'estimate_affine_partial_2d' => 'estimateAffinePartial2D',
-														'fast' => 'FAST',
-														'filter_2d' => 'filter2D',
-														'find_chessboard_corners_sb?' => 'findChessboardCornersSB',
-														'find_transform_ecc' => 'findTransformECC',
-														'fit_ellipse_ams' => 'fitEllipseAMS',
-														'flip_nd' => 'flipND',
-														'gaussian_blur' => 'GaussianBlur',
-														'get_cpu_features_line' => 'getCPUFeaturesLine',
-														'get_cpu_tick_count' => 'getCPUTickCount',
-														'get_number_of_cp_us' => 'getNumberOfCPUs',
-														'get_optimal_dft_size' => 'getOptimalDFTSize',
-														'get_rotation_matrix_2d' => 'getRotationMatrix2D',
-														'get_valid_disparity_roi' => 'getValidDisparityROI',
-														'group_rectangles_meanshift' => 'groupRectangles_meanshift',
-														'have_open_vx?' => 'haveOpenVX',
-														'hough_circles' => 'HoughCircles',
-														'hough_lines' => 'HoughLines',
-														'hough_lines_p' => 'HoughLinesP',
-														'hough_lines_point_set' => 'HoughLinesPointSet',
-														'hu_moments' => 'HuMoments',
-														'init_camera_matrix_2d' => 'initCameraMatrix2D',
-														'lu' => 'LU',
-														'lut' => 'LUT',
-														'pca_back_project' => 'PCABackProject',
-														'pca_compute' => 'PCACompute',
-														'pca_project' => 'PCAProject',
-														'psnr' => 'PSNR',
-														'rq_decomp3x3' => 'RQDecomp3x3',
-														'select_roi	' => 'selectROI',
-														'sep_filter_2d' => 'sepFilter2D',
-														'set_rng_seed' => 'setRNGSeed',
-														'set_use_open_vx' => 'setUseOpenVX',
-														'solve_lp' => 'solveLP',
-														'solve_pn_p_refine_lm' => 'solvePnPRefineLM',
-														'solve_pn_p_refine_vvs' => 'solvePnPRefineVVS',
-														'sv_back_subst' => 'SVBackSubst',
-														'sv_decomp' => 'SVDecomp',
-														'the_rng' => 'theRNG',
-														'transpose_nd' => 'transposeND',
-														'use_open_vx?' => 'useOpenVX',
-														'wrapper_emd' => 'wrapperEMD'},
-									 'Cv::AsyncArray' => {'_get_impl' => '_getImpl',
-																				'wait_for?' => 'wait_for'},
-									 'Cv::BackgroundSubtractorKNN' => {'getk_nn_samples' => 'getkNNSamples',
-																										 'setk_nn_samples' => 'setkNNSamples'},
-									 'Cv::Cuda::DeviceInfo' => {'device_id' => 'deviceID',
-																							'ecc_enabled?' => 'ECCEnabled',
-																							'max_surface_2d' => 'maxSurface2D',
-																							'max_texture_2d' => 'maxTexture2D',
-																							'pci_bus_id' => 'pciBusID',
-																							'pci_device_id' => 'pciDeviceID',
-																							'pci_domain_id' => 'pciDomainID'},
-									 'Cv::Cuda::GpuMat' => {'adjust_roi' => 'adjustROI',
-																					'locate_roi' => 'locateROI'},
-									 'Cv::Cuda::GpuMatND' => {'to_gpu_mat' => 'operator GpuMat'},
-									 'Cv::FaceDetectorYN' => {'get_nms_threshold' => 'getNMSThreshold'},
-									 'Cv::FaceRecognizerSF' => {'set_nms_threshold' => 'setNMSThreshold'},
-									 'Cv::HOGDescriptor' => {'detect_multi_scale_roi' => 'detectMultiScaleROI',
-																					 'detect_roi' => 'detectROI'},
-									 'Cv::HOGDescriptor::DescriptorStorageFormat' => {'set_svm_detector' => 'setSVMDetector'},
-									 'Cv::Hfloat' => {'to_float' => 'operator float'},
-									 'Cv::Mat' => {'locate_roi' => 'locateROI'},
-									 'Cv::Ml::ANN_MLP' => {'get_rprop_dw0' => 'getRpropDW0',
-																				 'get_rprop_dw_max' => 'getRpropDWMax',
-																				 'get_rprop_dw_min' => 'getRpropDWMin',
-																				 'get_rprop_dw_minus' => 'getRpropDWMinus',
-																				 'get_rprop_dw_plus' => 'getRpropDWPlus',
-																				 'set_anneal_energy_rng' => 'setAnnealEnergyRNG',
-																				 'set_rprop_dw0' => 'setRpropDW0',
-																				 'set_rprop_dw_max' => 'setRpropDWMax',
-																				 'set_rprop_dw_min' => 'setRpropDWMin',
-																				 'set_rprop_dw_minus' => 'setRpropDWMinus',
-																				 'set_rprop_dw_plus' => 'setRpropDWPlus'},
-									 'Cv::Ml::DTrees' => {'get_cv_folds' => 'getCVFolds',
-																				'get_use1_se_rule?' => 'getUse1SERule',
-																				'set_cv_folds' => 'setCVFolds',
-																				'set_use1_se_rule' => 'setUse1SERule'},
-									 'Cv::Ml::RTrees' => {'get_oob_error' => 'getOOBError'}
-}
-
-doxygen_resolver = Rice::Doc::Doxygen.new(doxygen_root, doxygen_index, type_mappings, method_mappings)
-
-# Setup resolvers per namespace
-resolvers = {nil => Rice::Doc::Ruby.new,
-						 'Cv' => doxygen_resolver,
-						 'Rice' => Rice::Doc::Rice.new,
-						 'Std' => Rice::Doc::CppReference.new}
-
-generator = Rice::Doc::Mkdocs.new(modules + klasses, resolvers, options.output)
+# Generate documentation
+generator = Rice::Doc::Mkdocs.new(modules + klasses, config.resolvers, config.output)
 generator.generate

data/include/rice/api.hpp

@@ -0,0 +1,261 @@
+// This file is part of [rice](https://github.com/ruby-rice/rice).
+//
+// Copyright (C) 2025 Jason Roelofs <jasongroelofs@gmail.com>
+//                    Paul Brannan <curlypaul924@gmail.com>,
+//                    Charlie Savage
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions
+// are met:
+//
+// 1. Redistributions of source code must retain the above copyright
+//    notice, this list of conditions and the following disclaimer.
+// 2. Redistributions in binary form must reproduce the above copyright
+//    notice, this list of conditions and the following disclaimer in the
+//    documentation and/or other materials provided with the distribution.
+//
+// THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+// IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+// OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+// IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+// NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+// THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#ifndef Rice__Api_hpp_
+#define Rice__Api_hpp_
+
+
+// =========   ModuleRegistry.hpp   =========
+#ifndef Rice_Api_Module_Registry_hpp
+#define Rice_Api_Module_Registry_hpp
+
+extern "C"
+void Init_Module_Registry();
+
+#endif
+
+// =========   ModuleRegistry.ipp   =========
+using namespace Rice;
+
+extern "C"
+void Init_Module_Registry()
+{
+  Module rb_mRice = define_module("Rice");
+
+  Rice::define_class_under<detail::ModuleRegistry>(rb_mRice, "ModuleRegistry").
+    define_method("modules", &detail::ModuleRegistry::modules, Return().setValue());
+}
+
+// =========   NativeRegistry.hpp   =========
+#ifndef Rice_Api_Native_Registry_hpp
+#define Rice_Api_Native_Registry_hpp
+
+extern "C"
+void Init_Native_Registry();
+
+#endif
+
+// =========   NativeRegistry.ipp   =========
+using namespace Rice;
+
+extern "C"
+inline void Init_Native_Registry()
+{
+  Module rb_mRice = define_module("Rice");
+
+  Rice::define_class_under<detail::NativeRegistry>(rb_mRice, "NativeRegistry").
+    define_method("lookup", [](detail::NativeRegistry& self, VALUE klass) -> Array
+    {
+      Array result;
+
+      const std::vector<detail::Native*> natives = self.lookup(klass);
+      for (detail::Native* native : natives)
+      {
+        result.push(native, false);
+      }
+
+      return result;
+    }, Arg("klass").setValue()).
+
+    define_method("lookup_by_kind", [](detail::NativeRegistry& self, VALUE klass, detail::NativeKind kind) -> Array
+    {
+      Array result;
+
+      const std::vector<detail::Native*> natives = self.lookup(klass, kind);
+      for (detail::Native* native : natives)
+      {
+        result.push(native, false);
+      }
+
+      return result;
+    }, Arg("klass").setValue(), Arg("kind"));
+}
+
+// =========   TypeRegistry.hpp   =========
+#ifndef Rice_Api_Type_Registry_hpp
+#define Rice_Api_Type_Registry_hpp
+
+extern "C"
+void Init_Type_Registry();
+
+#endif
+
+// =========   TypeRegistry.ipp   =========
+using namespace Rice;
+
+extern "C"
+void Init_Type_Registry()
+{
+  Module rb_mRice = define_module("Rice");
+
+  Rice::define_class_under<detail::TypeRegistry>(rb_mRice, "TypeRegistry").
+    define_method("klasses", &detail::TypeRegistry::klasses, Return().setValue());
+}
+
+// =========   Registries.hpp   =========
+#ifndef Rice_Api_Registries_hpp
+#define Rice_Api_Registries_hpp
+
+void Init_Registries();
+
+#endif
+
+// =========   Registries.ipp   =========
+using namespace Rice;
+
+inline void Init_Registries()
+{
+  Module rb_mRice = define_module("Rice");
+
+  define_class_under<detail::Registries>(rb_mRice, "Registries").
+    define_singleton_attr("instance", &detail::Registries::instance, AttrAccess::Read).
+    define_attr("modules", &detail::Registries::modules, AttrAccess::Read).
+    define_attr("natives", &detail::Registries::natives, AttrAccess::Read).
+    define_attr("types", &detail::Registries::types, AttrAccess::Read);
+}
+
+// =========   Arg.hpp   =========
+#ifndef Rice_Api_Arg_hpp
+#define Rice_Api_Arg_hpp
+
+extern "C"
+void Init_Arg();
+
+#endif
+
+// =========   Arg.ipp   =========
+using namespace Rice;
+
+inline void Init_Arg()
+{
+  Module rb_mRice = define_module("Rice");
+
+  define_class_under<Arg>(rb_mRice, "Arg").
+    define_attr("name", &Arg::name, AttrAccess::Read);
+}
+
+// =========   Parameter.hpp   =========
+#ifndef Rice_Api_Parameter_hpp
+#define Rice_Api_Parameter_hpp
+
+extern "C"
+void Init_Parameter();
+
+#endif
+
+// =========   Parameter.ipp   =========
+using namespace Rice;
+
+inline void Init_Parameter()
+{
+  Module rb_mRice = define_module("Rice");
+
+  define_class_under<detail::ParameterAbstract>(rb_mRice, "Parameter").
+    define_method("arg", &detail::ParameterAbstract::arg).
+    define_method("klass", &detail::ParameterAbstract::klass, Return().setValue()).
+    define_method("cpp_klass", &detail::ParameterAbstract::cppTypeName);
+}
+
+// =========   Native.hpp   =========
+#ifndef Rice_Api_Native_Function_hpp
+#define Rice_Api_Native_Function_hpp
+
+extern "C"
+void Init_Native();
+
+#endif
+
+// =========   Native.ipp   =========
+using namespace Rice;
+
+#include <ostream>
+
+extern "C"
+inline void Init_Native()
+{
+  Module rb_mRice = define_module("Rice");
+
+  define_enum_under<detail::NativeKind>("NativeKind", rb_mRice)
+    .define_value("Function", detail::NativeKind::Function)
+    .define_value("Method", detail::NativeKind::Method)
+    .define_value("AttributeReader", detail::NativeKind::AttributeReader)
+    .define_value("AttributeWriter", detail::NativeKind::AttributeWriter)
+    .define_value("Proc", detail::NativeKind::Proc)
+    .define_value("Callback", detail::NativeKind::Callback);
+
+  define_class_under<detail::Native>(rb_mRice, "Native").
+    define_method("name", &detail::Native::name).
+    define_method("kind", &detail::Native::kind).
+    define_method("return_klass", &detail::Native::returnKlass, Return().setValue()).
+    define_method("parameters", &detail::Native::parameters).
+    define_method("to_s", [](detail::Native& self) -> std::string
+      {
+        std::ostringstream stream;
+        stream << "Native";
+
+        switch (self.kind())
+        {
+          case detail::NativeKind::Function:
+            stream << "Function";
+            break;
+          case detail::NativeKind::Method:
+            stream << "Method";
+            break;
+          case detail::NativeKind::Iterator:
+            stream << "Iterator";
+            break;
+          case detail::NativeKind::AttributeReader:
+            stream << "AttributeReader";
+            break;
+          case detail::NativeKind::AttributeWriter:
+            stream << "AttributeWriter";
+            break;
+          case detail::NativeKind::Proc:
+            stream << "Proc";
+            break;
+          case detail::NativeKind::Callback:
+            stream << "Callback";
+            break;
+        }
+
+        stream << "<" << self.name() << "> ";
+        return stream.str();
+      });
+}
+
+extern "C"
+inline void Init_Rice_Api()
+{
+  Init_Registries();
+  Init_Module_Registry();
+  Init_Native_Registry();
+  Init_Type_Registry();
+  Init_Arg();
+  Init_Parameter();
+  Init_Native();
+}
+#endif