RubyGems - phlex - Versions diffs - 1.3.2 → 1.5.1 - Mend

phlex 1.3.2 → 1.5.1

Potentially problematic release.

This version of phlex might be problematic. Click here for more details.

Files changed (23) hide show

checksums.yaml +4 -4
data/.rubocop.yml +2 -24
data/Gemfile +0 -2
data/README.md +12 -0
data/fixtures/view_helper.rb +6 -0
data/lib/phlex/black_hole.rb +15 -9
data/lib/phlex/callable.rb +3 -5
data/lib/phlex/deferred_render.rb +2 -4
data/lib/phlex/element_clobbering_guard.rb +13 -0
data/lib/phlex/elements.rb +64 -54
data/lib/phlex/helpers.rb +9 -2
data/lib/phlex/html/standard_elements.rb +0 -14
data/lib/phlex/html.rb +19 -297
data/lib/{overrides → phlex/overrides}/symbol/name.rb +1 -1
data/lib/phlex/sgml.rb +313 -0
data/lib/phlex/svg/standard_elements.rb +389 -0
data/lib/phlex/svg.rb +14 -0
data/lib/phlex/testing/view_helper.rb +10 -12
data/lib/phlex/unbuffered.rb +34 -36
data/lib/phlex/version.rb +1 -1
data/lib/phlex.rb +5 -1
metadata +21 -4
data/lib/phlex/buffered.rb +0 -19

data/lib/phlex/html.rb CHANGED Viewed

@@ -1,47 +1,14 @@
 # frozen_string_literal: true
-if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.0")
-	using Overrides::Symbol::Name
-end
 module Phlex
-	class HTML
-		DOCTYPE = "<!DOCTYPE html>"
-		STANDARD_ELEMENTS = Concurrent::Map.new
-		VOID_ELEMENTS = Concurrent::Map.new
+	class HTML < SGML
+		# A list of HTML attributes that have the potential to execute unsafe JavaScript.
 		EVENT_ATTRIBUTES = %w[onabort onafterprint onbeforeprint onbeforeunload onblur oncanplay oncanplaythrough onchange onclick oncontextmenu oncopy oncuechange oncut ondblclick ondrag ondragend ondragenter ondragleave ondragover ondragstart ondrop ondurationchange onemptied onended onerror onfocus onhashchange oninput oninvalid onkeydown onkeypress onkeyup onload onloadeddata onloadedmetadata onloadstart onmessage onmousedown onmousemove onmouseout onmouseover onmouseup onmousewheel onoffline ononline onpagehide onpageshow onpaste onpause onplay onplaying onpopstate onprogress onratechange onreset onresize onscroll onsearch onseeked onseeking onselect onstalled onstorage onsubmit onsuspend ontimeupdate ontoggle onunload onvolumechange onwaiting onwheel].to_h { [_1, true] }.freeze
 		UNBUFFERED_MUTEX = Mutex.new
-		extend Elements
-		include Helpers
-		include VoidElements
-		include StandardElements
 		class << self
-			def call(...)
-				new(...).call
-			end
-			alias_method :render, :call
-			def new(*args, **kwargs, &block)
-				if block
-					object = super(*args, **kwargs, &nil)
-					object.instance_variable_set(:@_content_block, block)
-					object
-				else
-					super
-				end
-			end
-			def rendered_at_least_once!
-				alias_method :__attributes__, :__final_attributes__
-				alias_method :call, :__final_call__
-			end
+			# @api private
 			def __unbuffered_class__
 				UNBUFFERED_MUTEX.synchronize do
 					if defined? @unbuffered_class
@@ -53,280 +20,35 @@ module Phlex
 			end
 		end
-		def call(...)
-			__final_call__(...).tap do
-				self.class.rendered_at_least_once!
-			end
-		end
-		def __final_call__(buffer = +"", view_context: nil, parent: nil, &block)
-			@_target = buffer
-			@_view_context = view_context
-			@_parent = parent
-			block ||= @_content_block
-			return buffer unless render?
-			around_template do
-				if block
-					if DeferredRender === self
-						__vanish__(self, &block)
-						template
-					else
-						template do |*args|
-							if args.length > 0
-								yield_content_with_args(*args, &block)
-							else
-								yield_content(&block)
-							end
-						end
-					end
-				else
-					template
-				end
-			end
-			buffer
-		end
-		def render(renderable, &block)
-			case renderable
-			when Phlex::HTML
-				renderable.call(@_target, view_context: @_view_context, parent: self, &block)
-			when Class
-				if renderable < Phlex::HTML
-					renderable.new.call(@_target, view_context: @_view_context, parent: self, &block)
-				end
-			else
-				raise ArgumentError, "You can't render a #{renderable}."
-			end
+		extend Elements
+		include Helpers, VoidElements, StandardElements
+		# Output an HTML doctype.
+		def doctype
+			@_target << "<!DOCTYPE html>"
 			nil
 		end
