phlex 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e84eae72307b1f6e6bf3337cd74d1208d3c2fb58f11e7c08eaf6dd0272fbc702
-  data.tar.gz: a2edd58bd5a1c5185bf9b4222cb0f674fcd488243b4a33c140c92577cd74cbb8
+  metadata.gz: b8db189359fc8003771075a598fbeed0c2205ca52604fd829d77afe3c0b3a467
+  data.tar.gz: e5446344e9a83c982fdfa94d4d31abd4b7511858704cc2e9f9d285ad9740b9c3
 SHA512:
-  metadata.gz: 22c542f19b5121666bca2f3bf661ff05488c21d5b593578f704dbe9f69643d48b839deddd9898214638a21dc7fb9de56dcb750f7401082710a13a5544668a643
-  data.tar.gz: a81c55fb957fa70907fac519b08c072521701908385227f93284219de34e0338a48276faff36ef54ba60d552511a579a734725fcbfea7b6d302edbaaf9e94c54
+  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/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

@@ -288,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.

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?

data/lib/phlex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phlex
-	VERSION = "2.0.2"
+	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.2
+  version: 2.1.0
 platform: ruby
 authors:
 - Joel Drapper
 - Will Cosgrove
 bindir: bin
 cert_chain: []
-date: 2025-02-16 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: []