ffi-clang 0.13.0 → 0.14.0

data/lib/ffi/clang/source_location.rb

@@ -3,148 +3,231 @@
 # Released under the MIT License.
 # Copyright, 2010, 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, 2014, by Masahiro Sano.
 # Copyright, 2024, by Charlie Savage.
 
-require_relative 'lib/source_location'
-require_relative 'lib/file'
+require_relative "lib/source_location"
+require_relative "lib/file"
 
 module FFI
 	module Clang
+		# Represents a location in source code.
+		# This base class provides common functionality for source locations,
+		# with specific subclasses for different types of location information.
 		class SourceLocation
+			# Get a null source location.
+			# @returns [ExpansionLocation] A null location that can be used for comparisons.
 			def self.null_location
 				ExpansionLocation.new Lib.get_null_location
 			end
-
+			
+			# @attribute [r] location
+			# 	@returns [FFI::Pointer] The underlying location pointer.
 			attr_reader :location
+			
+			# Create a new source location.
+			# @parameter location [FFI::Pointer] The low-level location handle.
 			def initialize(location)
 				@location = location
 			end
-
+			
+			# Check if this location is in a system header.
+			# @returns [Boolean] True if the location is in a system header file.
 			def in_system_header?
 				Lib.location_in_system_header(@location) != 0
 			end
-
+			
+			# Check if this location is from the main file.
+			# @returns [Boolean] True if the location is from the main translation unit file.
 			def from_main_file?
 				Lib.location_is_from_main_file(@location) != 0
 			end
-
+			
+			# Check if this location is null.
+			# @returns [Boolean] True if this is a null location.
 			def null?
 				Lib.equal_locations(@location, Lib.get_null_location) != 0
 			end
-
+			
+			# Compare this location with another for equality.
+			# @parameter other [SourceLocation] The other location to compare.
+			# @returns [Boolean] True if the locations are equal.
 			def ==(other)
 				Lib.equal_locations(@location, other.location) != 0
 			end
 		end
-
+		
+		# Represents the expansion location of a macro.
+		# This provides the location where a macro was expanded, including file, line, column, and byte offset.
 		class ExpansionLocation < SourceLocation
+			# @attribute [r] file
+			# 	@returns [String] The file path.
+			# @attribute [r] line
+			# 	@returns [Integer] The line number.
+			# @attribute [r] column
+			# 	@returns [Integer] The column number.
+			# @attribute [r] offset
+			# 	@returns [Integer] The byte offset in the file.
 			attr_reader :file, :line, :column, :offset
-
+			
+			# Create a new expansion location and extract its components.
+			# @parameter location [FFI::Pointer] The low-level location handle.
 			def initialize(location)
 				super(location)
-
+				
 				cxfile = MemoryPointer.new :pointer
 				line   = MemoryPointer.new :uint
 				column = MemoryPointer.new :uint
 				offset = MemoryPointer.new :uint
-
+				
 				Lib::get_expansion_location(@location, cxfile, line, column, offset)
-
+				
 				@file = Lib.extract_string Lib.get_file_name(cxfile.read_pointer)
 				@line = line.get_uint(0)
 				@column = column.get_uint(0)
 				@offset = offset.get_uint(0)
 			end
-
+			
+			# Get a string representation of this location.
+			# @returns [String] The location in format "file:line:column:offset".
 			def as_string
 				"#{@file}:#{@line}:#{@column}:#{@offset}"
 			end
-
+			
+			# Get a detailed string representation.
+			# @returns [String] A string describing this expansion location.
 			def to_s
 				"ExpansionLocation <#{self.as_string}>"
 			end
 		end
-
+		
+		# Represents a presumed location in source code.
+		# This is the location that appears to the user after macro expansion and #line directives.
 		class PresumedLocation < SourceLocation
+			# @attribute [r] filename
+			# 	@returns [String] The presumed filename.
+			# @attribute [r] line
+			# 	@returns [Integer] The presumed line number.
+			# @attribute [r] column
+			# 	@returns [Integer] The presumed column number.
+			# @attribute [r] offset
+			# 	@returns [Integer] The presumed byte offset.
 			attr_reader :filename, :line, :column, :offset
-
+			
+			# Create a new presumed location and extract its components.
+			# @parameter location [FFI::Pointer] The low-level location handle.
 			def initialize(location)
 				super(location)
-
+				
 				cxstring = MemoryPointer.new Lib::CXString
 				line = MemoryPointer.new :uint
 				column = MemoryPointer.new :uint
-
+				
 				Lib::get_presumed_location(@location, cxstring, line, column)
-
+				
 				@filename = Lib.extract_string cxstring
 				@line = line.get_uint(0)
 				@column = column.get_uint(0)
 			end
-
+			
+			# Get a string representation of this location.
+			# @returns [String] The location in format "filename:line:column".
 			def as_string
 				"#{@filename}:#{@line}:#{@column}"
 			end
