phlex 2.0.0.rc1 → 2.0.0.rc2

data/lib/phlex/sgml.rb

@@ -8,6 +8,7 @@ class Phlex::SGML
 	autoload :Elements, "phlex/sgml/elements"
 	autoload :SafeObject, "phlex/sgml/safe_object"
 	autoload :SafeValue, "phlex/sgml/safe_value"
+	autoload :State, "phlex/sgml/state"
 
 	include Phlex::Helpers
 
@@ -28,25 +29,13 @@ class Phlex::SGML
 				super
 			end
 		end
-
-		def __element_method__?(method_name)
-			if instance_methods.include?(method_name)
-				owner = instance_method(method_name).owner
-
-				if Phlex::SGML::Elements === owner && owner.__registered_elements__[method_name]
-					true
-				else
-					false
-				end
-			else
-				false
-			end
-		end
 	end
 
 	def view_template
 		if block_given?
 			yield
+		else
+			plain "Phlex Warning: Your `#{self.class.name}` class doesn't define a `view_template` method. If you are upgrading to Phlex 2.x make sure to rename your `template` method to `view_template`. See: https://beta.phlex.fun/guides/v2-upgrade.html"
 		end
 	end
 
@@ -54,25 +43,35 @@ class Phlex::SGML
 		proc { |c| c.render(self) }
 	end
 
-	def call(buffer = +"", context: {}, view_context: nil, parent: nil, fragments: nil, &block)
-		@_buffer = buffer
-		@_context = phlex_context = parent&.__context__ || Phlex::Context.new(user_context: context, view_context:)
-		@_parent = parent
+	def call(buffer = +"", context: {}, view_context: nil, fragments: nil, &)
+		state = Phlex::SGML::State.new(
+			user_context: context,
+			view_context:,
+			output_buffer: buffer,
+			fragments: fragments&.to_set,
+		)
+
+		internal_call(parent: nil, state:, &)
+
+		state.output_buffer << state.buffer
+	end
 
-		raise Phlex::DoubleRenderError.new("You can't render a #{self.class.name} more than once.") if @_rendered
-		@_rendered = true
+	def internal_call(parent: nil, state: nil, &block)
+		return "" unless render?
 
-		if fragments
-			phlex_context.target_fragments(fragments)
+		if @_state
+			raise Phlex::DoubleRenderError.new(
+				"You can't render a #{self.class.name} more than once."
+			)
 		end
 
-		block ||= @_content_block
+		@_state = state
 
-		return "" unless render?
+		block ||= @_content_block
 
-		Thread.current[:__phlex_component__] = [self, Fiber.current.object_id]
+		Thread.current[:__phlex_component__] = [self, Fiber.current.object_id].freeze
 
-		phlex_context.around_render do
+		state.around_render(self) do
 			before_template(&block)
 
 			around_template do
@@ -91,18 +90,12 @@ class Phlex::SGML
 
 			after_template(&block)
 		end
-
-		unless parent
-			buffer << phlex_context.buffer
-		end
 	ensure
-		Thread.current[:__phlex_component__] = [parent, Fiber.current.object_id]
+		Thread.current[:__phlex_component__] = [parent, Fiber.current.object_id].freeze
 	end
 
-	protected def __context__ = @_context
-
 	def context
-		@_context.user_context
+		@_state.user_context
 	end
 
 	# Output plain text.
@@ -116,10 +109,10 @@ class Phlex::SGML
 
 	# Output a single space character. If a block is given, a space will be output before and after the block.
 	def whitespace(&)
-		context = @_context
-		return if context.fragments && !context.in_target_fragment
+		state = @_state
+		return unless state.should_render?
 
-		buffer = context.buffer
+		buffer = state.buffer
 
 		buffer << " "
 
@@ -135,10 +128,10 @@ class Phlex::SGML
 	#
 	# [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Comments)
 	def comment(&)
-		context = @_context
-		return if context.fragments && !context.in_target_fragment
+		state = @_state
+		return unless state.should_render?
 
-		buffer = context.buffer
+		buffer = state.buffer
 
 		buffer << "<!-- "
 		__yield_content__(&)
@@ -151,10 +144,10 @@ class Phlex::SGML
 	def raw(content)
 		case content
 		when Phlex::SGML::SafeObject
-			context = @_context
-			return if context.fragments && !context.in_target_fragment
+			state = @_state
+			return unless state.should_render?
 
-			context.buffer << content.to_s
+			state.buffer << content.to_s
 		when nil, "" # do nothing
 		else
 			raise Phlex::ArgumentError.new("You passed an unsafe object to `raw`.")
@@ -168,12 +161,21 @@ class Phlex::SGML
 		return "" unless block
 
 		if args.length > 0
-			@_context.capturing_into(+"") { __yield_content_with_args__(*args, &block) }
+			@_state.capturing_into(+"") { __yield_content_with_args__(*args, &block) }
 		else
-			@_context.capturing_into(+"") { __yield_content__(&block) }
+			@_state.capturing_into(+"") { __yield_content__(&block) }
 		end
 	end
 
+	# Define a named fragment that can be selectively rendered.
+	def fragment(name)
+		state = @_state
+		state.begin_fragment(name)
+		yield
+		state.end_fragment(name)
+		nil
+	end
+
 	# Mark the given string as safe for HTML output.
 	def safe(value)
 		case value
@@ -187,20 +189,18 @@ class Phlex::SGML
 	alias_method :🦺, :safe
 
 	def flush
-		return if @_context.capturing
-
-		buffer = @_context.buffer
-		@_buffer << buffer.dup
-		buffer.clear
+		@_state.flush
 	end
 
 	def render(renderable = nil, &)
 		case renderable
 		when Phlex::SGML
