ffi-clang 0.15.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33f36e58a42accf204240213d014bfbd1527ebe23239a74c7472829d502d8fc5
-  data.tar.gz: 9b1e75ed934bb3572fd324cf80ea1c1278880abdc487482281e181bb4098932d
+  metadata.gz: 1550a49c2829fb140990ff821a8681f1c6ab38587e167b408a6d7dccc8bee9df
+  data.tar.gz: 9ce46bcbba80c9f97bef6f5f3a444fb8608d280dc21c75410855088fdbc2eaec
 SHA512:
-  metadata.gz: 07164ccdc62ecb4e8a106fa49f0776c2487e38a2d0aa2df47cf32f0ae2402a63bfb4ac7e27f5ed41d5222cc61a09eca3b64963c7c560b846e5329ef1173d3168
-  data.tar.gz: 7e5ae23e82ec66cb97a6d6943fcdf99b124dd6cb902cd12e10216b75310885b2f10a1ec9b62855a83d2acfe523202fa1382fdedebc1c302b25c1315a586591cd
+  metadata.gz: 03053f8d75313265b8bfba38addd7b3ba5fcfc93f064136e79fd9b6c09a97c268b56eb02ad1716c352eade3121483d3c0b7d5b6caf6745f5f2e8cd2e72e74f3f
+  data.tar.gz: b987eb3c2ebfc91f946079b8ee0e64c8cf21181791393a934c7c6fdd3bfab0c4147afeda83198b52d85c1a07a69ed2e0d97a34bc5084d9f72a5b2057c05122bc

data/lib/ffi/clang/cursor.rb

@@ -813,6 +813,61 @@ module FFI
 				Lib.is_abstract(@cursor) != 0
 			end
 			
+			# Check if this class/struct is copyable: it has no inaccessible
+			# (deleted, private, or protected) copy constructor, and every base
+			# class is copyable (recursively). Returns true on cursors that
+			# don't denote a class/struct, since the question doesn't apply.
+			#
+			# A class with no explicit copy constructor is treated as copyable —
+			# the implicit one is generated. We only flag explicit `= delete` or
+			# private/protected access.
+			#
+			# @returns [Boolean] True if instances of this type can be copied.
+			def copyable?
+				return true unless [:cursor_class_decl, :cursor_struct].include?(self.kind)
+				
+				copy_constructors = self.find_by_kind(false, :cursor_constructor).select(&:copy_constructor?)
+				copy_constructors.each do |constructor|
+					return false if constructor.deleted? || constructor.private? || constructor.protected?
+				end
+				
+				self.find_by_kind(false, :cursor_cxx_base_specifier).each do |base|
+					base_decl = base.type.declaration
+					next if base_decl.kind == :cursor_no_decl_found
+					return false unless base_decl.copyable?
+				end
+				
+				true
+			end
+			
+			# Check if this class/struct is copy-assignable: it has no
+			# inaccessible (deleted, private, or protected) copy assignment
+			# operator, and every base class is copy-assignable (recursively).
+			# Returns true on cursors that don't denote a class/struct, since
+			# the question doesn't apply.
+			#
+			# A class with no explicit copy assignment operator is treated as
+			# copy-assignable — the implicit one is generated. We only flag
+			# explicit `= delete` or private/protected access.
+			#
+			# @returns [Boolean] True if instances of this type can be copy-assigned.
+			def copy_assignable?
+				return true unless [:cursor_class_decl, :cursor_struct].include?(self.kind)
+				
+				copy_assignment_operators = self.find_by_kind(false, :cursor_cxx_method).select(&:copy_assignment_operator?)
+				copy_assignment_operators.each do |operator|
+					return false if operator.deleted? || operator.private? || operator.protected?
+				end
+				
+				self.find_by_kind(false, :cursor_cxx_base_specifier).each do |base|
+					base_decl = base.type.declaration
+					next if base_decl.kind == :cursor_no_decl_found
+					return false unless base_decl.copy_assignable?
+				end
+				
+				true
+			end
+			
 			# Check if this is a scoped enum.
 			# @returns [Boolean] True if it's a scoped enum.
 			def enum_scoped?

data/lib/ffi/clang/types/type.rb

