ffi-clang 0.13.0 → 0.14.0

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

@@ -2,101 +2,145 @@
 
 # Released under the MIT License.
 # Copyright, 2013, by Carlos Martín Nieto.
-# Copyright, 2013-2024, by Samuel Williams.
+# Copyright, 2013-2025, by Samuel Williams.
 # Copyright, 2013, by Takeshi Watanabe.
 # Copyright, 2014, by Masahiro Sano.
 # Copyright, 2014, by Niklas Therning.
-# Copyright, 2024, by Charlie Savage.
+# Copyright, 2024-2025, by Charlie Savage.
 
 module FFI
 	module Clang
 		module Types
+			# Represents a type in the C/C++ type system.
+			# This class wraps libclang's type representation and provides methods to query type properties.
 			class Type
+				# @attribute [r] type
+				# 	@returns [FFI::Struct] The underlying CXType structure.
+				# @attribute [r] translation_unit
+				# 	@returns [TranslationUnit] The translation unit this type belongs to.
 				attr_reader :type, :translation_unit
-
-				# Just hard code the types - they are not likely to change
+				
+				# Create a type instance of the appropriate subclass based on the type kind.
+				# @parameter cxtype [FFI::Struct] The low-level CXType structure.
+				# @parameter translation_unit [TranslationUnit] The translation unit this type belongs to.
+				# @returns [Type] A Type instance of the appropriate subclass.
 				def self.create(cxtype, translation_unit)
 					case cxtype[:kind]
-						when :type_pointer, :type_block_pointer, :type_obj_c_object_pointer, :type_member_pointer
-							Pointer.new(cxtype, translation_unit)
-						when :type_constant_array, :type_incomplete_array, :type_variable_array, :type_dependent_sized_array
-							Array.new(cxtype, translation_unit)
-						when :type_vector
-							Vector.new(cxtype, translation_unit)
-						when :type_function_no_proto, :type_function_proto
-							Function.new(cxtype, translation_unit)
-						when :type_elaborated
-							Elaborated.new(cxtype, translation_unit)
-						when :type_typedef
-							TypeDef.new(cxtype, translation_unit)
-						when :type_record
-							Record.new(cxtype, translation_unit)
-						else
-							Type.new(cxtype, translation_unit)
+					when :type_pointer, :type_block_pointer, :type_obj_c_object_pointer, :type_member_pointer
+						Pointer.new(cxtype, translation_unit)
+					when :type_constant_array, :type_incomplete_array, :type_variable_array, :type_dependent_sized_array
+						Array.new(cxtype, translation_unit)
+					when :type_vector
+						Vector.new(cxtype, translation_unit)
+					when :type_function_no_proto, :type_function_proto
+						Function.new(cxtype, translation_unit)
+					when :type_elaborated
+						Elaborated.new(cxtype, translation_unit)
+					when :type_typedef
+						TypeDef.new(cxtype, translation_unit)
+					when :type_record
+						Record.new(cxtype, translation_unit)
+					else
+						Type.new(cxtype, translation_unit)
 					end
 				end
-
+				
+				# Create a new type instance.
+				# @parameter type [FFI::Struct] The low-level CXType structure.
+				# @parameter translation_unit [TranslationUnit] The translation unit this type belongs to.
 				def initialize(type, translation_unit)
 					@type = type
 					@translation_unit = translation_unit
 				end
-
+				
+				# Get the kind of this type.
+				# @returns [Symbol] The type kind (e.g., :type_int, :type_pointer).
 				def kind
 					@type[:kind]
 				end
-
+				
+				# Get the spelling of this type's kind.
+				# @returns [String] A human-readable string describing the type kind.
 				def kind_spelling
 					Lib.extract_string Lib.get_type_kind_spelling @type[:kind]
 				end
-
+				
+				# Get the spelling of this type.
+				# @returns [String] The type as it would appear in source code.
 				def spelling
 					Lib.extract_string Lib.get_type_spelling(@type)
 				end
-
+				
+				# Get the canonical type.
+				# @returns [Type] The canonical (unqualified, unaliased) form of this type.
 				def canonical
 					Type.create Lib.get_canonical_type(@type), @translation_unit
 				end
-
+				
+				# Check if this is a Plain Old Data (POD) type.
+				# @returns [Boolean] True if this is a POD type.
 				def pod?
 					Lib.is_pod_type(@type) != 0
 				end
