apex-ruby 1.0.18 → 1.0.20

data/ext/apex_ext/apex_src/objc/ApexPlugins.swift

@@ -0,0 +1,79 @@
+/**
+ * ApexPlugins.swift
+ * Swift API for plugin catalog and installation.
+ */
+
+import Foundation
+@_exported import ApexObjC
+
+/// Metadata for one Apex plugin (available or installed).
+public struct ApexPluginInfo: Identifiable, Hashable, Sendable {
+    public let id: String
+    public let title: String?
+    public let description: String?
+    public let author: String?
+    public let homepage: String?
+    public let repo: String?
+
+    init(_ objc: ApexObjC.ApexPluginInfo) {
+        self.id = objc.pluginId
+        self.title = objc.title
+        self.description = objc.pluginDescription
+        self.author = objc.author
+        self.homepage = objc.homepage
+        self.repo = objc.repo
+    }
+}
+
+/// Fetch, list, install, and uninstall Apex plugins from app code.
+public enum ApexPluginManager {
+    /// Default `apex-plugins.json` URL.
+    public static var defaultDirectoryURL: String {
+        ApexPluginCatalog.defaultDirectoryURL
+    }
+
+    /// User-global plugins directory (`~/.config/apex/plugins` or XDG equivalent).
+    public static var globalPluginsDirectory: String? {
+        ApexPluginCatalog.globalPluginsDirectory()
+    }
+
+    /// Fetch plugins from the central Apex directory.
+    public static func fetchAvailable() throws -> [ApexPluginInfo] {
+        let items = try ApexPluginCatalog.fetchAvailablePlugins()
+        return items.map(ApexPluginInfo.init)
+    }
+
+    /// Fetch plugins from a custom directory JSON URL.
+    public static func fetchAvailable(from url: String) throws -> [ApexPluginInfo] {
+        let items = try ApexPluginCatalog.fetchAvailablePlugins(fromURL: url)
+        return items.map(ApexPluginInfo.init)
+    }
+
+    /// List installed plugins (project-scoped + user-global).
+    public static func installed(baseDirectory: String? = nil) -> [ApexPluginInfo] {
+        ApexPluginCatalog.installedPlugins(withBaseDirectory: baseDirectory)
+            .map(ApexPluginInfo.init)
+    }
+
+    /// Install a curated plugin by id from the central directory.
+    public static func install(id: String) throws {
+        try install(idOrRepository: id, allowUntrustedSource: false)
+    }
+
+    /// Install by directory id, Git URL, or GitHub `user/repo` shorthand.
+    public static func install(idOrRepository: String, allowUntrustedSource: Bool = false) throws {
+        if allowUntrustedSource {
+            try ApexPluginCatalog.installPlugin(
+                fromRepository: idOrRepository,
+                allowUntrustedSource: true
+            )
+        } else {
+            try ApexPluginCatalog.installPlugin(withId: idOrRepository)
+        }
+    }
+
+    /// Remove a plugin from the user-global plugins directory.
+    public static func uninstall(id: String) throws {
+        try ApexPluginCatalog.uninstallPlugin(withId: id)
+    }
+}

data/ext/apex_ext/apex_src/objc/NSString+Apex.h

@@ -16,6 +16,7 @@ extern NSString * const ApexModeGFM;
 extern NSString * const ApexModeMultiMarkdown;
 extern NSString * const ApexModeKramdown;
 extern NSString * const ApexModeUnified;
+extern NSString * const ApexModeQuarto;
 
 @interface NSString (Apex)
 
@@ -40,7 +41,7 @@ extern NSString * const ApexModeUnified;
 /**
  * Convert Markdown to HTML using Apex with specific processor mode
  * @param inputString The markdown text to convert
- * @param mode Processor mode: Use ApexMode* constants (ApexModeCommonmark, ApexModeGFM, ApexModeMultiMarkdown, ApexModeKramdown, or ApexModeUnified) or string values: "commonmark", "gfm", "multimarkdown", "kramdown", or "unified"
+ * @param mode Processor mode: Use ApexMode* constants (ApexModeCommonmark, ApexModeGFM, ApexModeMultiMarkdown, ApexModeKramdown, ApexModeUnified, or ApexModeQuarto) or string values: "commonmark", "gfm", "multimarkdown", "kramdown", "unified", or "quarto"
  * @return HTML string
  */
 + (NSString *)convertWithApex:(NSString *)inputString mode:(NSString *)mode;