@@ -127,17 +127,79 @@ module FFI
 				
 				# Get the type with all qualifiers (const, volatile, restrict) removed.
 				# @returns [Type] The unqualified type.
+				#
+				# Guards against :type_invalid input: clang_getUnqualifiedType has
+				# no null check on the underlying QualType (unlike its siblings
+				# clang_getNonReferenceType / clang_getCanonicalType / etc.) and
+				# segfaults on invalid types. Returning self preserves the
+				# invalid kind without entering libclang.
 				def unqualified_type
+					return self if self.kind == :type_invalid
 					Type.create Lib.get_unqualified_type(@type), @translation_unit
 				end
 				
+				# True if this type is an lvalue or rvalue reference.
+				# @returns [Boolean] Whether this type is `T &` or `T &&`.
+				def reference?
+					self.kind == :type_lvalue_ref || self.kind == :type_rvalue_ref
+				end
+				
 				# Get the non-reference type.
 				# For reference types, returns the type that is being referenced.
 				# @returns [Type] The non-reference type.
+				#
+				# Guards against :type_invalid input: clang_getNonReferenceType
+				# dereferences the underlying QualType without a null check and
+				# segfaults on invalid types. Returning self preserves the
+				# invalid kind without entering libclang.
 				def non_reference_type
+					return self if self.kind == :type_invalid
 					Type.create Lib.get_non_reference_type(@type), @translation_unit
 				end
 				
+				# Get the intrinsic type — strip the reference, follow pointer
+				# indirection until reaching a non-pointer type, then drop
+				# cv-qualifiers. Named after Rice's `intrinsic_type` metafunction
+				# of the same shape. Useful when asking "what does this type
+				# ultimately denote?" for skip-list and bindability checks.
+				#
+				# Examples:
+				# * `T &`        becomes `T`
+				# * `T *`        becomes `T`
+				# * `T **&`      becomes `T`
+				# * `const T &`  becomes `T`
+				#
+				# @returns [Type] The intrinsic (innermost, unqualified) type.
+				def intrinsic_type
+					type = self.non_reference_type
+					while type.kind == :type_pointer
+						type = type.pointee
+					end
+					type.unqualified_type
+				end
+				
+				# Check if this type's declaration (after reference stripping)
+				# has an accessible copy constructor and copyable bases.
+				# Returns true for non-class types (fundamentals, pointers,
+				# enums) and for types whose declaration is unavailable
+				# (:cursor_no_decl_found).
+				#
+				# @returns [Boolean] True if instances of this type can be copied.
+				def copyable?
+					self.non_reference_type.declaration.copyable?
+				end
+				
+				# Check if this type's declaration (after reference stripping)
+				# has an accessible copy assignment operator and copy-assignable
+				# bases. Returns true for non-class types (fundamentals, pointers,
+				# enums) and for types whose declaration is unavailable
+				# (:cursor_no_decl_found).
+				#
+				# @returns [Boolean] True if instances of this type can be copy-assigned.
+				def copy_assignable?
+					self.non_reference_type.declaration.copy_assignable?
+				end
+				
 				# Get the type of a template argument at the given index.
 				# For template specializations (e.g., `std::vector<int>`), this returns the type of
 				# the template argument at the specified position.
@@ -199,11 +261,236 @@ module FFI
 				end
 				
 				# Get the fully qualified name of this type.
-				# @parameter policy [PrintingPolicy] The printing policy to use.
+				#
+				# On libclang 21+ this dispatches to clang_getFullyQualifiedName.
+				# On earlier libclang versions it falls back to a Ruby shim that
+				# composes existing libclang APIs (declaration, qualified_name,
+				# template arguments, pointer/array/reference unwrapping, etc.).
+				#
+				# Known shim limitation: STL container typedefs that depend on
+				# default template arguments (e.g., `std::vector<T>::iterator`)
+				# don't expand the defaults. Output is valid C++ and matches
+				# the native result for non-STL types.
+				#
+				# @parameter policy [PrintingPolicy] The printing policy to use. Ignored by the shim.
 				# @parameter with_global_ns_prefix [Boolean] Whether to prepend "::".
 				# @returns [String] The fully qualified type name.
