commonmarker 1.0.4-x64-mingw-ucrt → 1.1.0-x64-mingw-ucrt

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0927c9bca4fc3f31ed22b4410a1f755864a47c6765f319121bc86cdc8ee57e12'
-  data.tar.gz: a286020b5244d5d39ab7dd77516d65d59a44da44d8154686fec5e70b1c93421b
+  metadata.gz: 421d9fa8cf8dfe3f1d2aec2f6d807178e559fb9fa1eac70ccb705e3291cb66ca
+  data.tar.gz: 8f93b47d3413886cc15e86b7b047498aa037b07f6e07ac1605e62f143ff2717b
 SHA512:
-  metadata.gz: 921122ece29ec0b3a6b7d2eb07dc1b7fd77343f32f1ae67ed4e3d07eb7d1f8fcbd66de968215e40bc8258a6e86f1ad68e49fb58a22322821d782309310a2bd83
-  data.tar.gz: 8506a1881fb1c38139848f59c2105acd30cc29d03e7e6e52625286f9dbf4894ecea04e7d9230fd2f456d287deb2c846c1e5989237bbd7948cd925cfc9144d473
+  metadata.gz: d5bb4f64cab71d9bcac24e45ed8991af0fb7855fbfec05afa175762b710ecce11579ffe87a9c03f13e376a7dfa993638f225d59fdae8205a1edf187ef36abf0c
+  data.tar.gz: 111e08b3eb304d9014f106e72afc161a8df77a0d1c6e52893b2261dcda793d80da824ab6a39aa3273e11a767d40d02f0e8aa142f5cd2477da913adc92298b7b9

data/README.md

@@ -1,8 +1,5 @@
 # Commonmarker
 
