ffi-clang 0.13.0 → 0.14.0

data/lib/ffi/clang/lib/string.rb

@@ -1,25 +1,30 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2013-2024, by Samuel Williams.
+# Copyright, 2013-2025, by Samuel Williams.
 
 module FFI
 	module Clang
 		module Lib
+			# FFI struct representing a string returned by libclang.
+			# @private
 			class CXString < FFI::Struct
 				layout(
 					:data, :pointer,
 					:private_flags, :uint
 				)
 			end
-
+			
 			attach_function :get_string, :clang_getCString, [CXString.by_value], :string
 			attach_function :dispose_string, :clang_disposeString, [CXString.by_value], :void
-
+			
+			# Extract a Ruby string from a CXString and dispose of the CXString.
+			# @parameter cxstring [CXString] The CXString to extract from.
+			# @returns [String] The extracted string.
 			def self.extract_string(cxstring)
 				result = get_string(cxstring)
 				dispose_string cxstring
-
+				
 				return result
 			end
 		end

data/lib/ffi/clang/lib/token.rb

@@ -2,28 +2,41 @@
 
 # Released under the MIT License.
 # Copyright, 2014, by Masahiro Sano.
-# Copyright, 2014-2022, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
 module FFI
 	module Clang
 		module Lib
+			# FFI struct representing a token in libclang.
+			# @private
 			class CXToken < FFI::Struct
 				layout(
 					:int_data, [:uint, 4],
 					:ptr_data, :pointer,
 				)
 			end
-
+			
+			# FFI pointer wrapper for token arrays that tracks size and translation unit.
+			# @private
 			class TokensPointer < FFI::Pointer
+				# @attribute [r] token_size
+				# 	@returns [Integer] The number of tokens.
+				# @attribute [r] translation_unit
+				# 	@returns [TranslationUnit] The translation unit these tokens belong to.
 				attr_reader :token_size
 				attr_reader :translation_unit
+				
+				# Create a new tokens pointer.
+				# @parameter ptr [FFI::Pointer] The pointer to the token array.
+				# @parameter token_size [Integer] The number of tokens.
+				# @parameter translation_unit [TranslationUnit] The translation unit.
 				def initialize(ptr, token_size, translation_unit)
 					super ptr
 					@token_size = token_size
 					@translation_unit = translation_unit
 				end
 			end
-
+			
 			enum :token_kind, [
 				:punctuation,
 				:keyword,
@@ -31,7 +44,7 @@ module FFI
 				:literal,
 				:comment,
 			]
-
+			
 			attach_function :get_token_kind, :clang_getTokenKind, [CXToken.by_value], :token_kind
 			attach_function :get_token_spelliing, :clang_getTokenSpelling, [:CXTranslationUnit, CXToken.by_value], CXString.by_value
 			attach_function :get_token_location, :clang_getTokenLocation, [:CXTranslationUnit, CXToken.by_value], CXSourceLocation.by_value

data/lib/ffi/clang/lib/translation_unit.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2013-2024, by Samuel Williams.
+# Copyright, 2013-2025, by Samuel Williams.
 # Copyright, 2014, by Masahiro Sano.
 # Copyright, 2019, by Hayden Purdy.
 # Copyright, 2022, by Motonori Iwamuro.
 # Copyright, 2023, by Charlie Savage.
 
-require_relative 'index'
+require_relative "index"
 
 module FFI
 	module Clang
 		module Lib
 			typedef :pointer, :CXTranslationUnit
-
+			
 			TranslationUnitFlags = enum [
 				:none, 0x0,
 				:detailed_preprocessing_record, 0x01,
@@ -33,22 +33,22 @@ module FFI
 				:ignore_non_errors_from_included_files, 0x4000,
 				:retain_excluded_conditional_blocks, 0x8000,
 			]
-
+			
 			SaveTranslationUnitFlags = enum [
 				:save_translation_unit_none, 0x0,
 			]
-
+			
 			SaveError = enum [
 				:none, 0,
 				:unknown, 1,
 				:translation_errors, 2,
 				:invalid_translation_unit, 3
 			]
-
+			
 			ReparseFlags = enum [
 				:none, 0x0,
 			]
-
+			
 			enum :resource_usage_kind, [
 				:ast, 1,
 				:identifiers, 2,
@@ -65,7 +65,7 @@ module FFI
 				:sourcemanager_data_structures, 13,
 				:preprocessor_header_search, 14,
 			]
