xrb 0.1 → 0.2.0

data/lib/xrb/fallback/template.rl

@@ -0,0 +1,80 @@
+# Released under the MIT License.
+# Copyright, 2016-2024, by Samuel Williams.
+
+%%{
+	machine template;
+	
+	action instruction_begin {
+		instruction_begin = p
+	}
+	
+	action instruction_end {
+		instruction_end = p
+	}
+	
+	action emit_instruction {
+		delegate.instruction(data.byteslice(instruction_begin...instruction_end))
+	}
+	
+	action emit_instruction_line {
+		delegate.instruction(data.byteslice(instruction_begin...instruction_end), "\n")
+	}
+	
+	action instruction_error {
+		raise ParseError.new("failed to parse instruction", buffer, p)
+	}
+	
+	action expression_begin {
+		expression_begin = p
+	}
+	
+	action expression_end {
+		expression_end = p
+	}
+	
+	action emit_expression {
+		delegate.expression(data.byteslice(expression_begin...expression_end))
+	}
+	
+	action expression_error {
+		raise ParseError.new("failed to parse expression", buffer, p)
+	}
+	
+	action emit_text {
+		delegate.text(data.byteslice(ts...te))
+	}
+	
+	# This magic ensures that we process bytes.
+	getkey bytes[p];
+	
+	include template "xrb/template.rl";
+}%%
+
+require_relative '../error'
+
+module XRB
+	module Fallback
+		%% write data;
+		
+		def self.parse_template(buffer, delegate)
+			data = buffer.read
+			bytes = data.bytes
+			
+			p = 0
+			pe = eof = data.bytesize
+			stack = []
+			
+			expression_begin = expression_end = nil
+			instruction_begin = instruction_end = nil
+			
+			%% write init;
+			%% write exec;
+			
+			if p != eof
+				raise ParseError.new("could not consume all input", buffer, p)
+			end
+			
+			return nil
+		end
+	end
+end

data/lib/xrb/markup.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2016-2024, by Samuel Williams.
+
+require 'cgi'
+
+module XRB
+	# A wrapper which indicates that `value` can be appended to the output buffer without any changes.
+	module Markup
+		# Converts special characters `<`, `>`, `&`, and `"` into their equivalent entities.
+		# @return [String] May return the original string if no changes were made.
+		def self.escape_string(string)
+			CGI.escape_html(string)
+		end
+		
+		# Appends a string to the output buffer, escaping if if necessary.
+		def self.append(buffer, value)
+			if value.is_a? Markup
+				buffer << value
+			elsif value
+				buffer << self.escape_string(value.to_s)
+			end
+		end
+	end
+	
+	# Initialized from text which is escaped to use HTML entities.
+	class MarkupString < String
+		include Markup
+		
+		# @param string [String] the string value itself.
+		# @param escape [Boolean] whether or not to escape the string.
+		def initialize(string = nil, escape = true)
+			if string
+				if escape
+					string = Markup.escape_string(string)
+				end
+				
+				super(string)
+			else
+				super()
+			end
+		end
+		
+		# Generate a valid MarkupString withot any escaping.
+		def self.raw(string)
+			self.new(string, false)
+		end
+	end
+	
+	module Script
+		def self.json(value)
+			MarkupString.new(JSON.dump(value), false)
+		end
+	end
+end

data/lib/xrb/native.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2016-2024, by Samuel Williams.
+
+require_relative 'error'
+
+# Methods on the following classes may be replaced by native implementations:
+require_relative 'tag'
+
+begin
+	require 'XRB_Extension'
+rescue LoadError => error
+	warn "Could not load native parsers: #{error}"
+end unless ENV['XRB_PREFER_FALLBACK']

data/lib/xrb/parse_delegate.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2016-2024, by Samuel Williams.
+
+module XRB
+	# This is a sample delegate for capturing all events. It's only use is for testing.
+	class ParseDelegate
+		def initialize
+			@events = []
+		end
+		
+		attr :events
+		
+		def method_missing(*args)
+			@events << args
+		end
+	end
+end

data/lib/xrb/parsers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2012-2024, by Samuel Williams.
+
+require_relative 'native'
+require_relative 'parse_delegate'
+
+if defined? XRB::Native
+	XRB::Parsers = XRB::Native
+else
+	require_relative 'fallback/markup'
+	require_relative 'fallback/template'
+	require_relative 'fallback/query'
+	
+	XRB::Parsers = XRB::Fallback
+end

