xrb 0.11.2 → 0.12.0

data/lib/xrb/markup.rb

@@ -6,20 +6,33 @@
 require "cgi"
 
 module XRB
-	# A wrapper which indicates that `value` can be appended to the output buffer without any changes.
+	# Provides the default markup rendering protocol, escaping object string representations.
 	module Markup
+		# Wrap a string as markup without escaping it.
+		# @parameter string [String] The already-safe markup string.
+		# @returns [MarkupString] The unescaped markup string.
 		def self.raw(string)
 			MarkupString.raw(string)
 		end
 		
+		# Append a value to an output buffer using its markup representation.
+		# @parameter output [Interface(:<<)] The output buffer.
+		# @parameter value [Interface(:append_markup)] The value to append.
+		# @returns [Object] The result of appending the value.
 		def self.append(output, value)
 			value.append_markup(output)
 		end
 		
+		# Append the escaped string representation of the receiver to an output buffer.
+		# @parameter output [Interface(:<<)] The output buffer.
+		# @returns [Object] The output buffer.
 		def append_markup(output)
 			output << ::CGI.escape_html(self.to_s)
 		end
 		
+		# Append the escaped string representation of the receiver using a builder.
+		# @parameter builder [Builder] The builder receiving the escaped markup.
+		# @returns [Object] The builder's output buffer.
 		def build_markup(builder)
 			append_markup(builder.output)
 		end
@@ -29,8 +42,8 @@ module XRB
 	
 	# Initialized from text which is escaped to use HTML entities.
 	class MarkupString < String
-		# @param string [String] the string value itself.
-		# @param escape [Boolean] whether or not to escape the string.
+		# @parameter string [String | Nil] The string value itself.
+		# @parameter escape [Boolean] Whether to escape the string.
 		def initialize(string = nil, escape = true)
 			if string
 				if escape
@@ -54,12 +67,19 @@ module XRB
 			true
 		end
 		
+		# Append this already-safe markup string to an output buffer.
+		# @parameter output [Interface(:<<)] The output buffer.
+		# @returns [Object] The output buffer.
 		def append_markup(output)
 			output << self
 		end
 	end
 	
+	# Helpers for constructing script-compatible markup values.
 	module Script
+		# Serialize a value as raw JSON markup without HTML escaping it.
+		# @parameter value [Object] The value to serialize.
+		# @returns [MarkupString] The serialized JSON markup.
 		def self.json(value)
 			MarkupString.new(JSON.dump(value), false)
 		end

data/lib/xrb/query.rb

@@ -9,14 +9,21 @@ require_relative "parsers"
 require "uri"
 
 module XRB
+	# Parses URL query strings into nested Ruby objects.
 	module Query
+		# Parse a query string buffer.
+		# @parameter buffer [Buffer] The buffer containing the query string.
+		# @returns [Hash] The parsed query parameters.
 		def self.parse(buffer)
 			Hash.new.tap do |query|
 				Parsers.parse_query(buffer, Delegate.new(query))
 			end
 		end
 		
+		# Receives query parser events and assembles them into nested hashes and arrays.
 		class Delegate
+			# Initialize a query delegate with the top-level result hash.
+			# @parameter top [Hash] The hash which receives parsed query parameters.
 			def initialize(top = {})
 				@top = top
 				
@@ -24,6 +31,10 @@ module XRB
 				@index = nil
 			end
 			
+			# Select a symbolic key parsed from a query string.
+			# @parameter key [String] The parsed key.
+			# @parameter encoded [Boolean] Whether the key is URL encoded.
+			# @returns [Symbol] The selected key.
 			def string(key, encoded)
 				if encoded
 					key = ::URI.decode_www_form_component(key)
@@ -32,10 +43,16 @@ module XRB
 				index(key.to_sym)
 			end
 			
+			# Select an integer key parsed from an array or hash index.
+			# @parameter key [String] The parsed integer key.
+			# @returns [Integer] The selected key.
 			def integer(key)
 				index(key.to_i)
 			end
 			
+			# Descend into the previously selected key and select the next nested key.
+			# @parameter key [Symbol | Integer] The next key to select.
+			# @returns [Symbol | Integer] The selected key.
 			def index(key)
 				if @index
 					@current = @current.fetch(@index) do