-				def fully_qualified_name(policy, with_global_ns_prefix: false)
-					Lib.extract_string Lib.get_fully_qualified_name(@type, policy, with_global_ns_prefix ? 1 : 0)
+				def fully_qualified_name(policy = nil, with_global_ns_prefix: false)
+					if Lib.respond_to?(:get_fully_qualified_name)
+						Lib.extract_string Lib.get_fully_qualified_name(@type, policy, with_global_ns_prefix ? 1 : 0)
+					else
+						result = fqn_impl(policy)
+						with_global_ns_prefix ? "::#{result}" : result
+					end
+				end
+				
+				# Shim implementation of fully_qualified_name. Recursively walks the
+				# type tree, dispatching by kind. Public so it can be invoked across
+				# Type subclass boundaries during recursion.
+				# @parameter policy [PrintingPolicy] Threaded for native API parity; ignored.
+				# @returns [String] The fully qualified type spelling.
+				def fqn_impl(policy)
+					case self.kind
+					when :type_lvalue_ref
+						"#{self.non_reference_type.fqn_impl(policy)} &"
+					when :type_rvalue_ref
+						"#{self.non_reference_type.fqn_impl(policy)} &&"
+					when :type_pointer
+						fqn_pointer(policy)
+					when :type_constant_array
+						"#{self.element_type.fqn_impl(policy)}[#{self.size}]"
+					when :type_incomplete_array
+						"#{self.element_type.fqn_impl(policy)}[]"
+					when :type_elaborated
+						fqn_elaborated(policy)
+					when :type_record
+						fqn_record
+					else
+						self.spelling
+					end
+				end
+				
+				# Spell a pointer type and its qualifier chain. Function pointers
+				# get a single rendering with parameter list; data pointers walk
+				# the chain collecting `*`/`*const` parts and qualify the leaf
+				# child once. Output matches native fqn: `int **`, `const char *const`, etc.
+				# @parameter policy [PrintingPolicy] Threaded to recursive fqn_impl calls.
+				# @returns [String] The fully qualified pointer type spelling.
+				def fqn_pointer(policy)
+					pointee = self.pointee
+					
+					if [:type_function_proto, :type_function_no_proto].include?(pointee.kind)
+						ptr_const = self.const_qualified? ? " const" : ""
+						result_type = pointee.result_type.fqn_impl(policy)
+						arg_types = pointee.arg_types.map{|arg_type| arg_type.fqn_impl(policy)}.join(", ")
+						return "#{result_type} (*#{ptr_const})(#{arg_types})"
+					end
+					
+					parts = []
+					current = self
+					while current.kind == :type_pointer
+						inner = current.pointee
+						break if [:type_function_proto, :type_function_no_proto].include?(inner.kind)
+						
+						parts << (current.const_qualified? ? "*const" : "*")
+						current = inner
+					end
+					
+					"#{current.fqn_impl(policy)} #{parts.reverse.join}"
+				end
+				
+				# Spell an elaborated type (typedef / type alias / enum / class)
+				# preserving the alias name where appropriate and qualifying
+				# template arguments recursively.
+				# @parameter policy [PrintingPolicy] Threaded to recursive calls.
+				# @returns [String] The fully qualified elaborated type spelling.
+				def fqn_elaborated(policy)
+					decl = self.declaration
+					const_prefix = self.const_qualified? ? "const " : ""
+					
+					case decl.kind
+					when :cursor_typedef_decl, :cursor_type_alias_decl
+						# Preserve the typedef/alias name and qualify with namespace.
+						spelling = self.unqualified_type.spelling
+						qualified = decl.qualified_name
+						
+						if spelling.include?("::")
+							# Already partially qualified. For nested typedefs in
+							# template classes (e.g., std::vector<Pixel>::iterator),
+							# qualify template args using the parent type's fqn.
+							parent = decl.semantic_parent
+							if parent.kind == :cursor_class_decl || parent.kind == :cursor_struct
+								parent_type = parent.type
+								parent_fqn = parent_type.fqn_impl(policy)
+								member_name = decl.spelling
+								"#{const_prefix}#{parent_fqn}::#{member_name}"
+							else
+								"#{const_prefix}#{spelling}"
+							end
+						elsif qualified
+							"#{const_prefix}#{qualified}"
+						else
+							"#{const_prefix}#{spelling}"
+						end
+						
+					when :cursor_enum_decl
+						"#{const_prefix}#{decl.qualified_name}"
+						
+					else
+						# Alias-template detection: e.g. `AliasOptional<int>` -> `Optional<int>`.
+						# The elaborated spelling preserves the alias; fqn_record
+						# would resolve to the underlying type. Use spelling when
+						# it's already qualified.
+						unqual = self.unqualified_type.spelling
+						if unqual.include?("::") && decl.spelling != unqual.sub(/<.*/, "").split("::").last
+							"#{const_prefix}#{unqual}"
+						else
+							base = fqn_record
+							if self.const_qualified? && !base.start_with?("const ")
+								"const #{base}"
+							else
+								base
+							end
+						end
+					end
+				end
+				
+				# Spell a record type (class/struct) using its declaration's
+				# type spelling, which suppresses inline namespaces and includes
+				# template args. Falls back to qualified_name + spelling args
+				# for dependent types.
+				# @returns [String] The fully qualified record type spelling.
+				def fqn_record
+					decl = self.declaration
+					return self.spelling if decl.kind == :cursor_no_decl_found
+					
+					const_prefix = self.const_qualified? ? "const " : ""
+					
+					# decl.type.spelling gives the right qualification (no inline
+					# ns, with template args).
+					decl_spelling = decl.type.spelling
+					if decl_spelling && !decl_spelling.empty? && decl_spelling.include?("::")
+						# For concrete template types, recursively qualify args.
+						n = self.num_template_arguments
+						if n > 0
+							base = decl_spelling.sub(/<.*/, "")
+							template_args = fqn_template_args(nil)
+							"#{const_prefix}#{base}#{template_args}"
+						else
+							"#{const_prefix}#{decl_spelling}"
+						end
+					else
+						# Fallback for types where decl.type.spelling is unqualified.
+						qualified = decl.qualified_name
+						bare_spelling = self.unqualified_type.spelling
+						template_args = bare_spelling.include?("<") ? bare_spelling[/<.*/] : ""
+						"#{const_prefix}#{qualified}#{template_args}"
+					end
+				end
+				
+				# Build the qualified template argument list by recursing into
+				# each type argument. Non-type template parameters (e.g.
+				# integral values) are recovered from the type's spelling.
+				# @parameter policy [PrintingPolicy] Threaded to recursive calls.
+				# @returns [String] The bracketed argument list, including angle brackets, or empty.
+				def fqn_template_args(policy)
+					n = self.num_template_arguments
+					return "" unless n > 0
+					
+					# Extract original args from spelling for non-type template params.
+					spelling_args = parse_template_args_from_spelling
+					
+					args = (0...n).map do |i|
+						arg_type = self.template_argument_type(i)
+						if arg_type.kind == :type_invalid
+							# Non-type template arg (e.g., int N=3) — use from spelling.
+							spelling_args ? spelling_args[i] : nil
+						else
+							arg_type.fqn_impl(policy)
+						end
+					end.compact
+					
+					return "" if args.empty?
+					"<#{args.join(", ")}>"
+				end
+				
+				# Parse template arguments from the type's unqualified spelling,
+				# respecting nested angle brackets. Used to recover non-type
+				# template arguments that libclang surfaces only as text.
+				# @returns [Array(String) | nil] The argument substrings, or nil if no `<` was found.
+				def parse_template_args_from_spelling
+					bare = self.unqualified_type.spelling
+					start = bare.index("<")
+					return nil unless start
+					
+					depth = 0
+					args = []
+					current = +""
+					bare[start + 1..].each_char do |c|
+						case c
+						when "<"
+							depth += 1
+							current << c
+						when ">"
+							if depth == 0
+								args << current.strip unless current.strip.empty?
+								break
+							else
+								depth -= 1
+								current << c
+							end
+						when ","
+							if depth == 0
+								args << current.strip
+								current = +""
+							else
+								current << c
+							end
+						else
+							current << c
+						end
+					end
+					args
 				end
 				
 				# Visit all base classes of a C++ record type.