-
+				
+				# Check if this type is const-qualified.
+				# @returns [Boolean] True if the type has a const qualifier.
 				def const_qualified?
 					Lib.is_const_qualified_type(@type) != 0
 				end
-
+				
+				# Check if this type is volatile-qualified.
+				# @returns [Boolean] True if the type has a volatile qualifier.
 				def volatile_qualified?
 					Lib.is_volatile_qualified_type(@type) != 0
 				end
-
+				
+				# Check if this type is restrict-qualified.
+				# @returns [Boolean] True if the type has a restrict qualifier.
 				def restrict_qualified?
 					Lib.is_restrict_qualified_type(@type) != 0
 				end
-
+				
+				# Get the alignment of this type in bytes.
+				# @returns [Integer] The alignment requirement in bytes.
 				def alignof
 					Lib.type_get_align_of(@type)
 				end
-
+				
+				# Get the size of this type in bytes.
+				# @returns [Integer] The size in bytes, or -1 if the size cannot be determined.
 				def sizeof
 					Lib.type_get_size_of(@type)
 				end
-
+				
+				# Get the ref-qualifier for this type (C++ only).
+				# @returns [Symbol] The ref-qualifier (:ref_qualifier_none, :ref_qualifier_lvalue, :ref_qualifier_rvalue).
 				def ref_qualifier
 					Lib.type_get_cxx_ref_qualifier(@type)
 				end
-
+				
+				# Get the cursor for the declaration of this type.
+				# @returns [Cursor] The cursor representing the type declaration.
 				def declaration
 					Cursor.new Lib.get_type_declaration(@type), @translation_unit
 				end
-
+				
+				# Get the non-reference type.
+				# For reference types, returns the type that is being referenced.
+				# @returns [Type] The non-reference type.
 				def non_reference_type
 					Type.create Lib.get_non_reference_type(@type),@translation_unit
 				end
-
+				
+				# Compare this type with another for equality.
+				# @parameter other [Type] The other type to compare.
+				# @returns [Boolean] True if the types are equal.
 				def ==(other)
 					Lib.equal_types(@type, other.type) != 0
 				end
-
+				
+				# Get a string representation of this type.
+				# @returns [String] A string describing this type.
 				def to_s
 					"#{self.class.name} <#{self.kind}: #{self.spelling}>"
 				end

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

@@ -1,15 +1,27 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Charlie Savage.
+# Copyright, 2025, by Samuel Williams.
+
 module FFI
 	module Clang
 		module Types
+			# Represents a typedef type.
+			# A typedef provides an alias for another type.
 			class TypeDef < Type
+				# Get the canonical (underlying) type.
+				# @returns [Type] The canonical type that this typedef aliases.
 				def canonical
 					Type.create Lib.get_canonical_type(@type), @translation_unit
 				end
-
+				
+				# Check if this typedef aliases an anonymous type.
+				# @returns [Boolean] True if the canonical type is an anonymous record.
 				def anonymous?
 					self.canonical.kind == :type_record && self.canonical.anonymous?
 				end
 			end
 		end
 	end
-end
+end

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

@@ -1,11 +1,23 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Charlie Savage.
+# Copyright, 2025, by Samuel Williams.
+
 module FFI
 	module Clang
 		module Types
+			# Represents a vector type (SIMD vector).
+			# Vector types are used for SIMD operations and have a fixed number of elements of the same type.
 			class Vector < Type
+				# Get the element type of this vector.
+				# @returns [Type] The type of elements in this vector.
 				def element_type
 					Type.create Lib.get_element_type(@type), @translation_unit
 				end
-
+				
+				# Get the number of elements in this vector.
+				# @returns [Integer] The number of elements.
 				def size
 					Lib.get_num_elements(@type)
 				end

data/lib/ffi/clang/unsaved_file.rb

@@ -2,32 +2,42 @@
 
 # Released under the MIT License.
 # Copyright, 2013, by Carlos Martín Nieto.
-# Copyright, 2013-2022, by Samuel Williams.
+# Copyright, 2013-2025, by Samuel Williams.
 # Copyright, 2014, by Masahiro Sano.
 
 module FFI
 	module Clang
