md4c 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c064e8f934590bb55c5edfd5d1cb73821ef8c424347a58d48f9b4c00ccb85b8b
-  data.tar.gz: 35ca53caca0fd1184ee86a5330b720f00e87af94cfa8fd0f86b1ffaab5ed4819
+  metadata.gz: e5fd2f4d2ffb435e1c54d1113f52900e4420d081f07cb9b15ee9edf5ba29e044
+  data.tar.gz: 56dddc4ad5106e31c46aef15f6c061d8da99371e38b4be164efcd26f2ae8bb2e
 SHA512:
-  metadata.gz: 919321d66c7e6a59676c471d97210c805e60492fabc706ac1b9d53d0d31362edc85d9c8237ea2eee3b67d69fa18f62d12ead2fd30c46ffbacd1222322d732a4b
-  data.tar.gz: ff3fd7f61e2fcbb8ce5a19d7a67605752df59c67efaa19b2fe7b36f0e2cc45434cd032c5af10f439832abbfb00739bb9fb7b0b216f04c5d36c3839211c5c659c
+  metadata.gz: e21e520b23859198597e3a5a15806abac7f65a6df15e37cfe555dafb7462ff9bf89f62e29f8064367df90d14390c2b9b9f11f7a037d377465db8ff293634c26b
+  data.tar.gz: 68a9668c3180204220ff663b0ffcd14d3cc92befdf1d02da26908e3204474470cd787250995cd35933afd01e5b7e1f79ae8591c9e40bc1580e0fb689ff7fbddf

data/.envrc

@@ -6,3 +6,4 @@ path_add C_INCLUDE_PATH /usr/local/include/ruby-4.0
 path_add C_INCLUDE_PATH /usr/local/include/ruby-4.0/x86_64-openbsd
 path_add C_INCLUDE_PATH /usr/local/llvm21/lib/clang/21/include
 path_add LD_LIBRARY_PATH /usr/local/lib
+export LANG=en_US.UTF-8

data/.rdoc_options

@@ -0,0 +1,9 @@
+title: MD4C RubyGem
+main_page: README.md
+exclude:
+  - Gemfile*
+  - Rakefile
+  - bin/
+  - compile_flags.txt
+  - tmp/
+  - .direnv/

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.1.0 - 2026-08-17
+
+- Fixed reader methods which gets a sequence of text nodes.
+  Remove the `StringAttribute` class and its usages.  Now `content`
+  methods return `Array` of text nodes.
+- Use UTF-8 encoding for potentially multibyte text contents.
+- Add RBS type definitions.
+- Add some doc-comments.
+- Update readme with simple usages.
+
 ## 0.0.1 - 2026-08-14
 
 - Initial release

data/README.md

@@ -1,26 +1,58 @@
 # Markdown for C, for Ruby
 