-		def format
-			:html
+		# @deprecated use {#plain} instead.
+		def text(...)
+			warn "DEPRECATED: The `text` method has been deprecated in favour of `plain`. Please use `plain` instead. The `text` method will be removed in a future version of Phlex. Called from: #{caller.first}"
+			plain(...)
 		end
-		def text(content)
-			@_target << ERB::Util.html_escape(
-				case content
-					when String then content
-					when Symbol then content.name
-					when Integer then content.to_s
-					else format_object(content) || content.to_s
+		def svg(...)
+			super do
+				render Phlex::SVG.new do |svg|
+					yield(svg)
 				end
-			)
-			nil
-		end
-		def whitespace
-			@_target << " "
-			if block_given?
-				yield
-				@_target << " "
 			end
-			nil
-		end
-		def comment(&block)
-			@_target << "<!-- "
-			yield_content(&block)
-			@_target << " -->"
-			nil
-		end
-		def doctype
-			@_target << DOCTYPE
-			nil
-		end
-		def unsafe_raw(content = nil)
-			return nil unless content
-			@_target << content
-		end
-		def capture(&block)
-			return unless block_given?
-			original_buffer = @_target
-			new_buffer = +""
-			@_target = new_buffer
-			yield_content(&block)
-			new_buffer
-		ensure
-			@_target = original_buffer
 		end
+		# @api private
 		def unbuffered
 			self.class.__unbuffered_class__.new(self)
 		end