@@ -86,7 +87,10 @@ extern NSString * const ApexModeUnified;
  *   - @"headerAnchors": NSNumber (BOOL) - Generate anchor tags instead of IDs
  *   - @"obfuscateEmails": NSNumber (BOOL) - Obfuscate email links
  *   - @"embedImages": NSNumber (BOOL) - Embed images as base64 data URLs
- * @return HTML string
+ *   - @"enablePlugins": NSNumber (BOOL) - Enable external plugin processing
+ *   - @"enableAutolink": NSNumber (BOOL) - Autolink bare URLs and emails
+ *   - @"outputFormat": NSString - @"html" (default) or @"rtf"
+ * @return HTML or RTF string depending on outputFormat
  */
 + (NSString *)convertWithApex:(NSString *)inputString
                          mode:(NSString *)mode
@@ -104,9 +108,30 @@ extern NSString * const ApexModeUnified;
  */
 + (NSString *)convertWithApex:(NSString *)inputString
                          mode:(NSString *)mode
-              generateHeaderIDs:(BOOL)generateHeaderIDs
-                    hardBreaks:(BOOL)hardBreaks
-                        pretty:(BOOL)pretty;
+            generateHeaderIDs:(BOOL)generateHeaderIDs
+                   hardBreaks:(BOOL)hardBreaks
+                       pretty:(BOOL)pretty;
+
+/**
+ * Convert Markdown to HTML using Apex with source file URL for includes.
+ * Does not embed local images (callers may embed after security-scoped access).
+ * @param inputString The markdown text to convert
+ * @param mode Processor mode
+ * @param sourceURL File URL used for include resolution and base directory
+ * @return HTML string
+ */
++ (NSString *)convertWithApex:(NSString *)inputString
+                         mode:(NSString *)mode
+                    sourceURL:(NSURL *)sourceURL;
+
+/**
+ * Same as convertWithApex:mode:sourceURL: with explicit autolink control.
+ * Disabling autolink avoids a costly scan on large URL-heavy documents.
+ */
++ (NSString *)convertWithApex:(NSString *)inputString
+                         mode:(NSString *)mode
+                    sourceURL:(NSURL *)sourceURL
+               enableAutolink:(BOOL)enableAutolink;
 
 /**
  * Convert this string (as Markdown) to HTML using Apex in unified mode
@@ -123,6 +148,59 @@ extern NSString * const ApexModeUnified;
  */
 - (NSString *)apexHTMLWithMode:(NSString *)mode;
 
