phlex 2.0.3 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecf456b3eda7d172d484d81175dbb08c80c9c2387cab5e534cb0f7c31293df88
-  data.tar.gz: 402dd5813b07b2a5dbd6120808d3bfca5fe1241704d414339a44e8cddf130639
+  metadata.gz: b8db189359fc8003771075a598fbeed0c2205ca52604fd829d77afe3c0b3a467
+  data.tar.gz: e5446344e9a83c982fdfa94d4d31abd4b7511858704cc2e9f9d285ad9740b9c3
 SHA512:
-  metadata.gz: 816fe5523cb3ba2ec4bb953cbcefda9aa2901bd781feb8f0fbcf74f69410606118311aaa893c9c4f7e781e2b2e1a754d07f6df24ba5f80966fe6b12b2dbcf3e4
-  data.tar.gz: cbab8596e518be9be3c6cc4496dafb4f3e5862be778fec2aeb619f4866b323e6b65c26db5a8355ceb98084410c7fbab20ed6b00515a567877c8352c06e02a0c7
+  metadata.gz: db1c7e4b591440cea077fb99285552f443301564b293f2a0cf0098750d514af3ac48684d820398ac588570ba71f6f1c1284b72c3b32d6f54f48d20c457a476eb
+  data.tar.gz: fb9ff7728339e8edbcae2b9031c41f77ae2d28e68963b8c27368575d44a20935ff6393730d180579bb29d9a3786e43c1c6388223d0115b17c6d35b31245b64ff

data/lib/phlex/csv.rb

@@ -1,63 +1,122 @@
 # frozen_string_literal: true
 
 class Phlex::CSV
-	FORMULA_PREFIXES = Set["=", "+", "-", "@", "\t", "\r"].freeze
-	SPACE_CHARACTERS = Set[" ", "\t", "\r"].freeze
+	FORMULA_PREFIXES_MAP = Array.new(128).tap do |map|
+		"=+-@\t\r".each_byte do |byte|
+			map[byte] = true
+		end
+	end.freeze
+
+	UNDEFINED = Object.new
 
 	def initialize(collection)
 		@collection = collection
+		@_row_buffer = []
 		@_headers = []
-		@_current_row = []
-		@_current_column_index = 0
-		@_first = true
 	end
 
 	attr_reader :collection
 
-	def call(buffer = +"", context: nil)
-		unless escape_csv_injection? == true || escape_csv_injection? == false
-			raise <<~MESSAGE
-				You need to define escape_csv_injection? in #{self.class.name}, returning either `true` or `false`.
+	def call(buffer = +"", context: nil, delimiter: self.delimiter)
+		ensure_escape_csv_injection_configured!
 
-				CSV injection is a security vulnerability where malicious spreadsheet formulae are used to execute code or exfiltrate data when a CSV is opened in a spreadsheet program such as Microsoft Excel or Google Sheets.
-
-				For more information, see https://owasp.org/www-community/attacks/CSV_Injection
+		strip_whitespace = trim_whitespace?
+		escape_csv_injection = escape_csv_injection?
+		row_buffer = @_row_buffer
+		headers = @_headers
+		has_yielder = respond_to?(:yielder, true)
+		first_row = true
+		render_headers = render_headers?
 
-				If you're sure this CSV will never be opened in a spreadsheet program, you can disable CSV injection escapes:
-
-				  def escape_csv_injection? = false
-
-				This is useful when using CSVs for byte-for-byte data exchange between secure systems.
+		if delimiter.length != 1
+			raise Phlex::ArgumentError.new("Delimiter must be a single character")
+		end
 