+		# Represents an unsaved file with in-memory contents for parsing.
 		class UnsavedFile
+			# Initialize an unsaved file with filename and contents.
+			# @parameter filename [String] The path to the unsaved file.
+			# @parameter contents [String] The in-memory contents of the file.
 			def initialize(filename, contents)
 				@filename = filename
 				@contents = contents
 			end
-
-			attr_accessor :filename, :contents
-
-
+			
+			# @attribute [String] The path to the unsaved file.
+			attr_accessor :filename
+			
+			# @attribute [String] The in-memory contents of the file.
+			attr_accessor :contents
+			
+			# Convert an array of unsaved files to a libclang pointer structure.
+			# @parameter unsaved [Array(UnsavedFile)] The array of unsaved files.
+			# @returns [FFI::MemoryPointer | Nil] A pointer to the unsaved file structures, or `nil` if empty.
 			def self.unsaved_pointer_from(unsaved)
 				return nil if unsaved.length == 0
-
+				
 				vec = MemoryPointer.new(Lib::CXUnsavedFile, unsaved.length)
-
+				
 				unsaved.each_with_index do |file, i|
 					uf = Lib::CXUnsavedFile.new(vec + i * Lib::CXUnsavedFile.size)
 					uf[:filename] = MemoryPointer.from_string(file.filename)
 					uf[:contents] = MemoryPointer.from_string(file.contents)
 					uf[:length] = file.contents.length
 				end
-
+				
 				vec
 			end
 		end

data/lib/ffi/clang/version.rb

@@ -3,10 +3,12 @@
 # Released under the MIT License.
 # Copyright, 2010, by Jari Bakken.
 # Copyright, 2012, by Hal Brodigan.
-# Copyright, 2013-2024, by Samuel Williams.
+# Copyright, 2013-2025, by Samuel Williams.
 
+# @namespace
 module FFI
+	# @namespace
 	module Clang
-		VERSION = "0.13.0"
+		VERSION = "0.14.0"
 	end
 end

data/lib/ffi/clang.rb

@@ -3,55 +3,33 @@
 # Released under the MIT License.
 # Copyright, 2010-2011, by Jari Bakken.
 # Copyright, 2012, by Hal Brodigan.
-# Copyright, 2013-2022, by Samuel Williams.
+# Copyright, 2013-2025, by Samuel Williams.
 # Copyright, 2013, by Garry Marshall.
 # Copyright, 2013, by Carlos Martín Nieto.
 # Copyright, 2014, by Masahiro Sano.
-
-require 'ffi'
-require 'rbconfig'
-
-module FFI::Clang
-	class Error < StandardError
-	end
-
-	def self.platform
-		os = RbConfig::CONFIG["host_os"]
-
-		case os
-		when /darwin/
-			:darwin
-		when /linux/
-			:linux
-		when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
-			:windows
-		else
-			os
-		end
-	end
-end
+# Copyright, 2024, by Charlie Savage.
 
 # Load the shared object:
-require_relative 'clang/lib'
+require_relative "clang/lib"
 
 # Wrappers around C functionality:
-require_relative 'clang/clang_version'
-require_relative 'clang/index'
-require_relative 'clang/translation_unit'
-require_relative 'clang/diagnostic'
-require_relative 'clang/cursor'
-require_relative 'clang/source_location'
-require_relative 'clang/source_range'
-require_relative 'clang/unsaved_file'
-require_relative 'clang/token'
-require_relative 'clang/code_completion'
-require_relative 'clang/compilation_database'
-
-require_relative 'clang/types/type'
-require_relative 'clang/types/array'
-require_relative 'clang/types/elaborated'
-require_relative 'clang/types/function'
-require_relative 'clang/types/pointer'
-require_relative 'clang/types/record'
-require_relative 'clang/types/type_def'
-require_relative 'clang/types/vector'
+require_relative "clang/clang_version"
+require_relative "clang/index"
+require_relative "clang/translation_unit"
+require_relative "clang/diagnostic"
+require_relative "clang/cursor"
+require_relative "clang/source_location"
+require_relative "clang/source_range"
+require_relative "clang/unsaved_file"
+require_relative "clang/token"
+require_relative "clang/code_completion"
+require_relative "clang/compilation_database"
+
+require_relative "clang/types/type"
+require_relative "clang/types/array"
+require_relative "clang/types/elaborated"
+require_relative "clang/types/function"
+require_relative "clang/types/pointer"
+require_relative "clang/types/record"
+require_relative "clang/types/type_def"
+require_relative "clang/types/vector"