-> **Note**
-> This README refers to the behavior in the new 1.0.0.pre gem.
-
 Ruby wrapper for Rust's [comrak](https://github.com/kivikakk/comrak) crate.
 
 It passes all of the CommonMark test suite, and is therefore spec-complete. It also includes extensions to the CommonMark spec as documented in the [GitHub Flavored Markdown spec](http://github.github.com/gfm/), such as support for tables, strikethroughs, and autolinking.
@@ -34,10 +31,108 @@ require 'commonmarker'
 Commonmarker.to_html('"Hi *there*"', options: {
     parse: { smart: true }
 })
-# <p>“Hi <em>there</em>”</p>\n
+# => <p>“Hi <em>there</em>”</p>\n
+```
+
+(The second argument is optional--[see below](#options-and-plugins) for more information.)
+
+### Generating a document
+
+You can also parse a string to receive a `:document` node. You can then print that node to HTML, iterate over the children, and do other fun node stuff. For example:
+
+```ruby
+require 'commonmarker'
+
+doc = Commonmarker.parse("*Hello* world", options: {
+    parse: { smart: true }
+})
+puts(doc.to_html) # => <p><em>Hello</em> world</p>\n
+
+doc.walk do |node|
+  puts node.type # => [:document, :paragraph, :emph, :text, :text]
+end
 ```
 
-The second argument is optional--[see below](#options) for more information.
+(The second argument is optional--[see below](#options-and-plugins) for more information.)
+
+When it comes to modifying the document, you can perform the following operations:
+
+- `insert_before`
+- `insert_after`
+- `prepend_child`
+- `append_child`
+- `delete`
+
+You can also get the source position of a node by calling `source_position`:
+
+```ruby
+doc = Commonmarker.parse("*Hello* world")
+puts doc.first_child.first_child.source_position
+# => {:start_line=>1, :start_column=>1, :end_line=>1, :end_column=>7}
+```
+
+You can also modify the following attributes:
+
+- `url`
+- `title`
+- `header_level`
+- `list_type`
+- `list_start`
+- `list_tight`
+- `fence_info`
+
+#### Example: Walking the AST
+
+You can use `walk` or `each` to iterate over nodes:
+
+- `walk` will iterate on a node and recursively iterate on a node's children.
+- `each` will iterate on a node and its children, but no further.
+
+```ruby
+require 'commonmarker'
+
+# parse some string
+doc = Commonmarker.parse("# The site\n\n [GitHub](https://www.github.com)")
+
+# Walk tree and print out URLs for links
+doc.walk do |node|
+  if node.type == :link
+    printf("URL = %s\n", node.url)
+  end
+end
+# => URL = https://www.github.com
+
+# Transform links to regular text
+doc.walk do |node|
+  if node.type == :link
+    node.insert_before(node.first_child)
+    node.delete
+  end
+end
+# => <h1><a href=\"#the-site\"></a>The site</h1>\n<p>GitHub</p>\n
+```
+
+#### Example: Converting a document back into raw CommonMark
+
+You can use `to_commonmark` on a node to render it as raw text:
+
+```ruby
+require 'commonmarker'
+
+# parse some string
+doc = Commonmarker.parse("# The site\n\n [GitHub](https://www.github.com)")
+
+# Transform links to regular text
+doc.walk do |node|
+  if node.type == :link
+    node.insert_before(node.first_child)
+    node.delete
+  end
+end
+
+doc.to_commonmark
+# => # The site\n\nGitHub\n
+```
 
 ## Options and plugins
 
@@ -56,21 +151,23 @@ Note that there is a distinction in comrak for "parse" options and "render" opti
 
 ### Parse options
 
-| Name                  | Description                                                                          | Default |
-| --------------------- | ------------------------------------------------------------------------------------ | ------- |
-| `smart`               | Punctuation (quotes, full-stops and hyphens) are converted into 'smart' punctuation. | `false` |
-| `default_info_string` | The default info string for fenced code blocks.                                      | `""`    |
+| Name                  | Description                                                                                                                                | Default |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
+| `smart`               | Punctuation (quotes, full-stops and hyphens) are converted into 'smart' punctuation.                                                       | `false` |
+| `default_info_string` | The default info string for fenced code blocks.                                                                                            | `""`    |
+| `relaxed_autolinks`   | Enable relaxing of the autolink extension parsing, allowing links to be recognized when in brackets, as well as permitting any url scheme. | `false` |
 
 ### Render options
 
-| Name              | Description                                                                                            | Default |
-| ----------------- | ------------------------------------------------------------------------------------------------------ | ------- |
-| `hardbreaks`      | [Soft line breaks](http://spec.commonmark.org/0.27/#soft-line-breaks) translate into hard line breaks. | `true`  |
-| `github_pre_lang` | GitHub-style `<pre lang="xyz">` is used for fenced code blocks with info tags.                         | `true`  |
-| `width`           | The wrap column when outputting CommonMark.                                                            | `80`    |
-| `unsafe`          | Allow rendering of raw HTML and potentially dangerous links.                                           | `false` |
-| `escape`          | Escape raw HTML instead of clobbering it.                                                              | `false` |
-| `sourcepos`       | Include source position attribute in HTML and XML output.                                              | `false` |
+| Name                 | Description                                                                                            | Default |
+| -------------------- | ------------------------------------------------------------------------------------------------------ | ------- |
+| `hardbreaks`         | [Soft line breaks](http://spec.commonmark.org/0.27/#soft-line-breaks) translate into hard line breaks. | `true`  |
+| `github_pre_lang`    | GitHub-style `<pre lang="xyz">` is used for fenced code blocks with info tags.                         | `true`  |
+| `width`              | The wrap column when outputting CommonMark.                                                            | `80`    |
+| `unsafe`             | Allow rendering of raw HTML and potentially dangerous links.                                           | `false` |
+| `escape`             | Escape raw HTML instead of clobbering it.                                                              | `false` |
+| `sourcepos`          | Include source position attribute in HTML and XML output.                                              | `false` |
+| `escaped_char_spans` | Wrap escaped characters in span tags                                                                   | `true`  |
 
 As well, there are several extensions which you can toggle in the same manner:
 
@@ -83,19 +180,21 @@ Commonmarker.to_html('"Hi *there*"', options: {
 
 ### Extension options
 
-| Name                     | Description                                                                                                         | Default |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------- | ------- |
-| `strikethrough`          | Enables the [strikethrough extension](https://github.github.com/gfm/#strikethrough-extension-) from the GFM spec.   | `true`  |
-| `tagfilter`              | Enables the [tagfilter extension](https://github.github.com/gfm/#disallowed-raw-html-extension-) from the GFM spec. | `true`  |
-| `table`                  | Enables the [table extension](https://github.github.com/gfm/#tables-extension-) from the GFM spec.                  | `true`  |
-| `autolink`               | Enables the [autolink extension](https://github.github.com/gfm/#autolinks-extension-) from the GFM spec.            | `true`  |
-| `tasklist`               | Enables the [task list extension](https://github.github.com/gfm/#task-list-items-extension-) from the GFM spec.     | `true`  |
-| `superscript`            | Enables the superscript Comrak extension.                                                                           | `false` |
-| `header_ids`             | Enables the header IDs Comrak extension. from the GFM spec.                                                         | `""`    |
-| `footnotes`              | Enables the footnotes extension per `cmark-gfm`.                                                                    | `false` |
-| `description_lists`      | Enables the description lists extension.                                                                            | `false` |
-| `front_matter_delimiter` | Enables the front matter extension.                                                                                 | `""`    |
-| `shortcodes`             | Enables the shortcodes extension.                                                                                   | `true`  |
+| Name                        | Description                                                                                                         | Default |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------- |
+| `strikethrough`             | Enables the [strikethrough extension](https://github.github.com/gfm/#strikethrough-extension-) from the GFM spec.   | `true`  |
+| `tagfilter`                 | Enables the [tagfilter extension](https://github.github.com/gfm/#disallowed-raw-html-extension-) from the GFM spec. | `true`  |
+| `table`                     | Enables the [table extension](https://github.github.com/gfm/#tables-extension-) from the GFM spec.                  | `true`  |
+| `autolink`                  | Enables the [autolink extension](https://github.github.com/gfm/#autolinks-extension-) from the GFM spec.            | `true`  |
+| `tasklist`                  | Enables the [task list extension](https://github.github.com/gfm/#task-list-items-extension-) from the GFM spec.     | `true`  |
+| `superscript`               | Enables the superscript Comrak extension.                                                                           | `false` |
+| `header_ids`                | Enables the header IDs Comrak extension. from the GFM spec.                                                         | `""`    |
+| `footnotes`                 | Enables the footnotes extension per `cmark-gfm`.                                                                    | `false` |
+| `description_lists`         | Enables the description lists extension.                                                                            | `false` |
+| `front_matter_delimiter`    | Enables the front matter extension.                                                                                 | `""`    |
+| `shortcodes`                | Enables the shortcodes extension.                                                                                   | `true`  |
+| `multiline_block_quotes`    | Enables the multiline block quotes extension.                                                                       | `false` |
+| `math_dollars`, `math_code` | Enables the math extension.                                                                                         | `false` |
 
 For more information on these options, see [the comrak documentation](https://github.com/kivikakk/comrak#usage).
 
@@ -205,26 +304,32 @@ If there were no errors, you're done! Otherwise, make sure to follow the comrak
 
 ## Benchmarks
 
-Some rough benchmarks:
-
 ```
-$ bundle exec rake benchmark
-
+❯ bundle exec rake benchmark
 input size = 11064832 bytes
 
+ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]
 Warming up --------------------------------------
