apex-ruby 1.0.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 246b73a353cd5ad9f40ddf21474502ddf7b7b35e094c1c4ce5010c3615ae2536
+  data.tar.gz: 82f2120a839c164d26c258ff2b7f034bc26ddf4bfa93e61d248cb893219a30c2
+SHA512:
+  metadata.gz: cf4368bc5090e6dbefae29f5c6d8af8981af1272b477805f8bb3ba56dbef4bf8fe80df4555ababe4c1eae1bdb554f7341b5f3ab89f631eb292f973630b3d2760
+  data.tar.gz: 5ef47aa92805e6d98f3928c8c309eb4128db716227241c3363fa16130b42b8e52edea7d167bc0dc0226f795015a5389b2fc68a1a922e2a10194ce24dc79c8952

data/README.md

@@ -0,0 +1,119 @@
+# Apex Ruby Bindings
+
+Ruby bindings for the [Apex](https://github.com/ApexMarkdown/apex) unified Markdown processor.
+
+Apex is a C library that supports CommonMark, GFM, MultiMarkdown, Kramdown, and a number of
+Marked-specific extensions. This gem vendors the Apex sources and exposes a small, kramdown-style
+Ruby API for converting Markdown to HTML.
+
+## Requirements
+
+Before installing the gem, you must have the **cmark-gfm** C library available on your system. The gem compiles a native extension that links against it.
+
+- **macOS (Homebrew):**  
+  ```sh
+  brew install cmark-gfm
+  ```
+- **Other platforms:** Install the `cmark-gfm` package for your distribution and ensure development headers and `pkg-config` are available. See [cmark-gfm](https://github.com/github/cmark-gfm) for build instructions.
+
+If you run `gem install apex-ruby` without cmark-gfm installed, the build will fail with a clear error message and the same installation instructions.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "apex-ruby"
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+Or install it yourself as:
+
+```sh
+gem install apex-ruby
+```
+
+## Usage
+
+The main API mirrors the simplicity of the `kramdown` gem:
+
+```ruby
+require "apex"
+
+html = Apex::Document.markdown_to_html(text)
+```
+
+### Modes
+
+You can select a compatibility mode via the `mode:` keyword argument:
+
+```ruby
+html = Apex::Document.markdown_to_html(text, mode: :unified)      # default
+html = Apex::Document.markdown_to_html(text, mode: :gfm)          # or :github
+html = Apex::Document.markdown_to_html(text, mode: :multimarkdown) # or :mmd
+html = Apex::Document.markdown_to_html(text, mode: :commonmark)   # or :cmark
+html = Apex::Document.markdown_to_html(text, mode: :kramdown)
+```
+
+### Options
+
+Any additional keyword arguments are mapped directly to the underlying `apex_options` struct
+defined in `apex.h`. For example:
+
+```ruby
+html = Apex::Document.markdown_to_html(
+  text,
+  mode: :unified,
+  enable_tables: true,
+  enable_footnotes: true,
+  generate_header_ids: true,
+  relaxed_tables: true,
+  wikilink_extension: "html"
+)
+```
+
+See the Apex documentation for the complete list of options and their semantics.
+
+### Instance API
+
+If you prefer an object-oriented style (similar to `Kramdown::Document`), you can use
+`Apex::Document` instances:
+
+```ruby
+doc = Apex::Document.new(text, mode: :gfm, enable_tables: true)
+html = doc.to_html
+```
+
+### Jekyll
+
+You can use Apex as Jekyll’s Markdown converter instead of Kramdown via a custom converter plugin. See **[Jekyll-Apex.md](Jekyll-Apex.md)** for step-by-step instructions. *That integration is currently untested and documented as a placeholder; feedback from anyone willing to try it is welcome at [ApexMarkdown/apex-ruby/issues](https://github.com/ApexMarkdown/apex-ruby/issues).*
+
+## Development
+
+To run the test suite:
+
+```sh
+bundle exec rake test
+```
+
+To build and install the gem into all Ruby versions managed by [mise](https://mise.jdx.dev/):
+
+```sh
+bundle exec rake install
+```
+
+This will:
+
+1. Build `pkg/apex-ruby-<version>.gem`
+2. Run `gem install` for each Ruby reported by `mise ls ruby`.
+
+## License
+
+This project is licensed under the MIT license. See the Apex repository for the license of the
+underlying C implementation.
+

data/apex-ruby.gemspec

@@ -0,0 +1,31 @@
+require_relative "lib/apex/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = 'apex-ruby'
+  spec.version       = Apex::VERSION
+  spec.authors       = ['Brett Terpstra']
+  spec.email         = ['me@brettterpstra.com']
+
+  spec.summary       = 'Ruby bindings for the Apex unified Markdown processor'
+  spec.description   = 'Apex is a unified Markdown engine with CommonMark, GFM, MultiMarkdown, and Kramdown compatibility. This gem provides a kramdown-style Ruby API backed by the Apex C library.'
+  spec.homepage      = 'https://github.com/ApexMarkdown/apex-ruby'
+  spec.license       = 'MIT'
+
+  spec.required_ruby_version = '>= 3.0'
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir[
+      'README.md',
+      'apex-ruby.gemspec',
+      'lib/**/*.rb',
+      'ext/**/*.{c,h,rb}',
+      'ext/apex_ext/apex_src/**/*'
+    ]
+  end
+
+  spec.require_paths = ['lib']
+  spec.extensions    = ['ext/apex_ext/extconf.rb']
+
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri']   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+end

data/ext/apex_ext/apex_ext.c

@@ -0,0 +1,215 @@
+#include "ruby.h"
+#include "apex/apex.h"
+#include <strings.h>
+
+static VALUE mApex;
+static VALUE mApexNative;
+
+/* Map Ruby mode symbol/string to apex_mode_t. */
+static apex_mode_t
+mode_from_ruby(VALUE mode_val)
+{
+  if (NIL_P(mode_val)) return APEX_MODE_UNIFIED;
+
+  VALUE str = rb_funcall(mode_val, rb_intern("to_s"), 0);
+  const char *cstr = StringValueCStr(str);
+
+  if (!strcasecmp(cstr, "commonmark") || !strcasecmp(cstr, "cmark"))
+    return APEX_MODE_COMMONMARK;
+  if (!strcasecmp(cstr, "gfm") || !strcasecmp(cstr, "github"))
+    return APEX_MODE_GFM;
+  if (!strcasecmp(cstr, "multimarkdown") || !strcasecmp(cstr, "mmd"))
+    return APEX_MODE_MULTIMARKDOWN;
+  if (!strcasecmp(cstr, "kramdown"))
+    return APEX_MODE_KRAMDOWN;
+  if (!strcasecmp(cstr, "unified"))
+    return APEX_MODE_UNIFIED;
+
+  return APEX_MODE_UNIFIED;
+}
+
+static void
+set_bool(VALUE h, const char *key, bool *field)
+{
+  ID id = rb_intern(key);
+  VALUE k = ID2SYM(id);
+  VALUE v = rb_funcall(h, rb_intern("key?"), 1, k);
+  if (RTEST(v)) {
+    VALUE val = rb_hash_aref(h, k);
+    *field = RTEST(val);
+  }
+}
+
+static void
+set_int(VALUE h, const char *key, int *field)
+{
+  ID id = rb_intern(key);
+  VALUE k = ID2SYM(id);
+  VALUE v = rb_funcall(h, rb_intern("key?"), 1, k);
+  if (RTEST(v)) {
+    VALUE val = rb_hash_aref(h, k);
+    if (!NIL_P(val)) *field = NUM2INT(val);
+  }
+}
+
+static void
+set_cstr(VALUE h, const char *key, const char **field)
+{
+  ID id = rb_intern(key);
+  VALUE k = ID2SYM(id);
+  VALUE v = rb_funcall(h, rb_intern("key?"), 1, k);
+  if (!RTEST(v)) return;
+
+  VALUE val = rb_hash_aref(h, k);
+  if (NIL_P(val)) {
+    *field = NULL;
+  } else {
+    val = StringValue(val);
+    *field = StringValueCStr(val);
+  }
+}
+
+/* Build apex_options from a Ruby Hash. */
+static apex_options
+options_from_hash(VALUE h)
+{
+  apex_options o = apex_options_default();
+
+  if (NIL_P(h) || TYPE(h) != T_HASH) return o;
+
+  VALUE mode_val = rb_hash_aref(h, ID2SYM(rb_intern("mode")));
+  o.mode = mode_from_ruby(mode_val);
+
+  /* Feature flags */
+  set_bool(h, "enable_plugins",     &o.enable_plugins);
+  set_bool(h, "enable_tables",      &o.enable_tables);
+  set_bool(h, "enable_footnotes",   &o.enable_footnotes);
+  set_bool(h, "enable_definition_lists", &o.enable_definition_lists);
+  set_bool(h, "enable_smart_typography", &o.enable_smart_typography);
+  set_bool(h, "enable_math",        &o.enable_math);
+  set_bool(h, "enable_wiki_links",  &o.enable_wiki_links);
+  set_bool(h, "enable_task_lists",  &o.enable_task_lists);
+  set_bool(h, "enable_attributes",  &o.enable_attributes);
+  set_bool(h, "enable_callouts",    &o.enable_callouts);
+  set_bool(h, "enable_divs",        &o.enable_divs);
+  set_bool(h, "enable_spans",       &o.enable_spans);
+
+  /* Metadata handling */
+  set_bool(h, "strip_metadata",            &o.strip_metadata);
+  set_bool(h, "enable_metadata_variables", &o.enable_metadata_variables);
+  set_bool(h, "enable_metadata_transforms",&o.enable_metadata_transforms);
+
+  /* File inclusion */
+  set_bool(h, "enable_file_includes", &o.enable_file_includes);
+  set_int (h, "max_include_depth",    &o.max_include_depth);
+  set_cstr(h, "base_directory",       &o.base_directory);
+
+  /* Output options */
+  set_bool(h, "unsafe",          &o.unsafe);
+  set_bool(h, "validate_utf8",   &o.validate_utf8);
+  set_bool(h, "github_pre_lang", &o.github_pre_lang);
+  set_bool(h, "standalone",      &o.standalone);
+  set_bool(h, "pretty",          &o.pretty);
+  set_cstr(h, "document_title",  &o.document_title);
+
+  /* Line break handling */
+  set_bool(h, "hardbreaks", &o.hardbreaks);
+  set_bool(h, "nobreaks",   &o.nobreaks);
+
+  /* Header ID generation */
+  set_bool(h, "generate_header_ids", &o.generate_header_ids);
+  set_bool(h, "header_anchors",      &o.header_anchors);
+  set_int (h, "id_format",           &o.id_format);
+
+  /* Table options */
+  set_bool(h, "relaxed_tables",     &o.relaxed_tables);
+  set_int (h, "caption_position",   &o.caption_position);
+  set_bool(h, "per_cell_alignment", &o.per_cell_alignment);
+
+  /* List options */
+  set_bool(h, "allow_mixed_list_markers", &o.allow_mixed_list_markers);
+  set_bool(h, "allow_alpha_lists",        &o.allow_alpha_lists);
+
+  /* Superscript and subscript */
+  set_bool(h, "enable_sup_sub",      &o.enable_sup_sub);
+
+  /* Strikethrough */
+  set_bool(h, "enable_strikethrough",&o.enable_strikethrough);
+
+  /* Autolink options */
+  set_bool(h, "enable_autolink",  &o.enable_autolink);
+  set_bool(h, "obfuscate_emails", &o.obfuscate_emails);
+
+  /* Image options */
+  set_bool(h, "enable_image_captions", &o.enable_image_captions);
+  set_bool(h, "title_captions_only",   &o.title_captions_only);
+
+  /* Wiki link options */
+  set_int (h, "wikilink_space",     &o.wikilink_space);
+  set_cstr(h, "wikilink_extension", &o.wikilink_extension);
+  set_bool(h, "wikilink_sanitize",  &o.wikilink_sanitize);
+
+  /* ARIA accessibility options */
+  set_bool(h, "enable_aria", &o.enable_aria);
+
+  /* Emoji options */
+  set_bool(h, "enable_emoji_autocorrect", &o.enable_emoji_autocorrect);
+
+  /* Syntax highlighting options */
+  set_cstr(h, "code_highlighter",    &o.code_highlighter);
+  set_bool(h, "code_line_numbers",   &o.code_line_numbers);
+  set_bool(h, "highlight_language_only", &o.highlight_language_only);
+
+  /* Marked / integration-specific options */
+  set_bool(h, "enable_widont",           &o.enable_widont);
+  set_bool(h, "code_is_poetry",          &o.code_is_poetry);
+  set_bool(h, "enable_markdown_in_html", &o.enable_markdown_in_html);
+  set_bool(h, "random_footnote_ids",     &o.random_footnote_ids);
+  set_bool(h, "enable_hashtags",         &o.enable_hashtags);
+  set_bool(h, "style_hashtags",          &o.style_hashtags);
+  set_bool(h, "proofreader_mode",        &o.proofreader_mode);
+  set_bool(h, "hr_page_break",           &o.hr_page_break);
+  set_bool(h, "title_from_h1",           &o.title_from_h1);
+  set_bool(h, "page_break_before_footnotes", &o.page_break_before_footnotes);
+
+  return o;
+}
+
+/*
+ * call-seq:
+ *   Apex::Native.markdown_to_html(text, options = {}) -> String
+ *
+ * Render Markdown +text+ to HTML using the Apex C library.
+ */
+static VALUE
+rb_apex_markdown_to_html(int argc, VALUE *argv, VALUE self)
+{
+  VALUE text, opts_hash;
+  rb_scan_args(argc, argv, "11", &text, &opts_hash);
+
+  Check_Type(text, T_STRING);
+  if (NIL_P(opts_hash)) opts_hash = rb_hash_new();
+
+  const char *c_text = RSTRING_PTR(text);
+  size_t len = (size_t)RSTRING_LEN(text);
+
+  apex_options opts = options_from_hash(opts_hash);
+
+  char *out = apex_markdown_to_html(c_text, len, &opts);
+  if (!out) return Qnil;
+
+  VALUE rb_out = rb_utf8_str_new_cstr(out);
+  apex_free_string(out);
+  return rb_out;
+}
+
+void
+Init_apex_ext(void)
+{
+  mApex       = rb_define_module("Apex");
+  mApexNative = rb_define_module_under(mApex, "Native");
+
+  rb_define_singleton_method(mApexNative, "markdown_to_html",
+                             rb_apex_markdown_to_html, -1);
+}
+

data/ext/apex_ext/apex_src/BENCHMARK.md

@@ -0,0 +1,32 @@
+# Apex Markdown Processor - Performance Benchmark
+
+## Test Document
+
+- **File:** `/Users/ttscoff/Desktop/Code/apex/tests/fixtures/comprehensive_test.md`
+- **Lines:**      619
+- **Words:**     2581
+- **Size:**    17008 bytes
+
+## Output Modes
+
+| Mode | Iterations | Average (ms) | Min (ms) | Max (ms) | Throughput (words/sec) |
+|------|------------|--------------|---------|---------|------------------------|
+| Fragment Mode (default HTML output) | 50 | 21 | 20 | 27 | 129050.00 |
+| Pretty-Print Mode (formatted HTML) | 50 | 22 | 21 | 26 | 129050.00 |
+| Standalone Mode (complete HTML document) | 50 | 21 | 20 | 24 | 129050.00 |
+| Standalone + Pretty (full features) | 50 | 22 | 20 | 25 | 129050.00 |
+
+## Mode Comparison
+
+| Mode | Iterations | Average (ms) | Min (ms) | Max (ms) | Throughput (words/sec) |
+|------|------------|--------------|---------|---------|------------------------|
+| CommonMark Mode (minimal, spec-compliant) | 50 | 12 | 10 | 35 | 258100.00 |
+| GFM Mode (GitHub Flavored Markdown) | 50 | 20 | 19 | 22 | 129050.00 |
+| MultiMarkdown Mode (metadata, footnotes, tables) | 50 | 21 | 20 | 23 | 129050.00 |
+| Kramdown Mode (attributes, definition lists) | 50 | 20 | 19 | 22 | 129050.00 |
+| Unified Mode (all features enabled) | 50 | 21 | 20 | 24 | 129050.00 |
+| Default Mode (unified, all features) | 50 | 21 | 20 | 24 | 129050.00 |
+
+---
+
+*Benchmark Complete*

data/ext/apex_ext/apex_src/BENCHMARK_COMPARISON.md

@@ -0,0 +1,67 @@
+# Markdown Processor Comparison Benchmark
+
+## Available Tools
+
+Found 7 tools:
+- apex
+- cmark-gfm
+- cmark
+- pandoc
+- multimarkdown
+- kramdown
+- marked
+
+## Processor Comparison
+
+**File:** `/Users/ttscoff/Desktop/Code/apex/tests/fixtures/comprehensive_test.md` (17008 bytes, 619 lines)
+
+| Processor | Time (ms) | Relative |
+|-----------|-----------|----------|
+| apex | 14.57 | 1.00x |
+| cmark-gfm | 3.13 | .21x |
+| cmark | 2.39 | .16x |
+| pandoc | 91.13 | 6.25x |
+| multimarkdown | 2.31 | .15x |
+| kramdown | 317.27 | 21.77x |
+| marked | 86.59 | 5.94x |
+
+## Processor Comparison
+
+**File:** `/Users/ttscoff/Desktop/Code/apex/tests/fixtures/large_doc.md` (29275 bytes, 1094 lines)
+
+| Processor | Time (ms) | Relative |
+|-----------|-----------|----------|
+| apex | 9.93 | 1.00x |
+| cmark-gfm | 2.32 | .23x |
+| cmark | 2.94 | .29x |
+| pandoc | 114.57 | 11.53x |
+| multimarkdown | 2.78 | .27x |
+| kramdown | 319.61 | 32.18x |
+| marked | 85.88 | 8.64x |
+
+## Apex Mode Comparison
+
+**Test File:** `/Users/ttscoff/Desktop/Code/apex/tests/fixtures/comprehensive_test.md`
+
+| Mode | Time (ms) | Relative |
+|------|-----------|----------|
+| commonmark | 2.98 | 1.00x |
+| gfm | 14.01 | 4.69x |
+| mmd | 13.83 | 4.63x |
+| kramdown | 12.09 | 4.05x |
+| unified | 14.00 | 4.69x |
+| default (unified) | 15.67 | 5.25x |
+
+## Apex Feature Overhead
+
+| Features | Time (ms) |
+|----------|-----------|
+| CommonMark (minimal) | 3.07 |
+| + GFM tables/strikethrough | 13.78 |
+| + All Apex features | 15.34 |
+| + Pretty printing | 15.93 |
+| + Standalone document | 16.08 |
+
+---
+
+*Benchmark Complete*