apex-ruby 1.0.6

data/ext/apex_ext/apex_src/examples/kbd_plugin.rb

@@ -0,0 +1,250 @@
+#!/usr/bin/env ruby
+# Minimal Apex pre-parse plugin for {% kbd ... %} syntax
+#
+# Protocol:
+#  - Reads a single JSON object from stdin:
+#      { "version": 1, "plugin_id": "...", "phase": "pre_parse", "text": "..." }
+#  - Writes the transformed markdown text to stdout (no JSON response).
+#
+# To use with Apex:
+#   export APEX_PRE_PARSE_PLUGIN="/usr/bin/env ruby /path/to/apex/examples/kbd_plugin.rb"
+#   apex input.md
+
+require 'json'
+
+payload = JSON.parse($stdin.read)
+text = payload['text'] || ''
+
+class String
+  def clean_combo
+    gsub!(/(?<=\S)-(?=\S)/, ' ')
+    gsub!(/\b(comm(and)?|cmd|clover)\b/i, '@')
+    gsub!(/\b(cont(rol)?|ctr?l)\b/i, '^')
+    gsub!(/\b(opt(ion)?|alt)\b/i, '~')
+    gsub!(/\bshift\b/i, '$')
+    gsub!(/\b(func(tion)?|fn)\b/i, '*')
+    gsub!(/\b(hyper)\b/i, '%')
+    self
+  end
+
+  def lower_to_upper
+    doubles = [
+      [',', '<'], ['.', '>'], ['/', '?'], [';', ':'], ["'", '"'],
+      ['[', '{'], [']', '}'], ['\\', '|'], ['-', '_'], ['=', '+']
+    ]
+    lowers = doubles.map { |d| d[0] }
+    uppers = doubles.map { |d| d[1] }
+    lowers.include?(self) ? uppers[lowers.index(self)] : self
+  end
+
+  def upper?
+    %w(< > ? : " { } | ! @ # $ % ^ & * \( \) _ +).include?(self)
+  end
+
+  def clean_combo!
+    replace clean_combo
+  end
+
+  def to_mod
+    characters = {
+      '^' => '⌃',
+      '~' => '⌥',
+      '$' => '⇧',
+      '@' => '⌘',
+      '*' => 'Fn',
+      '%' => 'Hyper'
+    }
+    characters.key?(self) ? characters[self] : self
+  end
+
+  def mod_to_ent(use_symbol)
+    entities = {
+      '⌃' => '&#8963;',
+      '⌥' => '&#8997;',
+      '⇧' => '&#8679;',
+      '⌘' => '&#8984;',
+      'Fn' => 'Fn',
+      'Hyper' => 'Hyper'
+    }
+    names = {
+      '⌃' => 'Control',
+      '⌥' => 'Option',
+      '⇧' => 'Shift',
+      '⌘' => 'Command',
+      'Fn' => 'Function',
+      'Hyper' => 'Hyper (Control+Option+Shift+Command)'
+    }
+    if entities.key?(self)
+      use_symbol ? entities[self] : names[self]
+    else
+      self
+    end
+  end
+
+  def mod_to_title
+    entities = {
+      '⌃' => 'Control',
+      '⌥' => 'Option',
+      '⇧' => 'Shift',
+      '⌘' => 'Command',
+      'Fn' => 'Function',
+      'Hyper' => 'Hyper (Control+Option+Shift+Command)'
+    }
+    entities.key?(self) ? entities[self] : self
+  end
+
+  def clarify_characters
+    unclear = {
+      ',' => 'Comma (,)',
+      '.' => 'Period (.)',
+      ';' => 'Semicolon (;)',
+      ':' => 'Colon (:)',
+      '`' => 'Backtick (`)',
+      '-' => 'Minus Sign (-)',
+      '+' => 'Plus Sign (+)',
+      '=' => 'Equals Sign (=)',
+      '_' => 'Underscore (_)',
+      '~' => 'Tilde (~)',
+      '\\' => 'Backslash (\\)',
+      '|' => 'Pipe (|)',
+      '←' => 'Left Arrow (←)',
+      '→' => 'Right Arrow (→)',
+      '↑' => 'Up Arrow (↑)',
+      '↓' => 'Down Arrow (↓)'
+    }
+    unclear.fetch(self, self)
+  end
+
+  def name_to_ent(use_symbol)
+    k = case strip.downcase
+        when /^f(\d{1,2})$/
+          num = Regexp.last_match(1)
+          ["F#{num}", "F#{num}", "F#{num} Key"]
+        when /^apple$/
+          ['Apple', '&#63743;', 'Apple menu']
+        when /^tab$/
+          ['', '&#8677;', 'Tab Key']
+        when /^caps(lock)?$/
+          ['Caps Lock', '&#8682;', 'Caps Lock Key']
+        when /^eject$/
+          ['Eject', '&#9167;', 'Eject Key']
+        when /^return$/
+          ['Return', '&#9166;', 'Return Key']
+        when /^enter$/
+          ['Enter', '&#8996;', 'Enter (Fn Return) Key']
+        when /^(del(ete)?|back(space)?)$/
+          ['Del', '&#9003;', 'Delete']
+        when /^fwddel(ete)?$/
+          ['Fwd Del', '&#8998;', 'Forward Delete (Fn Delete)']
+        when /^(esc(ape)?)$/
+          ['Esc', '&#9099;', 'Escape Key']
+        when /^(right|rt)$/
+          ['Right Arrow', '&#8594;', 'Right Arrow Key']
+        when /^(left|lt)$/
+          ['Left Arrow', '&#8592;', 'Left Arrow Key']
+        when /^up$/
+          ['Up Arrow', '&#8593;', 'Up Arrow Key']
+        when /^(down|dn)$/
+          ['Down Arrow', '&#8595;', 'Down Arrow Key']
+        when /^p(age|g)up$/
+          ['PgUp', '&#8670;', 'Page Up Key']
+        when /^p(age|g)d(ow)?n$/
+          ['PgDn', '&#8671;', 'Page Down Key']
+        when /^home$/
+          ['Home', '&#8598;', 'Home Key']
+        when /^end$/
+          ['End', '&#8600;', 'End Key']
+        when /^semi(colon)$/
+          ['Semicolon', ';', 'Semicolon']
+        when /^(single([- ]?quote?)?|quote?)$/
+          ['Single Quote', "'", 'Single Quote']
+        when /^double([- ]?quote?)?$/
+          ['Double Quote', '"', 'Double Quote']
+        when /^click$/
+          ['click', '<i class="fas fa-mouse-pointer"></i>', 'left click']
+        when /^hyper/i
+          ['Hyper', 'Hyper', 'Hyper (Control+Option+Shift+Command)']
+        else
+          [self, self, capitalize]
+        end
+    use_symbol ? [k[1], k[2]] : [k[0], k[2]]
+  end
+end
+
+def render_kbd(markup, use_key_symbol: true, use_mod_symbol: true, use_plus: false)
+  combos = []
+
+  markup.split(%r{ / }).each do |combo|
+    mods = []
+    key = ''
+    combo.clean_combo!
+    combo.strip.split(//).each do |char|
+      next if char == ' '
+      case char
+      when /[⌃⇧⌥⌘]/
+        mods << char
+      when /[*\^$@~%]/
+        mods << char.to_mod
+      else
+        key << char
+      end
+    end
+    mods = sort_mods(mods)
+    title = ''
+    if key.length == 1
+      if mods.empty? && (key =~ /[A-Z]/ || key.upper?)
+        mods << '$'.to_mod
+      end
+      key = key.lower_to_upper if mods.include?('$'.to_mod)
+      key = key.upcase
+      title = key.clarify_characters
+    elsif mods.include?('$'.to_mod)
+      key = key.lower_to_upper
+    end
+    key.gsub!(/"/, '&quot;')
+    combos << { mods: mods, key: key, title: title }
+  end
+
+  outputs = combos.map do |combo|
+    next if combo[:mods].empty? && combo[:key].empty?
+    kbds = []
+    title = []
+
+    combo[:mods].each do |mod|
+      mod_class = use_mod_symbol ? 'mod symbol' : 'mod'
+      kbds << %(<kbd class="#{mod_class}">#{mod.mod_to_ent(use_mod_symbol)}</kbd>)
+      title << mod.mod_to_title
+    end
+
+    unless combo[:key].empty?
+      key, keytitle = combo[:key].name_to_ent(use_key_symbol)
+      key_class = use_key_symbol ? 'key symbol' : 'key'
+      keytitle = keytitle.clarify_characters if keytitle.length == 1
+      kbds << %(<kbd class="#{key_class}">#{key}</kbd>)
+      title << keytitle
+    end
+
+    kbd = if use_mod_symbol
+            use_plus ? kbds.join('<span class="keycombo combiner">+</span>') : kbds.join
+          else
+            kbds.join('-')
+          end
+    span_class = "keycombo #{use_mod_symbol && !use_plus ? 'combined' : 'separated'}"
+    %(<span class="#{span_class}" title="#{title.join('-')}">#{kbd}</span>)
+  end.compact
+
+  outputs.join('<span class="keycombo separator">/</span>')
+end
+
+def sort_mods(mods)
+  order = ['Fn', '⌃', '⌥', '⇧', '⌘']
+  mods.uniq.sort { |a, b| order.index(a) < order.index(b) ? -1 : 1 }
+end
+
+result = text.gsub(/\{%\s*kbd\s+([^%]+)%\}/) do
+  markup = Regexp.last_match(1)
+  render_kbd(markup)
+end
+
+print result
+

data/ext/apex_ext/apex_src/examples/kbd_plugin.yml

@@ -0,0 +1,9 @@
+---
+id: kbd-inline
+description: Inline {% kbd ... %} keyboard shortcut syntax
+phase: pre_parse
+handler.command: "/usr/bin/env ruby ${APEX_PLUGIN_DIR}/kbd_plugin.rb"
+priority: 100
+timeout_ms: 500
+---
+

data/ext/apex_ext/apex_src/include/apex/apex.h

@@ -0,0 +1,247 @@
+/**
+ * Apex - Unified Markdown Processor
+ *
+ * A comprehensive Markdown processor with support for CommonMark, GFM,
+ * MultiMarkdown, Kramdown, and Marked's special syntax extensions.
+ */
+
+#ifndef APEX_H
+#define APEX_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stddef.h>
+#include <stdbool.h>
+
+#define APEX_VERSION_MAJOR 0
+#define APEX_VERSION_MINOR 1
+#define APEX_VERSION_PATCH 73
+#define APEX_VERSION_STRING "0.1.73"
+
+/**
+ * Processor compatibility modes
+ */
+#ifndef APEX_MODE_DEFINED
+#define APEX_MODE_DEFINED
+typedef enum {
+    APEX_MODE_COMMONMARK = 0,      /* Pure CommonMark spec */
+    APEX_MODE_GFM = 1,              /* GitHub Flavored Markdown */
+    APEX_MODE_MULTIMARKDOWN = 2,    /* MultiMarkdown compatibility */
+    APEX_MODE_KRAMDOWN = 3,         /* Kramdown compatibility */
+    APEX_MODE_UNIFIED = 4           /* All features enabled */
+} apex_mode_t;
+#endif
+
+/**
+ * Configuration options for the parser and renderer
+ */
+typedef struct {
+    apex_mode_t mode;
+
+    /* Feature flags */
+    bool enable_plugins;  /* Enable external/plugin processing */
+    bool enable_tables;
+    bool enable_footnotes;
+    bool enable_definition_lists;
+    bool enable_smart_typography;
+    bool enable_math;
+    bool enable_critic_markup;
+    bool enable_wiki_links;
+    bool enable_task_lists;
+    bool enable_attributes;
+    bool enable_callouts;
+    bool enable_marked_extensions;
+    bool enable_divs;  /* Enable Pandoc fenced divs (Unified mode only) */
+    bool enable_spans;  /* Enable bracketed spans [text]{IAL} (Pandoc-style) */
+
+    /* Critic markup mode */
+    int critic_mode;  /* 0=markup (default), 1=accept, 2=reject */
+
+    /* Metadata handling */
+    bool strip_metadata;
+    bool enable_metadata_variables;  /* [%key] replacement */
+    bool enable_metadata_transforms; /* [%key:transform] transforms */
+
+    /* File inclusion */
+    bool enable_file_includes;
+    int max_include_depth;
+    const char *base_directory;
+
+    /* Output options */
+    bool unsafe;  /* Allow raw HTML */
+    bool validate_utf8;
+    bool github_pre_lang;  /* Use GitHub code block language format */
+    bool standalone;  /* Generate complete HTML document */
+    bool pretty;      /* Pretty-print HTML with indentation */
+    const char **stylesheet_paths;  /* NULL-terminated array of CSS file paths to link in head */
+    size_t stylesheet_count;        /* Number of stylesheets */
+    const char *document_title;   /* Title for HTML document */
+
+    /* Line break handling */
+    bool hardbreaks;  /* Treat newlines as hard breaks (GFM style) */
+    bool nobreaks;    /* Render soft breaks as spaces */
+
+    /* Header ID generation */
+    bool generate_header_ids;  /* Generate IDs for headers */
+    bool header_anchors;  /* Generate <a> anchor tags instead of header IDs */
+    int id_format;  /* 0=GFM (with dashes), 1=MMD (no dashes) */
+
+    /* Table options */
+    bool relaxed_tables;  /* Support tables without separator rows (kramdown/unified only) */
+    int caption_position;  /* 0=above, 1=below (default: 1=below) */
+    bool per_cell_alignment;  /* Enable per-cell alignment markers (colons at start/end of cells) */
+
+    /* List options */
+    bool allow_mixed_list_markers;  /* Allow mixed list markers at same level (inherit type from first item) */
+    bool allow_alpha_lists;  /* Support alpha list markers (a., b., c. and A., B., C.) */
+
+    /* Superscript and subscript */
+    bool enable_sup_sub;  /* Support MultiMarkdown-style ^text^ and ~text~ syntax */
+
+    /* Strikethrough (GFM-style ~~text~~) */
+    bool enable_strikethrough;
+
+    /* Autolink options */
+    bool enable_autolink;  /* Enable autolinking of URLs and email addresses */
+    bool obfuscate_emails; /* Obfuscate email links/text using HTML entities */
+
+    /* Image options */
+    bool embed_images;           /* Embed local images as base64 data URLs */
+    bool enable_image_captions;  /* Wrap images in <figure> with <figcaption> when alt/title present */
+    bool title_captions_only;    /* When enable_image_captions is true, only add captions for images with a title attribute (ignore alt) */
+
+    /* Citation options */
+    bool enable_citations;  /* Enable citation processing */
+    char **bibliography_files;  /* NULL-terminated array of bibliography file paths */
+    const char *csl_file;  /* CSL style file path */
+    bool suppress_bibliography;  /* Suppress bibliography output */
+    bool link_citations;  /* Link citations to bibliography entries */
+    bool show_tooltips;  /* Show tooltips on citations */
+    const char *nocite;  /* Comma-separated citation keys to include without citing, or "*" for all */
+
+    /* Index options */
+    bool enable_indices;  /* Enable index processing */
+    bool enable_mmark_index_syntax;  /* Enable mmark (!item) syntax */
+    bool enable_textindex_syntax;  /* Enable TextIndex {^} syntax */
+    bool enable_leanpub_index_syntax;  /* Enable Leanpub {i: "term"} syntax */
+    bool suppress_index;  /* Suppress index output */
+    bool group_index_by_letter;  /* Group index entries by first letter */
+
+    /* Wiki link options */
+    int wikilink_space;  /* Space replacement: 0=dash, 1=none, 2=underscore, 3=space */
+    const char *wikilink_extension;  /* File extension to append (e.g., "html") */
+    bool wikilink_sanitize;  /* Sanitize URLs: lowercase, remove apostrophes, replace non-alnum */
+
+    /* Script injection options */
+    /* Raw <script>...</script> HTML snippets to inject either:
+     * - Before </body> when generating standalone HTML
+     * - At the end of the HTML fragment in snippet mode
+     *
+     * This is typically populated by the CLI --script flag.
+     */
+    char **script_tags;  /* NULL-terminated array of script tag strings (may be NULL for none) */
+
+    /* Stylesheet embedding options */
+    /* When true and a stylesheet path is provided, Apex will attempt to
+     * read the CSS file and embed it directly into a <style> block in the
+     * document head instead of emitting a <link rel="stylesheet"> tag.
+     * This is typically enabled via the CLI --embed-css flag.
+     */
+    bool embed_stylesheet;
+
+    /* ARIA accessibility options */
+    bool enable_aria;  /* Add ARIA labels and accessibility attributes to HTML output */
+
+    /* Emoji options */
+    bool enable_emoji_autocorrect;  /* Enable emoji name autocorrect (enabled by default in unified mode) */
+
+    /* Syntax highlighting options */
+    const char *code_highlighter;   /* External tool: "pygments", "skylighting", or NULL for no highlighting */
+    bool code_line_numbers;         /* Enable line numbers in syntax-highlighted code blocks */
+    bool highlight_language_only;   /* Only highlight code blocks that have a language specified */
+
+    /* Marked / integration-specific options */
+    bool enable_widont;                 /* Apply widont to headings (prevent short widows) */
+    bool code_is_poetry;                /* Treat unlanguaged code blocks as poetry */
+    bool enable_markdown_in_html;       /* Process markdown inside HTML when enabled */
+    bool random_footnote_ids;           /* Use hash-based/randomized footnote IDs */
+    bool enable_hashtags;               /* Convert #tags to span-marked hashtags */
+    bool style_hashtags;                /* Use styled hashtag class instead of basic */
+    bool proofreader_mode;              /* Convert == / ~~ to CriticMarkup syntax */
+    bool hr_page_break;                 /* Replace <hr> with page break divs */
+    bool title_from_h1;                 /* Use first H1 as document title fallback */
+    bool page_break_before_footnotes;   /* Insert page break before footnotes section */
+
+    /* Source file information for plugins */
+    /* When Apex is invoked on a file, this is the full path to that file. */
+    /* When reading from stdin, this is either the base directory (if set) or empty. */
+    const char *input_file_path;
+
+    /* Progress reporting callback */
+    /* Called during processing to report progress. Parameters:
+     * - stage: Description of current processing stage (e.g., "Processing tables", "Running plugin: kbd")
+     * - percent: Progress percentage (0-100), or -1 if unknown
+     * - user_data: User-provided context (can be NULL)
+     * If NULL, no progress reporting is performed.
+     */
+    void (*progress_callback)(const char *stage, int percent, void *user_data);
+    void *progress_user_data;  /* User data passed to progress callback */
+} apex_options;
+
+/**
+ * Get default options for a specific mode
+ */
+apex_options apex_options_default(void);
+apex_options apex_options_for_mode(apex_mode_t mode);
+
+/**
+ * Main conversion function: Markdown to HTML
+ *
+ * @param markdown Input markdown text
+ * @param len Length of input text
+ * @param options Processing options (NULL for defaults)
+ * @return Newly allocated HTML string (must be freed with apex_free_string)
+ */
+char *apex_markdown_to_html(const char *markdown, size_t len, const apex_options *options);
+
+/**
+ * Wrap HTML content in complete HTML5 document structure
+ *
+ * @param content HTML content to wrap
+ * @param title Document title (NULL for default)
+ * @param stylesheet_paths NULL-terminated array of CSS file paths to link in head
+ * @param html_header Raw HTML to insert in <head> section (NULL for none)
+ * @param html_footer Raw HTML to append before </body> (NULL for none)
+ * @param language Language code for <html lang> attribute (NULL for "en")
+ * @return Newly allocated HTML document string (must be freed with apex_free_string)
+ */
+char *apex_wrap_html_document(const char *content, const char *title, const char **stylesheet_paths, size_t stylesheet_count, const char *code_highlighter, const char *html_header, const char *html_footer, const char *language);
+
+/**
+ * Pretty-print HTML with proper indentation
+ *
+ * @param html HTML to format
+ * @return Newly allocated formatted HTML string (must be freed with apex_free_string)
+ */
+char *apex_pretty_print_html(const char *html);
+
+/**
+ * Free a string allocated by Apex
+ */
+void apex_free_string(char *str);
+
+/**
+ * Get version information
+ */
+const char *apex_version_string(void);
+int apex_version_major(void);
+int apex_version_minor(void);
+int apex_version_patch(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* APEX_H */

data/ext/apex_ext/apex_src/include/apex/buffer.h

@@ -0,0 +1,93 @@
+/**
+ * @file buffer.h
+ * @brief Dynamic string buffer for efficient string building
+ */
+
+#ifndef APEX_BUFFER_H
+#define APEX_BUFFER_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stddef.h>
+#include <stdbool.h>
+
+/**
+ * Dynamic buffer structure
+ */
+typedef struct {
+    char *data;           /**< Buffer data */
+    size_t size;          /**< Current size */
+    size_t capacity;      /**< Allocated capacity */
+} apex_buffer;
+
+/**
+ * Initialize a buffer
+ *
+ * @param buf Buffer to initialize
+ * @param initial_capacity Initial capacity
+ */
+void apex_buffer_init(apex_buffer *buf, size_t initial_capacity);
+
+/**
+ * Free buffer resources
+ *
+ * @param buf Buffer to free
+ */
+void apex_buffer_free(apex_buffer *buf);
+
+/**
+ * Clear buffer contents
+ *
+ * @param buf Buffer to clear
+ */
+void apex_buffer_clear(apex_buffer *buf);
+
+/**
+ * Append string to buffer
+ *
+ * @param buf Buffer
+ * @param data String to append
+ * @param len Length of string
+ */
+void apex_buffer_append(apex_buffer *buf, const char *data, size_t len);
+
+/**
+ * Append null-terminated string to buffer
+ *
+ * @param buf Buffer
+ * @param str String to append
+ */
+void apex_buffer_append_str(apex_buffer *buf, const char *str);
+
+/**
+ * Append single character to buffer
+ *
+ * @param buf Buffer
+ * @param c Character to append
+ */
+void apex_buffer_append_char(apex_buffer *buf, char c);
+
+/**
+ * Get buffer contents as string
+ *
+ * @param buf Buffer
+ * @return Null-terminated string (do not free)
+ */
+const char *apex_buffer_cstr(const apex_buffer *buf);
+
+/**
+ * Detach buffer data (caller must free)
+ *
+ * @param buf Buffer
+ * @return Buffer data (must be freed with free())
+ */
+char *apex_buffer_detach(apex_buffer *buf);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* APEX_BUFFER_H */
+

data/ext/apex_ext/apex_src/include/apex/module.modulemap

@@ -0,0 +1,16 @@
+module Apex {
+    umbrella header "apex.h"
+    explicit module parser {
+        header "parser.h"
+        export *
+    }
+    explicit module renderer {
+        header "renderer.h"
+        export *
+    }
+    explicit module buffer {
+        header "buffer.h"
+        export *
+    }
+    export *
+}