-
+			
 			ErrorCodes = enum [
 				:cx_error_success, 0,
 				:cx_error_failure, 1,
@@ -73,7 +73,9 @@ module FFI
 				:cx_error_invalid_arguments, 3,
 				:cx_error_ast_read_error, 4,
 			]
-
+			
+			# FFI struct representing translation unit resource usage.
+			# @private
 			class CXTUResourceUsage < FFI::Struct
 				layout(
 					:data, :pointer,
@@ -81,27 +83,29 @@ module FFI
 					:entries, :pointer
 				)
 			end
-
+			
+			# FFI struct representing a single resource usage entry.
+			# @private
 			class CXTUResourceUsageEntry < FFI::Struct
 				layout(
 					:kind, :resource_usage_kind,
 					:amount, :ulong,
 				)
 			end
-
+			
 			# Source code translation units:
 			attach_function :parse_translation_unit, :clang_parseTranslationUnit, [:CXIndex, :string, :pointer, :int, :pointer, :uint, :uint], :CXTranslationUnit
 			attach_function :parse_translation_unit2, :clang_parseTranslationUnit2, [:CXIndex, :string, :pointer, :int, :pointer, :uint, :uint, :pointer], ErrorCodes
 			attach_function :create_translation_unit, :clang_createTranslationUnit, [:CXIndex, :string], :CXTranslationUnit
 			attach_function :dispose_translation_unit, :clang_disposeTranslationUnit, [:CXTranslationUnit], :void
 			attach_function :get_translation_unit_spelling, :clang_getTranslationUnitSpelling, [:CXTranslationUnit], CXString.by_value
-
+			
 			attach_function :default_editing_translation_unit_options, :clang_defaultEditingTranslationUnitOptions, [], :uint
 			attach_function :default_save_options, :clang_defaultSaveOptions, [:CXTranslationUnit], :uint
 			attach_function :save_translation_unit, :clang_saveTranslationUnit, [:CXTranslationUnit, :string, :uint], :int
 			attach_function :default_reparse_options, :clang_defaultReparseOptions, [:CXTranslationUnit], :uint
 			attach_function :reparse_translation_unit, :clang_reparseTranslationUnit, [:CXTranslationUnit, :uint, :pointer, :uint], :int
-
+			
 			attach_function :resource_usage, :clang_getCXTUResourceUsage, [:CXTranslationUnit], CXTUResourceUsage.by_value
 			attach_function :dispose_resource_usage, :clang_disposeCXTUResourceUsage, [CXTUResourceUsage.by_value], :void
 			attach_function :resource_usage_name, :clang_getTUResourceUsageName, [:resource_usage_kind], :string

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

@@ -2,11 +2,11 @@
 
 # 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, 2013-2014, by Masahiro Sano.
 # Copyright, 2014, by Niklas Therning.
-# Copyright, 2024, by Charlie Savage.
+# Copyright, 2024-2025, by Charlie Savage.
 
 module FFI
 	module Clang
@@ -126,7 +126,7 @@ module FFI
 				:type_atomic, 177,
 				:type_btf_tag_attributed, 178
 			]
-
+			
 			enum :calling_conv, [
 				:calling_conv_default, 0,
 				:calling_conv_c, 1,
@@ -153,13 +153,13 @@ module FFI
 				:calling_conv_invalid, 100,
 				:calling_conv_unexposed, 200
 			]
-
+			
 			enum :ref_qualifier_kind, [
 				:ref_qualifier_none, 0,
 				:ref_qualifier_lvalue, 1,
 				:ref_qualifier_rvalue, 2,
 			]
-
+			
 			enum :layout_error, [
 				:layout_error_invalid, -1,
 				:layout_error_incomplete, -2,
@@ -168,7 +168,7 @@ module FFI
 				:layout_error_invalid_field_name, -5,
 				:layout_error_undeduced, -6
 			]
-
+			
 			# Also defined in cursor.rb
 			enum :exception_specification_type, [
 				:none,
@@ -182,47 +182,49 @@ module FFI
 				:unparsed,
 				:no_throw
 			]
-
+			
+			# FFI struct representing a type in libclang.
+			# @private
 			class CXType < FFI::Struct
 				layout(
 					:kind, :kind,
 					:data, [:pointer, 2]
 				)
 			end