-				Alternatively, you can enable CSV injection escapes at the cost of data integrity:
+		if strip_whitespace
+			escape_regex = /[\n"#{delimiter}]/
+		else
+			escape_regex = /^\s|\s$|[\n"#{delimiter}]/
+		end
 
-				  def escape_csv_injection? = true
+		if has_yielder
+			warn <<~MESSAGE
+				Custom yielders are deprecated in Phlex::CSV.
 
-				Note: Enabling the CSV injection escapes will prefix any values that start with `=`, `+`, `-`, `@`, `\\t`, or `\\r` with a single quote `'` to prevent them from being interpreted as formulae by spreadsheet programs.
+				Please replace your yielder with an `around_row` method.
 
-				Unfortunately, there is no one-size-fits-all solution to CSV injection. You need to decide based on your specific use case.
+				You should be able to just rename your yielder method
+				and change `yield` to `super`.
 			MESSAGE
 		end
 
 		each_item do |record|
-			yielder(record) do |*args, **kwargs|
-				view_template(*args, **kwargs)
+			if has_yielder
+				yielder(record) { |*a, **k| row = row_template(*a, **k) }
+			else
+				around_row(record)
+			end
+
+			row = row_buffer
+
+			if first_row
+				first_row = false
+
+				i = 0
+				number_of_columns = row.length
+				first_col = true
+
+				while i < number_of_columns
+					header, = row[i]
+					headers[i] = header
 
-				if @_first && render_headers?
-					buffer << @_headers.join(",") << "\n"
+					if render_headers
+						if first_col
+							first_col = false
+						else
+							buffer << delimiter
+						end
+
+						__escape__(buffer, header, escape_csv_injection:, strip_whitespace:, escape_regex:)
+					end
+					i += 1
+				end
+
+				buffer << "\n" if render_headers
+			end
+
+			i = 0
+			number_of_columns = row.length
+			first_col = true
+
+			while i < number_of_columns
+				header, value = row[i]
+
+				unless headers[i] == header
+					raise Phlex::RuntimeError.new("Header mismatch at index #{i}: expected #{headers[i]}, got #{header}.")
+				end
+
+				if first_col
+					first_col = false
+				else
+					buffer << delimiter
 				end
 
-				buffer << @_current_row.join(",") << "\n"
-				@_current_column_index = 0
-				@_current_row.clear
+				__escape__(buffer, value, escape_csv_injection:, strip_whitespace:, escape_regex:)
+				i += 1
 			end
 
-			@_first = false
+			buffer << "\n"
+
+			row_buffer.clear
 		end
 
 		buffer
 	end
 
+	def around_row(item)
+		row_template(item)
+	end
+
 	def filename
 		nil
 	end
@@ -66,27 +125,20 @@ class Phlex::CSV
 		"text/csv"
 	end
 
+	def delimiter
+		","
+	end
+
 	private
 
 	def column(header = nil, value)
-		if @_first
-			@_headers << __escape__(header)
-		elsif header != @_headers[@_current_column_index]
-			raise "Inconsistent header."
-		end
-
-		@_current_row << __escape__(value)
-		@_current_column_index += 1
+		@_row_buffer << [header, value]
 	end
 
 	def each_item(&)
 		collection.each(&)
 	end
 
-	def yielder(record)
-		yield(record)
-	end
-
 	# Override and set to `false` to disable rendering headers.
 	def render_headers?
 		true
@@ -99,22 +151,101 @@ class Phlex::CSV
 
 	# Override and set to `false` to disable CSV injection escapes or `true` to enable.
 	def escape_csv_injection?
-		nil
+		UNDEFINED
 	end
 
-	def __escape__(value)
-		value = trim_whitespace? ? value.to_s.strip : value.to_s
-		first_char = value[0]
-		last_char = value[-1]
-
-		if escape_csv_injection? && FORMULA_PREFIXES.include?(first_char)
-			# Prefix a single quote to prevent Excel, Google Docs, etc. from interpreting the value as a formula.
-			# See https://owasp.org/www-community/attacks/CSV_Injection
-			%("'#{value.gsub('"', '""')}")
-		elsif (!trim_whitespace? && (SPACE_CHARACTERS.include?(first_char) || SPACE_CHARACTERS.include?(last_char))) || value.include?('"') || value.include?(",") || value.include?("\n")
-			%("#{value.gsub('"', '""')}")
-		else
+	def __escape__(buffer, value, escape_csv_injection:, strip_whitespace:, escape_regex:)
+		value = case value
+		when String
 			value
+		when Symbol
+			value.name
+		else
+			value.to_s
+		end
+
+		if strip_whitespace
+			value = value.strip
+
+			if escape_csv_injection
+				if FORMULA_PREFIXES_MAP[value.getbyte(0)]
+					value.gsub!('"', '""')
+					buffer << '"\'' << value << '"'
+				elsif value.match?(escape_regex)
+					value.gsub!('"', '""')
+					buffer << '"' << value << '"'
+				else
+					buffer << value
+				end
+			else # not escaping CSV injection
+				buffer << value
+			end
+		else # not stripping whitespace
+			if escape_csv_injection
+				first_byte = value.getbyte(0)
+
+				if FORMULA_PREFIXES_MAP[first_byte]
+					buffer << '"\'' << value.gsub('"', '""') << '"'
+				elsif value.match?(escape_regex)
+					buffer << '"' << value.gsub('"', '""') << '"'
+				else
+					buffer << value
+				end
+			else # not escaping CSV injection
+				if value.match?(escape_regex)
+					buffer << '"' << value.gsub('"', '""') << '"'
+				else
+					buffer << value
+				end
+			end
+		end
+	end
+
+	# Handle legacy `view_template` method
+	def respond_to_missing?(method_name, include_private)
+		(method_name == :row_template && respond_to?(:view_template)) || super
+	end
+
+	# Handle legacy `view_template` method
+	def method_missing(method_name, ...)
+		if method_name == :row_template && respond_to?(:view_template)
+			warn "Deprecated: Use `row_template` instead of `view_template` in Phlex CSVs."
+			self.class.alias_method :row_template, :view_template
+			view_template(...)
+		else
+			super
+		end
+	end
+
+	def ensure_escape_csv_injection_configured!
+		if escape_csv_injection? == UNDEFINED
+			raise <<~MESSAGE
+				You need to define `escape_csv_injection?` in #{self.class.name}.
+
+				CSV injection is a security vulnerability where malicious spreadsheet
+				formulae are used to execute code or exfiltrate data when a CSV is opened
+				in a spreadsheet program such as Microsoft Excel or Google Sheets.
+
+				For more information, see https://owasp.org/www-community/attacks/CSV_Injection
+
+				If you’re sure this CSV will never be opened in a spreadsheet program,
+				you can *disable* CSV injection escapes:
+
+				  def escape_csv_injection? = false
+
+				This is useful when using CSVs for byte-for-byte data exchange between secure systems.
+
+				Alternatively, you can *enable* CSV injection escapes at the cost of data integrity:
+
+				  def escape_csv_injection? = true
+
+				Enabling the CSV injection escapes will prefix with a single quote `'` any
+				values that start with: `=`, `+`, `-`, `@`, `\\t`, `\\r`
+
+				Unfortunately, there is no one-size-fits-all solution to CSV injection.
+
+				You need to decide based on your specific use case.
+			MESSAGE
 		end
 	end
 end

data/lib/phlex/html.rb

@@ -58,7 +58,7 @@ class Phlex::HTML < Phlex::SGML
 			raise Phlex::ArgumentError.new("Expected the tag name to be a Symbol.")
 		end
 
-		if (tag = StandardElements.__registered_elements__[name]) || ((tag = name.name.tr("_", "-")).include?("-") && tag.match?(/\A[a-z0-9-]+\z/))
+		if (tag = StandardElements.__registered_elements__[name]) || (tag = name.name.tr("_", "-")).include?("-")
 			if attributes.length > 0 # with attributes
 				if block_given # with content block
 					buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << ">"

data/lib/phlex/kit.rb

@@ -15,11 +15,7 @@ module Phlex::Kit
 		def respond_to_missing?(name, include_private = false)
 			mod = self.class
 
-			if name[0] == name[0].upcase && mod.constants.include?(name) && mod.const_get(name) && methods.include?(name)
-				true
-			else
-				super
-			end
+			(name[0] == name[0].upcase && mod.constants.include?(name) && mod.const_get(name) && methods.include?(name)) || super
 		end
 	end
 
@@ -45,11 +41,7 @@ module Phlex::Kit
 	end
 
 	def respond_to_missing?(name, include_private = false)
-		if name[0] == name[0].upcase && constants.include?(name) && const_get(name) && methods.include?(name)
-			true
-		else
-			super
-		end
+		(name[0] == name[0].upcase && constants.include?(name) && const_get(name) && methods.include?(name)) || super
 	end
 
 	def const_added(name)

data/lib/phlex/sgml/elements.rb

@@ -21,55 +21,69 @@ module Phlex::SGML::Elements
 
 				if attributes.length > 0 # with attributes
 					if block_given # with content block
-						buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << ">"
-
-						original_length = buffer.bytesize
-						content = yield(self)
-						if original_length == buffer.bytesize
-							case content
-							when ::Phlex::SGML::SafeObject
-								buffer << content.to_s
-							when String
-								buffer << ::Phlex::Escape.html_escape(content)
-							when Symbol
-								buffer << ::Phlex::Escape.html_escape(content.name)
-							when nil
-								nil
-							else
-								if (formatted_object = format_object(content))
-									buffer << ::Phlex::Escape.html_escape(formatted_object)
+						buffer << "<#{tag}"
+						begin
+							buffer << (Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes))
+						ensure
+							buffer << ">"
+						end
+
+						begin
+							original_length = buffer.bytesize
+							content = yield(self)
+							if original_length == buffer.bytesize
+								case content
+								when ::Phlex::SGML::SafeObject
+									buffer << content.to_s
+								when String
+									buffer << ::Phlex::Escape.html_escape(content)
+								when Symbol
+									buffer << ::Phlex::Escape.html_escape(content.name)
+								when nil
+									nil
+								else
+									if (formatted_object = format_object(content))
+										buffer << ::Phlex::Escape.html_escape(formatted_object)
+									end
 								end
 							end
+						ensure
+							buffer << "</#{tag}>"
 						end
-
-						buffer << "</#{tag}>"
 					else # without content
-						buffer << "<#{tag}" << (::Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << "></#{tag}>"
+						buffer << "<#{tag}"
+						begin
+							buffer << (::Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes))
+						ensure
+							buffer << "></#{tag}>"
+						end
 					end
 				else # without attributes
 					if block_given # with content block
 						buffer << "<#{tag}>"
 
-						original_length = buffer.bytesize
-						content = yield(self)
-						if original_length == buffer.bytesize
-							case content
-							when ::Phlex::SGML::SafeObject
-								buffer << content.to_s
-							when String
-								buffer << ::Phlex::Escape.html_escape(content)
-							when Symbol
-								buffer << ::Phlex::Escape.html_escape(content.name)
-							when nil
-								nil
-							else
-								if (formatted_object = format_object(content))
-									buffer << ::Phlex::Escape.html_escape(formatted_object)
+						begin
+							original_length = buffer.bytesize
+							content = yield(self)
+							if original_length == buffer.bytesize
+								case content
+								when ::Phlex::SGML::SafeObject
+									buffer << content.to_s
+								when String
+									buffer << ::Phlex::Escape.html_escape(content)
+								when Symbol
+									buffer << ::Phlex::Escape.html_escape(content.name)
+								when nil
+									nil
+								else
+									if (formatted_object = format_object(content))
+										buffer << ::Phlex::Escape.html_escape(formatted_object)
+									end
 								end
 							end
+						ensure
+							buffer << "</#{tag}>"
 						end
-
-						buffer << "</#{tag}>"
 					else # without content
 						buffer << "<#{tag}></#{tag}>"
 					end
@@ -95,10 +109,17 @@ module Phlex::SGML::Elements
 
 				return unless state.should_render?
 
+				buffer = state.buffer
+
 				if attributes.length > 0 # with attributes
-					state.buffer << "<#{tag}" << (::Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << ">"
+					buffer << "<#{tag}"
+					begin
+						buffer << (::Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes))
+					ensure
+						buffer << ">"
+					end
 				else # without attributes
-					state.buffer << "<#{tag}>"
+					buffer << "<#{tag}>"
 				end
 
 				nil

data/lib/phlex/sgml/state.rb

@@ -12,10 +12,19 @@ class Phlex::SGML::State
 		@output_buffer = output_buffer
 	end
 
-	attr_accessor :buffer, :capturing, :user_context
+	attr_accessor :capturing, :user_context
 
 	attr_reader :fragments, :fragment_depth, :output_buffer
 
+	def buffer
+		case @buffer
+		when Proc
+			@buffer.call
+		else
+			@buffer
+		end
+	end
+
 	def around_render(component)
 		stack = @stack
 

data/lib/phlex/sgml.rb

@@ -3,13 +3,7 @@
 # **Standard Generalized Markup Language** for behaviour common to {HTML} and {SVG}.
 class Phlex::SGML
 	UNSAFE_ATTRIBUTES = Set.new(%w[srcdoc sandbox http-equiv]).freeze
-	REF_ATTRIBUTES = Set.new(%w[href src action formaction lowsrc dynsrc background ping xlinkhref]).freeze
-	NAMED_CHARACTER_REFERENCES = {
-		"colon" => ":",
-		"tab" => "\t",
-		"newline" => "\n",
-	}.freeze
-	UNSAFE_ATTRIBUTE_NAME_CHARS = %r([<>&"'/=\s\x00])
+	REF_ATTRIBUTES = Set.new(%w[href src action formaction lowsrc dynsrc background ping]).freeze
 
 	autoload :Elements, "phlex/sgml/elements"
 	autoload :SafeObject, "phlex/sgml/safe_object"
@@ -294,6 +288,10 @@ class Phlex::SGML
 		end
 	end
 
+	def json_escape(string)
+		ERB::Util.json_escape(string)
+	end
+
 	private
 
 	# Override this method to use a different deployment key.
@@ -483,9 +481,7 @@ class Phlex::SGML
 				if value != true && REF_ATTRIBUTES.include?(normalized_name)
 					case value
 					when String
-						decoded_value = decode_html_character_references(value)
-
-						if decoded_value.downcase.delete("^a-z:").start_with?("javascript:")
+						if value.downcase.delete("^a-z:").start_with?("javascript:")
 							# We just ignore these because they were likely not specified by the developer.
 							next
 						end
@@ -503,7 +499,7 @@ class Phlex::SGML
 				end
 			end
 
-			if name.match?(UNSAFE_ATTRIBUTE_NAME_CHARS)
+			if name.match?(/[<>&"']/)
 				raise Phlex::ArgumentError.new("Unsafe attribute name detected: #{k}.")
 			end
 
@@ -534,7 +530,7 @@ class Phlex::SGML
 				else raise Phlex::ArgumentError.new("Attribute keys should be Strings or Symbols")
 			end
 
-			if name.match?(UNSAFE_ATTRIBUTE_NAME_CHARS)
+			if name.match?(/[<>&"']/)
 				raise Phlex::ArgumentError.new("Unsafe attribute name detected: #{k}.")
 			end
 
@@ -610,27 +606,6 @@ class Phlex::SGML
 		buffer.gsub('"', "&quot;")
 	end
 
-	private def decode_html_character_references(value)
-		value
-			.gsub(/&#x([0-9a-f]+);?/i) {
-				begin
-					[$1.to_i(16)].pack("U*")
-				rescue
-					""
-				end
-			}
-			.gsub(/&#(\d+);?/) {
-				begin
-					[$1.to_i].pack("U*")
-				rescue
-					""
-				end
-			}
-			.gsub(/&([a-z][a-z0-9]+);?/i) {
-				NAMED_CHARACTER_REFERENCES[$1.downcase] || ""
-			}
-	end
-
 	# Result is **unsafe**, so it should be escaped!
 	def __styles__(styles)
 		case styles

data/lib/phlex/svg.rb

@@ -15,6 +15,20 @@ class Phlex::SVG < Phlex::SGML
 		nil
 	end
 
+	def cdata(content = nil, &block)
+		state = @_state
+		return unless state.should_render?
+
+		if !block && String === content
+			state.buffer << "<![CDATA[" << content.gsub("]]>", "]]>]]<![CDATA[") << "]]>"
+		elsif block && nil == content
+			state.buffer << "<![CDATA[" << capture(&block).gsub("]]>", "]]>]]<![CDATA[") << "]]>"
+		else
+
+			raise Phlex::ArgumentError.new("Expected a String or block.")
+		end
+	end
+
 	def tag(name, **attributes, &)
 		state = @_state
 		block_given = block_given?
@@ -29,7 +43,7 @@ class Phlex::SVG < Phlex::SGML
 			raise Phlex::ArgumentError.new("Expected the tag name to be a Symbol.")
 		end
 
-		if (tag = StandardElements.__registered_elements__[name]) || ((tag = name.name.tr("_", "-")).include?("-") && tag.match?(/\A[a-z0-9-]+\z/))
+		if (tag = StandardElements.__registered_elements__[name]) || (tag = name.name.tr("_", "-")).include?("-")
 			if attributes.length > 0 # with attributes
 				if block_given # with content block
 					buffer << "<#{tag}" << (Phlex::ATTRIBUTE_CACHE[attributes] ||= __attributes__(attributes)) << ">"

data/lib/phlex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phlex
-	VERSION = "2.0.3"
+	VERSION = "2.1.0"
 end

data/lib/phlex.rb

@@ -4,6 +4,8 @@ require "erb"
 require "set"
 
 module Phlex
+	autoload :VERSION, "phlex/version"
+
 	autoload :Kit, "phlex/kit"
 	autoload :FIFO, "phlex/fifo"
 	autoload :Vanish, "phlex/vanish"

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: phlex
 version: !ruby/object:Gem::Version
-  version: 2.0.3
+  version: 2.1.0
 platform: ruby
 authors:
 - Joel Drapper
 - Will Cosgrove
 bindir: bin
 cert_chain: []
-date: 2026-02-06 00:00:00.000000000 Z
+date: 2025-03-05 00:00:00.000000000 Z
 dependencies: []
-description: Build HTML & SVG view components with Ruby classes.
+description: Build HTML, SVG and CSV views with Ruby classes.
 email:
 - joel@drapper.me
 executables: []
@@ -65,7 +65,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.6
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Object-oriented views in Ruby.
 test_files: []