rice 4.6.1 → 4.7.0

data/lib/rice/doc/mkdocs.rb

@@ -0,0 +1,298 @@
+require 'fileutils'
+
+module Rice
+	module Doc
+		class Mkdocs
+			ESCAPE_METHODS = {'*' => '\*',
+												'+' => '\+',
+												'-' => '\-',
+												'.' => '\.',
+												'!' => '\!',
+												'|' => '\|',
+												'[]' => '\[\]',
+			                  '[]=' => '\[\]='}
+
+			attr_reader :klasses, :output
+
+			def initialize(klasses, doc_resolvers, output)
+				@klasses = klasses
+				@doc_resolvers = doc_resolvers
+				@output = output
+			end
+
+			def generate
+				FileUtils.mkdir_p(@output)
+
+				klasses.sort_by(&:name).each.with_index do |klass, i|
+					STDOUT << klass.name << " (" << i << "/" << klasses.count << ")" << "\n"
+					if klass.instance_of?(Module)
+						write_module(klass)
+					elsif klass.cpp_class.match(/^enum/i)
+						write_enum(klass)
+					elsif klass.cpp_class.match(/^union/i)
+						write_union(klass)
+					else
+						write_class(klass)
+					end
+				end
+			end
+
+			def output_path(klass)
+				parts = klass.name.split("::")
+				path = if klass.instance_of?(Module)
+								 File.join(@output, *parts[0..-1], "index.md")
+							 else
+								 File.join(@output, *parts[0..-2], "#{parts.last}.md")
+							 end
+
+				unless Dir.exist?(File.dirname(path))
+					FileUtils.mkdir_p((File.dirname(path)))
+				end
+				path
+			end
+
+			def resolver(klass)
+				parts = klass.name.split("::")
+				key = if parts.length == 1 && !klass.instance_of?(Module)
+								nil
+							else
+								parts.first
+							end
+
+				@doc_resolvers[key]
+			end
+
+			def class_sig(klass)
+				klass_name = klass.name.split("::").last
+
+				url = resolver(klass)&.class_url(klass)
+				if url
+					"#[#{klass_name}](#{url})"
+				else
+					"##{klass_name}"
+				end
+			end
+
+			def enum_sig(klass)
+				klass_name = klass.name.split("::").last
+				url = resolver(klass)&.enum_url(klass)
+				if url
+					"#[#{klass_name} Enum](#{url})"
+				else
+					"##{klass_name} Enum"
+				end
+			end
+
+			def enum_value_sig(klass, value)
+				url = resolver(klass)&.enum_value_url(klass, value)
+
+				if url
+					"[#{value}](#{url})"
+				else
+					"#{value}"
+				end
+			end
+
+			def union_sig(klass)
+				klass_name = klass.name.split("::").last
+				url =  resolver(klass)&.union_url(klass)
+				if url
+					"#[#{klass_name} Union](#{url})"
+				else
+					"##{klass_name} Union"
+				end
+			end
+
+			def method_sigs(klass, native_methods, method_sig)
+				native_methods.map do |native_method|
+					method_sig(klass, native_method, method_sig)
+				end.join("\n\n")
+			end
+
+			def type_url(klass)
+				resolver = resolver(klass)
+
+				if klass.instance_of?(Module)
+					resolver&.module_url(klass)
+				elsif !klass.respond_to?(:cpp_class)
+					resolver&.class_url(klass)
+				elsif klass.cpp_class.match(/^enum/i)
+					resolver&.enum_url(klass)
+				elsif klass.cpp_class.match(/^union/i)
+					resolver&.union_url(klass)
+				else
+					resolver&.class_url(klass)
+				end
+			end
+
+			def parameters_sig(klass, native)
+				native.parameters.map do |parameter|
+					resolver = resolver(parameter.klass)
+					url = type_url(parameter.klass)
+					if url
+						"#{parameter.arg.name}: [#{parameter.klass}](#{url})"
+					else
+						"#{parameter.arg.name}: #{parameter.klass}"
+					end
+				end.join(", ")
+			end
+
+			def return_sig(klass, native)
+				resolver = resolver(native.return_klass)
+				url = type_url(native.return_klass)
+				if url
+					"[#{native.return_klass}](#{url})"
+				else
+					"#{native.return_klass}"
+				end
+			end
+
+			def constructor_sig(klass, native)
+				url =  resolver(klass)&.method_url(klass, native)
+
+				if url
+					"[initialize](#{url})(#{parameters_sig(klass, native)})"
+				else
+					"initialize(#{parameters_sig(klass, native)})"
+				end
+			end
+
+			def method_sig(klass, native, singleton)
+				url = if singleton
+								resolver(klass)&.singleton_method_url(klass, native)
+							else
+								resolver(klass)&.method_url(klass, native)
+							end
+
+				name = ESCAPE_METHODS[native.name] || native.name
+
+				if url
+					"[#{name}](#{url})(#{parameters_sig(klass, native)}) -> #{return_sig(klass, native)}"
+				else
+					"#{name}(#{parameters_sig(klass, native)}) -> #{return_sig(klass, native)}"
+				end
+			end
+
+			def attribute_sig(klass, native_attributes)
+				attr_type = if native_attributes.size == 2
+											"read/write"
+										elsif native_attributes.first.kind == NativeKind::AttributeReader
+											"read"
+										else
+											"write"
+										end
+
+				native_attribute = native_attributes.first
+
+				attribute_resolver = resolver(klass)
+				attribute_url = attribute_resolver&.attribute_url(klass, native_attribute)
+
+				type_resolver = resolver(native_attribute.return_klass)
+				type_url = type_url(native_attribute.return_klass)
+
+				if attribute_url
+					"[#{native_attribute.name}](#{attribute_url}): [#{native_attribute.return_klass}](#{type_url}) (#{attr_type})"
+				else
+					"#{native_attribute.name}: [#{native_attribute.return_klass}](#{type_url}) (#{attr_type})"
+				end
+			end
+
+			def write_module(a_module)
+				native_singleton_functions = Registries.instance.natives.native_singleton_functions(a_module).sort.group_by(&:name)
+
+				path = output_path(a_module)
+				File.open(path, 'w') do |file|
+					file << "#" << a_module.name << "\n"
+					unless native_singleton_functions.empty?
+						file << "## Singleton Methods" << "\n"
+						native_singleton_functions.each do |name, natives|
+							file << method_sigs(a_module, natives, false) << "\n\n"
+						end
+						file << "\n"
+					end
+				end
+			end
+
+			def write_class(klass)
+				native_attributes = Registries.instance.natives.native_attributes(klass).sort.group_by(&:name)
+				native_singleton_functions = Registries.instance.natives.native_singleton_functions(klass).sort.group_by(&:name)
+				native_methods = Registries.instance.natives.native_methods(klass).sort.group_by(&:name)
+
+				path = output_path(klass)
+				File.open(path, 'w') do |file|
+					file << class_sig(klass) << "\n"
+
+					# Singleton methods
+					unless native_singleton_functions.empty?
+						file << "## Singleton Methods" << "\n"
+						native_singleton_functions.each do |name, natives|
+							file << method_sigs(klass, natives, true) << "\n\n"
+						end
+						file << "\n"
+					end
+
+					# Constructors
+					constructors = native_methods["initialize"]
+					if constructors
+						file << "## Constructors" << "\n"
+						constructors.each do |constructor|
+							file << constructor_sig(klass, constructor) << "\n\n"
+						end
+						file << "\n"
+					end
+
+					# Attributes
+					unless native_attributes.empty?
+						file << "## Attributes" << "\n"
+						native_attributes.each do |name, natives|
+							file << attribute_sig(klass, natives) << "\n\n"
+						end
+						file << "\n"
+					end
+
+					# Instance methods
+					unless native_methods.empty?
+						file << "## Methods" << "\n"
+						native_methods.each do |name, natives|
+							next if name == "initialize"
+							file << method_sigs(klass, natives, false) << "\n\n"
+						end
+						file << "\n"
+					end
+				end
+			end
+
+			def write_enum(klass)
+				klass_name = klass.name.split('::').last
+
+				path = output_path(klass)
+				File.open(path, 'w') do |file|
+					file << enum_sig(klass) << "\n"
+					file << "## Values" << "\n"
+					klass.values.each do |value|
+						file << "* " << enum_value_sig(klass, value) << "\n"
+					end
+				end
+			end
+
+			def write_union(klass)
+				klass_name = klass.name.split('::').last
+				native_attributes = Registries.instance.natives.native_attributes(klass).sort.group_by(&:name)
+
+				path = output_path(klass)
+				File.open(path, 'w') do |file|
+					file << union_sig(klass) << "\n"
+
+					# Attributes
+					unless native_attributes.empty?
+						file << "## Attributes" << "\n"
+						native_attributes.each do |name, natives|
+							file << attribute_sig(klass, natives) << "\n\n"
+						end
+						file << "\n"
+					end
+				end
+			end
+		end
+	end
+end