data/lib/xrb/query.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2020-2024, by Samuel Williams.
+
+require_relative 'buffer'
+require_relative 'parsers'
+
+require 'uri'
+
+module XRB
+	module Query
+		def self.parse(buffer)
+			Hash.new.tap do |query|
+				Parsers.parse_query(buffer, Delegate.new(query))
+			end
+		end
+		
+		class Delegate
+			def initialize(top = {})
+				@top = top
+				
+				@current = @top
+				@index = nil
+			end
+			
+			def string(key, encoded)
+				if encoded
+					key = ::URI.decode_www_form_component(key)
+				end
+				
+				index(key.to_sym)
+			end
+			
+			def integer(key)
+				index(key.to_i)
+			end
+			
+			def index(key)
+				if @index
+					@current = @current.fetch(@index) do
+						@current[@index] = {}
+					end
+				end
+				
+				@index = key
+			end
+			
+			def append
+				if @index
+					@current = @current.fetch(@index) do
+						@current[@index] = []
+					end
+				end
+				
+				@index = @current.size
+			end
+			
+			def assign(value, encoded)
+				if encoded
+					value = ::URI.decode_www_form_component(value)
+				end
+				
+				@current[@index] = value
+				
+				@current = @top
+				@index = nil
+			end
+			
+			def pair
+				if @index
+					@current[@index] = true
+				end
+				
+				@current = @top
+				@index = nil
+			end
+		end
+	end
+end

data/lib/xrb/reference.rb

@@ -0,0 +1,108 @@
+# 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

