@xpack/doxygen2docusaurus 1.0.2

package/dist/doxygen/data-model/doxyfile/doxyfiletype-dm.js

@@ -0,0 +1,92 @@
+/*
+ * This file is part of the xPack project (http://xpack.github.io).
+ * Copyright (c) 2025 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software
+ * for any purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can
+ * be obtained from https://opensource.org/licenses/MIT.
+ */
+// ----------------------------------------------------------------------------
+import assert from 'node:assert';
+import * as util from 'node:util';
+import { DoxygenFileOptionDataModel } from './doxyfileoptiontype-dm.js';
+import { AbstractDataModelBase } from '../types.js';
+// ----------------------------------------------------------------------------
+// <xsd:complexType name="DoxygenFileType">
+//   <xsd:sequence>
+//     <xsd:element name="option" type="OptionType" minOccurs="0" maxOccurs="unbounded"/>
+//   </xsd:sequence>
+//   <xsd:attribute name="version" type="xsd:string" use="required"/>
+//   <xsd:attribute ref="xml:lang" use="required"/>
+// </xsd:complexType>
+/**
+ * @public
+ */
+export class AbstractDoxygenFileType extends AbstractDataModelBase {
+    // Mandatory attributes.
+    version = '';
+    lang = '';
+    // Optional elements.
+    options;
+    // Optional attributes.
+    noNamespaceSchemaLocation;
+    constructor(xml, element, elementName) {
+        super(elementName);
+        // console.log(elementName, util.inspect(element, { compact: false, depth: 999 }))
+        const innerElements = xml.getInnerElements(element, elementName);
+        assert(innerElements.length > 0);
+        for (const innerElement of innerElements) {
+            if (xml.hasInnerText(innerElement)) {
+                // Ignore texts.
+            }
+            else if (xml.hasInnerElement(innerElement, 'option')) {
+                this.options ??= [];
+                this.options.push(new DoxygenFileOptionDataModel(xml, innerElement));
+            }
+            else {
+                console.error(util.inspect(innerElement));
+                console.error(`doxyfile ${elementName} element:`, Object.keys(innerElement), 'not implemented yet in', this.constructor.name);
+            }
+        }
+        // ------------------------------------------------------------------------
+        // Process attributes.
+        assert(xml.hasAttributes(element));
+        const attributesNames = xml.getAttributesNames(element);
+        // console.log(attributesNames)
+        for (const attributeName of attributesNames) {
+            // console.log(attributeName)
+            if (attributeName === '@_version') {
+                this.version = xml.getAttributeStringValue(element, '@_version');
+            }
+            else if (attributeName === '@_lang') {
+                this.lang = xml.getAttributeStringValue(element, '@_lang');
+            }
+            else if (attributeName === '@_noNamespaceSchemaLocation') {
+                this.noNamespaceSchemaLocation = xml.getAttributeStringValue(element, '@_noNamespaceSchemaLocation');
+            }
+            else {
+                console.error(util.inspect(element, { compact: false, depth: 999 }));
+                console.error(`doxyfile ${elementName} attribute:`, attributeName, 'not implemented yet in', this.constructor.name);
+            }
+        }
+        assert(this.version.length > 0);
+        assert(this.lang.length > 0);
+        // ------------------------------------------------------------------------
+        // console.log(util.inspect(this, { compact: false, depth: 999 }))
+    }
+}
+// ----------------------------------------------------------------------------
+// <xsd:element name="doxyfile" type="DoxygenFileType"/>
+/**
+ * @public
+ */
+export class DoxygenFileDataModel extends AbstractDoxygenFileType {
+    constructor(xml, element) {
+        // console.log(elementName, util.inspect(element, { compact: false, depth: 999 }))
+        super(xml, element, 'doxyfile');
+    }
+}
+// ----------------------------------------------------------------------------
+//# sourceMappingURL=doxyfiletype-dm.js.map

package/dist/doxygen/data-model/doxyfile/doxyfiletype-dm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doxyfiletype-dm.js","sourceRoot":"","sources":["../../../../src/doxygen/data-model/doxyfile/doxyfiletype-dm.ts"],"names":[],"mappings":"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"}

package/dist/doxygen/data-model/doxygen-xml-parser.d.ts

@@ -0,0 +1,261 @@
+import { XMLParser } from 'fast-xml-parser';
+import { XmlElement } from './types.js';
+import { CliOptions } from '../../docusaurus/cli-options.js';
+import { AbstractDocImageType } from './compounds/descriptiontype-dm.js';
+/**
+ * The DoxygenXmlParser class is responsible for parsing
+ * Doxygen-generated XML files and constructing the internal data model.
+ *
+ * @remarks
+ * This class initialises the XML parser with options that preserve the order
+ * and structure of the original XML content, ensuring accurate conversion
+ * for documentation purposes. It maintains a counter for the number of files
+ * parsed and stores the resulting data model.
+ *
+ * @example
+ * ```typescript
+ * const parser = new DoxygenXmlParser({ options });
+ * const dataModel = await parser.parse();
+ * ```
+ *
+ * @public
+ */
+export declare class DoxygenXmlParser {
+    /**
+     * The global configuration options.
+     */
+    options: CliOptions;
+    /**
+     * The XML parser instance configured for Doxygen XML.
+     */
+    xmlParser: XMLParser;
+    images: AbstractDocImageType[];
+    /**
+     * Constructs a new instance of the DoxygenXmlParser class.
+     *
+     * @param options - The global configuration options
+     *
+     * @remarks
+     * This constructor initialises the XML parser with settings that preserve the
+     * order and structure of the original XML content, remove namespace prefixes,
+     * and ensure that both tag and attribute values are parsed. The values are
+     * not
+     * trimmed, maintaining fidelity to the source XML. The provided options are
+     * stored for use throughout the parsing process.
+     */
+    constructor(options: CliOptions);
+    /**
+     * Determines whether the specified XML element has any attributes.
+     *
+     * @param element - The XML element to inspect for attributes
+     * @returns True if the element has attributes; otherwise, false
+     *
+     * @remarks
+     * This method checks for the presence of the ':\@' property on the XML
+     * element, which is the convention used by the XML parser for storing
+     * attributes. If this property exists, the element has attributes; if not,
+     * the element has no attributes. This is a prerequisite check before calling
+     * {@link DoxygenXmlParser.getAttributesNames} or other attribute-related
+     * methods.
+     */
+    hasAttributes(element: object): boolean;
+    /**
+     * Retrieves the names of all attributes present on the specified XML element.
+     *
+     * @param element - The XML element to inspect for attribute names
+     * @returns An array of strings containing the names of all attributes
+     *
+     * @remarks
+     * This method accesses the ':\@' property of the XML element, which is the
+     * convention used by the XML parser for storing attributes, and returns the
+     * keys of this object as an array of attribute names. The method assumes the
+     * element has attributes and does not perform validation - use
+     * {@link DoxygenXmlParser.hasAttributes} to check for attribute presence
+     * first.
+     */
+    getAttributesNames(element: object): string[];
+    /**
+     * Determines whether the specified attribute exists on the given XML element.
+     *
+     * @param element - The XML element to inspect
+     * @param name - The name of the attribute to check for
+     * @returns True if the attribute exists; otherwise, false
+     *
+     * @remarks
+     * This method checks for the presence of an attribute within the ':\@'
+     * property of the XML element, which is the convention used by the XML
+     * parser for storing attributes. It returns true if the attribute is found,
+     * otherwise false.
+     */
+    hasAttribute(element: object, name: string): boolean;
+    /**
+     * Retrieves the value of a named attribute as a string.
+     *
+     * @param element - The XML element containing the attribute
+     * @param name - The name of the attribute to retrieve
+     * @returns The attribute value as a string
+     * @throws If the attribute does not exist
+     *
+     * @remarks
+     * This method checks whether the specified attribute exists on the XML
+     * element and returns its value as a string. If the attribute value is
+     * originally a number (as the XML parser may return numeric strings as
+     * numbers), it is converted to a string to maintain consistency with the
+     * DTD specification. If the attribute is missing, an error is thrown to
+     * indicate the absence.
+     */
+    getAttributeStringValue(element: object, name: string): string;
+    /**
+     * Retrieves the value of a named attribute as a number.
+     *
+     * @param element - The XML element containing the attribute
+     * @param name - The name of the attribute to retrieve
+     * @returns The attribute value as a number
+     * @throws If the attribute does not exist or is not a number
+     *
+     * @remarks
+     * This method checks whether the specified attribute exists on the XML
+     * element and returns its value as a number. If the attribute is missing
+     * or its value is not a number, an error is thrown to indicate the absence
+     * or incorrect type.
+     */
+    getAttributeNumberValue(element: object, name: string): number;
+    /**
+     * Retrieves the value of a named attribute as a boolean.
+     *
+     * @param element - The XML element containing the attribute
+     * @param name - The name of the attribute to retrieve
+     * @returns True if the attribute value is 'yes' (case-insensitive);
+     * otherwise, false
+     * @throws If the attribute does not exist or is not a string
+     *
+     * @remarks
+     * This method checks whether the specified attribute exists on the XML
+     * element, and returns true if its value is the string 'yes'
+     * (case-insensitive). If the attribute is missing or its value is not a
+     * string, an error is thrown.
+     */
+    getAttributeBooleanValue(element: object, name: string): boolean;
+    /**
+     * Determines whether the specified inner element exists on the given XML
+     * element.
+     *
+     * @param element - The XML element to inspect
+     * @param name - The name of the inner element to check for
+     * @returns True if the inner element exists; otherwise, false
+     *
+     * @remarks
+     * This method checks for the presence of a named property on the XML element.
+     * For text nodes ('#text'), it verifies the value is a string, number, or
+     * boolean. For other elements, it confirms the property is an array, as
+     * per the XML parser's convention.
+     */
+    hasInnerElement(element: object, name: string): boolean;
+    /**
+     * Determines whether a named inner element contains text.
+     *
+     * @param element - The XML element to inspect
+     * @param name - The name of the inner element
+     * @returns True if the inner element contains text or is empty;
+     * otherwise, false
+     *
+     * @remarks
+     * This method checks if the specified inner element exists and contains a
+     * single text node, or is an empty array (representing an empty string).
+     * It asserts the expected structure and type of the value for robustness.
+     */
+    isInnerElementText(element: object, name: string): boolean;
+    /**
+     * Determines whether the XML element contains a text node.
+     *
+     * @param element - The XML element to inspect
+     * @returns True if the element contains a text node; otherwise, false
+     *
+     * @remarks
+     * This method checks for the presence of a '#text' property on the XML
+     * element, and verifies that its value is a string, number, or boolean.
+     */
+    hasInnerText(element: object): boolean;
+    /**
+     * Retrieves an array of named child elements from the given XML element.
+     *
+     * @typeParam T - The expected type of the child elements array
+     * (defaults to XmlElement[])
+     * @param element - The XML element containing the child elements
+     * @param name - The name of the child elements to retrieve
+     * @returns The array of child elements
+     * @throws If the child elements do not exist
+     *
+     * @remarks
+     * This method accesses the specified property on the XML element and
+     * returns it as an array of child elements. If the property is undefined,
+     * an error is thrown indicating the absence of the expected child element.
+     */
+    getInnerElements<T = XmlElement[]>(element: object, name: string): T;
+    /**
+     * Retrieves the text content of a named child element.
+     *
+     * @param element - The XML element containing the child element
+     * @param name - The name of the child element
+     * @returns The text content of the child element
+     * @throws If the child element does not exist or contains more than one
+     * element
+     *
+     * @remarks
+     * This method accesses the specified child element and returns its text
+     * content. If the child element is missing, an error is thrown. If the
+     * child element is empty, an empty string is returned. If there is more
+     * than one child element, an error is thrown to indicate unexpected
+     * structure.
+     */
+    getInnerElementText(element: object, name: string): string;
+    /**
+     * Retrieves the numeric value of a named child element.
+     *
+     * @param element - The XML element containing the child element
+     * @param name - The name of the child element
+     * @returns The numeric value of the child element
+     * @throws If the child element does not exist or contains more than one
+     * element
+     *
+     * @remarks
+     * This method accesses the specified child element and returns its value
+     * as a number. If the child element is missing, an error is thrown. If the
+     * child element is empty, NaN is returned. If there is more than one child
+     * element, an error is thrown to indicate unexpected structure.
+     */
+    getInnerElementNumber(element: object, name: string): number;
+    /**
+     * Retrieves the boolean value of a named child element.
+     *
+     * @param element - The XML element containing the child element
+     * @param name - The name of the child element
+     * @returns True if the child element's text is 'true'
+     * (case-insensitive); otherwise, false
+     * @throws If the child element does not exist or contains more than one
+     * element
+     *
+     * @remarks
+     * This method accesses the specified child element and returns its value
+     * as a boolean. If the child element is missing, an error is thrown. If
+     * the child element is empty, false is returned. If there is more than one
+     * child element, an error is thrown to indicate unexpected structure.
+     */
+    getInnerElementBoolean(element: object, name: string): boolean;
+    /**
+     * Retrieves the text content of the XML element.
+     *
+     * @param element - The XML element to retrieve text from
+     * @returns The text content of the element
+     * @throws If the element does not contain a valid text node
+     *
+     * @remarks
+     * This method accesses the '#text' property of the XML element and
+     * returns its value as a string. It asserts that the value is of type
+     * string, number, or boolean before converting it to a string. If the
+     * property is missing or the value is of an unexpected type, an error is
+     * thrown.
+     */
+    getInnerText(element: object): string;
+}
+//# sourceMappingURL=doxygen-xml-parser.d.ts.map

