Class: Phlex::SGML

Inherits:
Object
  • Object
show all
Includes:
Helpers
Defined in:
lib/phlex/sgml.rb

Overview

**Standard Generalized Markup Language** for behaviour common to HTML and SVG.

Direct Known Subclasses

HTML, SVG

Defined Under Namespace

Modules: Elements, SafeObject Classes: SafeValue, State

Constant Summary collapse

UNSAFE_ATTRIBUTES = 
Set.new(%w[srcdoc sandbox http-equiv]).freeze
REF_ATTRIBUTES = 
Set.new(%w[href src action formaction lowsrc dynsrc background ping]).freeze
ERBCompiler = 
ERB::Compiler.new("<>").tap do |compiler|
	compiler.pre_cmd    = [""]
	compiler.put_cmd    = "@_state.buffer.<<"
	compiler.insert_cmd = "__implicit_output__"
	compiler.post_cmd   = ["nil"]

	def compiler.add_insert_cmd(out, content)
		out.push("#{@insert_cmd}((#{content}))")
	end
end

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.call ⇒ Object

Render the view to a String. Arguments are delegated to new.



28
29
30
 
# File 'lib/phlex/sgml.rb', line 28

def call(...)
	new(...).call
end

.erb(method_name, erb = nil, locals: nil, &block) ⇒ Object 



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/phlex/sgml.rb', line 44

def erb(method_name, erb = nil, locals: nil, &block)
	loc = caller_locations(1, 1)[0]
	path = loc.path.delete_suffix(".rb")
	file = loc.path
	line = loc.lineno - 1

	unless erb
		method_path = "#{path}/#{method_name}.html.erb"
		sidecar_path = "#{path}.html.erb"

		if File.exist?(method_path)
			erb = File.read(method_path)
			file = method_path
			line = 1
		elsif method_name == :view_template && File.exist?(sidecar_path)
			erb = File.read(sidecar_path)
			file = sidecar_path
			line = 1
		else
			raise Phlex::RuntimeError.new(<<~MESSAGE)
				No ERB template found for #{method_name}
			MESSAGE
		end
	end

	code, _enc = ERBCompiler.compile(erb)

	class_eval(<<~RUBY, file, line)
		def #{method_name} #{locals}
			#{code}
		end
	RUBY
end

.new(*a, **k, &block) ⇒ Object

Note:

The block will not be delegated #initialize. Instead, it will be sent to #template when rendering.

Create a new instance of the component.



34
35
36
37
38
39
40
41
42
 
# File 'lib/phlex/sgml.rb', line 34

def new(*a, **k, &block)
	if block
		object = super(*a, **k, &nil)
		object.instance_exec { @_content_block = block }
		object
	else
		super
	end
end

Instance Method Details

#cache(*cache_key, &content) ⇒ Object

Cache a block of content.