-This is a [MD4C](https://github.com/mity/md4c) binding for Ruby.
+This is a [MD4C](https://github.com/mity/md4c) binding for Ruby.  It
+can parse Markdown documents based on the CommonMark and with some
+extensions, including the GitHub Flavored Markdown.  It can also
+convert Markdown documents into HTML.
+
+Project links: [Codeberg][repo], [RubyGems.org][rubygems]
+
+[rubygems]: https://rubygems.org/gems/md4c
+[repo]: https://codeberg.org/gemmaro/ruby-md4c
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+This gem requires the MD4C C library.
 
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add md4c
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install md4c
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+The parser uses the callback approach:
+
+```ruby
+require 'md4c'
+parser = MD4C::Parser.new
+
+parser.on_enter_block do |block|
+  # do something with block
+end
+
+parser.parse(source)
+```
+
+There are also `on_leave_block`, `on_enter_span`, `on_leave_span`, and
+`on_text` methods.
+
+The `Parser`'s `initialize` method takes options for extensions.  For example,
+
+```ruby
+parser = MD4C::Parser.new(permissive_atx_headers: true)
+# [...]
+parser.parse(<<~END_MARKDOWN)
+#this is now header
+END_MARKDOWN
+```
 
 ## Development
 
@@ -37,7 +69,7 @@ tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/md4c.
+Bug reports and pull requests are welcome.
 
 ## License
 

data/ext/md4c/rb_md4c.c

@@ -21,9 +21,10 @@
 #include <ruby.h>
 #include <stddef.h>
 
-/* rbm_ prefix means "Ruby MD4C". */
+/* rbm_ prefix means "Ruby MD4C".
+ */
 
-static VALUE rb_mMD4C, rbm_cParser, rbm_cStringAttribute, /* blocks --> */
+static VALUE rb_mMD4C, rbm_cParser, /* blocks --> */
     rbm_cUnorderedList, rbm_cOrderedList, rbm_cListItem, rbm_cHeading,
     rbm_cCodeBlock, rbm_cTable, rbm_cTableHeader, rbm_cTableData,
     /* spans --> */ rbm_cAnchor, rbm_cImage, rbm_cWikiLink,
@@ -157,6 +158,11 @@ rbm_get_parser_flags (ID kwargs_vals[])
   return flags;
 }
 
+/**
+ * :call-seq: Parser.new (**flags) -> Parser
+ *
+ * All flags are false by default, which means it is CommonMark.
+ */
 static VALUE
 rbm_cParser_m_initialize (int argc, VALUE *argv, VALUE self)
 {
@@ -172,6 +178,9 @@ rbm_cParser_m_initialize (int argc, VALUE *argv, VALUE self)
   return self;
 }
 
+/**
+ * :call-seq: on_enter_block { |block_node| ... }
+ */
 static VALUE
 rbm_cParser_m_on_enter_block (VALUE self)
 {
@@ -179,6 +188,9 @@ rbm_cParser_m_on_enter_block (VALUE self)
   return p->on_enter_block = rb_block_proc ();
 }
 
+/**
+ * :call-seq: on_leave_block { |block_node| ... }
+ */
 static VALUE
 rbm_cParser_m_on_leave_block (VALUE self)
 {
@@ -186,6 +198,9 @@ rbm_cParser_m_on_leave_block (VALUE self)
   return p->on_leave_block = rb_block_proc ();
 }
 
+/**
+ * :call-seq: on_enter_span { |span_node| ... }
+ */
 static VALUE
 rbm_cParser_m_on_enter_span (VALUE self)
 {
@@ -193,6 +208,9 @@ rbm_cParser_m_on_enter_span (VALUE self)
   return p->on_enter_span = rb_block_proc ();
 }
 
+/**
+ * :call-seq: on_leave_span { |span_node| ... }
+ */
 static VALUE
 rbm_cParser_m_on_leave_span (VALUE self)
 {
@@ -200,6 +218,9 @@ rbm_cParser_m_on_leave_span (VALUE self)
   return p->on_leave_span = rb_block_proc ();
 }
 
+/**
+ * :call-seq: on_text { |text_node| ... }
+ */
 static VALUE
 rbm_cParser_m_on_text (VALUE self)
 {
@@ -207,26 +228,6 @@ rbm_cParser_m_on_text (VALUE self)
   return p->on_text = rb_block_proc ();
 }
 
-static size_t
-rbm_cStringAttribute_size (const void *ptr)
-{
-  return sizeof (MD_ATTRIBUTE);
-}
-
-static const rb_data_type_t rbm_cStringAttribute_type
-    = { .wrap_struct_name = "MD4C string attribute",
-        .function
-        = { .dfree = RUBY_DEFAULT_FREE, .dsize = rbm_cStringAttribute_size },
-        .flags = RUBY_TYPED_FREE_IMMEDIATELY };
-
-static VALUE
-rbm_cStringAttribute_alloc (VALUE self)
-{
-  MD_BLOCK_CODE_DETAIL *attr = ruby_xmalloc (sizeof (MD_ATTRIBUTE));
-  return rb_data_typed_object_wrap (rbm_cStringAttribute, attr,
-                                    &rbm_cStringAttribute_type);
-}
-
 static VALUE
 rbm_get_text_class (MD_TEXTTYPE type)
 {
@@ -259,23 +260,22 @@ rbm_get_text_class (MD_TEXTTYPE type)
 }
 
 static VALUE
-rbm_cStringAttribute_m_each (VALUE self)
+rbm_from_string_attribute (MD_ATTRIBUTE attr)
 {
-  RETURN_ENUMERATOR (self, 0, NULL);
-
-  MD_ATTRIBUTE *attr = RTYPEDDATA_DATA (self);
-  size_t index = 0;
-  while (attr->substr_offsets[index] >= attr->size)
+  if (attr.text == NULL)
+    return RUBY_Qnil;
+  VALUE ary = rb_ary_new ();
+  for (size_t index = 0; attr.substr_offsets[index] < attr.size; index++)
     {
-      VALUE klass = rbm_get_text_class (attr->substr_types[index]);
-      VALUE substr = rb_class_new_instance (0, NULL, klass);
-      VALUE content = rb_str_new (attr->text + attr->substr_offsets[index],
-                                  attr->substr_offsets[index + 1]
-                                      - attr->substr_offsets[index]);
-      rb_iv_set (substr, "@content", content);
-      rb_yield (substr);
+      VALUE klass = rbm_get_text_class (attr.substr_types[index]);
+      VALUE text = rb_class_new_instance (0, NULL, klass);
+      VALUE content = rb_utf8_str_new (attr.text + attr.substr_offsets[index],
+                                       attr.substr_offsets[index + 1]
+                                           - attr.substr_offsets[index]);
+      rb_iv_set (text, "@content", content);
+      rb_ary_push (ary, text);
     }
-  return RUBY_Qnil;
+  return ary;
 }
 
 static VALUE
@@ -354,12 +354,10 @@ rbm_callback_block_arguments (MD_BLOCKTYPE type, void *detail)
         arg = rb_class_new_instance (0, NULL, rbm_cCodeBlock);
         MD_BLOCK_CODE_DETAIL *d = detail;
 
-        VALUE info = rb_class_new_instance (0, NULL, rbm_cStringAttribute);
-        RTYPEDDATA_DATA (info) = &d->info;
+        VALUE info = rbm_from_string_attribute (d->info);
         rb_iv_set (arg, "@info", info);
 
-        VALUE lang = rb_class_new_instance (0, NULL, rbm_cStringAttribute);
-        RTYPEDDATA_DATA (lang) = &d->lang;
+        VALUE lang = rbm_from_string_attribute (d->lang);
         rb_iv_set (arg, "@lang", lang);
 
         VALUE fence
@@ -495,12 +493,10 @@ rbm_callback_span_arguments (MD_SPANTYPE type, void *detail)
 
         MD_SPAN_A_DETAIL *d = detail;
 
-        VALUE href = rb_class_new_instance (0, NULL, rbm_cStringAttribute);
-        RTYPEDDATA_DATA (href) = &d->href;
+        VALUE href = rbm_from_string_attribute (d->href);
         rb_iv_set (arg, "@href", href);
 
-        VALUE title = rb_class_new_instance (0, NULL, rbm_cStringAttribute);
-        RTYPEDDATA_DATA (title) = &d->title;
+        VALUE title = rbm_from_string_attribute (d->title);
         rb_iv_set (arg, "@title", title);
 
         VALUE autolink = d->is_autolink ? RUBY_Qtrue : RUBY_Qfalse;
@@ -514,12 +510,10 @@ rbm_callback_span_arguments (MD_SPANTYPE type, void *detail)
 
         MD_SPAN_IMG_DETAIL *d = detail;
 
-        VALUE src = rb_class_new_instance (0, NULL, rbm_cStringAttribute);
-        RTYPEDDATA_DATA (src) = &d->src;
+        VALUE src = rbm_from_string_attribute (d->src);
         rb_iv_set (arg, "@src", src);
 
-        VALUE title = rb_class_new_instance (0, NULL, rbm_cStringAttribute);
-        RTYPEDDATA_DATA (title) = &d->title;
+        VALUE title = rbm_from_string_attribute (d->title);
         rb_iv_set (arg, "@title", title);
         break;
       }