-		# Like `capture` but the output is vanished into a BlackHole buffer.
-		# Becuase the BlackHole does nothing with the output, this should be faster.
-		private def __vanish__(*args)
-			return unless block_given?
-			original_buffer = @_target
-			@_target = BlackHole
-			yield(*args)
-			nil
-		ensure
-			@_target = original_buffer
-		end
-		# Default render predicate can be overridden to prevent rendering
-		private def render?
-			true
-		end
-		private def format_object(object)
-			case object
-			when Float
-				object.to_s
-			end
-		end
-		private def around_template
-			before_template
-			yield
-			after_template
-		end
-		private def before_template
-			nil
-		end
-		private def after_template
-			nil
-		end
-		private def yield_content
-			return unless block_given?
-			original_length = @_target.length
-			content = yield(self)
-			unchanged = (original_length == @_target.length)
-			if unchanged
-				case content
-				when String
-					@_target << ERB::Util.html_escape(content)
-				when Symbol
-					@_target << ERB::Util.html_escape(content.name)
-				when Integer
-					@_target << ERB::Util.html_escape(content.to_s)
-				else
-					if (formatted_object = format_object(content))
-						@_target << ERB::Util.html_escape(formatted_object)
-					end
-				end
-			end
-			nil
-		end
-		private def yield_content_with_args(*args)
-			return unless block_given?
-			original_length = @_target.length
-			content = yield(*args)
-			unchanged = (original_length == @_target.length)
-			if unchanged
-				case content
-				when String
-					@_target << ERB::Util.html_escape(content)
-				when Symbol
-					@_target << ERB::Util.html_escape(content.name)
-				when Integer, Float
-					@_target << ERB::Util.html_escape(content.to_s)
-				else
-					if (formatted_object = format_object(content))
-						@_target << ERB::Util.html_escape(formatted_object)
-					end
-				end
-			end
-			nil
-		end
-		private def __attributes__(**attributes)
-			__final_attributes__(**attributes).tap do |buffer|
-				Phlex::ATTRIBUTE_CACHE[attributes.hash] = buffer.freeze
-			end
-		end
-		private def __final_attributes__(**attributes)
-			if attributes[:href]&.start_with?(/\s*javascript:/)
-				attributes.delete(:href)
-			end
-			if attributes["href"]&.start_with?(/\s*javascript:/)
-				attributes.delete("href")
-			end
-			buffer = +""
-			__build_attributes__(attributes, buffer: buffer)
-			buffer
-		end
-		private def __build_attributes__(attributes, buffer:)
-			attributes.each do |k, v|
-				next unless v
-				name = case k
-					when String then k
-					when Symbol then k.name.tr("_", "-")
-					else k.to_s
-				end
-				# Detect unsafe attribute names. Attribute names are considered unsafe if they match an event attribute or include unsafe characters.
-				if HTML::EVENT_ATTRIBUTES[name] || name.match?(/[<>&"']/)
-					raise ArgumentError, "Unsafe attribute name detected: #{k}."
-				end
-				case v
-				when true
-					buffer << " " << name
-				when String
-					buffer << " " << name << '="' << ERB::Util.html_escape(v) << '"'
-				when Symbol
-					buffer << " " << name << '="' << ERB::Util.html_escape(v.name) << '"'
-				when Hash
-					__build_attributes__(
-						v.transform_keys { |subkey|
-							case subkey
-								when Symbol then"#{k}-#{subkey.name.tr('_', '-')}"
-								else "#{k}-#{subkey}"
-							end
-						}, buffer: buffer
-					)
-				else
-					buffer << " " << name << '="' << ERB::Util.html_escape(v.to_s) << '"'
-				end
-			end
-			buffer
-		end
-		# This should be the last method defined
-		def self.method_added(method_name)
-			if method_name[0] == "_" && Phlex::HTML.instance_methods.include?(method_name) && instance_method(method_name).owner != Phlex::HTML
-				raise NameError, "👋 Redefining the method `#{name}##{method_name}` is not a good idea."
-			end
-			super
-		end
+		# This should be extended after all method definitions
+		extend ElementClobberingGuard
 	end
 end

data/lib/{overrides → phlex/overrides}/symbol/name.rb RENAMED Viewed

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-module Overrides::Symbol::Name
+module Phlex::Overrides::Symbol::Name
 	refine(Symbol) { alias_method :name, :to_s }
 end

data/lib/phlex/sgml.rb ADDED Viewed

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.0")
+	using Phlex::Overrides::Symbol::Name
+end
+module Phlex
+	class SGML
+		class << self
+			# Render the view to a String. Arguments are delegated to <code>new</code>.
+			def call(...)
+				new(...).call
+			end
+			alias_method :render, :call
+			# Create a new instance of the component.
+			# @note The block will not be delegated to the initializer. Instead, it will be provided to `template` when rendering.
+			def new(*args, **kwargs, &block)
+				if block
+					object = super(*args, **kwargs, &nil)
+					object.instance_variable_set(:@_content_block, block)
+					object
+				else
+					super
+				end
+			end
+			# @api private
+			def rendered_at_least_once!
+				alias_method :__attributes__, :__final_attributes__
+				alias_method :call, :__final_call__
+			end
+		end
+		# Renders the view and returns the buffer. The default buffer is a mutable String.
+		def call(buffer = nil, target: +"", view_context: nil, parent: nil, &block)
+			__final_call__(buffer, target: target, view_context: view_context, parent: parent, &block).tap do
+				self.class.rendered_at_least_once!
+			end
+		end
+		# @api private
+		def __final_call__(buffer = nil, target: +"", view_context: nil, parent: nil, &block)
+			@_target = target
+			@_view_context = view_context
+			@_parent = parent
+			block ||= @_content_block
+			return buffer || target unless render?
+			around_template do
+				if block
+					if DeferredRender === self
+						__vanish__(self, &block)
+						template
+					else
+						template do |*args|
+							if args.length > 0
+								yield_content_with_args(*args, &block)
+							else
+								yield_content(&block)
+							end
+						end
+					end
+				else
+					template
+				end
+			end
+			buffer ? (buffer << target) : target
+		end
+		# Render another view
+		# @param renderable [Phlex::SGML]
+		# @return [nil]
+		def render(renderable, &block)
+			case renderable
+			when Phlex::SGML
+				renderable.call(target: @_target, view_context: @_view_context, parent: self, &block)
+			when Class
+				if renderable < Phlex::SGML
+					renderable.new.call(target: @_target, view_context: @_view_context, parent: self, &block)
+				end
+			else
+				raise ArgumentError, "You can't render a #{renderable}."
+			end
+			nil
+		end
+		# Output text content. The text will be HTML-escaped.
+		# @return [nil]
+		def plain(content)
+			case content
+			when String
+				@_target << ERB::Escape.html_escape(content)
+			when Symbol
+				@_target << ERB::Escape.html_escape(content.name)
+			when Integer
+				@_target << ERB::Escape.html_escape(content.to_s)
+			when nil
+				nil
+			else
+				if (formatted_object = format_object(content))
+					@_target << ERB::Escape.html_escape(formatted_object)
+				end
+			end
+			nil
+		end
+		# Output a whitespace character. This is useful for getting inline elements to wrap. If you pass a block, a whitespace will be output before and after yielding the block.
+		# @return [nil]
+		def whitespace
+			@_target << " "
+			if block_given?
+				yield
+				@_target << " "
+			end
+			nil
+		end
+		# Output an HTML comment.
+		# @return [nil]
+		def comment(&block)
+			@_target << "<!-- "
+			yield_content(&block)
+			@_target << " -->"
+			nil
+		end
+		# This method is very dangerous and should usually be avoided. It will output the given String without any HTML safety. You should never use this method to output unsafe user input.
+		# @param content [String|nil]
+		# @return [nil]
+		def unsafe_raw(content = nil)
+			return nil unless content
+			@_target << content
+			nil
+		end
+		# Capture a block of output as a String.
+		# @return [String]
+		def capture(&block)
+			return "" unless block_given?
+			original_buffer_content = @_target.dup
+			@_target.clear
+			begin
+				yield_content(&block)
+				new_buffer_content = @_target.dup
+			ensure
+				@_target.clear
+				@_target << original_buffer_content
+			end
+			new_buffer_content.is_a?(String) ? new_buffer_content : ""
+		end
+		# Like `capture` but the output is vanished into a BlackHole buffer.
+		# Because the BlackHole does nothing with the output, this should be faster.
+		# @return [nil]
+		private def __vanish__(*args)
+			return unless block_given?
+			original_buffer = @_target
+			begin
+				@_target = BlackHole
+				yield(*args)
+			ensure
+				@_target = original_buffer
+			end
+			nil
+		end
+		# Default render predicate can be overridden to prevent rendering
+		# @return [bool]
+		private def render?
+			true
+		end
+		# Format the object for output
+		# @return [String]
+		private def format_object(object)
+			case object
+			when Float
+				object.to_s
+			end
+		end
+		# Override this method to hook in around a template render. You can do things before and after calling <code>super</code> to render the template. You should always call <code>super</code> so that callbacks can be added at different layers of the inheritance tree.
+		# @return [nil]
+		private def around_template
+			before_template
+			yield
+			after_template
+			nil
+		end
+		# Override this method to hook in right before a template is rendered. Please remember to call <code>super</code> so that callbacks can be added at different layers of the inheritance tree.
+		# @return [nil]
+		private def before_template
+			nil
+		end
+		# Override this method to hook in right after a template is rendered. Please remember to call <code>super</code> so that callbacks can be added at different layers of the inheritance tree.
+		# @return [nil]
+		private def after_template
+			nil
+		end
+		# Yields the block and checks if it buffered anything. If nothing was buffered, the return value is treated as text.
+		# @return [nil]
+		private def yield_content
+			return unless block_given?
+			original_length = @_target.length
+			content = yield(self)
+			plain(content) if original_length == @_target.length
+			nil
+		end
+		# Same as <code>yield_content</code> but accepts a splat of arguments to yield. This is slightly slower than <code>yield_content</code>, which is why it's defined as a different method because we don't always need arguments so we can usually use <code>yield_content</code> instead.
+		# @return [nil]
+		private def yield_content_with_args(*args)
+			return unless block_given?
+			original_length = @_target.length
+			content = yield(*args)
+			plain(content) if original_length == @_target.length
+			nil
+		end
+		# @api private
+		private def __attributes__(**attributes)
+			__final_attributes__(**attributes).tap do |buffer|
+				Phlex::ATTRIBUTE_CACHE[respond_to?(:process_attributes) ? (attributes.hash + self.class.hash) : attributes.hash] = buffer.freeze
+			end
+		end
+		# @api private
+		private def __final_attributes__(**attributes)
+			if respond_to?(:process_attributes)
+				attributes = process_attributes(**attributes)
+			end
+			if attributes[:href]&.start_with?(/\s*javascript:/)
+				attributes.delete(:href)
+			end
+			if attributes["href"]&.start_with?(/\s*javascript:/)
+				attributes.delete("href")
+			end
+			buffer = +""
+			__build_attributes__(attributes, buffer: buffer)
+			buffer
+		end
+		# @api private
+		private def __build_attributes__(attributes, buffer:)
+			attributes.each do |k, v|
+				next unless v
+				name = case k
+					when String then k
+					when Symbol then k.name.tr("_", "-")
+					else k.to_s
+				end
+				# Detect unsafe attribute names. Attribute names are considered unsafe if they match an event attribute or include unsafe characters.
+				if HTML::EVENT_ATTRIBUTES[name] || name.match?(/[<>&"']/)
+					raise ArgumentError, "Unsafe attribute name detected: #{k}."
+				end
+				case v
+				when true
+					buffer << " " << name
+				when String
+					buffer << " " << name << '="' << ERB::Escape.html_escape(v) << '"'
+				when Symbol
+					buffer << " " << name << '="' << ERB::Escape.html_escape(v.name) << '"'
+				when Hash
+					__build_attributes__(
+						v.transform_keys { |subkey|
+							case subkey
+								when Symbol then"#{k}-#{subkey.name.tr('_', '-')}"
+								else "#{k}-#{subkey}"
+							end
+						}, buffer: buffer
+					)
+				else
+					buffer << " " << name << '="' << ERB::Escape.html_escape(v.to_s) << '"'
+				end
+			end
+			buffer
+		end
+	end
+end