“‘ruby end “`



288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/phlex/sgml.rb', line 288

def cache(*cache_key, **, &content)
	location = caller_locations(1, 1)[0]

	full_key = [
		app_version_key,                                    # invalidates the key when deploying new code in case of changes
		self.class.name,                                   # prevents collisions between classes
		(self.class.object_id if enable_cache_reloading?), # enables reloading
		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)

	nil
end

#call(buffer = +"",, context: {}, fragments: nil) ⇒ Object 



91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/phlex/sgml.rb', line 91

def call(buffer = +"", context: {}, fragments: nil, &)
	state = Phlex::SGML::State.new(
		user_context: context,
		output_buffer: buffer,
		fragments: fragments&.to_set,
	)

	internal_call(parent: nil, state:, &)

	state.output_buffer << state.buffer
end

#capture(*args, &block) ⇒ Object

Capture the output of the block and returns it as a string.



216
217
218
219
220
221
222
223
224
 
# File 'lib/phlex/sgml.rb', line 216

def capture(*args, &block)
	return "" unless block

	if args.length > 0
		@_state.capture { __yield_content_with_args__(*args, &block) }
	else
		@_state.capture { __yield_content__(&block) }
	end
end

#comment ⇒ Object

Wrap the output in an HTML comment.

[MDN Docs](developer.mozilla.org/en-US/docs/Web/HTML/Comments)



186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/phlex/sgml.rb', line 186

def comment(&)
	state = @_state
	return unless state.should_render?

	buffer = state.buffer

	buffer << "<!-- "
	__yield_content__(&)
	buffer << " -->"

	nil
end

#context ⇒ Object 



141
142
143
144
145
146
147
148
149
 
# File 'lib/phlex/sgml.rb', line 141

def context
	if rendering?
		@_state.user_context
	else
		raise Phlex::ArgumentError.new(<<~MESSAGE)
			You can’t access the context before the component has started rendering.
		MESSAGE
	end
end

#flush ⇒ Object

Flush the current state to the output buffer.



248
249
250
 
# File 'lib/phlex/sgml.rb', line 248

def flush
	@_state.flush
end

#fragment(name) ⇒ Object

Define a named fragment that can be selectively rendered.



227
228
229
230
231
232
233
 
# File 'lib/phlex/sgml.rb', line 227

def fragment(name)
	state = @_state
	state.begin_fragment(name)
	yield
	state.end_fragment(name)
	nil
end

#internal_call(parent: nil, state: nil, &block) ⇒ Object 



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/phlex/sgml.rb', line 103

def internal_call(parent: nil, state: nil, &block)
	if @_state
		raise Phlex::DoubleRenderError.new(
			"You can't render a #{self.class.name} more than once."
		)
	end

	@_state = state

	return "" unless render?

	block ||= @_content_block

	Thread.current[:__phlex_component__] = [self, Fiber.current.object_id].freeze

	state.around_render(self) do
		before_template(&block)

		around_template do
			if block
				view_template do |*args|
					if args.length > 0
						__yield_content_with_args__(*args, &block)
					else
						__yield_content__(&block)
					end
				end
			else
				view_template
			end
		end

		after_template(&block)
	end
ensure
	Thread.current[:__phlex_component__] = [parent, Fiber.current.object_id].freeze
end

#json_escape(string) ⇒ Object 



340
341
342
 
# File 'lib/phlex/sgml.rb', line 340

def json_escape(string)
	ERB::Util.json_escape(string)
end

#low_level_cache(cache_key, **options, &content) ⇒ Object

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.



317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
 
# File 'lib/phlex/sgml.rb', line 317

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

	nil
end

#plain(content) ⇒ Object

Output plain text.



158
159
160
161
162
163
164
 
# File 'lib/phlex/sgml.rb', line 158

def plain(content)
	unless __text__(content)
		raise Phlex::ArgumentError.new("You've passed an object to plain that is not handled by format_object. See https://rubydoc.info/gems/phlex/Phlex/SGML#format_object-instance_method for more information")
	end

	nil
end

#raw(content) ⇒ Object

Output the given safe object as-is. You may need to use ‘safe` to mark a string as a safe object.



200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/phlex/sgml.rb', line 200

def raw(content)
	case content
	when Phlex::SGML::SafeObject
		state = @_state
		return unless state.should_render?

		state.buffer << content.to_s
	when nil, "" # do nothing
	else
		raise Phlex::ArgumentError.new("You passed an unsafe object to `raw`.")
	end

	nil
end

#render(renderable = nil) ⇒ Object 



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/phlex/sgml.rb', line 252

def render(renderable = nil, &)
	case renderable
	when Phlex::SGML
		renderable.internal_call(state: @_state, parent: self, &)
	when Class
		if renderable < Phlex::SGML
			render(renderable.new, &)
		end
	when Enumerable
		renderable.each { |r| render(r, &) }
	when Proc, Method
		if renderable.arity == 0
			__yield_content_with_no_yield_args__(&renderable)
		else
			__yield_content__(&renderable)
		end
	when String
		plain(renderable)
	when nil
		__yield_content__(&) if block_given?
	else
		raise Phlex::ArgumentError.new("You can't render a #{renderable.inspect}.")
	end

	nil
end

#rendering? ⇒ Boolean

Returns ‘false` before rendering and `true` once the component has started rendering. It will not reset back to false after rendering.

Returns:

  • (Boolean) 


153
154
155
 
# File 'lib/phlex/sgml.rb', line 153

def rendering?
	!!@_state
end

#safe(value) ⇒ Object Also known as: 🦺

Mark the given string as safe for HTML output.



236
237
238
239
240
241
242
243
 
# File 'lib/phlex/sgml.rb', line 236

def safe(value)
	case value
	when String
		Phlex::SGML::SafeValue.new(value)
	else
		raise Phlex::ArgumentError.new("Expected a String.")
	end
end

#to_proc ⇒ Object 



87
88
89
 
# File 'lib/phlex/sgml.rb', line 87

def to_proc
	proc { |c| c.render(self) }
end

#view_template ⇒ Object 



79
80
81
82
83
84
85
 
# File 'lib/phlex/sgml.rb', line 79

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

#whitespace ⇒ Object

Output a single space character. If a block is given, a space will be output before and after the block.



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/phlex/sgml.rb', line 167

def whitespace(&)
	state = @_state
	return unless state.should_render?

	buffer = state.buffer

	buffer << " "

	if block_given?
		__yield_content__(&)
		buffer << " "
	end

	nil
end