data/lib/rice/doc/rice.rb

@@ -0,0 +1,29 @@
+module Rice
+	module Doc
+		class Rice
+			def class_url(klass)
+			end
+
+			def module_url(klass)
+			end
+
+			def union_url(klass)
+			end
+
+			def enum_url(klass)
+			end
+
+			def enum_value_url(klass, enum_value)
+			end
+
+			def singleton_method_url(klass, native)
+			end
+
+			def method_url(klass, native)
+			end
+
+			def attribute_url(klass, native)
+			end
+		end
+	end
+end

data/lib/rice/doc/ruby.rb

@@ -0,0 +1,37 @@
+module Rice
+	module Doc
+		class Ruby
+			ROOT = "https://docs.ruby-lang.org/en/master"
+
+			def initialize
+			end
+
+			def class_url(klass)
+				name = klass.name.split('::').last
+				name[0].upcase! # Can't use capitalize because it lowercases other letters which breaks links like NilClass
+				"#{ROOT}/#{name}.html"
+			end
+
+			def module_url(klass)
+			end
+
+			def union_url(klass)
+			end
+
+			def enum_url(klass)
+			end
+
+			def enum_value_url(klass, enum_value)
+			end
+
+			def singleton_method_url(klass, native)
+			end
+
+			def method_url(klass, native)
+			end
+
+			def attribute_url(klass, native)
+			end
+		end
+	end
+end

data/lib/rice/doc.rb

@@ -0,0 +1,5 @@
+require_relative 'doc/cpp_reference'
+require_relative 'doc/doxygen'
+require_relative 'doc/rice'
+require_relative 'doc/ruby'
+require_relative 'doc/mkdocs'

data/lib/{make_rice_headers.rb → rice/make_rice_headers.rb}

@@ -76,4 +76,7 @@ combine_headers('rice.hpp')
 puts "Building stl.hpp"
 combine_headers('stl.hpp')
 
+puts "Building api.hpp"
+combine_headers('api.hpp')
+
 puts "Success"

data/lib/rice/native.rb

@@ -0,0 +1,18 @@
+module Rice
+	class Native
+		include Comparable
+
+		def <=>(other)
+			case
+				when self.name == other.name
+					self.parameters.size <=> other.parameters.size
+				when self.name == "initialize"
+					-1
+				when self.name == "initialize"
+					1
+				else
+					self.name <=> other.name
+			end
+		end
+	end
+end

data/lib/rice/native_registry.rb

@@ -0,0 +1,21 @@
+module Rice
+	class NativeRegistry
+		def native_attributes(klass)
+			self.native_by_kind(klass, [Rice::NativeKind::AttributeReader, Rice::NativeKind::AttributeWriter])
+		end
+
+		def native_methods(klass)
+			self.native_by_kind(klass, [Rice::NativeKind::Method])
+		end
+
+		def native_singleton_functions(klass)
+			self.native_by_kind(klass.singleton_class, [Rice::NativeKind::Function])
+		end
+
+		def native_by_kind(klass, kinds)
+			self.lookup(klass).find_all do |native|
+				kinds.include?(native.kind)
+			end
+		end
+	end
+end

data/lib/rice/parameter.rb

@@ -0,0 +1,7 @@
+module Rice
+	class Parameter
+		def to_s
+			"Parameter<#{self.arg.name}: #{self.klass.name}>"
+		end
+	end
+end

data/lib/rice/rbs.rb

