markly 0.16.0 → 0.18.0

data/ext/markly/node.c

@@ -145,16 +145,154 @@ cmark_node *cmark_node_new(cmark_node_type type) {
   return cmark_node_new_with_ext(type, NULL);
 }
 
+static cmark_chunk S_clone_chunk(cmark_mem *mem, const cmark_chunk *source) {
+  cmark_chunk clone = {NULL, source->len, 1};
+  clone.data = (unsigned char *)mem->calloc(source->len + 1, 1);
+  if (source->len > 0) {
+    memcpy(clone.data, source->data, source->len);
+  }
+  return clone;
+}
+
+static cmark_node *S_clone_node(cmark_node *node) {
+  cmark_mem *mem = NODE_MEM(node);
+  cmark_node *clone = cmark_node_new_with_mem_and_ext(
+      (cmark_node_type)node->type, mem, node->extension);
+
+  if (!clone) {
+    return NULL;
+  }
+
+  cmark_strbuf_set(&clone->content, node->content.ptr, node->content.size);
+  clone->start_line = node->start_line;
+  clone->start_column = node->start_column;
+  clone->end_line = node->end_line;
+  clone->end_column = node->end_column;
+  clone->internal_offset = node->internal_offset;
+  clone->flags = node->flags;
+  clone->footnote = node->footnote;
+
+  switch (node->type) {
+  case CMARK_NODE_HEADING:
+    clone->as.heading = node->as.heading;
+    break;
+  case CMARK_NODE_LIST:
+  case CMARK_NODE_ITEM:
+    clone->as.list = node->as.list;
+    break;
+  case CMARK_NODE_CODE_BLOCK:
+  case CMARK_NODE_FRONT_MATTER:
+  case CMARK_NODE_CODE:
+    clone->as.code = node->as.code;
+    clone->as.code.info = S_clone_chunk(mem, &node->as.code.info);
+    clone->as.code.literal = S_clone_chunk(mem, &node->as.code.literal);
+    break;
+  case CMARK_NODE_TEXT:
+  case CMARK_NODE_HTML_INLINE:
+  case CMARK_NODE_HTML_BLOCK:
+  case CMARK_NODE_FOOTNOTE_REFERENCE:
+  case CMARK_NODE_FOOTNOTE_DEFINITION:
+    clone->as.literal = S_clone_chunk(mem, &node->as.literal);
+    break;
+  case CMARK_NODE_LINK:
+  case CMARK_NODE_IMAGE:
+    clone->as.link.url = S_clone_chunk(mem, &node->as.link.url);
+    clone->as.link.title = S_clone_chunk(mem, &node->as.link.title);
+    break;
+  case CMARK_NODE_CUSTOM_BLOCK:
+  case CMARK_NODE_CUSTOM_INLINE:
+    clone->as.custom.on_enter = S_clone_chunk(mem, &node->as.custom.on_enter);
+    clone->as.custom.on_exit = S_clone_chunk(mem, &node->as.custom.on_exit);
+    break;
+  default:
+    break;
+  }
+
+  if (node->extension && node->extension->opaque_alloc_func) {
+    if (!node->extension->opaque_copy_func) {
+      cmark_node_free(clone);
+      return NULL;
+    }
+
+    node->extension->opaque_copy_func(node->extension, mem, clone, node);
+  }
+
+  for (cmark_node *child = node->first_child; child; child = child->next) {
+    cmark_node *child_clone = S_clone_node(child);
+    if (!child_clone) {
+      cmark_node_free(clone);
+      return NULL;
+    }
+
+    if (!cmark_node_append_child(clone, child_clone)) {
+      cmark_node_free(child_clone);
+      cmark_node_free(clone);
+      return NULL;
+    }
+  }
+
+  return clone;
+}
+
+static cmark_node *S_find_clone(cmark_node *source, cmark_node *clone,
+                                cmark_node *target) {
+  if (source == target) {
+    return clone;
+  }
+
+  cmark_node *source_child = source->first_child;
+  cmark_node *clone_child = clone->first_child;
+  while (source_child && clone_child) {
+    cmark_node *result = S_find_clone(source_child, clone_child, target);
+    if (result) {
+      return result;
+    }
+    source_child = source_child->next;
+    clone_child = clone_child->next;
+  }
+
+  return NULL;
+}
+
+static void S_clone_footnote_links(cmark_node *source, cmark_node *clone,
+                                   cmark_node *source_root,
+                                   cmark_node *clone_root) {
+  if (source->parent_footnote_def) {
+    clone->parent_footnote_def =
+        S_find_clone(source_root, clone_root, source->parent_footnote_def);
+  }
+
+  cmark_node *source_child = source->first_child;
+  cmark_node *clone_child = clone->first_child;
+  while (source_child && clone_child) {
+    S_clone_footnote_links(source_child, clone_child, source_root, clone_root);
+    source_child = source_child->next;
+    clone_child = clone_child->next;
+  }
+}
+
+cmark_node *cmark_node_clone(cmark_node *node) {
+  if (!node) {
+    return NULL;
+  }
+
+  cmark_node *clone = S_clone_node(node);
+  if (clone) {
+    S_clone_footnote_links(node, clone, node, clone);
+  }
+  return clone;
+}
+
 static void free_node_as(cmark_node *node) {
   switch (node->type) {
     case CMARK_NODE_CODE_BLOCK:
     case CMARK_NODE_FRONT_MATTER:
+    case CMARK_NODE_CODE:
     cmark_chunk_free(NODE_MEM(node), &node->as.code.info);
     cmark_chunk_free(NODE_MEM(node), &node->as.code.literal);
       break;
     case CMARK_NODE_TEXT:
     case CMARK_NODE_HTML_INLINE:
-    case CMARK_NODE_CODE:
     case CMARK_NODE_HTML_BLOCK:
     case CMARK_NODE_FOOTNOTE_REFERENCE:
     case CMARK_NODE_FOOTNOTE_DEFINITION:
@@ -378,11 +516,11 @@ const char *cmark_node_get_literal(cmark_node *node) {
   case CMARK_NODE_HTML_BLOCK:
   case CMARK_NODE_TEXT:
   case CMARK_NODE_HTML_INLINE:
-  case CMARK_NODE_CODE:
   case CMARK_NODE_FOOTNOTE_REFERENCE:
   case CMARK_NODE_FOOTNOTE_DEFINITION:
     return cmark_chunk_to_cstr(NODE_MEM(node), &node->as.literal);
 
+  case CMARK_NODE_CODE:
   case CMARK_NODE_CODE_BLOCK:
   case CMARK_NODE_FRONT_MATTER:
     return cmark_chunk_to_cstr(NODE_MEM(node), &node->as.code.literal);
@@ -403,11 +541,11 @@ int cmark_node_set_literal(cmark_node *node, const char *content) {
   case CMARK_NODE_HTML_BLOCK:
   case CMARK_NODE_TEXT:
   case CMARK_NODE_HTML_INLINE:
-  case CMARK_NODE_CODE:
   case CMARK_NODE_FOOTNOTE_REFERENCE:
     cmark_chunk_set_cstr(NODE_MEM(node), &node->as.literal, content);
     return 1;
 
+  case CMARK_NODE_CODE:
   case CMARK_NODE_CODE_BLOCK:
   case CMARK_NODE_FRONT_MATTER:
     cmark_chunk_set_cstr(NODE_MEM(node), &node->as.code.literal, content);
@@ -595,6 +733,59 @@ int cmark_node_set_item_index(cmark_node *node, int idx) {
   }
 }
 
+const char *cmark_node_get_code_info(cmark_node *node) {
+  if (node == NULL) {
+    return NULL;
+  }
+
+  if (node->type == CMARK_NODE_CODE ||
+      node->type == CMARK_NODE_CODE_BLOCK ||
+      node->type == CMARK_NODE_FRONT_MATTER) {
+    return cmark_chunk_to_cstr(NODE_MEM(node), &node->as.code.info);
+  } else {
+    return NULL;
+  }
+}
+
+static int valid_inline_code_info(const char *info) {
+  if (info == NULL || *info == '\0') {
+    return 1;
+  }
+
+  if (!cmark_is_inline_code_info_start_char(*info)) {
+    return 0;
+  }
+
+  while (*++info) {
+    if (!cmark_is_inline_code_info_char(*info)) {
+      return 0;
+    }
+  }
+
+  return 1;
+}
+
+int cmark_node_set_code_info(cmark_node *node, const char *info) {
+  if (node == NULL) {
+    return 0;
+  }
+
+  if (node->type == CMARK_NODE_CODE) {
+    if (!valid_inline_code_info(info)) {
+      return 0;
+    }
+
+    cmark_chunk_set_cstr(NODE_MEM(node), &node->as.code.info, info);
+    return 1;
+  } else if (node->type == CMARK_NODE_CODE_BLOCK ||
+             node->type == CMARK_NODE_FRONT_MATTER) {
+    cmark_chunk_set_cstr(NODE_MEM(node), &node->as.code.info, info);
+    return 1;
+  } else {
+    return 0;
+  }
+}
+
 const char *cmark_node_get_fence_info(cmark_node *node) {
   if (node == NULL) {
     return NULL;

data/ext/markly/syntax_extension.c

@@ -143,6 +143,11 @@ void cmark_syntax_extension_set_opaque_free_func(cmark_syntax_extension *extensi
   extension->opaque_free_func = func;
 }
 
+void cmark_syntax_extension_set_opaque_copy_func(
+    cmark_syntax_extension *extension, cmark_opaque_copy_func func) {
+  extension->opaque_copy_func = func;
+}
+
 void cmark_syntax_extension_set_commonmark_escape_func(cmark_syntax_extension *extension,
                                                        cmark_commonmark_escape_func func) {
   extension->commonmark_escape_func = func;

data/ext/markly/syntax_extension.h

@@ -28,6 +28,7 @@ struct cmark_syntax_extension {
   cmark_postprocess_func          postprocess_func;
   cmark_opaque_alloc_func         opaque_alloc_func;
   cmark_opaque_free_func          opaque_free_func;
+  cmark_opaque_copy_func          opaque_copy_func;
   cmark_commonmark_escape_func    commonmark_escape_func;
 };
 

data/ext/markly/xml.c

@@ -72,7 +72,6 @@ static int S_render_node(cmark_node *node, cmark_event_type ev_type,
       literal = true;
       break;
     case CMARK_NODE_TEXT:
-    case CMARK_NODE_CODE:
     case CMARK_NODE_HTML_BLOCK:
     case CMARK_NODE_HTML_INLINE:
       cmark_strbuf_puts(xml, " xml:space=\"preserve\">");
@@ -81,6 +80,18 @@ static int S_render_node(cmark_node *node, cmark_event_type ev_type,
       cmark_strbuf_puts(xml, cmark_node_get_type_string(node));
       literal = true;
       break;
+    case CMARK_NODE_CODE:
+      if (node->as.code.info.len > 0) {
+        cmark_strbuf_puts(xml, " info=\"");
+        escape_xml(xml, node->as.code.info.data, node->as.code.info.len);
+        cmark_strbuf_putc(xml, '"');
+      }
+      cmark_strbuf_puts(xml, " xml:space=\"preserve\">");
+      escape_xml(xml, node->as.code.literal.data, node->as.code.literal.len);
+      cmark_strbuf_puts(xml, "</");
+      cmark_strbuf_puts(xml, cmark_node_get_type_string(node));
+      literal = true;
+      break;
     case CMARK_NODE_LIST:
       switch (cmark_node_get_list_type(node)) {
       case CMARK_ORDERED_LIST:

data/lib/markly/flags.rb

@@ -20,12 +20,15 @@ module Markly
 	UNSAFE = 1 << 17
 	# Parse front matter ("---" delimited block at start of document).
 	# The raw content is available via node.string_content and the optional
-	# format hint (e.g. "yaml", "toml") via node.fence_info; interpretation
+	# format hint (e.g. "yaml", "toml") via node.code_info; interpretation
 	# is left to the caller.
 	FRONT_MATTER = 1 << 18
+	# Parse language prefixes on inline code spans, e.g. ruby:`Object.new`.
+	INLINE_CODE_INFO = 1 << 19
 	
 	PARSE_FLAGS = {
 		front_matter: FRONT_MATTER,
+		inline_code_info: INLINE_CODE_INFO,
 		validate_utf8: VALIDATE_UTF8,
 		smart_quotes: SMART,
 		liberal_html_tags: LIBERAL_HTML_TAG,

data/lib/markly/node/inspect.rb

@@ -4,20 +4,27 @@
 # Copyright, 2017, by Goro Fuji.
 # Copyright, 2017-2019, by Garen Torikian.
 # Copyright, 2020, by Olle Jonsson.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "pp"
 
 module Markly
 	class Node
+		# Provides concise pretty-printing for Markdown nodes.
 		module Inspect
+			# @constant [Integer] The indentation width used for nested node attributes.
 			PP_INDENT_SIZE = 2
 			
+			# Returns a pretty-printed representation of the node.
+			#
+			# @returns [String] The formatted node representation.
 			def inspect
 				PP.pp(self, +"", Float::INFINITY)
 			end
 			
-			# @param printer [PrettyPrint] pp
+			# Pretty-print this node and its children.
+			#
+			# @parameter printer [PrettyPrint] The pretty-print formatter.
 			def pretty_print(printer)
 				printer.group(PP_INDENT_SIZE, "#<#{self.class}(#{type}):", ">") do
 					printer.breakable
@@ -31,7 +38,7 @@ module Markly
 						list_type
 						list_start
 						list_tight
-						fence_info
+						code_info
 					].map do |name|
 						begin
 							[name, __send__(name)]

data/lib/markly/node.rb

@@ -5,32 +5,29 @@
 # Copyright, 2016-2017, by Yuki Izumi.
 # Copyright, 2017, by Goro Fuji.
 # Copyright, 2018, by Jerry van Leeuwen.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 # Copyright, 2025, by Olle Jonsson.
 
 require_relative "node/inspect"
 
 module Markly
+	# Represents a node in a parsed Markdown document tree.
 	class Node
 		include Enumerable
 		include Inspect
 		
-		# Duplicate the current node and all children.
+		# Duplicate the current node and all its children.
+		#
+		# @returns [Markly::Node] The duplicated node tree.
 		def dup
-			# This is a bit crazy, but it's the best I can come up with right now:
-			node = Markly.parse(self.to_markdown)
-			
-			# If we aren't duplicating a document, we return `first_child` as the root will be a document node:
-			if self.type == :document
-				return node
-			else
-				return node.first_child
-			end
+			_dup
 		end
 		
-		# Public: An iterator that "walks the tree," descending into children recursively.
+		# Walk the node tree recursively.
 		#
-		# block - A {Proc} representing the action to take for each child
+		# @yields {|node| ...} Each node in depth-first order, including this node.
+		# 	@parameter node [Markly::Node] The current node.
+		# @returns [Enumerator | Nil] An enumerator when no block is given.
 		def walk(&block)
 			return enum_for(:walk) unless block_given?
 			
@@ -40,39 +37,47 @@ module Markly
 			end
 		end
 		
-		# Public: Convert the node to an HTML string.
+		# Convert the node to an HTML string.
 		#
-		# flags - A {Symbol} or {Array of Symbol}s indicating the render options
-		# extensions - An {Array of Symbol}s indicating the extensions to use
-		#
-		# Returns a {String}.
+		# @parameter flags [Integer] The enabled rendering flags.
+		# @parameter extensions [Array(Symbol)] The extensions to enable.
+		# @returns [String] The rendered HTML.
 		def to_html(flags: DEFAULT, extensions: [])
 			_render_html(flags, extensions).force_encoding("utf-8")
 		end
 		
-		# Public: Convert the node to a CommonMark string.
-		#
-		# flags - A {Symbol} or {Array of Symbol}s indicating the render options
-		# width - Column to wrap the output at
+		# Convert the node to a CommonMark string.
 		#
-		# Returns a {String}.
+		# @parameter flags [Integer] The enabled rendering flags.
+		# @parameter width [Integer] The column at which to wrap output, or `0` to disable wrapping.
+		# @returns [String] The rendered CommonMark text.
 		def to_commonmark(flags: DEFAULT, width: 0)
 			_render_commonmark(flags, width).force_encoding("utf-8")
 		end
 		
 		alias to_markdown to_commonmark
 		
-		# Public: Convert the node to a plain text string.
+		# Return the language identifier from the code info string.
 		#
-		# flags - A {Symbol} or {Array of Symbol}s indicating the render options
-		# width - Column to wrap the output at
+		# @returns [String | Nil] The language identifier, or `nil` when none is present.
+		def code_language
+			code_info.split(/\s+/, 2).first
+		end
+		
+		# Convert the node to a plain-text string.
 		#
-		# Returns a {String}.
+		# @parameter flags [Integer] The enabled rendering flags.
+		# @parameter width [Integer] The column at which to wrap output, or `0` to disable wrapping.
+		# @returns [String] The rendered plain text.
 		def to_plaintext(flags: DEFAULT, width: 0)
 			_render_plaintext(flags, width).force_encoding("utf-8")
 		end
 		
-		# Public: Iterate over the children (if any) of the current pointer.
+		# Iterate over the direct children of this node.
+		#
+		# @yields {|child| ...} Each direct child of this node.
+		# 	@parameter child [Markly::Node] The current child node.
+		# @returns [Enumerator | Nil] An enumerator when no block is given.
 		def each
 			return enum_for(:each) unless block_given?
 			
@@ -84,6 +89,10 @@ module Markly
 			end
 		end
 		
+		# Finds a direct child header with the given text.
+		#
+		# @parameter title [String] The header text to match.
+		# @returns [Markly::Node | Nil] The matching header, if present.
 		def find_header(title)
 			each do |child|
 				if child.type == :header && child.first_child.string_content == title
@@ -94,7 +103,9 @@ module Markly
 		
 		# Delete all nodes until the block returns true.
 		#
-		# @returns [Markly::Node] the node that returned true.
+		# @yields {|node| ...} Each node before it is deleted.
+		# 	@parameter node [Markly::Node] The current node.
+		# @returns [Markly::Node | Nil] The node for which the block returned `true`, if any.
 		def delete_until
 			current = self
 			while current
@@ -107,9 +118,9 @@ module Markly
 		
 		# Replace a section (header + content) with a new node.
 		#
-		# @parameter new_node [Markly::Node] the node to replace the section with.
-		# @parameter replace_header [Boolean] whether to replace the header itself or not.
-		# @parameter remove_subsections [Boolean] whether to remove subsections or not.
+		# @parameter new_node [Markly::Node | Nil] The node with which to replace the section.
+		# @parameter replace_header [Boolean] Whether to replace the header itself.
+		# @parameter remove_subsections [Boolean] Whether to remove subsections.
 		def replace_section(new_node, replace_header: true, remove_subsections: true)
 			# Delete until the next heading:
 			self.next&.delete_until do |node|
@@ -120,21 +131,27 @@ module Markly
 			self.delete if replace_header
 		end
 		
-		def next_heading
+		# Finds the next sibling header.
+		#
+		# @returns [Markly::Node | Nil] The next header, if present.
+		def next_header
 			current = self.next
 			while current
-				if current.type == :heading
+				if current.type == :header
 					return current
 				end
 				current = current.next
 			end
 		end
 		
+		# An alias for {ruby Markly::Node#next_header}.
+		alias next_heading next_header
+		
 		# Append the given node after the current node.
 		#
 		# It's okay to provide a document node, its children will be appended.
 		#
-		# @parameter node [Markly::Node] the node to append.
+		# @parameter node [Markly::Node] The node to append.
 		def append_after(node)
 			if node.type == :document
 				node = node.first_child
@@ -153,7 +170,7 @@ module Markly
 		#
 		# It's okay to provide a document node, its children will be appended.
 		#
-		# @parameter node [Markly::Node] the node to append.
+		# @parameter node [Markly::Node] The node to append.
 		def append_before(node)
 			if node.type == :document
 				node = node.first_child
@@ -169,7 +186,7 @@ module Markly
 		
 		# Extract the children as a fragment.
 		#
-		# @returns [Markly::Node] the fragment.
+		# @returns [Markly::Node] The fragment.
 		def extract_children
 			fragment = Markly::Node.new(:custom_inline)
 			

data/lib/markly/renderer/generic.rb

@@ -3,26 +3,37 @@
 # Released under the MIT License.
 # Copyright, 2015-2019, by Garen Torikian.
 # Copyright, 2016-2017, by Yuki Izumi.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "set"
 require "stringio"
 
 module Markly
+	# @namespace
 	module Renderer
+		# Base class for renderers implemented in Ruby.
 		class Generic
+			# Initializes a renderer with rendering flags and extensions.
+			#
+			# @parameter flags [Integer] The enabled rendering flags.
+			# @parameter extensions [Array(Symbol)] The enabled extensions.
 			def initialize(flags: DEFAULT, extensions: [])
 				@flags = flags
 				@stream = StringIO.new(+"")
-				@need_blocksep = false
 				@in_tight = false
 				@in_plain = false
 				@tagfilter = extensions.include?(:tagfilter)
 			end
 			
+			# @attribute [Boolean] Whether the renderer is inside a tight container.
 			attr_accessor :in_tight
+			
+			# @attribute [Boolean] Whether the renderer is emitting plain text.
 			attr_accessor :in_plain
 			
+			# Writes strings, nodes, arrays of nodes, or child-node markers to the output.
+			#
+			# @parameter args [Array(Object)] Values to append or render.
 			def out(*args)
 				args.each do |arg|
 					if arg == :children
@@ -37,6 +48,10 @@ module Markly
 				end
 			end
 			
+			# Renders a node and returns the completed output for document nodes.
+			#
+			# @parameter node [Markly::Node] The node to render.
+			# @returns [String | Nil] The output string when rendering a document.
 			def render(node)
 				@node = node
 				if node.type == :document
@@ -49,42 +64,57 @@ module Markly
 				end
 			end
 			
+			# Renders a document node and all of its children.
+			#
+			# @parameter _node [Markly::Node] The document node.
 			def document(_node)
 				out(:children)
 			end
 			
-			def code_block(node)
-				code_block(node)
+			# Renders a code block node.
+			#
+			# Subclasses should override this callback.
+			# @parameter _node [Markly::Node] The code block node.
+			def code_block(_node)
+				raise NotImplementedError, "#{self.class} must implement #code_block"
 			end
 			
+			# Ignores reference-definition nodes, which have no direct output.
+			#
+			# @parameter _node [Markly::Node] The reference-definition node.
 			def reference_def(_node); end
 			
+			# Writes a newline unless the output is empty or already ends with one.
+			#
 			def cr
 				return if @stream.string.empty? || @stream.string[-1] == "\n"
 				
 				out("\n")
 			end
 			
-			def blocksep
-				out("\n")
-			end
-			
-			def containersep
-				cr unless @in_tight
-			end
-			
+			# Renders a block surrounded by normalized newlines.
+			#
+			# @yields {|| ...} The block content to render.
 			def block
 				cr
 				yield
 				cr
 			end
 			
+			# Renders content between opening and closing strings.
+			#
+			# @parameter starter [String] The opening output.
+			# @parameter ender [String] The closing output.
+			# @yields {|| ...} The container content to render.
 			def container(starter, ender)
 				out(starter)
 				yield
 				out(ender)
 			end
 			
+			# Renders a block in plain-text mode, suppressing structural markup.
+			#
+			# @yields {|| ...} The content to render as plain text.
 			def plain
 				old_in_plain = @in_plain
 				@in_plain = true