@@ -46,6 +63,8 @@ module XRB
 				@index = key
 			end
 			
+			# Descend into an array and select its next index.
+			# @returns [Integer] The selected array index.
 			def append
 				if @index
 					@current = @current.fetch(@index) do
@@ -56,6 +75,10 @@ module XRB
 				@index = @current.size
 			end
 			
+			# Assign a parsed value to the selected key.
+			# @parameter value [String] The parsed value.
+			# @parameter encoded [Boolean] Whether the value is URL encoded.
+			# @returns [Nil] This method always returns `nil`.
 			def assign(value, encoded)
 				if encoded
 					value = ::URI.decode_www_form_component(value)
@@ -67,6 +90,8 @@ module XRB
 				@index = nil
 			end
 			
+			# Assign `true` to a query key which has no explicit value.
+			# @returns [Nil] This method always returns `nil`.
 			def pair
 				if @index
 					@current[@index] = true

data/lib/xrb/strings.rb

@@ -4,14 +4,21 @@
 # Copyright, 2012-2024, by Samuel Williams.
 
 module XRB
+	# String transformation helpers used when generating markup and identifiers.
 	module Strings
 		HTML_ESCAPE = {"&" => "&amp;", "<" => "&lt;", ">" => "&gt;", "\"" => "&quot;"}
 		HTML_ESCAPE_PATTERN = Regexp.new("[" + Regexp.quote(HTML_ESCAPE.keys.join) + "]")
-
+		
+		# Escape HTML-sensitive characters in a string.
+		# @parameter string [String] The string to escape.
+		# @returns [String] The HTML-escaped string.
 		def self.to_html(string)
 			string.gsub(HTML_ESCAPE_PATTERN){|c| HTML_ESCAPE[c]}
 		end
-
+		
+		# Quote a string and escape quotes and line breaks within it.
+		# @parameter string [String] The string to quote.
+		# @returns [String] The quoted string.
 		def self.to_quoted_string(string)
 			string = string.gsub('"', '\\"')
 			string.gsub!(/\r/, "\\r")