@@ -0,0 +1,104 @@
+require 'erb'
+require 'fileutils'
+
+module Rice
+	class Rbs
+		attr_reader :extension, :output
+
+		def initialize(extension, output)
+			@extension = extension
+			@output = output
+		end
+
+		def generate
+			STDOUT << "Writing rbs files to #{@output}" << "\n"
+			require self.extension
+			types = Registries.instance.types
+			types.klasses.each do |klass|
+				process_class(klass)
+			end
+		end
+
+		def process_class(klass)
+			if ['Rice', 'Std'].include?(klass.name.split('::').first)
+				return
+			end
+
+			STDOUT << "  " << klass << "\n"
+
+			native_attributes = Registries.instance.natives.native_attributes(klass).sort.group_by(&:name)
+			native_functions = Registries.instance.natives.native_functions(klass).sort.group_by(&:name)
+			native_methods = Registries.instance.natives.native_methods(klass).sort.group_by(&:name)
+			content = render_template("class", :klass => klass,
+													      :native_attributes => native_attributes,
+    													  :native_functions => native_functions,
+		    											  :native_methods => native_methods)
+			write_file(klass, content)
+		end
+
+		def write_file(klass, content)
+			parts = klass.name.split("::")
+			file_name = "#{parts.pop}.rbs"
+			dir = File.join(self.output, *parts)
+			FileUtils.mkdir_p(dir)
+
+			path = File.join(dir, file_name)
+			File.write(path, content, mode: "wb")
+		end
+
+		def attribute_sig(native_attributes)
+			attr_type = if native_attributes.size == 2
+									 "attr_accessor"
+								 elsif native_attributes.first.kind == Rice::NativeKind::AttributeReader
+									 "attr_reader"
+								 else
+									 "attr_writer"
+									end
+			"#{attr_type} #{native_attributes.first.name}: #{native_attributes.first.return_type}"
+		end
+
+		def method_sigs(native_methods, indent = 0)
+			join_string = "\n" + (" " * indent) + "| "
+			a = native_methods.map do |native_method|
+				method_sig(native_method)
+			end
+			a.join(join_string)
+		end
+
+		def method_sig(native)
+			params = native.parameters.map do |parameter|
+				"#{parameter.arg.name}: #{parameter.klass}"
+			end.join(", ")
+			"(#{params}) -> #{native.return_type}"
+		end
+
+		def render_template(template, local_variables = {})
+			template = ERB.new(self.template, :trim_mode => '-')
+			b = self.binding
+			local_variables.each do |key, value|
+				b.local_variable_set(key, value)
+			end
+			template.result(b)
+		end
+
+		def template
+			content = <<~EOS
+        module <%= klass.name.split("::")[0..-2].join("::") %>
+          class <%= klass.name.split("::").last %>
+          <%- native_functions.each do |name, functions| -%>
+            def self.<%= name %>: <%= method_sigs(functions, name.length + 5) %>
+          <%- end -%>
+        <%= native_functions.empty? ? "" : "\n" -%>
+          <%- native_attributes.each do |name, attributes| -%>
+            <%= attribute_sig(attributes) %>
+          <%- end -%>
+        <%= native_attributes.empty? ? "" : "\n" -%>
+          <%- native_methods.each do |name, methods| -%>
+            def <%= name %>: <%= method_sigs(methods, name.length + 5) %>
+          <%- end -%>
+          end
+        end
+			EOS
+		end
+	end
+end

data/lib/rice/version.rb

@@ -1,3 +1,3 @@
 module Rice
-  VERSION = "4.6.1"
+  VERSION = "4.7.0"
 end

data/lib/rice.rb

@@ -1 +1,5 @@
 require_relative "rice/version"
+require_relative "rice/native"
+require_relative "rice/native_registry"
+require_relative "rice/parameter"
+require_relative "rice/rbs"

data/lib/rubygems/cmake_builder.rb

@@ -25,36 +25,31 @@
 #  -D<CMAKE_VARIABLE> to set a CMake variable (for example -DCMAKE_BUILD_TYPE=Release)
 #  --preset <preset_name> to use a preset
 #
-# If the Gem author provides presets, via CMakePresets.json file, you will likely want to us use one of them.
-# If not, then you may wish to specify a generator (Ninja is recommended since it can build projects in parallel
-# versus a Make generator which build ins serial and thus is *much* slower).
-
-require "fileutils"
+# If the Gem author provides presets, via CMakePresets.json file, you will likely want to use one of them.
+# If not, you may wish to specify a generator. Ninja is recommended because it can build projects in parallel
+# and thus much faster than building them serially like Make does.
 
 class Gem::Ext::CmakeBuilder
   attr_accessor :runner, :profile