+/**
+ * Convert this string (as Markdown) to RTF using Apex in unified mode.
+ */
+- (NSString *)apexRTF;
+
+/**
+ * Convert this string (as Markdown) to RTF using Apex with specific mode.
+ */
+- (NSString *)apexRTFWithMode:(NSString *)mode;
+
+/**
+ * Convert this string (as Markdown) to RTF with mode and options dictionary.
+ * Sets outputFormat to rtf automatically.
+ */
+- (NSString *)apexRTFWithMode:(NSString *)mode
+                      options:(NSDictionary<NSString *, id> * _Nullable)options;
+
+#if __has_include(<AppKit/AppKit.h>) || __has_include(<UIKit/UIKit.h>)
+/**
+ * Build an NSAttributedString from Markdown via Apex RTF output (preferred).
+ */
+- (NSAttributedString * _Nullable)apexAttributedString;
+
+/**
+ * Build an NSAttributedString from Markdown using RTF or HTML document type.
+ * @param useHTML If YES, use NSHTMLTextDocumentType; if NO, use NSRTFTextDocumentType.
+ */
+- (NSAttributedString * _Nullable)apexAttributedStringUsingHTML:(BOOL)useHTML;
+
+/**
+ * Build an NSAttributedString with mode/options, preferring RTF unless useHTML is YES.
+ */
+- (NSAttributedString * _Nullable)apexAttributedStringWithMode:(NSString *)mode
+                                                      options:(NSDictionary<NSString *, id> * _Nullable)options
+                                                     usingHTML:(BOOL)useHTML;
+#endif
+
+/**
+ * Extract a flat table of contents for outline / table-view UIs.
+ * Each dictionary has keys: @"level" (NSNumber 1-6), @"text", @"id".
+ * Nesting for collapsible sections is derived from level (same rules as -t toc).
+ */
++ (NSArray<NSDictionary<NSString *, id> *> *)tableOfContentsWithApex:(NSString *)inputString;
+
++ (NSArray<NSDictionary<NSString *, id> *> *)tableOfContentsWithApex:(NSString *)inputString
+                                                                mode:(NSString *)mode
+                                                             options:(NSDictionary<NSString *, id> * _Nullable)options;
+
+- (NSArray<NSDictionary<NSString *, id> *> *)apexTableOfContents;
+
+- (NSArray<NSDictionary<NSString *, id> *> *)apexTableOfContentsWithMode:(NSString *)mode
+                                                                 options:(NSDictionary<NSString *, id> * _Nullable)options;
+
 @end
 
 NS_ASSUME_NONNULL_END

data/ext/apex_ext/apex_src/objc/NSString+Apex.m

@@ -6,6 +6,12 @@
 #import "NSString+Apex.h"
 #import <apex/apex.h>
 
+#if __has_include(<AppKit/AppKit.h>)
+#import <AppKit/AppKit.h>
+#elif __has_include(<UIKit/UIKit.h>)
+#import <UIKit/UIKit.h>
+#endif
+
 /**
  * Apex mode constants
  */
@@ -14,6 +20,7 @@ NSString *const ApexModeGFM = @"gfm";
 NSString *const ApexModeMultiMarkdown = @"multimarkdown";
 NSString *const ApexModeKramdown = @"kramdown";
 NSString *const ApexModeUnified = @"unified";
+NSString *const ApexModeQuarto = @"quarto";
 
 @implementation NSString (Apex)
 
@@ -41,6 +48,8 @@ NSString *const ApexModeUnified = @"unified";
     return APEX_MODE_MULTIMARKDOWN;
   } else if ([mode isEqualToString:@"kramdown"]) {
     return APEX_MODE_KRAMDOWN;
+  } else if ([mode isEqualToString:@"quarto"]) {
+    return APEX_MODE_QUARTO;
   } else {
     return APEX_MODE_UNIFIED; /* Default to unified */
   }
@@ -267,9 +276,32 @@ NSString *const ApexModeUnified = @"unified";
     if (embedImagesValue && [embedImagesValue isKindOfClass:[NSNumber class]]) {
       options.embed_images = [embedImagesValue boolValue];
     }
+
+    /* Plugins */
+    id enablePluginsValue = optionsDict[@"enablePlugins"];
+    if (enablePluginsValue && [enablePluginsValue isKindOfClass:[NSNumber class]]) {
+      options.enable_plugins = [enablePluginsValue boolValue];
+    }
+
+    /* Autolink bare URLs / emails */
+    id enableAutolinkValue = optionsDict[@"enableAutolink"];
+    if (enableAutolinkValue && [enableAutolinkValue isKindOfClass:[NSNumber class]]) {
+      options.enable_autolink = [enableAutolinkValue boolValue];
+    }
+
+    /* Output format: html (default) or rtf */
+    id outputFormatValue = optionsDict[@"outputFormat"];
+    if (outputFormatValue && [outputFormatValue isKindOfClass:[NSString class]]) {
+      NSString *fmt = [(NSString *)outputFormatValue lowercaseString];
+      if ([fmt isEqualToString:@"rtf"]) {
+        options.output_format = APEX_OUTPUT_RTF;
+      } else {
+        options.output_format = APEX_OUTPUT_HTML;
+      }
+    }
   }
 