data/lib/ffi/clang/version.rb

@@ -10,6 +10,6 @@
 module FFI
 	# @namespace
 	module Clang
-		VERSION = "0.15.1"
+		VERSION = "0.16.0"
 	end
 end

data/readme.md

@@ -41,6 +41,16 @@ For example, to use a specific LLVM installation:
 
 Please see the [project releases](https://socketry.github.io/ffi-clang/releases/index) for all releases.
 
+### v0.16.0
+
+  - Add <code class="language-ruby">FFI::Clang::Types::Type\#intrinsic\_type</code>, which strips references and follows pointer indirection until reaching a non-pointer type and then drops cv-qualifiers.
+  - Add <code class="language-ruby">FFI::Clang::Types::Type\#reference?</code>, a one-liner predicate over `:type_lvalue_ref` and `:type_rvalue_ref`.
+  - Add <code class="language-ruby">FFI::Clang::Cursor\#copyable?</code> and <code class="language-ruby">FFI::Clang::Types::Type\#copyable?</code>, predicates that return true when a class/struct has an accessible copy constructor (none deleted, private, or protected) and every base class is copyable.
+  - Add <code class="language-ruby">FFI::Clang::Cursor\#copy\_assignable?</code> and <code class="language-ruby">FFI::Clang::Types::Type\#copy\_assignable?</code>, predicates that return true when a class/struct has an accessible copy assignment operator (none deleted, private, or protected) and every base class is copy-assignable.
+  - <code class="language-ruby">FFI::Clang::Types::Type\#fully\_qualified\_name</code> now works on libclang versions earlier than 21 via a Ruby shim that composes existing libclang APIs (declaration, qualified\_name, template arguments, pointer/array/reference unwrapping).
+  - Guard <code class="language-ruby">FFI::Clang::Types::Type\#unqualified\_type</code> against `:type_invalid` input.
+  - Guard <code class="language-ruby">FFI::Clang::Types::Type\#non\_reference\_type</code> against `:type_invalid` input.
+
 ### v0.15.1
 
   - Use `-isystem` instead of `-I` for auto-discovered MSVC system include paths so that `in_system_header?` correctly identifies system headers.
@@ -101,18 +111,6 @@ Please see the [project releases](https://socketry.github.io/ffi-clang/releases/
   - Set `cursor_translation_unit` enum value based on the Clang version. (\#64)
   - Add various C++ introspection methods. (\#66)
 
-### v0.7.0
-
-  - Fix incorrect return type of `clang_getTranslationUnitSpelling`.
-  - Fix `compilation_database_spec`.
-  - Fix libclang lookup for Xcode.
-  - Fix warning on class re-definition.
-  - Update cursor kinds.
-  - Find `libclang.dll` under Windows.
-  - Allow retrieval of list of references from a Cursor.
-  - Implement libclang `findReferencesInFile` functionality.
-  - Allow `TranslationUnit#file` to return the main file.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,15 @@
 # Releases
 
+## v0.16.0
+
+  - Add {ruby FFI::Clang::Types::Type\#intrinsic\_type}, which strips references and follows pointer indirection until reaching a non-pointer type and then drops cv-qualifiers.
+  - Add {ruby FFI::Clang::Types::Type\#reference?}, a one-liner predicate over `:type_lvalue_ref` and `:type_rvalue_ref`.
+  - Add {ruby FFI::Clang::Cursor\#copyable?} and {ruby FFI::Clang::Types::Type\#copyable?}, predicates that return true when a class/struct has an accessible copy constructor (none deleted, private, or protected) and every base class is copyable.
+  - Add {ruby FFI::Clang::Cursor\#copy\_assignable?} and {ruby FFI::Clang::Types::Type\#copy\_assignable?}, predicates that return true when a class/struct has an accessible copy assignment operator (none deleted, private, or protected) and every base class is copy-assignable.
+  - {ruby FFI::Clang::Types::Type\#fully\_qualified\_name} now works on libclang versions earlier than 21 via a Ruby shim that composes existing libclang APIs (declaration, qualified\_name, template arguments, pointer/array/reference unwrapping).
+  - Guard {ruby FFI::Clang::Types::Type\#unqualified\_type} against `:type_invalid` input.
+  - Guard {ruby FFI::Clang::Types::Type\#non\_reference\_type} against `:type_invalid` input.
+
 ## v0.15.1
 
   - Use `-isystem` instead of `-I` for auto-discovered MSVC system include paths so that `in_system_header?` correctly identifies system headers.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ffi-clang
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.16.0
 platform: ruby
 authors:
 - Samuel Williams