xrb 0.11.2 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 191b9d8b1c76135932e4b95c00603c31e9d8528bea772b8dcdb8f6a9c697e898
-  data.tar.gz: b05ffe7752fb49104e1a056ed96bc235676c19d06e2a4aa751c3e13a39e75637
+  metadata.gz: c405671464f8c345c353f1b8613e7f92c5aa7ce16ece92879a5430564130a1dc
+  data.tar.gz: d5408318e1f6d65ffd77380104e8b38e47cc38a54cf5333869fbfcb704191df8
 SHA512:
-  metadata.gz: 112685f3e991db8bcfcff7777e907111b2aae8621435bb9d176cff8359d0167627d1cb2d79f12e16adc0530458796317602a2b7700d2dee1f75e5d52fdab7ab4
-  data.tar.gz: 3e4ed11828e217d07459c7fb2ced92af58029392de6d3b49510336c3dfd9ab44777fbaf61b7de1124138b9e4d09183395e4148d6942e738f3ea311aeec4c61db
+  metadata.gz: f958390f0dca1de58d1181ad9e01c29fc5f8a49da8260e63082d2df1bd319d8e0c05ec207a4a8c01699c5e6afd1f69c92a42df747573693f220bd40daa1b1ed1
+  data.tar.gz: 54db6f9744055840a9153e4145eb6fb10a85d2ba28b836c7c629a556c817f8343e1e15004faf361fb2d493477f6ea145b10b72f4764b5937d925072dabde8510

data/lib/xrb/buffer.rb

@@ -17,6 +17,8 @@ module XRB
 		# @attribute [String] the path name of the buffer.
 		attr :path
 		
+		# Freeze the buffer and its contents.
+		# @returns [Buffer] The frozen buffer.
 		def freeze
 			return self if frozen?
 			

data/lib/xrb/builder.rb

@@ -75,6 +75,11 @@ module XRB
 			return nil
 		end
 		
+		# Create a markup fragment containing a single inline tag.
+		# @parameter name [String | Symbol] The tag name.
+		# @parameter content [Object] The tag content, which will be escaped as required.
+		# @parameter attributes [Hash] The tag attributes.
+		# @returns [Fragment] The generated markup fragment.
 		def self.tag(name, content, **attributes)
 			self.fragment do |builder|
 				builder.inline(name, attributes) do
@@ -83,6 +88,10 @@ module XRB
 			end
 		end
 		
+		# Initialize a builder which appends markup to the given output buffer.
+		# @parameter output [String | Nil] The output buffer, or `nil` to create a new markup string.
+		# @parameter indent [Boolean] Whether generated markup should be indented.
+		# @parameter encoding [Encoding] The encoding for a newly created output buffer.
 		def initialize(output = nil, indent: true, encoding: Encoding::UTF_8)
 			# This field gets togged in #inline so we keep track of it separately from @indentation.
 			@indent = indent
@@ -114,10 +123,15 @@ module XRB
 		
 		alias to_s to_str
 		
+		# Compare the generated output with another string-like object.
+		# @parameter other [Object] The object to compare with the output.
+		# @returns [Boolean] Whether the generated output is equal to the other object as a string.
 		def == other
 			@output == String(other)
 		end
 		
+		# Compute the indentation for the current nesting level.
+		# @returns [String] The current indentation, or an empty string when indentation is disabled.
 		def indentation
 			if @indent
 				INDENT * (@level.size - 1)
@@ -150,6 +164,9 @@ module XRB
 		
 		alias inline inline_tag
 		
+		# Temporarily disable indentation while yielding to the block.
+		# @yields {} The block which generates inline content.
+		# @returns [Object] The value returned by the block.
 		def inline!
 			original_indent = @indent
 			@indent = false
@@ -175,6 +192,9 @@ module XRB
 			end
 		end
 		
+		# Append unescaped content directly to the output buffer.
+		# @parameter content [String] The raw markup to append.
+		# @returns [String] The output buffer.
 		def raw(content)
 			@output << content
 		end

data/lib/xrb/error.rb

@@ -6,10 +6,16 @@
 require_relative "buffer"
 
 module XRB
+	# The base class for XRB errors.
 	class Error < StandardError
 	end
 	
+	# Raised when an XRB parser encounters invalid input.
 	class ParseError < Error
+		# Initialize a parse error at a specific byte offset within a buffer.
+		# @parameter message [String] The error message.
+		# @parameter buffer [Buffer] The input buffer being parsed.
+		# @parameter offset [Integer] The byte offset where parsing failed.
 		def initialize(message, buffer, offset)
 			super(message)
 			
@@ -17,6 +23,8 @@ module XRB
 			@offset = offset
 		end
 		
+		# Compute the location of the parse error within the input buffer.
+		# @returns [Location] The line and byte location of the error.
 		def location
 			@location ||= Location.new(@buffer.read, @offset)
 		end
@@ -24,12 +32,19 @@ module XRB
 		attr :buffer
 		attr :path
 		
+		# Format the error with its path, location, message, and source line.
+		# @returns [String] The formatted parse error.
 		def to_s
 			"#{buffer.path}#{location}: #{super}\n#{location.line_text}"
 		end
 	end
 	
+	# A byte offset resolved to a line within an input string.
 	class Location
+		# Initialize a location for a byte offset within an input string.
+		# @parameter input [String] The complete input string.
+		# @parameter offset [Integer] The byte offset within the input string.
+		# @raises [ArgumentError] If the offset is past the end of the input.
 		def initialize(input, offset)
 			raise ArgumentError.new("Offset #{index} is past end of input #{input.bytesize}") if offset > input.bytesize
 			
@@ -52,10 +67,14 @@ module XRB
 			end
 		end
 		
+		# Convert the location to its absolute byte offset.
+		# @returns [Integer] The byte offset within the input string.
 		def to_i
 			@offset
 		end
 		
+		# Format the location as a one-based line number and zero-based line offset.
+		# @returns [String] The formatted location.
 		def to_s
 			"[#{self.line_number}:#{self.line_offset}]"
 		end