@@ -25,10 +32,17 @@ module XRB
 			%Q{#{key}="#{value}"}
 		end
 		
+		# Format a boolean-style attribute.
+		# @parameter key [String | Symbol] The attribute name.
+		# @parameter strict [Boolean] Whether to include an explicit attribute value.
+		# @returns [String] The formatted attribute.
 		def self.to_simple_attribute(key, strict)
 			strict ? %Q{#{key}="#{key}"} : key.to_s
 		end
 		
+		# Convert a separated identifier to a human-readable title.
+		# @parameter string [String] The identifier to transform.
+		# @returns [String] The title-cased string.
 		def self.to_title(string)
 			string = string.gsub(/(^|[ \-_])(.)/){" " + $2.upcase}
 			string.strip!
@@ -36,6 +50,9 @@ module XRB
 			return string
 		end
 		
+		# Convert a constant-like name to a snake-case identifier.
+		# @parameter string [String] The name to transform.
+		# @returns [String] The snake-case identifier.
 		def self.to_snake(string)
 			string = string.gsub("::", "")
 			string.gsub!(/([A-Z]+)/){"_" + $1.downcase}

data/lib/xrb/tag.rb

@@ -8,6 +8,9 @@ require_relative "markup"
 module XRB
 	# This represents an individual SGML tag, e.g. <a>, </a> or <a />, with attributes. Attribute values must be escaped.
 	Tag = Struct.new(:name, :closed, :attributes) do
+		# Split a qualified tag name into its namespace and local name.
+		# @parameter qualified_name [String] The potentially namespaced tag name.
+		# @returns [Array(String | Nil)] The namespace and local name.
 		def self.split(qualified_name)
 			if i = qualified_name.index(":")
 				return qualified_name.slice(0...i), qualified_name.slice(i+1..-1)
@@ -16,38 +19,63 @@ module XRB
 			end
 		end
 		
+		# Create a self-closing tag.
+		# @parameter name [String] The tag name.
+		# @parameter attributes [Hash] The tag attributes.
+		# @returns [Tag] The self-closing tag.
 		def self.closed(name, attributes = {})
 			self.new(name, true, attributes)
 		end
 		
+		# Create a tag with separate opening and closing markup.
+		# @parameter name [String] The tag name.
+		# @parameter attributes [Hash] The tag attributes.
+		# @returns [Tag] The opened tag.
 		def self.opened(name, attributes = {})
 			self.new(name, false, attributes)
 		end
 		
+		# Append the tag to an output buffer.
+		# @parameter output [Interface(:<<)] The output buffer.
+		# @returns [Nil] This method always returns `nil`.
 		def append_markup(output)
 			self.write(output)
 		end
 		
+		# Append the tag using a markup builder.
+		# @parameter builder [Builder] The builder receiving the tag.
+		# @returns [Nil] This method always returns `nil`.
 		def build_markup(builder)
 			self.append_markup(builder.output)
 		end
 		
+		# Fetch an attribute value by key.
+		# @parameter key [Object] The attribute key.
+		# @returns [Object | Nil] The attribute value.
 		def [] key
 			attributes[key]
 		end
 		
 		alias to_hash attributes
 		
+		# Format the tag and optional content as markup.
+		# @parameter content [Object | Nil] The optional tag content.
+		# @returns [String] The formatted tag markup.
 		def to_s(content = nil)
 			self.class.format_tag(name, attributes, content || !closed)
 		end
 		
 		alias to_str to_s
 		
+		# Determine whether the tag is self-closing.
+		# @returns [Boolean] Whether the tag is self-closing.
 		def self_closed?
 			closed
 		end
 		
+		# Write the opening or self-closing tag to a buffer.
+		# @parameter buffer [Interface(:<<)] The output buffer.
+		# @returns [Object] The output buffer.
 		def write_opening_tag(buffer)
 			buffer << "<" << name
 			
@@ -60,14 +88,26 @@ module XRB
 			end
 		end
 		
+		# Write the closing tag to a buffer.
+		# @parameter buffer [Interface(:<<)] The output buffer.
+		# @returns [Object] The output buffer.
 		def write_closing_tag(buffer)
 			buffer << "</" << name << ">"
 		end
 		
+		# Write the complete tag and optional content to a buffer.
+		# @parameter buffer [Interface(:<<)] The output buffer.
+		# @parameter content [Object | Nil] The optional tag content.
+		# @returns [Nil] This method always returns `nil`.
 		def write(buffer, content = nil)
 			self.class.append_tag(buffer, name, attributes, content || !closed)
 		end
 		
+		# Format a tag as a new string.
+		# @parameter name [String] The tag name.
+		# @parameter attributes [Hash] The tag attributes.
+		# @parameter content [Object | Boolean | Nil] The tag content, `true` for empty content, or `nil` for a self-closing tag.
+		# @returns [String] The formatted tag markup.
 		def self.format_tag(name, attributes, content)
 			buffer = String.new.force_encoding(name.encoding)
 			
@@ -76,6 +116,12 @@ module XRB
 			return buffer
 		end
 		
+		# Append a complete tag to an output buffer.
+		# @parameter buffer [Interface(:<<)] The output buffer.
+		# @parameter name [String] The tag name.
+		# @parameter attributes [Hash] The tag attributes.
+		# @parameter content [Object | Boolean | Nil] The tag content, `true` for empty content, or `nil` for a self-closing tag.
+		# @returns [Nil] This method always returns `nil`.
 		def self.append_tag(buffer, name, attributes, content)
 			buffer << "<" << name.to_s
 			

data/lib/xrb/template.rb

@@ -16,6 +16,11 @@ module XRB
 	BINDING = binding
 	
 	class Builder
+		# Capture markup generated by a block using this builder as its output.
+		# @parameter arguments [Array] The arguments passed to the block.
+		# @yields {|*arguments| ...} The block whose generated markup will be captured.
+		# 	@parameter arguments [Array] The arguments supplied to {capture}.
+		# @returns [String] The captured markup.
 		def capture(*arguments, &block)
 			Template.capture(*arguments, output: self, &block)
 		end
@@ -46,7 +51,10 @@ module XRB
 			binding.local_variable_get(OUT)
 		end
 		
+		# Assembles parser events into executable Ruby source code for a template.
 		class Assembler
+			# Initialize an empty template assembler.
+			# @parameter encoding [Encoding] The encoding of the generated source code.
 			def initialize(encoding: Encoding::UTF_8)
 				@code = String.new.force_encoding(encoding)
 			end
@@ -60,7 +68,7 @@ module XRB
 				text = text.gsub("'", "\\\\'")
 				@code << "#{OUT}.raw('#{text}');"
 			end
-
+			
 			# Output a ruby expression (or part of).
 			def instruction(text, postfix = nil)
 				@code << text << (postfix || ";")
@@ -93,6 +101,8 @@ module XRB
 			@compiled = nil
 		end
 		
+		# Compile and freeze the template.
+		# @returns [Template] The frozen template.
 		def freeze
 			return self if frozen?
 			

data/lib/xrb/version.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2012-2024, by Samuel Williams.
+# Copyright, 2012-2026, by Samuel Williams.
 
+# @namespace
 module XRB
-	VERSION = "0.11.2"
+	VERSION = "0.12.0"
 end

data/lib/xrb.rb

@@ -7,5 +7,3 @@ require_relative "xrb/version"
 require_relative "xrb/native"
 require_relative "xrb/builder"
 require_relative "xrb/template"
-
-require_relative "xrb/reference"

data/readme.md

@@ -46,6 +46,14 @@ Please see the [project documentation](https://socketry.github.io/xrb/) for more
 
   - [Markup Parser](https://socketry.github.io/xrb/guides/markup-parser/index) - This guide explains how to parse and manipulate Markup using the XRB templating system.
 
+## Releases
+
+Please see the [project releases](https://socketry.github.io/xrb/releases/index) for all releases.
+
+### v0.12.0
+
+  - [URL Helpers](https://socketry.github.io/xrb/releases/index#url-helpers)
+
 ## See Also
 
   - [xrb-rails](https://github.com/socketry/xrb-rails) - A Rails ActionView integration for rendering XRB templates.
@@ -57,11 +65,27 @@ Please see the [project documentation](https://socketry.github.io/xrb/) for more
 
 We welcome contributions to this project.
 
-1.  Fork it.
+1.  Fork the repository.
 2.  Create your feature branch (`git checkout -b my-new-feature`).
-3.  Commit your changes (`git commit -am 'Add some feature'`).
+3.  Commit your changes (`git commit -am 'Add some feature.'`).
 4.  Push to the branch (`git push origin my-new-feature`).
-5.  Create new Pull Request.
+5.  Create a new pull request.
+
+### Running Tests
+
+To run the test suite:
+
+``` bash
+$ bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` bash
+$ bundle exec bake gem:release:patch # or minor or major
+```
 
 ### Developer Certificate of Origin
 

data/releases.md

@@ -0,0 +1,26 @@
+# Releases
+
+## v0.12.0
+
+### URL Helpers
+
+**Breaking:** XRB no longer provides the `XRB::Reference` and `XRB::URI` classes or their factory methods. Use `Protocol::URL::Reference` from the `protocol-url` gem instead.
+
+Add `gem "protocol-url"` to your application dependencies and replace `require "xrb/reference"` or `require "xrb/uri"` with `require "protocol/url"`.
+
+Replace `XRB::Reference(path, **parameters)` with:
+
+``` ruby
+reference = Protocol::URL::Reference.parse(path)
+reference.parse_query!.update(parameters)
+```
+
+This preserves the previous behavior of parsing existing query parameters before updating them with the supplied parameters.
+
+Replace direct `XRB::Reference.new(path, parameters, fragment: fragment)` calls with `Protocol::URL::Reference.new(path, nil, fragment, parameters)`.
+
+Replace `XRB::URI(path, parameters)` with `Protocol::URL::Reference.parse(path, parameters)`. This preserves an existing query string and appends the supplied parameters.
+
+Replace direct `XRB::URI.new(path, query, fragment, parameters)` calls with `Protocol::URL::Reference.new(path, query, fragment, parameters)`.
+
+`protocol-url` treats path strings as already encoded URL paths. When starting with decoded path components, encode them explicitly with `Protocol::URL::Path.for(components)`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xrb
 version: !ruby/object:Gem::Version
-  version: 0.11.2
+  version: 0.12.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -80,22 +80,22 @@ files:
 - lib/xrb/native.rb
 - lib/xrb/parsers.rb
 - lib/xrb/query.rb
-- lib/xrb/reference.rb
 - lib/xrb/strings.rb
 - lib/xrb/tag.rb
 - lib/xrb/template.rb
-- lib/xrb/uri.rb
 - lib/xrb/version.rb
 - license.md
 - notes.md
 - readme.md
-homepage: https://github.com/ioquatix/xrb
+- releases.md
+homepage: https://github.com/socketry/xrb
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/socketry/xrb/issues
   documentation_uri: https://socketry.github.io/xrb/
   funding_uri: https://github.com/sponsors/ioquatix
-  source_code_uri: https://github.com/ioquatix/xrb.git
+  source_code_uri: https://github.com/socketry/xrb.git
 rdoc_options: []
 require_paths:
 - lib
@@ -103,14 +103,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A fast native templating system that compiles directly to Ruby code.
 test_files: []

data/lib/xrb/reference.rb

@@ -1,108 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
-
-require_relative "query"
-
-module XRB
-	class Reference
-		def initialize(path, query = {}, fragment: nil)
-			@path = path.to_s
-			@query = query
-			@fragment = fragment
-		end
-		
-		# The path component of the URI, e.g. /foo/bar/index.html
-		attr :path
-		
-		# The query parameters.
-		attr :query
-		
-		# A fragment identifier, the part after the '#'
-		attr :fragment
-		
-		def append(buffer)
-			buffer << escape_path(@path)
-			
-			unless @query.empty?
-				buffer << "?" << query_string
-			end
-			
-			if @fragment
-				buffer << "#" << escape(@fragment)
-			end
-			
-			return buffer
-		end
-		
-		def to_str
-			append(String.new)
-		end
-		
-		alias to_s to_str
-		
-		private
-		
-		# According to https://tools.ietf.org/html/rfc3986#section-3.3, we escape non-pchar.
-		NON_PCHAR = /([^
-			a-zA-Z0-9
-			\-\._~
-			!\$&'\(\)\*\+,;=
-			:@\/
-		]+)/x.freeze
-		
-		def escape_path(path)
-			encoding = path.encoding
-			path.b.gsub(NON_PCHAR) do |m|
-				"%" + m.unpack("H2" * m.bytesize).join("%").upcase
-			end.force_encoding(encoding)
-		end
-		
-		# Escapes a generic string, using percent encoding.
-		def escape(string)
-			encoding = string.encoding
-			string.b.gsub(/([^a-zA-Z0-9_.\-]+)/) do |m|
-				"%" + m.unpack("H2" * m.bytesize).join("%").upcase
-			end.force_encoding(encoding)
-		end
-		
-		def query_string
-			build_nested_query(@query)
-		end
-		
-		def build_nested_query(value, prefix = nil)
-			case value
-			when Array
-				value.map { |v|
-					build_nested_query(v, "#{prefix}[]")
-				}.join("&")
-			when Hash
-				value.map { |k, v|
-					build_nested_query(v, prefix ? "#{prefix}[#{escape(k.to_s)}]" : escape(k.to_s))
-				}.reject(&:empty?).join("&")
-			when nil
-				prefix
-			else
-				raise ArgumentError, "value must be a Hash" if prefix.nil?
-				"#{prefix}=#{escape(value.to_s)}"
-			end
-		end
-	end
-	
-	# Generate a URI from a path and user parameters. The path may contain a `#fragment` or `?query=parameters`.
-	def self.Reference(path = "", **parameters)
-		base, fragment = path.split("#", 2)
-		path, query_string = base.split("?", 2)
-		
-		if query_string
-			query = Query.parse(Buffer.new(query_string))
-		else
-			query = {}
-		end
-		
-		query.update(parameters)
-		
-		Reference.new(path, query, fragment: fragment)
-	end
-end