package/dist/doxygen/data-model/doxygen-xml-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doxygen-xml-parser.d.ts","sourceRoot":"","sources":["../../../src/doxygen/data-model/doxygen-xml-parser.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAA;AAIxE;;;;;;;;;;;;;;;;;GAiBG;AAEH,qBAAa,gBAAgB;IAC3B;;OAEG;IACH,OAAO,EAAE,UAAU,CAAA;IAEnB;;OAEG;IACH,SAAS,EAAE,SAAS,CAAA;IAEpB,MAAM,EAAE,oBAAoB,EAAE,CAAK;IAEnC;;;;;;;;;;;;OAYG;gBACS,OAAO,EAAE,UAAU;IAe/B;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIvC;;;;;;;;;;;;;OAaG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAK7C;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAUpD;;;;;;;;;;;;;;;OAeG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAoB9D;;;;;;;;;;;;;OAaG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAgB9D;;;;;;;;;;;;;;OAcG;IACH,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAgBhE;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAoBvD;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IA6B1D;;;;;;;;;OASG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAetC;;;;;;;;;;;;;;OAcG;IAEH,gBAAgB,CAAC,CAAC,GAAG,UAAU,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IAapE;;;;;;;;;;;;;;;OAeG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAoB1D;;;;;;;;;;;;;;OAcG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAoB5D;;;;;;;;;;;;;;;OAeG;IACH,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAqB9D;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAUtC"}