-  /* Convert to HTML */
+  /* Convert to HTML or RTF */
   char *html_c = apex_markdown_to_html(markdown, strlen(markdown), &options);
 
   if (!html_c) {
@@ -324,6 +356,69 @@ NSString *const ApexModeUnified = @"unified";
   return html ? html : @"";
 }
 
+/**
+ * Convert Markdown to HTML using Apex with source file URL for includes.
+ * Leaves local images as paths; sandboxed callers (e.g. Marked Quick Look)
+ * embed after security-scoped folder grants.
+ */
++ (NSString *)convertWithApex:(NSString *)inputString
+                         mode:(NSString *)modeString
+                    sourceURL:(NSURL *)sourceURL {
+  return [self convertWithApex:inputString
+                          mode:modeString
+                     sourceURL:sourceURL
+                enableAutolink:YES];
+}
+
++ (NSString *)convertWithApex:(NSString *)inputString
+                         mode:(NSString *)modeString
+                    sourceURL:(NSURL *)sourceURL
+               enableAutolink:(BOOL)enableAutolink {
+  if (!inputString || [inputString length] == 0) {
+    return @"";
+  }
+
+  const char *markdown = [inputString UTF8String];
+  if (!markdown) {
+    return @"";
+  }
+
+  apex_mode_t mode = [self apexModeFromString:modeString];
+  apex_options options = apex_options_for_mode(mode);
+
+  options.unsafe = true;
+  options.generate_header_ids = true;
+  options.enable_critic_markup = true;
+  options.critic_mode = 2; /* CRITIC_MARKUP: show markup with classes */
+  /* Do not embed images here: fopen/stat under Dropbox/CloudStorage can stall
+   * sandboxed Quick Look. Callers (Marked Quick Look) embed after security-scoped
+   * folder grants with a non-blocking Swift pass. */
+  options.embed_images = false;
+  options.enable_autolink = enableAutolink;
+
+  if (sourceURL && sourceURL.isFileURL) {
+    NSString *path = sourceURL.path;
+    if (path.length > 0) {
+      options.input_file_path = [path UTF8String];
+      NSString *baseDir = [path stringByDeletingLastPathComponent];
+      if (baseDir.length > 0) {
+        options.base_directory = [baseDir UTF8String];
+      }
+    }
+  }
+
+  char *html_c = apex_markdown_to_html(markdown, strlen(markdown), &options);
+
+  if (!html_c) {
+    return @"";
+  }
+
+  NSString *html = [NSString stringWithUTF8String:html_c];
+  apex_free_string(html_c);
+
+  return html ? html : @"";
+}
+
 /**
  * Convert this string (as Markdown) to HTML using Apex in unified mode
  */
@@ -338,4 +433,152 @@ NSString *const ApexModeUnified = @"unified";
   return [NSString convertWithApex:self mode:mode];
 }
 