-
+			
 			attach_function :get_type_kind_spelling, :clang_getTypeKindSpelling, [:kind], CXString.by_value
 			attach_function :get_type_spelling, :clang_getTypeSpelling, [CXType.by_value], CXString.by_value
 			attach_function :get_named_type, :clang_Type_getNamedType, [CXType.by_value], CXType.by_value
-
+			
 			attach_function :is_function_type_variadic, :clang_isFunctionTypeVariadic, [CXType.by_value], :uint
 			attach_function :is_pod_type, :clang_isPODType, [CXType.by_value], :uint
-
+			
 			attach_function :get_pointee_type, :clang_getPointeeType, [CXType.by_value], CXType.by_value
 			attach_function :get_result_type, :clang_getResultType, [CXType.by_value], CXType.by_value
 			attach_function :get_canonical_type, :clang_getCanonicalType, [CXType.by_value], CXType.by_value
-
+			
 			attach_function :type_get_class_type, :clang_Type_getClassType, [CXType.by_value], CXType.by_value
-
+			
 			attach_function :is_const_qualified_type, :clang_isConstQualifiedType, [CXType.by_value], :uint
 			attach_function :is_volatile_qualified_type, :clang_isVolatileQualifiedType, [CXType.by_value], :uint
 			attach_function :is_restrict_qualified_type, :clang_isRestrictQualifiedType, [CXType.by_value], :uint
-
+			
 			attach_function :get_num_arg_types, :clang_getNumArgTypes, [CXType.by_value], :int
 			attach_function :get_arg_type, :clang_getArgType, [CXType.by_value, :uint], CXType.by_value
 			attach_function :get_num_elements, :clang_getNumElements, [CXType.by_value], :long_long
 			attach_function :get_element_type, :clang_getElementType, [CXType.by_value], CXType.by_value
 			attach_function :get_array_size, :clang_getArraySize, [CXType.by_value], :long_long
 			attach_function :get_array_element_type ,:clang_getArrayElementType, [CXType.by_value], CXType.by_value
-
+			
 			attach_function :type_get_align_of, :clang_Type_getAlignOf, [CXType.by_value], :long_long
 			attach_function :type_get_size_of, :clang_Type_getSizeOf, [CXType.by_value], :long_long
 			attach_function :type_get_offset_of, :clang_Type_getOffsetOf, [CXType.by_value, :string], :long_long
-
+			
 			attach_function :type_get_cxx_ref_qualifier, :clang_Type_getCXXRefQualifier, [CXType.by_value], :ref_qualifier_kind
-
+			
 			attach_function :get_fuction_type_calling_conv, :clang_getFunctionTypeCallingConv, [CXType.by_value], :calling_conv
 			attach_function :get_exception_specification_type, :clang_getExceptionSpecificationType, [CXType.by_value], :exception_specification_type
-
+			
 			attach_function :equal_types, :clang_equalTypes, [CXType.by_value, CXType.by_value], :uint
 		end
 	end

data/lib/ffi/clang/lib.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # 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-2014, by Carlos Martín Nieto.
 # Copyright, 2013, by Takeshi Watanabe.
 # Copyright, 2014, by Masahiro Sano.
@@ -14,41 +14,47 @@
 # Copyright, 2019, by Dominic Sisnero.
 # Copyright, 2020, by Zete Lui.
 # Copyright, 2023, by Charlie Savage.
+# Copyright, 2024, by msepga.
 
-require 'mkmf'
+require "ffi"
+require "mkmf"
+
+require_relative "platform"
+require_relative "error"
 
 module FFI
 	module Clang
+		# @namespace
 		module Lib
 			extend FFI::Library
 			
 			# Use LLVM_CONFIG if it was explicitly specified:
-			llvm_config = ENV['LLVM_CONFIG']
+			llvm_config = ENV["LLVM_CONFIG"]
 			
 			# If we aren't building for a specific version (e.g. travis) try to find llvm-config
-			unless ENV['LLVM_VERSION'] 
+			unless ENV["LLVM_VERSION"] 
 				llvm_config ||= MakeMakefile.find_executable("llvm-config")
 			end
-
+			
 			libs = []
-
-			if ENV['LIBCLANG']
-				libs << ENV['LIBCLANG']
+			
+			if ENV["LIBCLANG"]
+				libs << ENV["LIBCLANG"]
 			elsif llvm_config
 				llvm_library_dir = `#{llvm_config} --libdir`.chomp
 				platform = FFI::Clang.platform
 				
 				case platform
 				when :darwin
