@asciidoctor/core 3.0.3 → 4.0.0-alpha.1

package/src/list.js

@@ -0,0 +1,240 @@
+// ESM conversion of list.rb
+
+import { AbstractBlock } from './abstract_block.js'
+import { LF, NORMAL_SUBS } from './constants.js'
+
+/**
+ * @extends {AbstractBlock<any[]>}
+ */
+export class List extends AbstractBlock {
+  constructor(parent, context, opts = {}) {
+    super(parent, context, opts)
+  }
+
+  /** Alias for blocks — the list content. */
+  async content() {
+    return this.blocks
+  }
+
+  /**
+   * Alias for {@link getItems}.
+   * @returns {ListItem[]}
+   * @see {getItems}
+   */
+  get items() {
+    return this.blocks
+  }
+
+  /**
+   * Check whether this list has items (blocks).
+   * @returns {boolean}
+   */
+  hasItems() {
+    return this.blocks.length > 0
+  }
+
+  /**
+   * Check whether this list is an outline list (unordered or ordered).
+   * @returns {boolean}
+   */
+  outline() {
+    return this.context === 'ulist' || this.context === 'olist'
+  }
+
+  /**
+   * Convert this list, advancing the callout list pointer if a colist.
+   * @returns {Promise<string>}
+   */
+  async convert() {
+    const result = await super.convert()
+    if (this.context === 'colist') this.document.callouts.nextList()
+    return result
+  }
+
+  /**
+   * @deprecated Use {@link convert} instead.
+   */
+  render() {
+    return this.convert()
+  }
+
+  // ── JavaScript-style accessors ────────────────────────────────────────────────
+
+  /**
+   * Return the list items.
+   * @returns {ListItem[]}
+   */
+  getItems() {
+    return this.blocks
+  }
+
+  toString() {
+    return `#<List {context: '${this.context}', style: ${JSON.stringify(this.style ?? null)}, items: ${this.blocks.length}}>`
+  }
+}
+
+/**
+ * Methods for managing items for AsciiDoc olists, ulists, and dlists.
+ *
+ * In a description list (dlist), each item is a tuple: `[[term, term, ...], desc]`.
+ * If a description is not set, the second entry is null.
+ */
+export class ListItem extends AbstractBlock {
+  /**
+   * The string marker used for this list item.
+   * @type {string|null}
+   */
+  marker
+
+  /** @internal @type {string|null} */
+  _text
+
+  /** @internal */
+  _convertedText
+
+  /** @internal @type {string[]} */
+  _subsSnapshot
+
+  /**
+   * @param {List} parent - The parent List block.
+   * @param {string|null} [text=null] - The text of this item.
+   */
+  constructor(parent, text = null) {
+    super(parent, 'list_item')
+    this._text = text
+    this.level = parent.level
+    this.subs = [...NORMAL_SUBS]
+    this.marker = null
+  }
+
+  /**
+   * Contextual alias for parent.
+   * @see {getParent}
+   */
+  get list() {
+    return this.getParent()
+  }
+
+  /**
+   * Alias for {@link getText}.
+   * @see {getText}
+   */
+  get text() {
+    if (this._convertedText != null && this._subsSnapshot != null) {
+      const cur = this.subs
+      if (
+        cur.length !== this._subsSnapshot.length ||
+        cur.some((s, i) => s !== this._subsSnapshot[i])
+      ) {
+        return this._text ?? null
+      }
+    }
+    return this._convertedText ?? this._text ?? null
+  }
+
+  /**
+   * Alias for {@link setText}.
+   * @see {setText}
+   */
+  set text(val) {
+    this._text = val
+    this._convertedText = null
+    this._subsSnapshot = null
+  }
+
+  /**
+   * Check whether the text of this list item is non-blank.
+   * @returns {boolean}
+   */
+  hasText() {
+    return !!(this._text && this._text.length > 0)
+  }
+
+  /**
+   * Pre-compute the converted text asynchronously.
+   * Called during `Document.parse()` so the synchronous getter works during conversion.
+   * @returns {Promise<void>}
+   */
+  async precomputeText() {
+    if (this._text != null && this._convertedText == null) {
+      this._convertedText = await this.applySubs(this._text, this.subs)
+      this._subsSnapshot = [...this.subs]
+    }
+  }
+
+  /**
+   * Check whether this list item has simple content.
+   * @returns {boolean} `true` if the item has no blocks or only a single nested outline list.
+   */
+  simple() {
+    return (
+      this.blocks.length === 0 ||
+      (this.blocks.length === 1 &&
+        this.blocks[0] instanceof List &&
+        this.blocks[0].outline())
+    )
+  }
+
+  /**
+   * Check whether this list item has compound content.
+   * @returns {boolean} `true` if the item contains blocks other than a single nested outline list.
+   */
+  compound() {
+    return !this.simple()
+  }
+
+  /** @internal Fold the adjacent paragraph block into the list item text. */
+  foldFirst() {
+    const src = this.blocks.shift().source
+    this._text =
+      !this._text || this._text.length === 0 ? src : `${this._text}${LF}${src}`
+  }
+
+  // ── JavaScript-style accessors ────────────────────────────────────────────────
+
+  /**
+   * Return the parent List block (alias of {@link getParent}).
+   * @returns {List}
+   * @see {getParent}
+   */
+  getList() {
+    return this.list
+  }
+
+  /**
+   * Return the list marker string for this item (e.g. '.', '..', '*').
+   * @returns {string|null}
+   */
+  getMarker() {
+    return this.marker
+  }
+
+  /**
+   * Return the text of this list item with substitutions applied.
+   * The result is pre-computed during `Document.parse()` via {@link precomputeText}.
+   * Falls back to the raw text if {@link precomputeText} has not been called yet.
+   *
+   * In Ruby, text is lazy (`apply_subs` on first access), so API callers can modify
+   * subs before accessing text and get the result they expect. Here we replicate
+   * that by invalidating the pre-computed value when subs have changed since it
+   * was computed: returning raw text mirrors what Ruby would produce when subs are
+   * cleared or reduced to a no-op set (since `applySubs` is async and cannot be
+   * re-run synchronously).
+   * @returns {string|null}
+   */
+  getText() {
+    return this.text
+  }
+
+  /**
+   * Set the raw text of this list item.
+   * @param {string|null} val
+   */
+  setText(val) {
+    this.text = val
+  }
+
+  toString() {
+    return `#<ListItem {list_context: '${this.getParent().context}', text: ${JSON.stringify(this._text)}, blocks: ${(this.blocks ?? []).length}}>`
+  }
+}

package/src/load.js

@@ -0,0 +1,276 @@
+// ESM conversion of load.rb
+//
+// Ruby-to-JavaScript notes:
+//   - Ruby module methods on Asciidoctor → named exports load() and loadFile().
+//   - Ruby File === input branch → Node.js fs.createReadStream / fs.readFileSync
+//     adapted to check for an object with a .read() method (duck-typing).
+//   - Ruby File.absolute_path / File.dirname / Helpers.basename / Helpers.extname
+//     → implemented using Node's node:path and the helpers.js module.
+//   - The timings option is passed through but its start/record calls are no-ops
+//     unless a real Timings object is supplied (interface: { start(label), record(label) }).
+//   - LoggerManager from logging.js is used to honour the :logger option.
+//   - SpaceDelimiterRx / EscapedSpaceRx / NULL are imported from rx.js / constants.js
+//     for string-form attributes parsing (mirrors the Ruby gsub/split dance).
+//   - Circular dependencies (Document ↔ Parser, etc.) are resolved via static ESM imports
+//     with live bindings; no lazy import() needed. Built-in converters are still loaded
+//     lazily by Converter.create() and self-register on first use.
+
+import { SpaceDelimiterRx, EscapedSpaceRx } from './rx.js'
+import { NULL, BACKEND_ALIASES } from './constants.js'
+import { LoggerManager, NullLogger } from './logging.js'
+import { basename, extname } from './helpers.js'
+import { Document } from './document.js'
+import { Converter } from './converter.js'
+import { SyntaxHighlighter } from './syntax_highlighter.js'
+import HighlightJsAdapter from './syntaxHighlighter/highlightjs.js'
+import HtmlPipelineAdapter from './syntaxHighlighter/html_pipeline.js'
+import { AbstractNode } from './abstract_node.js'
+import { Substitutors } from './substitutors.js'
+
+// Apply the Substitutors mixin to AbstractNode so that all nodes (Document,
+// Section, Block, etc.) have subSpecialchars, subAttributes, etc. available.
+Object.assign(AbstractNode.prototype, Substitutors)
+
+// Register built-in syntax highlighters (mirrors Ruby's `register_for`).
+SyntaxHighlighter.register(HighlightJsAdapter, 'highlightjs', 'highlight.js')
+SyntaxHighlighter.register(HtmlPipelineAdapter, 'html-pipeline')
+
+// ── load ──────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse the AsciiDoc source input into a Document.
+ *
+ * Accepts input as a Node.js Readable stream (or any object with a read()
+ * method), a String, or a String Array. If the input is a file descriptor
+ * object produced by openFile() / Node's fs.openSync(), pass a plain object
+ * with { path, read() } instead; the function sets docfile/docdir/docname
+ * attributes automatically.
+ *
+ * @param {Buffer|string|string[]|{path?: string, read(): string|Promise<string>, mtime?: Date}} input - The AsciiDoc source.
+ * @param {Object} [options={}] - Options to control processing. See Document for the full list.
+ * @param {string|string[]|Object} [options.attributes] - Document attributes.
+ * @param {boolean} [options.parse] - Set to false to skip parsing after Document creation.
+ * @param {Object} [options.logger] - Logger instance to use for this call.
+ * @param {{start(label: string): void, record(label: string): void}} [options.timings] - Timings object.
+ * @returns {Promise<Document>} A Promise that resolves to the Document.
+ */
+export async function load(input, options = {}) {
+  // Shallow-copy options so we don't mutate the caller's object.
+  options = Object.assign({}, options)
+
+  const timings = options.timings ?? null
+  if (timings) timings.start('read')
+
+  // ── Logger override ───────────────────────────────────────────────────────
+  if ('logger' in options) {
+    const logger = options.logger
+    if (logger !== LoggerManager.logger) {
+      LoggerManager.logger = logger ?? new NullLogger()
+    }
+  }
+
+  // ── Attributes normalisation ──────────────────────────────────────────────
+  let attrs = options.attributes
+  if (!attrs) {
+    attrs = {}
+  } else if (typeof attrs === 'string') {
+    // Condense non-escaped whitespace runs to NULL, unescape escaped spaces, split on NULL.
+    attrs = _parseAttributeString(attrs)
+  } else if (Array.isArray(attrs)) {
+    attrs = _parseAttributeArray(attrs)
+  } else if (typeof attrs === 'object') {
+    attrs = Object.assign({}, attrs)
+  } else {
+    throw new TypeError(`illegal type for attributes option: ${typeof attrs}`)
+  }
+
+  // ── Input reading ─────────────────────────────────────────────────────────
+  let source
+  if (input && typeof input === 'object' && typeof input.read === 'function') {
+    // Duck-typed file-like object: { path?, mtime?, read() }
+    if (input.path) {
+      // Treat it like a File object: resolve path, set docfile/docdir/docname.
+      const nodePath = await _requirePath()
+      const inputPath = nodePath.resolve(input.path)
+      if (input.mtime) options.input_mtime = input.mtime
+      attrs.docfile = inputPath
+      attrs.docdir = nodePath.dirname(inputPath)
+      const docfilesuffix = extname(inputPath)
+      attrs.docfilesuffix = docfilesuffix
+      attrs.docname = basename(inputPath, docfilesuffix)
+    }
+    source = await _readStream(input)
+  } else if (
+    typeof input === 'object' &&
+    input?.constructor?.name === 'Buffer'
+  ) {
+    source = input.toString('utf8')
+  } else if (typeof input === 'string') {
+    source = input
+  } else if (Array.isArray(input)) {
+    source = input.slice()
+  } else if (input) {
+    throw new TypeError(`unsupported input type: ${typeof input}`)
+  }
+
+  if (timings) {
+    timings.record('read')
+    timings.start('parse')
+  }
+
+  options.attributes = attrs
+
+  // ── Document construction + optional parse ────────────────────────────────
+  let doc
+  try {
+    let backend = String(attrs.backend || options.backend || 'html5')
+    // Strip soft-set modifier (@) and value-based soft-set (ending with @)
+    if (backend.endsWith('@')) backend = backend.slice(0, -1)
+    if (backend.startsWith('xhtml')) backend = `html${backend.slice(5)}` // xhtml5 → html5
+    backend = BACKEND_ALIASES[backend] ?? backend
+    await Converter.create(backend, {})
+    // If template dirs are requested, pre-create the async template converter
+    // so that _createConverter() can use it synchronously during Document construction.
+    // (In Ruby, Converter.create is synchronous; in JS we bridge the gap here.)
+    if (options.template_dir || options.template_dirs) {
+      const templateDirs = [].concat(
+        options.template_dirs ?? options.template_dir
+      )
+      const converterOpts = {
+        template_dirs: templateDirs,
+        template_cache: options.template_cache ?? true,
+        template_engine: options.template_engine,
+        template_engine_options: options.template_engine_options,
+      }
+      options._preCreatedConverter = await Converter.create(
+        backend,
+        converterOpts
+      )
+    }
+    if (options.parse !== false) {
+      doc = await Document.create(source, options)
+    } else {
+      doc = new Document(source, options)
+    }
+  } catch (e) {
+    const docfile = attrs.docfile || '<stdin>'
+    const context = `asciidoctor: FAILED: ${docfile}: Failed to load AsciiDoc document`
+    let wrapped
+    try {
+      wrapped = new Error(`${context} - ${e.message}`)
+      wrapped.stack = e.stack
+      wrapped.cause = e
+    } catch {
+      wrapped = e
+    }
+    throw wrapped
+  }
+
+  if (timings) timings.record('parse')
+  return doc
+}
+
+// ── loadFile ──────────────────────────────────────────────────────────────────
+
+/**
+ * Parse the contents of the AsciiDoc source file into a Document.
+ *
+ * @param {string} filename - The path to the AsciiDoc source file.
+ * @param {Object} [options={}] - Options to control processing.
+ * @returns {Promise<Document>} A Promise that resolves to the Document.
+ */
+export async function loadFile(filename, options = {}) {
+  const { readFile } = await import('node:fs/promises')
+  const nodePath = await _requirePath()
+  const absPath = nodePath.resolve(filename)
+  const content = await readFile(absPath, 'utf8')
+  // Build a file-like object so load() can set docfile/docdir/docname.
+  const { stat } = await import('node:fs/promises')
+  let mtime
+  try {
+    const s = await stat(absPath)
+    mtime = s.mtime
+  } catch {
+    /* ignore */
+  }
+  const fileObj = {
+    path: absPath,
+    mtime,
+    read() {
+      return content
+    },
+  }
+  return load(fileObj, options)
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a whitespace-delimited attribute string into a plain object.
+ *
+ * Mirrors the Ruby idiom:
+ *   attrs.gsub(SpaceDelimiterRx, '\1' + NULL).gsub(EscapedSpaceRx, '\1').split(NULL)
+ *
+ * @param {string} str - The attribute string to parse.
+ * @returns {Object} A plain object mapping attribute keys to values.
+ * @internal
+ */
+function _parseAttributeString(str) {
+  const condensed = str
+    .replace(SpaceDelimiterRx, `$1${NULL}`)
+    .replace(EscapedSpaceRx, '$1')
+  const result = {}
+  for (const entry of condensed.split(NULL)) {
+    if (!entry) continue
+    const eqIdx = entry.indexOf('=')
+    if (eqIdx < 0) {
+      result[entry] = ''
+    } else {
+      result[entry.slice(0, eqIdx)] = entry.slice(eqIdx + 1)
+    }
+  }
+  return result
+}
+
+/**
+ * Parse an array of "key=value" entries into a plain object.
+ *
+ * @param {string[]} arr - Array of "key=value" strings.
+ * @returns {Object} A plain object mapping attribute keys to values.
+ * @internal
+ */
+function _parseAttributeArray(arr) {
+  const result = {}
+  for (const entry of arr) {
+    const eqIdx = entry.indexOf('=')
+    if (eqIdx < 0) {
+      result[entry] = ''
+    } else {
+      result[entry.slice(0, eqIdx)] = entry.slice(eqIdx + 1)
+    }
+  }
+  return result
+}
+
+/**
+ * Read all data from an object that has a .read() method.
+ * Supports both synchronous (returns string) and async (returns Promise) variants.
+ *
+ * @param {{read(): string|Promise<string>}} readable - The readable object.
+ * @returns {Promise<string>} A Promise that resolves to a String.
+ * @internal
+ */
+async function _readStream(readable) {
+  const data = readable.read()
+  return data instanceof Promise ? data : Promise.resolve(data ?? '')
+}
+
+/**
+ * Lazily import node:path to avoid issues in browser / Opal environments.
+ *
+ * @returns {Promise<typeof import('node:path')>} A Promise that resolves to the node:path module.
+ * @internal
+ */
+async function _requirePath() {
+  return import('node:path')
+}