@@ -547,8 +541,7 @@ rbm_callback_span_arguments (MD_SPANTYPE type, void *detail)
 
         MD_SPAN_WIKILINK_DETAIL *d = detail;
 
-        VALUE target = rb_class_new_instance (0, NULL, rbm_cStringAttribute);
-        RTYPEDDATA_DATA (target) = &d->target;
+        VALUE target = rbm_from_string_attribute (d->target);
         rb_iv_set (arg, "@target", target);
         break;
       }
@@ -592,7 +585,7 @@ rbm_callback_text (MD_TEXTTYPE type, const MD_CHAR *text, MD_SIZE size,
   struct rbm_cParser *p = userdata;
   if (!p->on_text)
     return 0;
-  VALUE string = rb_str_new (text, size);
+  VALUE string = rb_utf8_str_new (text, size);
   VALUE klass = rbm_get_text_class (type);
   VALUE args = rb_ary_new ();
   VALUE arg = rb_class_new_instance (0, NULL, klass);
@@ -602,6 +595,9 @@ rbm_callback_text (MD_TEXTTYPE type, const MD_CHAR *text, MD_SIZE size,
   return 0;
 }
 
+/**
+ * :call-seq: parse (source)
+ */
 static VALUE
 rbm_cParser_m_parse (VALUE self, VALUE source)
 {
@@ -632,12 +628,17 @@ rbm_markdown_to_html_callback (const MD_CHAR *input, MD_SIZE size,
                                void *userdata)
 {
   struct rbm_markdown_to_html_userdata *data = userdata;
-  VALUE text = rb_str_new (input, size);
+  VALUE text = rb_utf8_str_new (input, size);
   VALUE args = rb_ary_new ();
   rb_ary_push (args, text);
   rb_proc_call (data->block, args);
 }
 
+/**
+ * call-seq: MD4C.markdown_to_html (input, verbatim_entities: false, skip_utf8_bom: false, xhtml: false, **parser_flags) { |chunk| ... }
+ *
+ * +parser_flags+ are the same flags as MD4C::Parser.new method's.
+ */
 static VALUE
 rbm_m_markdown_to_html (int argc, VALUE *argv, VALUE self)
 {
@@ -686,12 +687,6 @@ Init_md4c (void)
 {
   rb_mMD4C = rb_define_module ("MD4C");
 
-  rbm_cStringAttribute
-      = rb_define_class_under (rb_mMD4C, "StringAttribute", rb_cObject);
-  rb_define_alloc_func (rbm_cStringAttribute, rbm_cStringAttribute_alloc);
-  rb_define_method (rbm_cStringAttribute, "each", rbm_cStringAttribute_m_each,
-                    0);
-
   rbm_cUnorderedList
       = rb_define_class_under (rb_mMD4C, "UnorderedList", rb_cObject);
   rbm_cOrderedList

data/lib/md4c/version.rb

@@ -18,5 +18,5 @@
 #++
 
 module MD4C
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/md4c.rb

@@ -23,11 +23,13 @@ require "md4c/md4c"
 # The class naming is based off the CommonMark specification, the
 # GitHub Flavored Markdown specification, and the MDN document about
 # HTML.
+#
+# Some classes have +content+ reader method (attribute).  This returns
+# Array of text nodes.
+#
+# For potentially multibyte contents, UTF-8 encoding is used.
+# Otherwise no encoding is specified (which means US-ASCII).
 module MD4C
-  class StringAttribute
-    include Enumerable
-  end
-
   class UnorderedList
     attr_reader :mark
 
@@ -96,7 +98,7 @@ module MD4C
     attr_reader :target
   end
 
-  module EqualByContent
+  module EqualByContent # :nodoc:
     def ==(other)
       self.class == other.class && @content == other.content
     end

data/sig/md4c.rbs

@@ -1,4 +1,128 @@
 module MD4C
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  type text_node = MD4C::NormalText | MD4C::NullChar | MD4C::HardBreak | MD4C::SoftBreak | MD4C::Entity | MD4C::CodeText | MD4C::HTMLText | MD4C::LaTeXMathText
+  type block_node = MD4C::UnorderedList | MD4C::OrderedList | MD4C::ListItem | MD4C::Heading | MD4C::CodeBlock | MD4C::Table | MD4C::TableHeader | MD4C::TableData
+  type span_node = MD4C::Anchor | MD4C::Image | MD4C::WikiLink
+  type align = nil | :left | :center | :right
+
+  def self.markdown_to_html: (input: String) { (text_node) -> void } -> void
+
+  class Anchor
+    attr_reader href: Array[text_node]
+    attr_reader title: Array[text_node]
+    def autolink?: -> bool
+  end
+
+  class CodeBlock
+    attr_reader fence_char: String
+    attr_reader info: Array[text_node]
+    attr_reader lang: Array[text_node]
+  end
+
+  class CodeText
+    attr_reader content: Array[text_node]
+  end
+
+  class Entity
+    attr_reader content: Array[text_node]
+  end
+
+  class HTMLText
+    attr_reader content: Array[text_node]
+  end
+
+  class HardBreak
+    attr_reader content: Array[text_node]
+  end
+
+  class Heading
+    attr_reader level: Integer
+  end
+
+  class Image
+    attr_reader src: Array[text_node]
+    attr_reader title: Array[text_node]
+  end
+
+  class LaTeXMathText
+    attr_reader content: Array[text_node]
+  end
+
+  class ListItem
+    attr_reader task_mark: String
+    attr_reader task_mark_offset: Integer
+    def task?: -> bool
+  end
+
+  class NormalText
+    attr_reader content: Array[text_node]
+  end
+
+  class NullChar
+    attr_reader content: Array[text_node]
+  end
+
+  class OrderedList
+    attr_reader mark_delimiter: String
+    attr_reader start: Integer
+    def tight?: -> bool
+  end
+
+  class Parser
+    def initialize: (
+      collapse_whitespace: bool,
+      permissive_atx_headers: bool,
+      permissive_url_autolinks: bool,
+      permissive_email_autolinks: bool,
+      no_indented_codeblocks: bool,
+      no_html_blocks: bool,
+      no_html_spans: bool,
+      tables: bool,
+      strikethrough: bool,
+      permissive_www_autolinks: bool,
+      task_lists: bool,
+      latex_math_spans: bool,
+      wiki_links: bool,
+      underline: bool,
+      hard_soft_breaks: bool,
+      permissive_autolinks: bool,
+      no_html: bool,
+      commonmark: bool,
+      github: bool) -> MD4C::Parser
+
+    def on_enter_block: { (block_node) -> void } -> void
+    def on_leave_block: { (block_node) -> void } -> void
+    def on_enter_span: { (span_node) -> void } -> void
+    def on_leave_span: { (span_node) -> void } -> void
+    def on_text: { (text_node) -> void } -> void
+    def parse: (String) -> void
+  end
+
+  class SoftBreak
+    attr_reader content: Array[text_node]
+  end
+
+  class Table
+    attr_reader body_row_count: Integer
+    attr_reader col_count: Integer
+    attr_reader head_row_count: Integer
+  end
+
+  class TableData
+    attr_reader align: align
+  end
+
+  class TableHeader
+    attr_reader align: align
+  end
+
+  class UnorderedList
+    attr_reader mark: String
+    def tight?: -> bool
+  end
+
+  class WikiLink
+    attr_reader target: Array[text_node]
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: md4c
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - gemmaro
@@ -21,6 +21,7 @@ extra_rdoc_files: []
 files:
 - ".clang-format"
 - ".envrc"
+- ".rdoc_options"
 - CHANGELOG.md
 - COPYING
 - README.md