slamdown 0.5.0

data/lib/slamdown/conversion/rendering/html.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Slamdown
+module Conversion
+module Rendering
+
+# Reconstructs canonical HTML islands solely from normalised nodes and post-policy attributes.
+class Html
+	SEMANTIC_TAGS = {
+		:paragraph => "p",
+		:blockquote => "blockquote",
+		:ordered_list => "ol",
+		:unordered_list => "ul",
+		:list_item => "li",
+		:definition_list => "dl",
+		:definition_term => "dt",
+		:definition_description => "dd",
+		:horizontal_rule => "hr",
+		:line_break => "br",
+		:code_span => "code",
+		:code_block => "pre",
+		:link => "a",
+		:image => "img",
+		:emphasis => "em",
+		:strong => "strong",
+		:deletion => "del",
+		:table => "table",
+		:table_head => "thead",
+		:table_body => "tbody",
+		:table_foot => "tfoot",
+		:table_row => "tr",
+		:table_cell => "td",
+		:table_caption => "caption",
+		:table_colgroup => "colgroup",
+		:table_column => "col"
+	}.freeze
+	BLOCK_TAGS = %w[address article aside blockquote div dl fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 header hr li main nav ol p pre section table thead tbody tfoot tr td th ul].freeze
+	VOID_TAGS = %w[area base br col embed hr img input link meta param source track wbr].freeze
+
+	def initialize(configuration, entity_encoder)
+		@indent = configuration.html_indent
+		@inline = configuration.inline
+		@entity_encoder = entity_encoder
+	end
+
+	def render(node)
+		block_node?(node) ? render_block(node, 0) : render_inline(node)
+	end
+
+	def render_inline(node)
+		return escape_text(node.value) if node.kind == :text
+		return render_entity(node) if entity_leaf?(node)
+
+		tag = tag_for(node)
+		return node.children.map { |child| render_inline(child) }.join unless tag
+		return start_tag(node, tag, true) if void_tag?(tag)
+		return render_code_span(node, tag) if node.semantic_kind == :code_span
+
+		"#{start_tag(node, tag)}#{node.children.map { |child| render_inline(child) }.join}</#{tag}>"
+	end
+
+	private
+
+	def render_block(node, depth)
+		tag = tag_for(node)
+		return render_block_children(node.children, depth) unless tag
+		return indent(depth) + start_tag(node, tag, true) if void_tag?(tag)
+		return render_preserved_code_block(node, tag, depth) if node.semantic_kind == :code_block && node.representation == :html
+		return render_code_block(node, depth) if node.semantic_kind == :code_block && node.representation != :html
+
+		if node.children.none? { |child| block_node?(child) }
+			return "#{indent(depth)}#{start_tag(node, tag)}#{node.children.map { |child| render_inline(child) }.join}</#{tag}>"
+		end
+
+		lines = [indent(depth) + start_tag(node, tag)]
+		lines.concat(render_mixed_children(node.children, depth + 1))
+		lines << "#{indent(depth)}</#{tag}>"
+		lines.join("\n")
+	end
+
+	def render_block_children(children, depth)
+		render_mixed_children(children, depth).join("\n")
+	end
+
+	def render_mixed_children(children, depth)
+		lines = []
+		inline_run = []
+		flush = lambda do
+			unless inline_run.empty?
+				lines << indent(depth) + inline_run.map { |child| render_inline(child) }.join
+				inline_run = []
+			end
+		end
+
+		children.each do |child|
+			if block_node?(child)
+				flush.call
+				lines << render_block(child, depth)
+			else
+				inline_run << child
+			end
+		end
+		flush.call
+		lines
+	end
+
+	def render_code_span(node, tag)
+		value = node.value.to_s
+		value = value.gsub(/\s+/, " ") if @inline
+		"#{start_tag(node, tag)}#{escape_text(value)}</#{tag}>"
+	end
+
+	def render_code_block(node, depth)
+		tag = tag_for(node)
+		language = node.semantic_values[:code_language]
+		code_attributes = language ? " class=\"#{escape_attribute("language-#{language}")}\"" : ""
+		"#{indent(depth)}#{start_tag(node, tag)}<code#{code_attributes}>#{escape_text(node.value.to_s)}</code></#{tag}>"
+	end
+
+	def render_preserved_code_block(node, tag, depth)
+		"#{indent(depth)}#{start_tag(node, tag)}#{escape_text(node.value.to_s)}</#{tag}>"
+	end
+
+	def start_tag(node, tag, void = false)
+		ending = void ? " />" : ">"
+		"<#{tag}#{render_attributes(node)}#{ending}"
+	end
+
+	def render_attributes(node)
+		pairs = []
+		pairs << ["id", node.id] if node.id
+		pairs << ["class", node.classes.join(" ")] unless node.classes.empty?
+		pairs.concat(node.attributes.reject { |name, _value| ["id", "class"].include?(name) }.sort_by(&:first))
+		return "" if pairs.empty?
+
+		" " + pairs.map { |name, value| "#{name}=\"#{escape_attribute(value)}\"" }.join(" ")
+	end
+
+	def tag_for(node)
+		return node.source_name if node.representation == :html && node.source_name
+		return "th" if node.semantic_kind == :table_cell && node.source_name == "th"
+		return "h#{node.properties[:level]}" if node.semantic_kind == :heading
+
+		SEMANTIC_TAGS[node.semantic_kind]
+	end
+
+	def block_node?(node)
+		return true if node.category == :block
+
+		tag = tag_for(node)
+		tag && BLOCK_TAGS.include?(tag)
+	end
+
+	def void_tag?(tag)
+		VOID_TAGS.include?(tag)
+	end
+
+	def entity_leaf?(node)
+		[:entity, :typographic_symbol, :smart_quote].include?(node.kind)
+	end
+
+	def render_entity(node)
+		value = @entity_encoder.encode(node)
+		@entity_encoder.character_mode? ? escape_text(value) : value
+	end
+
+	def escape_text(value)
+		value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+	end
+
+	def escape_attribute(value)
+		value = value.to_s.gsub(/[\r\n]+/, " ") if @inline
+		escape_text(value).gsub('"', "&quot;")
+	end
+
+	def indent(depth)
+		@indent * depth
+	end
+end
+
+end
+end
+end