-			renderable.call(@_buffer, parent: self, &)
+			Thread.current[:__phlex_component__] = [renderable, Fiber.current.object_id].freeze
+			renderable.internal_call(state: @_state, parent: self, &)
+			Thread.current[:__phlex_component__] = [self, Fiber.current.object_id].freeze
 		when Class
 			if renderable < Phlex::SGML
-				renderable.new.call(@_buffer, parent: self, &)
+				render(renderable.new, &)
 			end
 		when Enumerable
 			renderable.each { |r| render(r, &) }
@@ -221,15 +221,78 @@ class Phlex::SGML
 		nil
 	end
 
+	# Cache a block of content.
+	#
+	# ```ruby
+	# @products.each do |product|
+	#   cache product do
+	#     h1 { product.name }
+	#   end
+	# end
+	# ```
+	def cache(*cache_key, **, &content)
+		location = caller_locations(1, 1)[0]
+
+		full_key = [
+			Phlex::DEPLOY_KEY,   # invalidates the key when deploying new code in case of changes
+			self.class.name,     # prevents collisions between classes
+			location.base_label, # prevents collisions between different methods
+			location.lineno,     # prevents collisions between different lines
+			cache_key,           # allows for custom cache keys
+		].freeze
+
+		low_level_cache(full_key, **, &content)
+	end
+
+	# Cache a block of content where you control the entire cache key.
+	# If you really know what you’re doing and want to take full control
+	# and responsibility for the cache key, use this method.
+	#
+	# ```ruby
+	# low_level_cache([Commonmarker::VERSION, Digest::MD5.hexdigest(@content)]) do
+	#   markdown(@content)
+	# end
+	# ```
+	#
+	# Note: To allow you more control, this method does not take a splat of cache keys.
+	# If you need to pass multiple cache keys, you should pass an array.
+	def low_level_cache(cache_key, **options, &content)
+		state = @_state
+
+		cached_buffer, fragment_map = cache_store.fetch(cache_key, **options) { state.caching(&content) }
+
+		if state.should_render?
+			fragment_map.each do |fragment_name, (offset, length, nested_fragments)|
+				state.record_fragment(fragment_name, offset, length, nested_fragments)
+			end
+			state.buffer << cached_buffer
+		else
+			fragment_map.each do |fragment_name, (offset, length, nested_fragments)|
+				if state.fragments.include?(fragment_name)
+					state.fragments.delete(fragment_name)
+					state.fragments.subtract(nested_fragments)
+					state.buffer << cached_buffer.byteslice(offset, length)
+				end
+			end
+		end
+	end
+
+	# Points to the cache store used by this component.
+	# By default, it points to `Phlex::NullCacheStore`, which does no caching.
+	# Override this method to use a different cache store.
+	def cache_store
+		Phlex::NullCacheStore
+	end
+
 	private
 
 	def vanish(*args)
 		return unless block_given?
 
 		if args.length > 0
-			@_context.capturing_into(Phlex::Vanish) { yield(*args) }
+			@_state.capturing_into(Phlex::Vanish) { yield(*args) }
 		else
-			@_context.capturing_into(Phlex::Vanish) { yield(self) }
+			@_state.capturing_into(Phlex::Vanish) { yield(self) }
 		end
 
 		nil
@@ -262,7 +325,7 @@ class Phlex::SGML
 	def __yield_content__
 		return unless block_given?
 
-		buffer = @_context.buffer
+		buffer = @_state.buffer
 
 		original_length = buffer.bytesize
 		content = yield(self)
@@ -274,7 +337,7 @@ class Phlex::SGML
 	def __yield_content_with_no_args__
 		return unless block_given?
 
-		buffer = @_context.buffer
+		buffer = @_state.buffer
 
 		original_length = buffer.bytesize
 		content = yield
@@ -286,7 +349,7 @@ class Phlex::SGML
 	def __yield_content_with_args__(*a)
 		return unless block_given?
 
-		buffer = @_context.buffer
+		buffer = @_state.buffer
 
 		original_length = buffer.bytesize
 		content = yield(*a)
@@ -296,21 +359,21 @@ class Phlex::SGML
 	end
 
 	def __implicit_output__(content)
-		context = @_context
-		return true if context.fragments && !context.in_target_fragment
+		state = @_state
+		return true unless state.should_render?
 
 		case content
 		when Phlex::SGML::SafeObject
-			context.buffer << content.to_s
+			state.buffer << content.to_s
 		when String
-			context.buffer << Phlex::Escape.html_escape(content)
+			state.buffer << Phlex::Escape.html_escape(content)
 		when Symbol
-			context.buffer << Phlex::Escape.html_escape(content.name)
+			state.buffer << Phlex::Escape.html_escape(content.name)
 		when nil
 			nil
 		else
 			if (formatted_object = format_object(content))
-				context.buffer << Phlex::Escape.html_escape(formatted_object)
+				state.buffer << Phlex::Escape.html_escape(formatted_object)
 			else
 				return false
 			end
@@ -321,19 +384,19 @@ class Phlex::SGML
 
 	# same as __implicit_output__ but escapes even `safe` objects
 	def __text__(content)
-		context = @_context
-		return true if context.fragments && !context.in_target_fragment
+		state = @_state
+		return true unless state.should_render?
 
 		case content
 		when String
-			context.buffer << Phlex::Escape.html_escape(content)
+			state.buffer << Phlex::Escape.html_escape(content)
 		when Symbol
-			context.buffer << Phlex::Escape.html_escape(content.name)
+			state.buffer << Phlex::Escape.html_escape(content.name)
 		when nil
 			nil
 		else
 			if (formatted_object = format_object(content))
-				context.buffer << Phlex::Escape.html_escape(formatted_object)
+				state.buffer << Phlex::Escape.html_escape(formatted_object)
 			else
 				return false
 			end