-
   def initialize
     @runner = self.class.method(:run)
     @profile = :release
   end
 
-  def build(extension, gem_dir, results, args = [], lib_dir = nil, cmake_dir = Dir.pwd, target_rbconfig = Gem.target_rbconfig)
+  def build(extension, dest_path, results, args = [], lib_dir = nil, cmake_dir = Dir.pwd,
+            target_rbconfig = Gem.target_rbconfig)
     if target_rbconfig.path
       warn "--target-rbconfig is not yet supported for CMake extensions. Ignoring"
     end
 
-    # Make sure lib dir is set
-    lib_dir ||= File.join(gem_dir, "lib")
-
     # Figure the build dir
     build_dir = File.join(cmake_dir, "build")
 
     # Check if the gem defined presets
-    check_presets(cmake_dir, args)
+    check_presets(cmake_dir, args, results)
 
     # Configure
-    configure(cmake_dir, build_dir, lib_dir, args, results)
+    configure(cmake_dir, build_dir, dest_path, args, results)
 
     # Compile
     compile(cmake_dir, build_dir, args, results)
@@ -62,16 +57,17 @@ class Gem::Ext::CmakeBuilder
     results
   end
 
-  def configure(cmake_dir, build_dir, lib_dir, args, results)
+  def configure(cmake_dir, build_dir, install_dir, args, results)
     cmd = ["cmake",
            cmake_dir,
-           "-B #{build_dir}",
-           "-DCMAKE_RUNTIME_OUTPUT_DIRECTORY=#{lib_dir}", # Windows
-           "-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=#{lib_dir}", # Not Windows
+           "-B",
+           build_dir,
+           "-DCMAKE_RUNTIME_OUTPUT_DIRECTORY=#{install_dir}", # Windows
+           "-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=#{install_dir}", # Not Windows
            *Gem::Command.build_args,
            *args]
 
-    runner.call(cmd, results, "cmake", cmake_dir)
+    runner.call(cmd, results, "cmake_configure", cmake_dir)
   end
 
   def compile(cmake_dir, build_dir, args, results)
@@ -80,32 +76,33 @@ class Gem::Ext::CmakeBuilder
            build_dir.to_s,
            "--config",
            @profile.to_s]
-    runner.call(cmd, results, "cmake", cmake_dir)
+
+    runner.call(cmd, results, "cmake_compile", cmake_dir)
   end
 
   private
 
-  def check_presets(cmake_dir, args)
+  def check_presets(cmake_dir, args, results)
     # Return if the user specified a preset
     return unless args.grep(/--preset/i).empty?
 
     cmd = ["cmake",
            "--list-presets"]
 
+    presets = Array.new
     begin
-      require "open3"
-      build_env = { "SOURCE_DATE_EPOCH" => Gem.source_date_epoch_string }
-      stdout, _, _ = Open3.capture3(build_env, *cmd, chdir: cmake_dir)
-      message = <<~EOS
+      runner.call(cmd, presets, "cmake_presets", cmake_dir)
+
+      # Remove the first two lines of the array which is the current_directory and the command
+      # that was run
+      presets = presets[2..].join
+      results << <<~EOS
         The gem author provided a list of presets that can be used to build the gem. To use a preset specify it on the command line:
 
           gem install <gem_name> -- --preset <preset_name>
 
-        #{stdout}
+        #{presets}
       EOS
-
-      STDOUT << message << "\n"
-      STDOUT.flush
     rescue Gem::InstallError
       # Do nothing, CMakePresets.json was not included in the Gem
     end

data/rice/Arg.hpp

@@ -81,9 +81,9 @@ namespace Rice
     virtual Arg& takeOwnership();
     bool isOwner();
 
-    //! Is the parameter a C style array
-    virtual Arg& setArray();
-    bool isArray();
+    //! Is the parameter a buffer
+    virtual Arg& setBuffer();
+    bool isBuffer();
 
   public:
     std::string name;
@@ -96,7 +96,7 @@ namespace Rice
     bool isKeepAlive_ = false;
     bool isOwner_ = false;
     bool isOpaque_ = false;
-    bool isArray_ = false;
+    bool isBuffer_ = false;
 
   };
 } // Rice