-					libs << llvm_library_dir + '/libclang.dylib'
+					libs << llvm_library_dir + "/libclang.dylib"
 				when :windows
 					llvm_bin_dir = `#{llvm_config} --bindir`.chomp
-					libs << llvm_bin_dir + '/libclang.dll'
+					libs << llvm_bin_dir + "/libclang.dll"
 				else
-					libs << llvm_library_dir + '/libclang.so'
+					libs << llvm_library_dir + "/libclang.so"
 				end
 			end
-
+			
 			begin
 				xcode_dir = `xcode-select -p`.chomp
 				%W[
@@ -63,25 +69,35 @@ module FFI
 			rescue Errno::ENOENT
 				# Ignore
 			end
-
+			
 			libs << "clang"
-
+			
 			ffi_lib libs
-
+			
+			# Convert an options hash to a bitmask for libclang enums.
+			# @parameter enum [FFI::Enum] The enum type.
+			# @parameter opts [Array(Symbol)] The array of option symbols.
+			# @returns [Integer] The bitmask representing the options.
+			# @raises [Error] If an unknown option is provided.
 			def self.bitmask_from(enum, opts)
 				bitmask = 0
-
+				
 				opts.each do |symbol|
 					if int = enum[symbol]
 						bitmask |= int
 					else
-  						raise Error, "unknown option: #{symbol}, expected one of #{enum.symbols}"
+						raise Error, "unknown option: #{symbol}, expected one of #{enum.symbols}"
 					end
 				end
-
+				
 				bitmask
 			end
-
+			
+			# Convert a bitmask to an array of option symbols.
+			# @parameter enum [FFI::Enum] The enum type.
+			# @parameter bitmask [Integer] The bitmask to convert.
+			# @returns [Array(Symbol)] The array of option symbols.
+			# @raises [Error] If unknown bits are set in the bitmask.
 			def self.opts_from(enum, bitmask)
 				bit = 1
 				result = []

data/lib/ffi/clang/platform.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "rbconfig"
+
+module FFI
+	module Clang
+		# Get the current platform identifier.
+		# @returns [Symbol] The platform identifier (`:darwin`, `:linux`, `:windows`, or a custom platform string).
+		def self.platform
+			case RUBY_PLATFORM
+			when /darwin/
+				:darwin
+			when /linux/
+				:linux
+			when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+				:windows
+			else
+				RUBY_PLATFORM.split("-").last
+			end
+		end
+	end
+end

data/lib/ffi/clang/printing_policy.rb

@@ -2,35 +2,48 @@
 
 # Released under the MIT License.
 # Copyright, 2024, by Charlie Savage.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
-require_relative 'lib/printing_policy'
+require_relative "lib/printing_policy"
 
 module FFI
 	module Clang
+		# Represents a printing policy that controls how declarations are formatted.
 		class PrintingPolicy < AutoPointer
+			# Initialize a printing policy for a cursor.
+			# @parameter cursor [FFI::Pointer] The cursor to get the policy from.
 			def initialize(cursor)
-        policy = Lib.get_printing_policy(cursor)
+				policy = Lib.get_printing_policy(cursor)
 				super(policy)
-        @cursor = cursor
+				@cursor = cursor
 			end
-
+			
+			# Release the printing policy pointer.
+			# @parameter pointer [FFI::Pointer] The pointer to release.
 			def self.release(pointer)
 				Lib.dispose_printing_policy(pointer)
 			end
-
-      def get_property(property)
-        result = Lib.printing_policy_get_property(self, property)
-        result == 0 ? false : true
-      end
-
-      def set_property(property, value)
-        Lib.printing_policy_set_property(self, property, value ? 1 : 0)
-      end
-
-      def pretty_print
-        Lib.extract_string Lib.pretty_print(@cursor, self)
-      end
+			
+			# Get a printing policy property value.
+			# @parameter property [Symbol] The property name.
+			# @returns [Boolean] The property value.
+			def get_property(property)
+				result = Lib.printing_policy_get_property(self, property)
+				result == 0 ? false : true
+			end
+			
+			# Set a printing policy property value.
+			# @parameter property [Symbol] The property name.
+			# @parameter value [Boolean] The property value.
+			def set_property(property, value)
+				Lib.printing_policy_set_property(self, property, value ? 1 : 0)
+			end
+			
+			# Pretty print the cursor using this policy.
+			# @returns [String] The formatted cursor string.
+			def pretty_print
+				Lib.extract_string Lib.pretty_print(@cursor, self)
+			end
 		end
 	end
 end