-           redcarpet     2.000  i/100ms
-commonmarker with to_html
-                         1.000  i/100ms
-            kramdown     1.000  i/100ms
+  Markly.render_html     1.000 i/100ms
+Markly::Node#to_html     1.000 i/100ms
+Commonmarker.to_html     1.000 i/100ms
+Commonmarker::Node.to_html
+                         1.000 i/100ms
+Kramdown::Document#to_html
+                         1.000 i/100ms
 Calculating -------------------------------------
-           redcarpet     22.317  (± 4.5%) i/s -    112.000  in   5.036374s
-commonmarker with to_html
-                          5.815  (± 0.0%) i/s -     30.000  in   5.168869s
-            kramdown      0.327  (± 0.0%) i/s -      2.000  in   6.121486s
+  Markly.render_html     15.606 (±25.6%) i/s -     71.000 in   5.047132s
+Markly::Node#to_html     15.692 (±25.5%) i/s -     72.000 in   5.095810s
+Commonmarker.to_html      4.482 (± 0.0%) i/s -     23.000 in   5.137680s
+Commonmarker::Node.to_html
+                          5.092 (±19.6%) i/s -     25.000 in   5.072220s
+Kramdown::Document#to_html
+                          0.379 (± 0.0%) i/s -      2.000 in   5.277770s
 
 Comparison:
-           redcarpet:       22.3 i/s
-commonmarker with to_html:        5.8 i/s - 3.84x  (± 0.00) slower
-            kramdown:        0.3 i/s - 68.30x  (± 0.00) slower
+Markly::Node#to_html:       15.7 i/s
+  Markly.render_html:       15.6 i/s - same-ish: difference falls within error
+Commonmarker::Node.to_html:        5.1 i/s - 3.08x  slower
+Commonmarker.to_html:        4.5 i/s - 3.50x  slower
+Kramdown::Document#to_html:        0.4 i/s - 41.40x  slower
 ```

data/lib/commonmarker/config.rb

@@ -8,6 +8,7 @@ module Commonmarker
       parse: {
         smart: false,
         default_info_string: "",
+        relaxed_autolinks: false,
       }.freeze,
       render: {
         hardbreaks: true,
@@ -16,6 +17,7 @@ module Commonmarker
         unsafe: false,
         escape: false,
         sourcepos: false,
+        escaped_char_spans: true,
       }.freeze,
       extension: {
         strikethrough: true,
@@ -29,6 +31,9 @@ module Commonmarker
         description_lists: false,
         front_matter_delimiter: "",
         shortcodes: true,
+        multiline_block_quotes: false,
+        math_dollars: false,
+        math_code: false,
       },
       format: [:html].freeze,
     }.freeze

data/lib/commonmarker/node/ast.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Commonmarker
+  class Node
+    class Ast
+    end
+  end
+end

data/lib/commonmarker/node/inspect.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "pp"
+
+module Commonmarker
+  class Node
+    module Inspect
+      PP_INDENT_SIZE = 2
+
+      def inspect
+        PP.pp(self, +"", Float::INFINITY)
+      end
+
+      # @param printer [PrettyPrint] pp
+      def pretty_print(printer)
+        printer.group(PP_INDENT_SIZE, "#<#{self.class}(#{type}):", ">") do
+          printer.breakable
+
+          attrs = [
+            :source_position,
+            :string_content,
+            :url,
+            :title,
+            :header_level,
+            :list_type,
+            :list_start,
+            :list_tight,
+            :fence_info,
+          ].filter_map do |name|
+            [name, __send__(name)]
+          rescue StandardError
+            nil
+          end.compact
+
+          printer.seplist(attrs) do |name, value|
+            printer.text("#{name}=")
+            printer.pp(value)
+          end
+
+          if first_child
+            printer.breakable
+            printer.group(PP_INDENT_SIZE) do
+              children = []
+              node = first_child
+              while node
+                children << node
+                node = node.next_sibling
+              end
+              printer.text("children=")
+              printer.pp(children)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/commonmarker/node.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "commonmarker/node/ast"
+require "commonmarker/node/inspect"
+
+module Commonmarker
+  class Node
+    include Enumerable
+    include Inspect
+
+    # Public: An iterator that "walks the tree," descending into children recursively.
+    #
+    # blk - A {Proc} representing the action to take for each child
+    def walk(&block)
+      return enum_for(:walk) unless block
+
+      yield self
+      each do |child|
+        child.walk(&block)
+      end
+    end
+
+    # Public: Iterate over the children (if any) of the current pointer.
+    def each
+      return enum_for(:each) unless block_given?
+
+      child = first_child
+      while child
+        next_child = child.next_sibling
+        yield child
+        child = next_child
+      end
+    end
+
+    # Public: Converts a node to an HTML string.
+    #
+    # options - A {Hash} of render, parse, and extension options to transform the text.
+    # plugins - A {Hash} of additional plugins.
+    #
+    # Returns a {String} of HTML.
+    def to_html(options: Commonmarker::Config::OPTIONS, plugins: Commonmarker::Config::PLUGINS)
+      raise TypeError, "options must be a Hash; got a #{options.class}!" unless options.is_a?(Hash)
+
+      opts = Config.process_options(options)
+      plugins = Config.process_plugins(plugins)
+
+      node_to_html(options: opts, plugins: plugins).force_encoding("utf-8")
+    end
+
+    # Public: Convert the node to a CommonMark string.
+    #
+    # options - A {Symbol} or {Array of Symbol}s indicating the render options
+    # plugins - A {Hash} of additional plugins.
+    #
+    # Returns a {String}.
+    def to_commonmark(options: Commonmarker::Config::OPTIONS, plugins: Commonmarker::Config::PLUGINS)
+      raise TypeError, "options must be a Hash; got a #{options.class}!" unless options.is_a?(Hash)
+
+      opts = Config.process_options(options)
+      plugins = Config.process_plugins(plugins)
+
+      node_to_commonmark(options: opts, plugins: plugins).force_encoding("utf-8")
+    end
+  end
+end

data/lib/commonmarker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Commonmarker
-  VERSION = "1.0.4"
+  VERSION = "1.1.0"
 end

data/lib/commonmarker.rb

@@ -3,12 +3,29 @@
 require_relative "commonmarker/extension"
 
 require "commonmarker/utils"
+require "commonmarker/node"
 require "commonmarker/config"
 require "commonmarker/renderer"
 require "commonmarker/version"
 
 module Commonmarker
   class << self
+    # Public: Parses a CommonMark string into an HTML string.
+    #
+    # text - A {String} of text
+    # options - A {Hash} of render, parse, and extension options to transform the text.
+    #
+    # Returns the `parser` node.
+    def parse(text, options: Commonmarker::Config::OPTIONS)
+      raise TypeError, "text must be a String; got a #{text.class}!" unless text.is_a?(String)
+      raise TypeError, "text must be UTF-8 encoded; got #{text.encoding}!" unless text.encoding.name == "UTF-8"
+      raise TypeError, "options must be a Hash; got a #{options.class}!" unless options.is_a?(Hash)
+
+      opts = Config.process_options(options)
+
+      commonmark_parse(text, options: opts)
+    end
+
     # Public: Parses a CommonMark string into an HTML string.
     #
     # text - A {String} of text

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: commonmarker
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.1.0
 platform: x64-mingw-ucrt
 authors:
 - Garen Torikian
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-01-03 00:00:00.000000000 Z
+date: 2024-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -55,6 +55,9 @@ files:
 - lib/commonmarker/config.rb
 - lib/commonmarker/constants.rb
 - lib/commonmarker/extension.rb
+- lib/commonmarker/node.rb
+- lib/commonmarker/node/ast.rb
+- lib/commonmarker/node/inspect.rb
 - lib/commonmarker/renderer.rb
 - lib/commonmarker/utils.rb
 - lib/commonmarker/version.rb