+- (NSString *)apexRTF {
+  return [self apexRTFWithMode:ApexModeUnified options:nil];
+}
+
+- (NSString *)apexRTFWithMode:(NSString *)mode {
+  return [self apexRTFWithMode:mode options:nil];
+}
+
+- (NSString *)apexRTFWithMode:(NSString *)mode
+                      options:(NSDictionary<NSString *, id> *_Nullable)options {
+  NSMutableDictionary *dict =
+      options ? [options mutableCopy] : [NSMutableDictionary dictionary];
+  dict[@"outputFormat"] = @"rtf";
+  return [NSString convertWithApex:self mode:mode options:dict];
+}
+
+#if __has_include(<AppKit/AppKit.h>) || __has_include(<UIKit/UIKit.h>)
+- (NSAttributedString *)apexAttributedString {
+  return [self apexAttributedStringWithMode:ApexModeUnified options:nil usingHTML:NO];
+}
+
+- (NSAttributedString *)apexAttributedStringUsingHTML:(BOOL)useHTML {
+  return [self apexAttributedStringWithMode:ApexModeUnified options:nil usingHTML:useHTML];
+}
+
+- (NSAttributedString *)apexAttributedStringWithMode:(NSString *)mode
+                                             options:(NSDictionary<NSString *, id> *_Nullable)options
+                                            usingHTML:(BOOL)useHTML {
+  NSString *source = nil;
+  NSAttributedStringDocumentType docType;
+  if (useHTML) {
+    source = [NSString convertWithApex:self mode:mode options:options];
+    docType = NSHTMLTextDocumentType;
+  } else {
+    source = [self apexRTFWithMode:mode options:options];
+    docType = NSRTFTextDocumentType;
+  }
+  if (!source || [source length] == 0) {
+    return [[NSAttributedString alloc] initWithString:@""];
+  }
+  NSData *data = [source dataUsingEncoding:NSUTF8StringEncoding];
+  if (!data) {
+    return nil;
+  }
+  NSDictionary *attrs = @{
+    NSDocumentTypeDocumentAttribute : docType,
+    NSCharacterEncodingDocumentAttribute : @(NSUTF8StringEncoding)
+  };
+  NSError *error = nil;
+  NSAttributedString *attr =
+      [[NSAttributedString alloc] initWithData:data options:attrs documentAttributes:nil error:&error];
+  (void)error;
+  return attr;
+}
+#endif
+
+/**
+ * Extract a flat table of contents as dictionaries suitable for Swift OutlineGroup.
+ * Each entry: @{ @"level": NSNumber, @"text": NSString, @"id": NSString }
+ * Optional options keys: @"idFormat" (@"gfm"/@"mmd"/@"kramdown"),
+ * @"tocMinMax" (@"2,4" or @[@2, @4]).
+ */
++ (NSArray<NSDictionary<NSString *, id> *> *)tableOfContentsWithApex:(NSString *)inputString
+                                                                mode:(NSString *)modeString
+                                                             options:(NSDictionary<NSString *, id> *_Nullable)optionsDict {
+  if (!inputString || [inputString length] == 0) {
+    return @[];
+  }
+
+  const char *markdown = [inputString UTF8String];
+  if (!markdown) {
+    return @[];
+  }
+
+  apex_mode_t mode = [self apexModeFromString:modeString ?: ApexModeUnified];
+  apex_options options = apex_options_for_mode(mode);
+
+  if (optionsDict) {
+    id idFormatVal = optionsDict[@"idFormat"];
+    if ([idFormatVal isKindOfClass:[NSString class]]) {
+      NSString *fmt = [(NSString *)idFormatVal lowercaseString];
+      if ([fmt isEqualToString:@"mmd"]) {
+        options.id_format = 1;
+      } else if ([fmt isEqualToString:@"kramdown"]) {
+        options.id_format = 2;
+      } else {
+        options.id_format = 0;
+      }
+    }
+    id tocMinMaxVal = optionsDict[@"tocMinMax"];
+    if ([tocMinMaxVal isKindOfClass:[NSString class]]) {
+      int min = 0, max = 0;
+      if (sscanf([(NSString *)tocMinMaxVal UTF8String], "%d,%d", &min, &max) == 2 &&
+          min >= 1 && max <= 6 && min <= max) {
+        options.toc_min = min;
+        options.toc_max = max;
+      }
+    } else if ([tocMinMaxVal isKindOfClass:[NSArray class]] &&
+               [(NSArray *)tocMinMaxVal count] >= 2) {
+      int min = [[(NSArray *)tocMinMaxVal objectAtIndex:0] intValue];
+      int max = [[(NSArray *)tocMinMaxVal objectAtIndex:1] intValue];
+      if (min >= 1 && max <= 6 && min <= max) {
+        options.toc_min = min;
+        options.toc_max = max;
+      }
+    }
+  }
+
+  size_t count = 0;
+  apex_toc_entry *entries =
+      apex_markdown_to_toc_entries(markdown, strlen(markdown), &options, &count);
+  if (!entries || count == 0) {
+    apex_toc_entries_free(entries, count);
+    return @[];
+  }
+
+  NSMutableArray<NSDictionary<NSString *, id> *> *result =
+      [NSMutableArray arrayWithCapacity:count];
+  for (size_t i = 0; i < count; i++) {
+    NSString *text = entries[i].text
+                         ? [NSString stringWithUTF8String:entries[i].text]
+                         : @"";
+    NSString *ident = entries[i].id
+                          ? [NSString stringWithUTF8String:entries[i].id]
+                          : @"";
+    [result addObject:@{
+      @"level" : @(entries[i].level),
+      @"text" : text ?: @"",
+      @"id" : ident ?: @""
+    }];
+  }
+  apex_toc_entries_free(entries, count);
+  return result;
+}
+
++ (NSArray<NSDictionary<NSString *, id> *> *)tableOfContentsWithApex:(NSString *)inputString {
+  return [self tableOfContentsWithApex:inputString mode:ApexModeUnified options:nil];
+}
+
+- (NSArray<NSDictionary<NSString *, id> *> *)apexTableOfContents {
+  return [NSString tableOfContentsWithApex:self];
+}
+
+- (NSArray<NSDictionary<NSString *, id> *> *)apexTableOfContentsWithMode:(NSString *)mode
+                                                                 options:(NSDictionary<NSString *, id> *_Nullable)options {
+  return [NSString tableOfContentsWithApex:self mode:mode options:options];
+}
+
 @end

