xrb 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0bf51a6404c03e4c10d3a2ada0c804fdcc5df0daa1574d050811f617afcedbc
-  data.tar.gz: 59f805082ef9ce5c561d774a3ee7692adbfa05555fd7780422a76e411b9bfbd4
+  metadata.gz: d6f3f374f9c7841a9aabbe4a4f30a598e8567d9357d0fef4113770b318fc76ed
+  data.tar.gz: 16aff80df195168a9a2ec179c79d8219d18eaebb344e94e6fe668ea814b4e02e
 SHA512:
-  metadata.gz: 3d40c30425864483f9c5c51427cf658a6d155037c2af514891ebf4a10e419344bcb844c4ee5341c6593392a42da9b3550a33c29ba36d3c3ba0301b2d17a66c3b
-  data.tar.gz: 2db7b9b57170efaafc057a1ab298a8a320954ef492c1181da26866087731ce34daf3c989e8dd5d4616deb808766fede23785ba699247270506bf6d08fe511137
+  metadata.gz: 90ba6bdffb495cd7356eb8818dd8649b2fcffddd903e756b4724cda48420fbea6ce9e6fa8a49ff8b3f084cca00783322d1ffd814e3cd00bcf93e07389e63385e
+  data.tar.gz: 52057eebbfee6c4b10c0258f2199c895f7a960f17bdae3892793a8e99647364d32868d2c7f91a5c6a6596db3d1d028fa0b2ed0f100a0af64db1c8aca524e753d

data/lib/xrb/buffer.rb

@@ -4,40 +4,68 @@
 # Copyright, 2016-2024, by Samuel Williams.
 
 module XRB
+	# Represents a string buffer with a given path.
 	class Buffer
+		# Create a new buffer from a string.
+		# @parameter string [String] the string to use as the buffer.
+		# @parameter path [String] the path to use for the buffer.
 		def initialize(string, path: "<string>")
 			@string = string
 			@path = path
 		end
 		
+		# @attribute [String] the path name of the buffer.
 		attr :path
 		
+		def freeze
+			return self if frozen?
+			
+			@string.freeze
+			@path.freeze
+			
+			super
+		end
+		
+		# @returns [Encoding] the encoding of the buffer.
 		def encoding
 			@string.encoding
 		end
 		
+		# @returns [String] the content of the buffer.
 		def read
 			@string
 		end
 		
+		# Create a buffer from the specified file.
+		# @parameter path [String] the path to load the file from.
+		# @returns [Buffer] a buffer with the contents of the specified path.
 		def self.load_file(path)
 			FileBuffer.new(path).freeze
 		end
 		
+		# Create a buffer from the specified string.
+		# @parameter string [String] the string to load into the buffer.
+		# @returns [Buffer] a buffer with the contents of the specified string.
 		def self.load(string)
 			Buffer.new(string).freeze
 		end
 		
+		# @returns [Buffer] itself.
 		def to_buffer
 			self
 		end
 	end
 	
+	# Represents a file buffer with a given path.
 	class FileBuffer
+		# Create a new file buffer from a file path.
+		# @parameter path [String] the path to the file.
 		def initialize(path)
 			@path = path
+			@cache = nil
 		end
 		
+		# Freeze the buffer, caching the contents of the file.
 		def freeze
 			return self if frozen?
 			
@@ -46,27 +74,38 @@ module XRB
 			super
 		end
 		
+		# @attribute [String] the path name of the buffer.
 		attr :path
 		
+		# @returns [Encoding] the encoding of the buffer.
 		def encoding
 			read.encoding
 		end
 		
+		# Read the contents of the file into the buffer.
+		# @returns [String] the content of the buffer.
 		def read
 			@cache ||= File.read(@path).freeze
 		end
 		
+		# @returns [Buffer] a buffer with the contents of the file.
 		def to_buffer
 			Buffer.new(self.read, @path)
 		end
 	end
 	
+	# Represents an IO buffer with a given path.
 	class IOBuffer
+		# Create a new IO buffer from an IO object.
+		# @parameter io [IO] the IO object to use as the buffer.
+		# @parameter path [String] the path to use for the buffer.
 		def initialize(io, path: io.inspect)
 			@io = io
 			@path = path
+			@cache = nil
 		end
 		
+		# Freeze the buffer, caching the contents of the IO object.
 		def freeze
 			return self if frozen?
 			
@@ -75,21 +114,31 @@ module XRB
 			super
 		end
 		
+		# @attribute [String] the path name of the buffer.
 		attr :path
 		
+		# @returns [Encoding] the encoding of the buffer.
 		def encoding
 			read.encoding
 		end
 		
+		# Read the contents of the IO object into the buffer.
 		def read
-			@cache ||= @io.read.freeze
+			unless @cache
+				@cache = @io.read.freeze
+				@io.close
+			end
+			
+			return @cache
 		end
 		
+		# @returns [Buffer] a buffer with the contents of the IO object.
 		def to_buffer
 			Buffer.new(self.read, path: @path)
 		end
 	end
 	
+	# Convert the given value to a buffer.
 	def self.Buffer(value)
 		case value
 		when String

data/lib/xrb/builder.rb

@@ -11,12 +11,16 @@ module XRB
 	class Builder
 		INDENT = "\t"
 		
+		# Represents a lazy fragment of markup that can be generated on demand.
 		class Fragment
+			# Initialize the fragment with a block that will be called to generate the markup.
+			# @parameter block [Proc] the block that will be called to generate the markup.
 			def initialize(block)
 				@block = block
 				@builder = nil
 			end
 			