-
+			
+			# Get a detailed string representation.
+			# @returns [String] A string describing this presumed location.
 			def to_s
 				"PresumedLocation <#{self.as_string}>"
 			end
 		end
-
+		
+		# Represents the spelling location of a token in source code.
+		# This is the actual location where the token was written in the source file.
 		class SpellingLocation < SourceLocation
+			# @attribute [r] file
+			# 	@returns [String] The file path.
+			# @attribute [r] line
+			# 	@returns [Integer] The line number.
+			# @attribute [r] column
+			# 	@returns [Integer] The column number.
+			# @attribute [r] offset
+			# 	@returns [Integer] The byte offset in the file.
 			attr_reader :file, :line, :column, :offset
-
+			
+			# Create a new spelling location and extract its components.
+			# @parameter location [FFI::Pointer] The low-level location handle.
 			def initialize(location)
 				super(location)
-
+				
 				cxfile = MemoryPointer.new :pointer
 				line   = MemoryPointer.new :uint
 				column = MemoryPointer.new :uint
 				offset = MemoryPointer.new :uint
-
+				
 				Lib::get_spelling_location(@location, cxfile, line, column, offset)
-
+				
 				@file = Lib.extract_string Lib.get_file_name(cxfile.read_pointer)
 				@line = line.get_uint(0)
 				@column = column.get_uint(0)
 				@offset = offset.get_uint(0)
 			end
-
+			
+			# Get a string representation of this location.
+			# @returns [String] The location in format "file:line:column:offset".
 			def as_string
 				"#{@file}:#{@line}:#{@column}:#{@offset}"
 			end
-
+			
+			# Get a detailed string representation.
+			# @returns [String] A string describing this spelling location.
 			def to_s
 				"SpellingLocation <#{self.as_string}>"
 			end
 		end
-
+		
+		# Represents a file location in source code.
+		# This provides the physical location in the file system where code appears.
 		class FileLocation < SourceLocation
+			# @attribute [r] file
+			# 	@returns [String] The file path.
+			# @attribute [r] line
+			# 	@returns [Integer] The line number.
+			# @attribute [r] column
+			# 	@returns [Integer] The column number.
+			# @attribute [r] offset
+			# 	@returns [Integer] The byte offset in the file.
 			attr_reader :file, :line, :column, :offset
-
+			
+			# Create a new file location and extract its components.
+			# @parameter location [FFI::Pointer] The low-level location handle.
 			def initialize(location)
 				super(location)
-
+				
 				cxfile = MemoryPointer.new :pointer
 				line   = MemoryPointer.new :uint
 				column = MemoryPointer.new :uint
 				offset = MemoryPointer.new :uint
-
+				
 				Lib::get_file_location(@location, cxfile, line, column, offset)
-
+				
 				@file = Lib.extract_string Lib.get_file_name(cxfile.read_pointer)
 				@line = line.get_uint(0)
 				@column = column.get_uint(0)
 				@offset = offset.get_uint(0)
 			end
-
+			
+			# Get a string representation of this location.
+			# @returns [String] The location in format "file:line:column:offset".
 			def as_string
 				"#{@file}:#{@line}:#{@column}:#{@offset}"
 			end
-
+			
+			# Get a detailed string representation.
+			# @returns [String] A string describing this file location.
 			def to_s
 				"FileLocation <#{self.as_string}>"
 			end

data/lib/ffi/clang/source_range.rb

@@ -3,19 +3,25 @@
 # Released under the MIT License.
 # Copyright, 2010, 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, 2014, by Masahiro Sano.
 
-require_relative 'lib/source_range'
+require_relative "lib/source_range"
 
 module FFI
 	module Clang
+		# Represents a source range in a file.
 		class SourceRange
+			# Get a null source range.
+			# @returns [SourceRange] A null source range.
 			def self.null_range
 				SourceRange.new Lib.get_null_range
 			end
-
+			
+			# Initialize a source range.
+			# @parameter range_or_begin_location [Lib::CXSourceRange | SourceLocation] Either a range structure or the beginning location.
+			# @parameter end_location [SourceLocation | Nil] The end location, or `nil` if first parameter is a range.
 			def initialize(range_or_begin_location, end_location = nil)
 				if end_location.nil?
 					@range = range_or_begin_location
@@ -23,34 +29,46 @@ module FFI
 					@range = Lib.get_range(range_or_begin_location.location, end_location.location)
 				end
 			end
-
+			
+			# Get the start location of this range.
+			# @returns [ExpansionLocation] The start location.
 			def start
 				@start ||= ExpansionLocation.new(Lib.get_range_start @range)
 			end
-
+			
+			# Get the end location of this range.
+			# @returns [ExpansionLocation] The end location.
 			def end
 				@end ||= ExpansionLocation.new(Lib.get_range_end @range)
 			end
-
-			# The size, in bytes, of the source range.
+			
+			# Get the size in bytes of the source range.
+			# @returns [Integer] The byte size.
 			def bytesize
 				self.end.offset - self.start.offset
 			end
-
-			# Read the part of the source file referred to by this source range.
+			
+			# Read the text from the source file for this range.
+			# @returns [String] The source text.
 			def text
 				::File.open(self.start.file, "r") do |file|
 					file.seek(self.start.offset)
 					return file.read(self.bytesize)
 				end
 			end
-
+			
+			# Check if this range is null.
+			# @returns [Boolean] True if the range is null.
 			def null?
 				Lib.range_is_null(@range) != 0
 			end
-
+			
+			# @attribute [Lib::CXSourceRange] The underlying range structure.
 			attr_reader :range
-
+			
+			# Check if this range equals another range.
+			# @parameter other [SourceRange] The range to compare with.
+			# @returns [Boolean] True if the ranges are equal.
 			def ==(other)
 				Lib.equal_range(@range, other.range) != 0
 			end

data/lib/ffi/clang/token.rb

@@ -2,77 +2,102 @@
 
 # Released under the MIT License.
 # Copyright, 2014, by Masahiro Sano.
-# Copyright, 2014-2022, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
-require_relative 'lib/token'
-require_relative 'lib/cursor'
-require_relative 'source_location'
+require_relative "lib/token"
+require_relative "lib/cursor"
+require_relative "source_location"
 
 module FFI
 	module Clang
+		# Represents a collection of tokens from a source range.
 		class Tokens < AutoPointer
 			include Enumerable
-
+			
+			# @attribute [Integer] The number of tokens.
 			attr_reader :size
+			
+			# @attribute [Array(Token)] The array of tokens.
 			attr_reader :tokens
-
+			
+			# Initialize a token collection.
+			# @parameter pointer [FFI::Pointer] The tokens pointer.
+			# @parameter token_size [Integer] The number of tokens.
+			# @parameter translation_unit [TranslationUnit] The parent translation unit.
 			def initialize(pointer, token_size, translation_unit)
 				ptr = Lib::TokensPointer.new(pointer,token_size, translation_unit)
 				super ptr
-
+				
 				@translation_unit = translation_unit
 				@size = token_size
-
+				
 				@tokens = []
 				cur_ptr = pointer
-				token_size.times {
-					@tokens << Token.new(cur_ptr, translation_unit)
-					cur_ptr += Lib::CXToken.size
+				token_size.times {@tokens << Token.new(cur_ptr, translation_unit)
+																						cur_ptr += Lib::CXToken.size
 				}
 			end
-
+			
+			# Release the tokens pointer.
+			# @parameter pointer [Lib::TokensPointer] The tokens pointer to release.
 			def self.release(pointer)
 				Lib.dispose_tokens(pointer.translation_unit, pointer, pointer.token_size)
 			end
-
+			
+			# Iterate over each token.
+			# @yields {|token| ...} Each token in the collection.
+			# 	@parameter token [Token] The token.
 			def each(&block)
 				@tokens.each do |token|
 					block.call(token)
 				end
 			end
-
+			
+			# Get cursors corresponding to each token.
+			# @returns [Array(Cursor)] Array of cursors for each token.
 			def cursors
 				ptr = MemoryPointer.new(Lib::CXCursor, @size)
 				Lib.annotate_tokens(@translation_unit, self, @size, ptr)
-
+				
 				cur_ptr = ptr
 				arr = []
-				@size.times {
-					arr << Cursor.new(cur_ptr, @translation_unit)
-					cur_ptr += Lib::CXCursor.size
+				@size.times {arr << Cursor.new(cur_ptr, @translation_unit)
+																	cur_ptr += Lib::CXCursor.size
 				}
 				arr
 			end
 		end
-
+		
+		# Represents a single token in the source code.
 		class Token
+			# Initialize a token.
+			# @parameter token [FFI::Pointer] The token pointer.
+			# @parameter translation_unit [TranslationUnit] The parent translation unit.
 			def initialize(token, translation_unit)
 				@token = token
 				@translation_unit = translation_unit
 			end
-
+			
+			# Get the kind of this token.
+			# @returns [Symbol] The token kind.
 			def kind
 				Lib.get_token_kind(@token)
 			end
-
+			
+			# Get the spelling (text) of this token.
+			# @returns [String] The token spelling.
 			def spelling
 				Lib.extract_string Lib.get_token_spelliing(@translation_unit, @token)
 			end
-
+			
+			# Get the location of this token.
+			# @returns [ExpansionLocation] The token location.
 			def location
 				ExpansionLocation.new Lib.get_token_location(@translation_unit, @token)
 			end
-
+			
+			# Get the extent (source range) of this token.
+			# @returns [SourceRange] The token extent.
 			def extent
 				SourceRange.new Lib.get_token_extent(@translation_unit, @token)
 			end