data/license.md

@@ -2,7 +2,7 @@
 
 Copyright, 2010-2012, by Jari Bakken.  
 Copyright, 2012, by Hal Brodigan.  
-Copyright, 2013-2024, by Samuel Williams.  
+Copyright, 2013-2025, by Samuel Williams.  
 Copyright, 2013, by Garry Marshall.  
 Copyright, 2013-2014, by Carlos Martín Nieto.  
 Copyright, 2013, by Dave Wilkinson.  
@@ -18,7 +18,8 @@ Copyright, 2019, by Michael Metivier.
 Copyright, 2019, by Dominic Sisnero.  
 Copyright, 2020, by Zete Lui.  
 Copyright, 2022, by Motonori Iwamuro.  
-Copyright, 2023-2024, by Charlie Savage.  
+Copyright, 2023-2025, by Charlie Savage.  
+Copyright, 2024, by msepga.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -20,16 +20,7 @@ Or install it yourself as:
 
 ## Usage
 
-Traverse the AST in the given file:
-
-    index = Index.new
-    translation_unit = index.parse_translation_unit("list.c")
-    cursor = translation_unit.cursor
-    cursor.visit_children do |cursor, parent|
-    	puts "#{cursor.kind} #{cursor.spelling.inspect}"
-    	
-    	next :recurse 
-    end
+Please see the [project documentation](https://ioquatix.github.io/ffi-clang/) for more details.
 
 ### Library Version
 
@@ -37,6 +28,14 @@ Due to issues figuring out which library to use, we require you to manually spec
 
     LLVM_CONFIG=llvm-config-mp-3.4 rake
 
+## Releases
+
+Please see the [project releases](https://ioquatix.github.io/ffi-clang/releases/index) for all releases.
+
+### v0.14.0
+
+  - Helper method that returns a curors's <code class="language-ruby">FFI::Clang::Cursor\#qualified\_display\_name</code>.
+
 ## Contributing
 
 We welcome contributions to this project.
@@ -49,8 +48,8 @@ We welcome contributions to this project.
 
 ### Developer Certificate of Origin
 
-This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
 
-### Contributor Covenant
+### Community Guidelines
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,5 @@
+# Releases
+
+## v0.14.0
+
+  - Helper method that returns a curors's {ruby FFI::Clang::Cursor\#qualified\_display\_name}.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ffi-clang
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Samuel Williams
 - Masahiro Sano
-- Carlos Martín Nieto
 - Charlie Savage
+- Carlos Martín Nieto
 - Jari Bakken
 - Takeshi Watanabe
 - Garry Marshall
@@ -23,6 +23,7 @@ authors:
 - Cameron Dutro
 - Dominic Sisnero
 - Hal Brodigan
+- msepga
 bindir: bin
 cert_chain:
 - |
@@ -54,7 +55,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -83,6 +84,7 @@ files:
 - lib/ffi/clang/compilation_database.rb
 - lib/ffi/clang/cursor.rb
 - lib/ffi/clang/diagnostic.rb
+- lib/ffi/clang/error.rb
 - lib/ffi/clang/file.rb
 - lib/ffi/clang/index.rb
 - lib/ffi/clang/lib.rb
@@ -102,6 +104,7 @@ files:
 - lib/ffi/clang/lib/token.rb
 - lib/ffi/clang/lib/translation_unit.rb
 - lib/ffi/clang/lib/type.rb
+- lib/ffi/clang/platform.rb
 - lib/ffi/clang/printing_policy.rb
 - lib/ffi/clang/source_location.rb
 - lib/ffi/clang/source_range.rb
@@ -119,10 +122,12 @@ files:
 - lib/ffi/clang/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/ioquatix/ffi-clang
 licenses:
 - MIT
 metadata:
+  documentation_uri: https://ioquatix.github.io/ffi-clang/
   funding_uri: https://github.com/sponsors/ioquatix/
   source_code_uri: https://github.com/ioquatix/ffi-clang.git
 rdoc_options: []
@@ -132,14 +137,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Ruby FFI bindings for libclang C interface.
 test_files: []