data/lib/xrb/strings.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2012-2024, by Samuel Williams.
+
+module XRB
+	module Strings
+		HTML_ESCAPE = {"&" => "&amp;", "<" => "&lt;", ">" => "&gt;", "\"" => "&quot;"}
+		HTML_ESCAPE_PATTERN = Regexp.new("[" + Regexp.quote(HTML_ESCAPE.keys.join) + "]")
+
+		def self.to_html(string)
+			string.gsub(HTML_ESCAPE_PATTERN){|c| HTML_ESCAPE[c]}
+		end
+
+		def self.to_quoted_string(string)
+			string = string.gsub('"', '\\"')
+			string.gsub!(/\r/, "\\r")
+			string.gsub!(/\n/, "\\n")
+			
+			return "\"#{string}\""
+		end
+		
+		# `value` must already be escaped.
+		def self.to_attribute(key, value)
+			%Q{#{key}="#{value}"}
+		end
+		
+		def self.to_simple_attribute(key, strict)
+			strict ? %Q{#{key}="#{key}"} : key.to_s
+		end
+		
+		def self.to_title(string)
+			string = string.gsub(/(^|[ \-_])(.)/){" " + $2.upcase}
+			string.strip!
+			
+			return string
+		end
+		
+		def self.to_snake(string)
+			string = string.gsub("::", "")
+			string.gsub!(/([A-Z]+)/){"_" + $1.downcase}
+			string.sub!(/^_+/, "")
+			
+			return string
+		end
+	end
+end

data/lib/xrb/tag.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2017-2024, by Samuel Williams.
+
+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
+		include XRB::Markup
+		
+		def self.split(qualified_name)
+			if i = qualified_name.index(':')
+				return qualified_name.slice(0...i), qualified_name.slice(i+1..-1)
+			else
+				return nil, qualified_name
+			end
+		end
+		
+		def self.closed(name, attributes = {})
+			self.new(name, true, attributes)
+		end
+		
+		def self.opened(name, attributes = {})
+			self.new(name, false, attributes)
+		end
+		
+		def [] key
+			attributes[key]
+		end
+		
+		alias to_hash attributes
+		
+		def to_s(content = nil)
+			self.class.format_tag(name, attributes, content || !closed)
+		end
+		
+		alias to_str to_s
+		
+		def self_closed?
+			closed
+		end
+		
+		def write_opening_tag(buffer)
+			buffer << '<' << name
+			
+			self.class.append_attributes(buffer, attributes, nil)
+			
+			if self_closed?
+				buffer << '/>'
+			else
+				buffer << '>'
+			end
+		end
+		
+		def write_closing_tag(buffer)
+			buffer << '</' << name << '>'
+		end
+		
+		def write(buffer, content = nil)
+			self.class.append_tag(buffer, name, attributes, content || !closed)
+		end
+		
+		def self.format_tag(name, attributes, content)
+			buffer = String.new.force_encoding(name.encoding)
+			
+			self.append_tag(buffer, name, attributes, content)
+			
+			return buffer
+		end
+		
+		def self.append_tag(buffer, name, attributes, content)
+			buffer << '<' << name.to_s
+			
+			self.append_attributes(buffer, attributes, nil)
+			
+			if !content
+				buffer << '/>'
+			else
+				buffer << '>'
+				unless content == true
+					Markup.append(buffer, content)
+				end
+				buffer << '</' << name.to_s << '>'
+			end
+			
+			return nil
+		end
+		
+		# Convert a set of attributes into a string suitable for use within a <tag>.
+		def self.append_attributes(buffer, attributes, prefix)
+			attributes.each do |key, value|
+				next unless value
+				
+				attribute_key = prefix ? "#{prefix}-#{key}" : key
+				
+				case value
+				when Hash
+					self.append_attributes(buffer, value, attribute_key)
+				when Array
+					self.append_attributes(buffer, value, attribute_key)
+				when TrueClass
+					buffer << ' ' << attribute_key.to_s
+				else
+					buffer << ' ' << attribute_key.to_s << '="'
+					Markup.append(buffer, value)
+					buffer << '"'
+				end
+			end
+			
+			return nil
+		end
+	end
+end

data/lib/xrb/template.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2012-2024, by Samuel Williams.
+
+require_relative 'parsers'
+require_relative 'markup'
+require_relative 'buffer'
+require_relative 'builder'
+
+module XRB
+	# The output variable that will be used in templates:
+	OUT = :_out
+	BINDING = binding
+	
+	class Builder
+		def capture(*arguments, &block)
+			Template.capture(*arguments, output: self, &block)
+		end
+	end
+	
+	class Template
+		# Returns the output produced by calling the given block.
+		def self.capture(*arguments, output: nil, &block)
+			scope = block.binding
+			previous_output = scope.local_variable_get(OUT)
+			
+			output ||= previous_output.class.new(encoding: previous_output.encoding)
+			scope.local_variable_set(OUT, output)
+			
+			begin
+				block.call(*arguments)
+			ensure
+				scope.local_variable_set(OUT, previous_output)
+			end
+			
+			return output
+		end
+		
+		# Returns the buffer used for capturing output.
+		def self.buffer(binding)
+			binding.local_variable_get(OUT)
+		end
+		
+		class Assembler
+			def initialize(encoding: Encoding::UTF_8)
+				@code = String.new.force_encoding(encoding)
+			end
+
+			attr :code
+
+			# Output raw text to the template.
+			def text(text)
+				text = text.gsub("'", "\\\\'")
+				@code << "#{OUT}<<'#{text}';"
+				
+				# This is an interesting approach, but it doens't preserve newlines or tabs as raw characters, so template line numbers don't match up.
+				# @parts << "#{OUT}<<#{text.dump};"
+			end
+
+			# Output a ruby expression (or part of).
+			def instruction(text, postfix = nil)
+				@code << text << (postfix || ';')
+			end
+			
+			# Output a string interpolation.
+			def expression(text)
+				# Double brackets are required here to handle expressions like #{foo rescue "bar"}.
+				@code << "#{OUT}<<String(#{text});"
+			end
+		end
+		
+		def self.load_file(path, **options)
+			self.new(FileBuffer.new(path), **options).freeze
+		end
+		
+		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`.
+		def initialize(buffer, binding: BINDING)
+			@buffer = buffer
+			@binding = binding
+		end
+		
+		def freeze
+			return self if frozen?
+			
+			to_proc
+			
+			super
+		end
+		
+		def to_string(scope = Object.new, output = nil)
+			output ||= output_buffer
+			
+			scope.instance_exec(output, &to_proc)
+			
+			return output
+		end
+		
+		def to_buffer(scope)
+			Buffer.new(to_string(scope), path: @buffer.path)
+		end
+		
+		def to_proc(scope = @binding.dup)
+			@compiled_proc ||= eval("\# frozen_string_literal: true\nproc{|#{OUT}|;#{code}}", scope, @buffer.path, 0).freeze
+		end
+		
+		protected
+		
+		def output_buffer
+			String.new.force_encoding(code.encoding)
+		end
+		
+		def code
+			@code ||= compile!
+		end
+		
+		def make_assembler
+			Assembler.new
+		end
+		
+		def compile!
+			assembler = make_assembler
+			
+			Parsers.parse_template(@buffer, assembler)
+			
+			assembler.code
+		end
+	end
+	
+	class MarkupTemplate < Template
+		class Assembler < Template::Assembler
+			# Output a string interpolation.
+			def expression(code)
+				@code << "#{OUT}<<(#{code});"
+			end
+			
+			# Output raw text to the template.
+			def text(text)
+				text = text.gsub("'", "\\\\'")
+				@code << "#{OUT}.raw('#{text}');"
+			end
+		end
+		
+		def to_string(scope = Object.new, output = nil)
+			super.output
+		end
+		
+		protected
+		
+		# We need an assembler which builds specific `Markup.append` sequences.
+		def make_assembler
+			Assembler.new
+		end
+		
+		# The output of the markup template is encoded markup (e.g. with entities, tags, etc).
+		def output_buffer
+			Builder.new(encoding: code.encoding)
+		end
+	end
+end