data/lib/slamdown/conversion/rendering/result.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Slamdown
+module Conversion
+module Rendering
+
+# Carries one rendered document together with node-local failures contained during traversal.
+class Result
+	attr_reader :output, :diagnostics
+
+	def initialize(output, diagnostics)
+		raise ArgumentError, "output must be a string" unless output.is_a?(String)
+		raise ArgumentError, "diagnostics must contain only Slamdown diagnostics" unless diagnostics.is_a?(Array) && diagnostics.all? { |diagnostic| diagnostic.is_a?(Diagnostic) }
+
+		@output = output.dup.freeze
+		@diagnostics = diagnostics.dup.freeze
+		freeze
+	end
+end
+
+end
+end
+end

data/lib/slamdown/conversion/rendering/strategy.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Slamdown
+module Conversion
+module Rendering
+
+# Supplies the small set of output-format differences used by the shared renderer.
+module Strategy
+	class << self
+		def build(format)
+			format == "kramdown" ? Kramdown.new : Markdown.new
+		end
+	end
+
+	# Defines common format hooks and groups definition-list terms with their following descriptions.
+	class Base
+		def pad_space_bounded_code_span?
+			false
+		end
+
+		def html_for_space_bounded_code_span?
+			false
+		end
+
+		def escape_link_ampersands?
+			true
+		end
+
+		def escape_definition_marker?
+			false
+		end
+
+		def decorate_inline(_node, syntax)
+			syntax
+		end
+
+		def decorate_block(_node, syntax)
+			syntax
+		end
+
+		private
+
+		def definition_groups(node)
+			groups = []
+			terms = []
+			descriptions = []
+			flush = lambda do
+				groups << [terms, descriptions] unless terms.empty? && descriptions.empty?
+				terms = []
+				descriptions = []
+			end
+
+			node.children.each do |child|
+				if child.semantic_kind == :definition_term
+					flush.call unless descriptions.empty?
+					terms << child
+				elsif child.semantic_kind == :definition_description
+					descriptions << child
+				end
+			end
+			flush.call
+			groups
+		end
+
+		def prefix_lines(value, first_prefix, continuation_prefix)
+			lines = value.split("\n", -1)
+			lines.each_with_index.map do |line, index|
+				prefix = index.zero? ? first_prefix : continuation_prefix
+				line.empty? ? prefix.rstrip : prefix + line
+			end.join("\n")
+		end
+	end
+
+	# Implements definition-list degradation for the restricted Markdown profile.
+	class Markdown < Base
+		def pad_space_bounded_code_span?
+			true
+		end
+
+		def render_definition_list(renderer, node)
+			groups = definition_groups(node).map do |terms, descriptions|
+				term = terms.map do |item|
+					renderer.render_inlines(item.children, :suppress_strong => true, :line_start => false).strip
+				end.join("<br />")
+				lines = ["* **#{term}**"]
+				descriptions.each do |description|
+					content = renderer.render_container_contents(description)
+					lines << prefix_lines(content, "  * ", "    ")
+				end
+				lines.join("\n")
+			end
+			groups.join("\n")
+		end
+	end
+
+	# Adds Kramdown IALs and emits native definition-list syntax while sharing all ordinary rendering primitives.
+	class Kramdown < Base
+		IAL_TOKEN = /\A[A-Za-z_][A-Za-z0-9_-]*\z/.freeze
+
+		def html_for_space_bounded_code_span?
+			true
+		end
+
+		def escape_definition_marker?
+			true
+		end
+
+		def decorate_inline(node, syntax)
+			attribute_list = ial(node)
+			attribute_list ? syntax + attribute_list : syntax
+		end
+
+		def decorate_block(node, syntax)
+			attribute_list = ial(node)
+			attribute_list ? "#{syntax}\n#{attribute_list}" : syntax
+		end
+
+		def render_definition_list(renderer, node)
+			groups = definition_groups(node).map do |terms, descriptions|
+				lines = terms.map { |term| renderer.render_inlines(term.children, :line_start => true).strip }
+				descriptions.each do |description|
+					content = renderer.render_container_contents(description)
+					lines << prefix_lines(content, ": ", "  ")
+				end
+				lines.join("\n")
+			end
+			decorate_block(node, groups.join("\n\n"))
+		end
+
+		private
+
+		def ial(node)
+			return if !node.id && node.classes.empty?
+
+			parts = []
+			parts << ial_id(node.id) if node.id
+			if node.classes.all? { |name| IAL_TOKEN.match(name) }
+				parts.concat(node.classes.map { |name| ".#{name}" })
+			elsif !node.classes.empty?
+				parts << "class=\"#{quoted(node.classes.join(" "))}\""
+			end
+			"{: #{parts.join(" ")}}"
+		end
+
+		def ial_id(value)
+			IAL_TOKEN.match(value) ? "##{value}" : "id=\"#{quoted(value)}\""
+		end
+
+		def quoted(value)
+			value.gsub("\\", "\\\\").gsub('"', '\\"')
+		end
+	end
+end
+
+end
+end
+end

data/lib/slamdown/conversion/semantic_extractor.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Slamdown
+module Conversion
+
+# Reads the small registered set of semantic source attributes before retention policy can discard those attributes.
+class SemanticExtractor
+	HTML_WHITESPACE = /[\t\n\f\r ]+/.freeze
+	LANGUAGE_CLASS = /\Alanguage-([A-Za-z0-9+_.-]+)\z/.freeze
+	RECOGNISED_STYLE_PROPERTIES = %w[font-weight font-style text-decoration].freeze
+
+	def extract(node)
+		attributes = Hash[node.attributes]
+		values = {}
+
+		extract_image_fallback(node, attributes, values)
+		extract_span_styles(node, attributes, values)
+		extract_code_language(node, attributes, values)
+		extract_table_spans(node, attributes, values)
+
+		values
+	end
+
+	# Language classes become fence metadata and must not also survive as presentation classes.
+	def consumed_class?(node, token)
+		["code", "pre"].include?(node.source_name) && LANGUAGE_CLASS.match(token)
+	end
+
+	private
+
+	def extract_image_fallback(node, attributes, values)
+		return unless node.source_name == "img" && !attributes.key?("alt")
+
+		title = attributes["title"]
+		values[:image_fallback_alt] = title if title.is_a?(String) && !title.strip.empty?
+	end
+
+	def extract_span_styles(node, attributes, values)
+		return unless node.source_name == "span" && attributes["style"].is_a?(String)
+
+		declarations = recognised_declarations(attributes["style"])
+		styles = []
+		styles << :strong if bold?(declarations["font-weight"])
+		styles << :emphasis if declarations["font-style"] == "italic"
+
+		decorations = declarations.fetch("text-decoration", "").split(HTML_WHITESPACE)
+		styles << :deletion if decorations.include?("line-through")
+		styles << :underline if decorations.include?("underline")
+		values[:styled_as] = styles unless styles.empty?
+	end
+
+	def recognised_declarations(style)
+		style.split(";").each_with_object({}) do |declaration, result|
+			property, value = declaration.split(":", 2)
+			next unless property && value
+
+			property = property.strip.downcase
+			value = value.strip.downcase
+			next unless RECOGNISED_STYLE_PROPERTIES.include?(property) && !value.empty?
+
+			# Every syntactically usable declaration replaces the previous value, even when its value has no Slamdown semantic equivalent.
+			result[property] = value
+		end
+	end
+
+	def bold?(value)
+		return true if ["bold", "bolder"].include?(value)
+		return false unless /\A\d+\z/.match(value)
+
+		value.to_i > 400
+	end
+
+	def extract_code_language(node, attributes, values)
+		return unless ["code", "pre"].include?(node.source_name)
+
+		attributes.fetch("class", "").split(HTML_WHITESPACE).each do |token|
+			match = LANGUAGE_CLASS.match(token)
+			next unless match
+
+			values[:code_language] = match[1]
+			break
+		end
+	end
+
+	def extract_table_spans(node, attributes, values)
+		return unless ["td", "th"].include?(node.source_name)
+
+		spans = ["colspan", "rowspan"].each_with_object({}) do |name, result|
+			value = attributes[name]
+			result[name] = value if value.is_a?(String)
+		end
+		values[:table_spans] = spans unless spans.empty?
+	end
+end
+
+end
+end