data/ext/apex_ext/apex_src/objc/NSString+ApexPlugins.h

@@ -0,0 +1,76 @@
+/**
+ * NSString+ApexPlugins.h
+ * Objective-C API for Apex plugin catalog and installation.
+ */
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/** Metadata for one plugin (catalog or installed). */
+@interface ApexPluginInfo : NSObject
+
+@property (nonatomic, copy, readonly) NSString *pluginId;
+@property (nonatomic, copy, readonly, nullable) NSString *title;
+@property (nonatomic, copy, readonly, nullable) NSString *pluginDescription;
+@property (nonatomic, copy, readonly, nullable) NSString *author;
+@property (nonatomic, copy, readonly, nullable) NSString *homepage;
+@property (nonatomic, copy, readonly, nullable) NSString *repo;
+
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
+/** Plugin catalog and install helpers for app UIs. */
+@interface ApexPluginCatalog : NSObject
+
+/** Default apex-plugins.json URL. */
+@property (class, nonatomic, readonly) NSString *defaultDirectoryURL;
+
+/**
+ * Fetch available plugins from the central directory.
+ * @param error Set on failure (network, parse, curl missing).
+ */
++ (nullable NSArray<ApexPluginInfo *> *)fetchAvailablePlugins:(NSError **)error;
+
+/**
+ * Fetch available plugins from a custom directory JSON URL.
+ */
++ (nullable NSArray<ApexPluginInfo *> *)fetchAvailablePluginsFromURL:(NSString *)url
+                                                               error:(NSError **)error;
+
+/**
+ * List installed plugins (project + user-global, same order as runtime loading).
+ * @param baseDirectory Optional document base for .apex/plugins lookup.
+ */
++ (NSArray<ApexPluginInfo *> *)installedPluginsWithBaseDirectory:(NSString * _Nullable)baseDirectory;
+
+/**
+ * Install a plugin by directory id into ~/.config/apex/plugins.
+ */
++ (BOOL)installPluginWithId:(NSString *)pluginId error:(NSError **)error;
+
+/**
+ * Install from a Git URL or GitHub shorthand (user/repo). Requires explicit opt-in.
+ */
++ (BOOL)installPluginFromRepository:(NSString *)idOrRepo
+              allowUntrustedSource:(BOOL)allowUntrusted
+                             error:(NSError **)error;
+
+/** Remove a plugin from the user-global plugins directory. */
++ (BOOL)uninstallPluginWithId:(NSString *)pluginId error:(NSError **)error;
+
+/** User-global plugins directory path. */
++ (nullable NSString *)globalPluginsDirectory;
+
+@end
+
+FOUNDATION_EXPORT NSErrorDomain const ApexPluginErrorDomain;
+
+typedef NS_ERROR_ENUM(ApexPluginErrorDomain, ApexPluginError) {
+    ApexPluginErrorFetchFailed = 1,
+    ApexPluginErrorInstallFailed = 2,
+    ApexPluginErrorUninstallFailed = 3,
+};
+
+NS_ASSUME_NONNULL_END