+			# Append the markup to the given output.
 			def append_markup(output)
 				builder = Builder.new(output)
 				
@@ -25,19 +29,25 @@ module XRB
 				return builder.output
 			end
 			
+			# Build the markup using the given builder.
 			def build_markup(builder)
 				@block.call(builder)
 			end
 			
+			# Convert the fragment to a string.
+			# @returns [MarkupString] the markup generated by the fragment.
 			def to_s
 				self.append_markup(nil)
 			end
 			
+			# Compare the fragment to another object as a string. Primarily useful for testing.
 			def == other
 				# This is a bit of a hack... but is required for existing specs to pass:
 				self.to_s == other.to_s
 			end
 			
+			# Assuming the fragment is generated in the context of a template being rendered, append the fragment to the output buffer.
+			# @parameter block [Proc] the block which is within the scope of the template being rendered.
 			def >> block
 				if block
 					Template.buffer(block.binding) << self
@@ -84,12 +94,15 @@ module XRB
 			@children = [0]
 		end
 		
+		# Append the markup to the given output.
 		def build_markup(builder)
 			builder.append(@output)
 		end
 		
+		# @attribute [Object] the output buffer.
 		attr :output
 		
+		# @returns [Encoding] the encoding of the output.
 		def encoding
 			@output.encoding
 		end
@@ -113,16 +126,17 @@ module XRB
 			end
 		end
 		
+		# Append a doctype declaration to the output.
 		def doctype(attributes = "html")
 			@output << "<!doctype #{attributes}>\n"
 		end
 		
-		# Begin a block tag.
+		# Append a tag to the output.
 		def tag(name, attributes = {}, &block)
 			full_tag(name, attributes, @indent, @indent, &block)
 		end
 		
-		# Begin an inline tag.
+		# Append a tag to the output without indentation or whitespace.
 		def inline_tag(name, attributes = {}, &block)
 			original_indent = @indent
 			
@@ -145,6 +159,7 @@ module XRB
 			@indent = original_indent
 		end
 		
+		# Append text to the output, escaping it if necessary.
 		def text(content)
 			return unless content
 			
@@ -164,6 +179,7 @@ module XRB
 			@output << content
 		end
 		
+		# Append content to the output.
 		def <<(content)
 			content&.build_markup(self)
 		end

data/lib/xrb/template.rb

@@ -41,7 +41,7 @@ module XRB
 			return output.to_str
 		end
 		
-		# Returns the buffer used for capturing output.
+		# @returns [Object] the buffer used for capturing output.
 		def self.buffer(binding)
 			binding.local_variable_get(OUT)
 		end
@@ -72,15 +72,19 @@ module XRB
 			end
 		end
 		
+		# Load a template from a file.
 		def self.load_file(path, **options)
 			self.new(FileBuffer.new(path), **options).freeze
 		end
 		
+		# Load a template from a string.
 		def self.load(string, *arguments, **options)
 			self.new(Buffer.new(string), **options).freeze
 		end
 		
-		# @param binding [Binding] The binding in which the template is compiled. e.g. `TOPLEVEL_BINDING`.
+		# Initialize a new template.
+		# @parameter buffer [Buffer] The buffer containing the template.
+		# @parameter binding [Binding] The binding in which the template is compiled. e.g. `TOPLEVEL_BINDING`.
 		def initialize(buffer, binding: BINDING)
 			@buffer = buffer
 			@binding = binding
@@ -96,14 +100,23 @@ module XRB
 			super
 		end
 		
+		# The compiled code for the template.
+		# @returns [String] the compiled Ruby code.
 		def code
 			@code ||= compile!
 		end
 		
+		# The compiled template as a proc.
+		# @parameter scope [Object] The scope in which the template will be compiled.
+		# @returns [Proc] a proc that can be called with an output object.
 		def compiled(scope = @binding.dup)
 			@compiled ||= eval("\# frozen_string_literal: true\nproc{|#{OUT}|;#{code}}", scope, @buffer.path, 0).freeze
 		end
 		
+		# Renders the template to a string.
+		#
+		# @parameter scope [Object] The scope in which the template will be evaluated.
+		# @parameter output [String | Nil] The output string to append to.
 		def to_string(scope = Object.new, output = nil)
 			builder = Builder.new(output, encoding: code.encoding)
 			
@@ -112,13 +125,29 @@ module XRB
 			return builder.output
 		end
 		
+		# Renders the template to a buffer.
 		def to_buffer(scope)
 			Buffer.new(to_string(scope), path: @buffer.path)
 		end
 		
+		# Convert the template to a proc that can be called with an output object. The proc renders the template using `to_string` and writes the output to the given output object. The output should implement `<<` and `close_write(error = nil)` methods.
+		#
+		# @parameter scope [Object] The scope in which the template will be evaluated.
+		# @returns [Proc] a proc that can be called with an output object.
 		def to_proc(scope = @binding.dup)
 			proc do |output|
 				to_string(scope, output)
+			rescue Exception => error
+				# I find this a bit ugly but we only use this code path on errors, so it's not performance critical.
+				if output.method(:close_write).arity != 0
+					# Inform the output that an error occured and the output was not generated correctly.
+					output.close_write(error)
+					output = nil
+				end
+				
+				raise
+			ensure
+				output&.close_write
 			end
 		end
 		

data/lib/xrb/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2012-2024, by Samuel Williams.
 
 module XRB
-	VERSION = "0.10.2"
+	VERSION = "0.11.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xrb
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.11.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -40,7 +40,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-10-28 00:00:00.000000000 Z
+date: 2024-10-30 00:00:00.000000000 Z
 dependencies: []
 description:
 email: