slamdown 0.5.0

data/lib/slamdown/diagnostic.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Slamdown
+
+# Describes one construction or conversion observation without exposing mutable internal state.
+class Diagnostic
+	SEVERITIES = [:info, :warning, :error].freeze
+
+	attr_reader :code, :severity, :message, :node_path
+
+	def initialize(code:, severity:, message:, node_path: nil)
+		raise ArgumentError, "diagnostic code must be a Symbol" unless code.is_a?(Symbol)
+		raise ArgumentError, "invalid diagnostic severity: #{severity.inspect}" unless SEVERITIES.include?(severity)
+		raise ArgumentError, "diagnostic message must be a String" unless message.is_a?(String)
+		raise ArgumentError, "diagnostic node_path must contain only non-negative integers" unless valid_node_path?(node_path)
+
+		@code = code
+		@severity = severity
+		@message = message.dup.freeze
+		@node_path = node_path && node_path.dup.freeze
+		freeze
+	end
+
+	private
+
+	def valid_node_path?(node_path)
+		return true if node_path.nil?
+		return false unless node_path.is_a?(Array)
+
+		node_path.all? { |index| index.is_a?(Integer) && index >= 0 }
+	end
+end
+
+end

data/lib/slamdown/document.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Slamdown
+
+# Owns Slamdown's immutable, format-neutral representation of one HTML input.
+class Document
+	ERROR_MODES = [:raise, :warn, :silent].freeze
+
+	attr_reader :tree, :diagnostics
+
+	def initialize(input, errors: :warn)
+		validate_error_mode(errors)
+		construct(input, errors)
+	end
+
+	class << self
+		# Converts a document or block-level parsed subtree through the selected output pipeline.
+		def convert(input, format:, options: {}, errors: :warn)
+			Conversion::Converter.convert(input, :format => format, :options => options, :errors => errors)
+		end
+	end
+
+	# Returns only the rendered Markdown string for the common convenience path.
+	def to_markdown(options = {}, controls = {})
+		convert_convenience(:markdown, options, controls)
+	end
+
+	# Returns only the rendered Kramdown string for the common convenience path.
+	def to_kramdown(options = {}, controls = {})
+		convert_convenience(:kramdown, options, controls)
+	end
+
+	private
+
+	def convert_convenience(format, options, controls)
+		if controls.empty? && options.is_a?(Hash) && options.keys == [:errors]
+			controls = options
+			options = {}
+		end
+
+		self.class.convert(self, :format => format, :options => options, :errors => conversion_errors(controls)).output
+	end
+
+	def conversion_errors(controls)
+		unless controls.is_a?(Hash) && (controls.keys - [:errors]).empty?
+			raise ArgumentError, "conversion controls accept only errors"
+		end
+
+		controls.fetch(:errors, :warn)
+	end
+
+	def construct(input, errors)
+		@tree, parser_warnings = Parsing.parse(input.to_s)
+		raise "the parser did not return a usable document tree" unless usable_tree?(@tree)
+
+		@diagnostics = parser_warnings.map { |message| parser_warning(message) }.freeze
+		freeze
+	rescue StandardError => error
+		handle_parse_error(error, errors)
+	end
+
+	def validate_error_mode(errors)
+		return if ERROR_MODES.include?(errors)
+
+		raise ArgumentError, "errors must be :raise, :warn or :silent"
+	end
+
+	def usable_tree?(tree)
+		tree.is_a?(Parsing::Node) && tree.kind == :document
+	end
+
+	def parser_warning(message)
+		Diagnostic.new(
+			:code => :parser_warning,
+			:severity => :warning,
+			:message => message.to_s,
+			:node_path => nil
+		)
+	end
+
+	def handle_parse_error(error, errors)
+		diagnostic = Diagnostic.new(
+			:code => :parse_error,
+			:severity => :error,
+			:message => "Unable to parse HTML: #{error.message}",
+			:node_path => nil
+		)
+		parse_error = ParseError.new(diagnostic)
+
+		raise parse_error if errors == :raise
+		Kernel.warn(parse_error.message) if errors == :warn
+
+		@tree = empty_tree
+		@diagnostics = [diagnostic].freeze
+		freeze
+	end
+
+	def empty_tree
+		Parsing::Node.new(
+			:kind => :document,
+			:children => [],
+			:properties => {:encoding => "UTF-8"}
+		)
+	end
+end
+
+end

data/lib/slamdown/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Slamdown
+
+# Reports a construction failure together with the diagnostic exposed by non-raising error modes.
+class ParseError < StandardError
+	attr_reader :diagnostic
+
+	def initialize(diagnostic)
+		@diagnostic = diagnostic
+		super(diagnostic.message)
+	end
+end
+
+# Reports a conversion failure. Conversion stages populate this error as they are implemented.
+class ConversionError < StandardError
+	attr_reader :diagnostic
+
+	def initialize(diagnostic)
+		@diagnostic = diagnostic
+		super(diagnostic.message)
+	end
+end
+
+end

data/lib/slamdown/immutable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Slamdown
+
+# Copies nested public values into an immutable representation shared by Slamdown's boundary objects.
+module Immutable
+	def self.copy(value)
+		case value
+		when String, Regexp
+			value.dup.freeze
+		when Array
+			value.map { |item| copy(item) }.freeze
+		when Hash
+			value.each_with_object({}) do |(name, item), result|
+				result[copy(name)] = copy(item)
+			end.freeze
+		else
+			value
+		end
+	end
+end
+
+end

data/lib/slamdown/output.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Slamdown
+
+# Contains the immutable public values returned by full conversions.
+module Output
+	# Owns the canonical string and conversion-only diagnostics shared by every output format.
+	class Base
+		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
+
+	# Identifies output rendered through Slamdown's restricted Markdown profile.
+	class Markdown < Base
+	end
+
+	# Identifies output rendered through Slamdown's specified Kramdown extensions.
+	class Kramdown < Base
+	end
+end
+
+end

data/lib/slamdown/parsing/html.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "kramdown/parser/html"
+
+module Slamdown
+module Parsing
+
+# Parses HTML with Kramdown while retaining the explicit name of every source element that survives Kramdown's native conversion.
+class Html < ::Kramdown::Parser::Html
+	# Extends only converter instances selected by Slamdown. Ordinary Kramdown parsing continues to instantiate its original converter class.
+	class SourceAwareElementConverter < ::Kramdown::Parser::Html::ElementConverter
+		CODE_SOURCE_NAMES = %w[code kbd pre samp tt var].freeze
+
+		def initialize(root)
+			@raw_elements = {}
+			@raw_list_children = {}
+			capture_raw_element(root)
+			super
+		end
+
+		# Captures the source name and contains a failure of Kramdown's optional native conversion to the affected element.
+		def process(element, do_conversion = true, preserve_text = false, parent = nil)
+			source_name = element.value if element.type == :html_element
+			raw_element = @raw_elements[element.object_id] if source_name
+			result = begin
+				super
+			rescue StandardError
+				raise unless source_name && do_conversion && @raw_elements.key?(element.object_id)
+
+				restore_raw_element(element)
+				process_html_element(element, false, preserve_text)
+			end
+			element.options[:source_name] = source_name if source_name
+			restore_list_text(element) if ["ol", "ul"].include?(source_name)
+			attach_code_source(element, raw_element) if CODE_SOURCE_NAMES.include?(source_name)
+			result
+		end
+
+		private
+
+		# Retains code text before Kramdown can flatten element boundaries or leave raw code text in child nodes.
+		def attach_code_source(element, raw_element)
+			state = {:value => String.new, :structural_boundary => false, :explicit_break => false}
+			raw_element.children.each { |child| append_code_source(child, state) }
+			element.options[:code_source] = decoded_code_source(raw_element, state[:value])
+			element.options[:code_source_has_break] = state[:explicit_break]
+		end
+
+		def append_code_source(element, state)
+			if element.type == :text
+				flush_structural_boundary(state)
+				state[:value] << element.value.to_s
+			elsif element.type == :html_element && element.value.to_s.downcase == "br"
+				state[:structural_boundary] = false
+				state[:value] << "\n"
+				state[:explicit_break] = true
+			elsif element.type == :html_element
+				block = HTML_BLOCK_ELEMENTS.include?(element.value.to_s.downcase)
+				state[:structural_boundary] = true if block
+				element.children.each { |child| append_code_source(child, state) }
+				state[:structural_boundary] = true if block
+			end
+		end
+
+		def flush_structural_boundary(state)
+			if state[:structural_boundary] && !state[:value].empty? && !state[:value].end_with?("\n")
+				state[:value] << "\n"
+			end
+			state[:structural_boundary] = false
+		end
+
+		# Reuses the active Kramdown version's entity handling instead of duplicating dependency-specific decoding rules.
+		def decoded_code_source(raw_element, value)
+			return "" if value.empty?
+
+			copy = duplicate_element_fields(raw_element)
+			copy.children = [::Kramdown::Element.new(:text, value)]
+			convert_code(copy)
+			copy.value.to_s
+		end
+
+		def capture_raw_element(element)
+			if element.type == :html_element && ["ol", "ul"].include?(element.value.to_s.downcase)
+				@raw_list_children[element.object_id] = element.children.map do |child|
+					child.type == :text ? [:text, child.value.to_s] : [:child, child.object_id]
+				end
+			end
+			copy = duplicate_element_fields(element)
+			@raw_elements[element.object_id] = copy
+			copy.children = element.children.map { |child| capture_raw_element(child) }
+			copy
+		end
+
+		# Kramdown discards direct text children of lists; retain non-blank runs as synthetic paragraphs in their source position.
+		def restore_list_text(element)
+			descriptors = @raw_list_children[element.object_id]
+			return unless descriptors
+
+			current = element.children.each_with_object({}) { |child, result| result[child.object_id] = child }
+			children = descriptors.each_with_object([]) do |(kind, value), result|
+				if kind == :child
+					child = current.delete(value)
+					result << child if child
+				elsif !value.to_s.strip.empty?
+					paragraph = ::Kramdown::Element.new(:p, nil, nil, :category => :block, :transparent => true)
+					paragraph.children << ::Kramdown::Element.new(:text, value)
+					result << paragraph
+				end
+			end
+			element.children = children + current.values
+		end
+
+		def restore_raw_element(element)
+			raw = duplicate_element(@raw_elements.fetch(element.object_id))
+			element.type = raw.type
+			element.value = raw.value
+			element.attr.replace(raw.attr)
+			element.options.replace(raw.options)
+			element.children = raw.children
+		end
+
+		def duplicate_element(element)
+			copy = duplicate_element_fields(element)
+			copy.children = element.children.map { |child| duplicate_element(child) }
+			copy
+		end
+
+		def duplicate_element_fields(element)
+			::Kramdown::Element.new(
+				element.type,
+				duplicate_value(element.value),
+				duplicate_value(element.attr),
+				duplicate_value(element.options)
+			)
+		end
+
+		def duplicate_value(value)
+			case value
+			when String
+				value.dup
+			when Array
+				value.map { |item| duplicate_value(item) }
+			when Hash
+				result = value.dup
+				result.clear
+				value.each_with_object(result) do |(key, item), copy|
+					copy[duplicate_value(key)] = duplicate_value(item)
+				end
+			else
+				value
+			end
+		end
+	end
+
+	# Reproduces Kramdown::Parser::Html#parse's orchestration so the existing scanner can feed Slamdown's converter without global mutation.
+	def parse
+		@stack, @tree = [], @root
+		@src = ::Kramdown::Utils::StringScanner.new(adapt_source(repair_unclosed_table_rows(source)))
+
+		while true
+			if (result = @src.scan(/\s*#{HTML_INSTRUCTION_RE}/o))
+				@tree.children << ::Kramdown::Element.new(:xml_pi, result.strip, nil, :category => :block)
+			elsif @src.scan(/\s*#{HTML_DOCTYPE_RE}/o)
+				# Kramdown deliberately discards the document type.
+			elsif (result = @src.scan(/\s*#{HTML_COMMENT_RE}/o))
+				@tree.children << ::Kramdown::Element.new(:xml_comment, result.strip, nil, :category => :block)
+			else
+				break
+			end
+		end
+
+		tag_handler = lambda do |child, closed, handle_body|
+			parse_raw_html(child, &tag_handler) if !closed && handle_body
+		end
+		parse_raw_html(@tree, &tag_handler)
+
+		SourceAwareElementConverter.convert(@tree)
+	end
+
+	private
+
+	# Browsers implicitly close a row when another row starts; Kramdown instead nests it and can expose closing markup as text.
+	def repair_unclosed_table_rows(value)
+		return value unless value.valid_encoding?
+
+		table_rows = []
+		cursor = 0
+		result = String.new
+		value.to_enum(:scan, /<\/?\s*(?:table|tr)\b[^>]*>/i).each do
+			match = Regexp.last_match
+			result << value[cursor...match.begin(0)]
+			tag = match[0]
+			closing = /\A<\//.match(tag)
+			name = tag[/\A<\/?\s*([A-Za-z]+)/, 1].downcase
+
+			if name == "table"
+				if closing
+					result << "</tr>" if table_rows.last
+					table_rows.pop
+				else
+					table_rows << false
+				end
+				result << tag
+			elsif !table_rows.empty? && closing
+				unless table_rows.last
+					cursor = match.end(0)
+					next
+				end
+				table_rows[-1] = false
+				result << tag
+			elsif !table_rows.empty?
+				result << "</tr>" if table_rows.last
+				table_rows[-1] = true
+				result << tag
+			else
+				result << tag
+			end
+			cursor = match.end(0)
+		end
+		result << value[cursor..-1].to_s
+		result
+	end
+end
+
+end
+end

data/lib/slamdown/parsing/node.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Slamdown
+module Parsing
+
+# Immutable, format-neutral representation of one parsed construct. It contains parser facts only; element policy, structural correction and rendering belong to later stages.
+class Node
+	ATTRIBUTES = [
+		:kind,
+		:source_name,
+		:semantic_kind,
+		:category,
+		:content_model,
+		:value,
+		:attributes,
+		:children,
+		:properties,
+		:source_form,
+		:synthetic
+	].freeze
+
+	attr_reader(*ATTRIBUTES)
+
+	def initialize(kind:, source_name: nil, semantic_kind: nil, category: nil, content_model: nil, value: nil, attributes: [], children: [], properties: {}, source_form: nil, synthetic: false)
+		@kind = kind
+		@source_name = Immutable.copy(source_name)
+		@semantic_kind = semantic_kind
+		@category = category
+		@content_model = content_model
+		@value = Immutable.copy(value)
+		@attributes = Immutable.copy(attributes)
+		@children = children.dup.freeze
+		@properties = Immutable.copy(properties)
+		@source_form = Immutable.copy(source_form)
+		@synthetic = synthetic
+		freeze
+	end
+
+	# Provides a stable plain-Ruby projection for diagnostics and characterisation.
+	def to_h
+		ATTRIBUTES.each_with_object({}) do |attribute, result|
+			value = public_send(attribute)
+			result[attribute] = attribute == :children ? value.map(&:to_h) : value
+		end
+	end
+
+end
+
+end
+end

data/lib/slamdown/parsing/parsed_node_adapter.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Slamdown
+module Parsing
+
+# Projects Kramdown elements into immutable Slamdown nodes while removing only dependency-specific representation details from the parser boundary.
+class ParsedNodeAdapter
+	SEMANTIC_KINDS = {
+		:p => :paragraph,
+		:header => :heading,
+		:blockquote => :blockquote,
+		:codeblock => :code_block,
+		:ul => :unordered_list,
+		:ol => :ordered_list,
+		:li => :list_item,
+		:dl => :definition_list,
+		:dt => :definition_term,
+		:dd => :definition_description,
+		:hr => :horizontal_rule,
+		:table => :table,
+		:thead => :table_head,
+		:tbody => :table_body,
+		:tfoot => :table_foot,
+		:tr => :table_row,
+		:td => :table_cell,
+		:a => :link,
+		:br => :line_break,
+		:img => :image,
+		:codespan => :code_span,
+		:em => :emphasis,
+		:strong => :strong,
+		:math => :math
+	}.freeze
+
+	NON_ELEMENT_KINDS = {
+		:root => :document,
+		:text => :text,
+		:raw => :raw,
+		:xml_comment => :comment,
+		:xml_pi => :processing_instruction,
+		:entity => :entity,
+		:typographic_sym => :typographic_symbol,
+		:smart_quote => :smart_quote
+	}.freeze
+
+	class << self
+		def adapt(root)
+			new.adapt_node(root)
+		end
+	end
+
+	# Recursively copies only fields that belong to Slamdown's parser contract.
+	def adapt_node(element, parent_type: nil, final_root_child: false)
+		source_name = explicit_source_name(element)
+		children = element.children.each_with_index.map do |child, index|
+			adapt_node(
+				child,
+				:parent_type => element.type,
+				:final_root_child => element.type == :root && index == element.children.length - 1
+			)
+		end.freeze
+
+		Node.new(
+			:kind => NON_ELEMENT_KINDS.fetch(element.type, :element),
+			:source_name => source_name,
+			:semantic_kind => SEMANTIC_KINDS[element.type],
+			:category => ::Kramdown::Element.category(element),
+			:content_model => element.options[:content_model],
+			:value => adapted_value(element, parent_type, final_root_child),
+			:attributes => adapted_attributes(element),
+			:children => children,
+			:properties => adapted_properties(element),
+			:source_form => adapted_source_form(element),
+			:synthetic => synthetic_element?(element, source_name)
+		)
+	end
+
+	private
+
+	def explicit_source_name(element)
+		name = element.options[:source_name]
+		name && name.downcase
+	end
+
+	def adapted_value(element, parent_type, final_root_child)
+		case element.type
+		when :raw, :xml_comment, :xml_pi, :html_element
+			nil
+		when :entity
+			{
+				:code_point => element.value.code_point,
+				:name => element.value.name,
+				:character => element.value.char
+			}
+		when :text
+			text = element.value
+			text = normalised_root_text(text, final_root_child) if parent_type == :root
+			text
+		else
+			element.value
+		end
+	end
+
+	# Kramdown 2.3.0 leaves root text adapted but unprocessed, whereas 2.5.2 collapses it and exposes the parser's terminal sentinel as a space.
+	def normalised_root_text(text, final_root_child)
+		result = text.gsub(/\s+/, " ")
+		result = result.sub(/\s+\z/, "") if final_root_child
+		result
+	end
+
+	def adapted_attributes(element)
+		element.attr.map do |name, value|
+			[name.downcase, value]
+		end
+	end
+
+	def adapted_properties(element)
+		properties = {}
+		properties[:encoding] = element.options[:encoding].name if element.options[:encoding]
+		properties[:level] = element.options[:level] if element.options.key?(:level)
+		properties[:alignment] = element.options[:alignment] if element.options.key?(:alignment)
+		properties[:code_source] = element.options[:code_source] if element.options.key?(:code_source)
+		properties[:code_source_has_break] = element.options[:code_source_has_break] if element.options.key?(:code_source_has_break)
+		properties
+	end
+
+	def adapted_source_form(element)
+		return unless element.type == :entity && element.options[:original]
+
+		element.options[:original]
+	end
+
+	def synthetic_element?(element, source_name)
+		return false unless NON_ELEMENT_KINDS.fetch(element.type, :element) == :element
+		return false if source_name
+		return true if element.type == :tbody || (element.type == :p && element.options[:transparent])
+
+		raise "Kramdown element #{element.type.inspect} lacks source provenance"
+	end
+
+end
+
+end
+end

data/lib/slamdown/parsing.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "parsing/html"
+require_relative "parsing/node"
+require_relative "parsing/parsed_node_adapter"
+
+module Slamdown
+module Parsing
+
+	# Parses HTML through Slamdown's isolated Kramdown extension and returns the format-neutral tree together with any parser warnings.
+	def self.parse(source, options = {})
+		root, warnings = Html.parse(source, options)
+		[ParsedNodeAdapter.adapt(root), warnings]
+	end
+
+end
+end

data/lib/slamdown/version.rb

@@ -0,0 +1,3 @@
+module Slamdown
+	VERSION = "0.5.0"
+end

data/lib/slamdown.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "slamdown/version"
+require "slamdown/immutable"
+require "slamdown/diagnostic"
+require "slamdown/errors"
+require "slamdown/parsing"
+require "slamdown/output"
+require "slamdown/document"
+require "slamdown/conversion"