nokogiri 1.11.7 → 1.12.5

data/gumbo-parser/src/gumbo.h

@@ -0,0 +1,943 @@
+// Copyright 2010 Google Inc.
+// Copyright 2018 Craig Barnes.
+// Licensed under the Apache License, version 2.0.
+
+// We use Gumbo as a prefix for types, gumbo_ as a prefix for functions,
+// GUMBO_ as a prefix for enum constants and kGumbo as a prefix for
+// static constants
+
+/**
+ * @file
+ * @mainpage Gumbo HTML Parser
+ *
+ * This provides a conformant, no-dependencies implementation of the
+ * [HTML5] parsing algorithm. It supports only UTF-8 -- if you need
+ * to parse a different encoding, run a preprocessing step to convert
+ * to UTF-8. It returns a parse tree made of the structs in this file.
+ *
+ * Example:
+ * @code
+ *    GumboOutput* output = gumbo_parse(input);
+ *    do_something_with_doctype(output->document);
+ *    do_something_with_html_tree(output->root);
+ *    gumbo_destroy_output(output);
+ * @endcode
+ *
+ * [HTML5]: https://html.spec.whatwg.org/multipage/
+ */
+
+#ifndef GUMBO_H
+#define GUMBO_H
+
+#include <stdbool.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * A struct representing a character position within the original text
+ * buffer. Line and column numbers are 1-based and offsets are 0-based,
+ * which matches how most editors and command-line tools work.
+ */
+typedef struct {
+  size_t line;
+  size_t column;
+  size_t offset;
+} GumboSourcePosition;
+
+/**
+ * A struct representing a string or part of a string. Strings within
+ * the parser are represented by a `char*` and a length; the `char*`
+ * points into an existing data buffer owned by some other code (often
+ * the original input). `GumboStringPiece`s are assumed (by convention)
+ * to be immutable, because they may share data. Clients should assume
+ * that it is not NUL-terminated and should always use explicit lengths
+ * when manipulating them.
+ */
+typedef struct {
+  /** A pointer to the beginning of the string. `NULL` if `length == 0`. */
+  const char* data;
+
+  /** The length of the string fragment, in bytes (may be zero). */
+  size_t length;
+} GumboStringPiece;
+
+#define GUMBO_EMPTY_STRING_INIT { .data = NULL, .length = 0 }
+/** A constant to represent a 0-length null string. */
+#define kGumboEmptyString (const GumboStringPiece)GUMBO_EMPTY_STRING_INIT
+
+/**
+ * Compares two `GumboStringPiece`s, and returns `true` if they're
+ * equal or `false` otherwise.
+ */
+bool gumbo_string_equals (
+  const GumboStringPiece* str1,
+  const GumboStringPiece* str2
+);
+
+/**
+ * Compares two `GumboStringPiece`s, ignoring case, and returns `true`
+ * if they're equal or `false` otherwise.
+ */
+bool gumbo_string_equals_ignore_case (
+  const GumboStringPiece* str1,
+  const GumboStringPiece* str2
+);
+
+/**
+ * Check if the first `GumboStringPiece` is a prefix of the second, ignoring
+ * case.
+ */
+bool gumbo_string_prefix_ignore_case (
+  const GumboStringPiece* prefix,
+  const GumboStringPiece* str
+);
+
+/**
+ * A simple vector implementation. This stores a pointer to a data array
+ * and a length. All elements are stored as `void*`; client code must
+ * cast to the appropriate type. Overflows upon addition result in
+ * reallocation of the data array, with the size doubling to maintain
+ * `O(1)` amortized cost. There is no removal function, as this isn't
+ * needed for any of the operations within this library. Iteration can
+ * be done through inspecting the structure directly in a `for` loop.
+ */
+typedef struct {
+  /**
+   * Data elements. This points to a dynamically-allocated array of
+   * `capacity` elements, each a `void*` to the element itself.
+   */
+  void** data;
+
+  /** Number of elements currently in the vector. */
+  unsigned int length;
+
+  /** Current array capacity. */
+  unsigned int capacity;
+} GumboVector;
+
+# define GUMBO_EMPTY_VECTOR_INIT { .data = NULL, .length = 0, .capacity = 0 }
+/** An empty (0-length, 0-capacity) `GumboVector`. */
+#define kGumboEmptyVector (const GumboVector)GUMBO_EMPTY_VECTOR_INIT
+
+/**
+ * Returns the first index at which an element appears in this vector
+ * (testing by pointer equality), or `-1` if it never does.
+ */
+int gumbo_vector_index_of(GumboVector* vector, const void* element);
+
+/**
+ * An `enum` for all the tags defined in the HTML5 standard. These
+ * correspond to the tag names themselves. Enum constants exist only
+ * for tags that appear in the spec itself (or for tags with special
+ * handling in the SVG and MathML namespaces). Any other tags appear
+ * as `GUMBO_TAG_UNKNOWN` and the actual tag name can be obtained
+ * through `original_tag`.
+ *
+ * This is mostly for API convenience, so that clients of this library
+ * don't need to perform a `strcasecmp` to find the normalized tag
+ * name. It also has efficiency benefits, by letting the parser work
+ * with enums instead of strings.
+ */
+typedef enum {
+  GUMBO_TAG_HTML,
+  GUMBO_TAG_HEAD,
+  GUMBO_TAG_TITLE,
+  GUMBO_TAG_BASE,
+  GUMBO_TAG_LINK,
+  GUMBO_TAG_META,
+  GUMBO_TAG_STYLE,
+  GUMBO_TAG_SCRIPT,
+  GUMBO_TAG_NOSCRIPT,
+  GUMBO_TAG_TEMPLATE,
+  GUMBO_TAG_BODY,
+  GUMBO_TAG_ARTICLE,
+  GUMBO_TAG_SECTION,
+  GUMBO_TAG_NAV,
+  GUMBO_TAG_ASIDE,
+  GUMBO_TAG_H1,
+  GUMBO_TAG_H2,
+  GUMBO_TAG_H3,
+  GUMBO_TAG_H4,
+  GUMBO_TAG_H5,
+  GUMBO_TAG_H6,
+  GUMBO_TAG_HGROUP,
+  GUMBO_TAG_HEADER,
+  GUMBO_TAG_FOOTER,
+  GUMBO_TAG_ADDRESS,
+  GUMBO_TAG_P,
+  GUMBO_TAG_HR,
+  GUMBO_TAG_PRE,
+  GUMBO_TAG_BLOCKQUOTE,
+  GUMBO_TAG_OL,
+  GUMBO_TAG_UL,
+  GUMBO_TAG_LI,
+  GUMBO_TAG_DL,
+  GUMBO_TAG_DT,
+  GUMBO_TAG_DD,
+  GUMBO_TAG_FIGURE,
+  GUMBO_TAG_FIGCAPTION,
+  GUMBO_TAG_MAIN,
+  GUMBO_TAG_DIV,
+  GUMBO_TAG_A,
+  GUMBO_TAG_EM,
+  GUMBO_TAG_STRONG,
+  GUMBO_TAG_SMALL,
+  GUMBO_TAG_S,
+  GUMBO_TAG_CITE,
+  GUMBO_TAG_Q,
+  GUMBO_TAG_DFN,
+  GUMBO_TAG_ABBR,
+  GUMBO_TAG_DATA,
+  GUMBO_TAG_TIME,
+  GUMBO_TAG_CODE,
+  GUMBO_TAG_VAR,
+  GUMBO_TAG_SAMP,
+  GUMBO_TAG_KBD,
+  GUMBO_TAG_SUB,
+  GUMBO_TAG_SUP,
+  GUMBO_TAG_I,
+  GUMBO_TAG_B,
+  GUMBO_TAG_U,
+  GUMBO_TAG_MARK,
+  GUMBO_TAG_RUBY,
+  GUMBO_TAG_RT,
+  GUMBO_TAG_RP,
+  GUMBO_TAG_BDI,
+  GUMBO_TAG_BDO,
+  GUMBO_TAG_SPAN,
+  GUMBO_TAG_BR,
+  GUMBO_TAG_WBR,
+  GUMBO_TAG_INS,
+  GUMBO_TAG_DEL,
+  GUMBO_TAG_IMAGE,
+  GUMBO_TAG_IMG,
+  GUMBO_TAG_IFRAME,
+  GUMBO_TAG_EMBED,
+  GUMBO_TAG_OBJECT,
+  GUMBO_TAG_PARAM,
+  GUMBO_TAG_VIDEO,
+  GUMBO_TAG_AUDIO,
+  GUMBO_TAG_SOURCE,
+  GUMBO_TAG_TRACK,
+  GUMBO_TAG_CANVAS,
+  GUMBO_TAG_MAP,
+  GUMBO_TAG_AREA,
+  GUMBO_TAG_MATH,
+  GUMBO_TAG_MI,
+  GUMBO_TAG_MO,
+  GUMBO_TAG_MN,
+  GUMBO_TAG_MS,
+  GUMBO_TAG_MTEXT,
+  GUMBO_TAG_MGLYPH,
+  GUMBO_TAG_MALIGNMARK,
+  GUMBO_TAG_ANNOTATION_XML,
+  GUMBO_TAG_SVG,
+  GUMBO_TAG_FOREIGNOBJECT,
+  GUMBO_TAG_DESC,
+  GUMBO_TAG_TABLE,
+  GUMBO_TAG_CAPTION,
+  GUMBO_TAG_COLGROUP,
+  GUMBO_TAG_COL,
+  GUMBO_TAG_TBODY,
+  GUMBO_TAG_THEAD,
+  GUMBO_TAG_TFOOT,
+  GUMBO_TAG_TR,
+  GUMBO_TAG_TD,
+  GUMBO_TAG_TH,
+  GUMBO_TAG_FORM,
+  GUMBO_TAG_FIELDSET,
+  GUMBO_TAG_LEGEND,
+  GUMBO_TAG_LABEL,
+  GUMBO_TAG_INPUT,
+  GUMBO_TAG_BUTTON,
+  GUMBO_TAG_SELECT,
+  GUMBO_TAG_DATALIST,
+  GUMBO_TAG_OPTGROUP,
+  GUMBO_TAG_OPTION,
+  GUMBO_TAG_TEXTAREA,
+  GUMBO_TAG_KEYGEN,
+  GUMBO_TAG_OUTPUT,
+  GUMBO_TAG_PROGRESS,
+  GUMBO_TAG_METER,
+  GUMBO_TAG_DETAILS,
+  GUMBO_TAG_SUMMARY,
+  GUMBO_TAG_MENU,
+  GUMBO_TAG_MENUITEM,
+  GUMBO_TAG_APPLET,
+  GUMBO_TAG_ACRONYM,
+  GUMBO_TAG_BGSOUND,
+  GUMBO_TAG_DIR,
+  GUMBO_TAG_FRAME,
+  GUMBO_TAG_FRAMESET,
+  GUMBO_TAG_NOFRAMES,
+  GUMBO_TAG_LISTING,
+  GUMBO_TAG_XMP,
+  GUMBO_TAG_NEXTID,
+  GUMBO_TAG_NOEMBED,
+  GUMBO_TAG_PLAINTEXT,
+  GUMBO_TAG_RB,
+  GUMBO_TAG_STRIKE,
+  GUMBO_TAG_BASEFONT,
+  GUMBO_TAG_BIG,
+  GUMBO_TAG_BLINK,
+  GUMBO_TAG_CENTER,
+  GUMBO_TAG_FONT,
+  GUMBO_TAG_MARQUEE,
+  GUMBO_TAG_MULTICOL,
+  GUMBO_TAG_NOBR,
+  GUMBO_TAG_SPACER,
+  GUMBO_TAG_TT,
+  GUMBO_TAG_RTC,
+  GUMBO_TAG_DIALOG,
+  // Used for all tags that don't have special handling in HTML.
+  GUMBO_TAG_UNKNOWN,
+  // A marker value to indicate the end of the enum, for iterating over it.
+  GUMBO_TAG_LAST,
+} GumboTag;
+
+/**
+ * Returns the normalized (all lower case) tag name for a `GumboTag` enum. The
+ * return value is static data owned by the library.
+ */
+const char* gumbo_normalized_tagname(GumboTag tag);
+
+/**
+ * Extracts the tag name from the `original_text` field of an element
+ * or token by stripping off `</>` characters and attributes and
+ * adjusting the passed-in `GumboStringPiece` appropriately. The tag
+ * name is in the original case and shares a buffer with the original
+ * text, to simplify memory management. Behavior is undefined if a
+ * string piece that doesn't represent an HTML tag (`<tagname>` or
+ * `</tagname>`) is passed in. If the string piece is completely
+ * empty (`NULL` data pointer), then this function will exit
+ * successfully as a no-op.
+ */
+void gumbo_tag_from_original_text(GumboStringPiece* text);
+
+/**
+ * Fixes the case of SVG elements that are not all lowercase. This is
+ * not done at parse time because there's no place to store a mutated
+ * tag name. `tag_name` is an enum (which will be `TAG_UNKNOWN` for most
+ * SVG tags without special handling), while `original_tag_name` is a
+ * pointer into the original buffer. Instead, we provide this helper
+ * function that clients can use to rename SVG tags as appropriate.
+ * Returns the case-normalized SVG tagname if a replacement is found, or
+ * `NULL` if no normalization is called for. The return value is static
+ * data and owned by the library.
+ *
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#parsing-main-inforeign
+ */
+const char* gumbo_normalize_svg_tagname(const GumboStringPiece* tagname);
+
+/**
+ * Converts a tag name string (which may be in upper or mixed case) to a
+ * tag enum.
+ */
+GumboTag gumbo_tagn_enum(const char* tagname, size_t length);
+
+/**
+ * Attribute namespaces.
+ * HTML includes special handling for XLink, XML, and XMLNS namespaces
+ * on attributes. Everything else goes in the generic "NONE" namespace.
+ */
+typedef enum {
+  GUMBO_ATTR_NAMESPACE_NONE,
+  GUMBO_ATTR_NAMESPACE_XLINK,
+  GUMBO_ATTR_NAMESPACE_XML,
+  GUMBO_ATTR_NAMESPACE_XMLNS,
+} GumboAttributeNamespaceEnum;
+
+/**
+ * A struct representing a single attribute on a HTML tag. This is a
+ * name-value pair, but also includes information about source locations
+ * and original source text.
+ */
+typedef struct {
+  /**
+   * The namespace for the attribute. This will usually be
+   * `GUMBO_ATTR_NAMESPACE_NONE`, but some XLink/XMLNS/XML attributes
+   * take special values, per:
+   * https://html.spec.whatwg.org/multipage/parsing.html#adjust-foreign-attributes
+   */
+  GumboAttributeNamespaceEnum attr_namespace;
+
+  /**
+   * The name of the attribute. This is in a freshly-allocated buffer to
+   * deal with case-normalization and is null-terminated.
+   */
+  const char* name;
+
+  /**
+   * The original text of the attribute name, as a pointer into the
+   * original source buffer.
+   */
+  GumboStringPiece original_name;
+
+  /**
+   * The value of the attribute. This is in a freshly-allocated buffer
+   * to deal with unescaping and is null-terminated. It does not include
+   * any quotes that surround the attribute. If the attribute has no
+   * value (for example, `selected` on a checkbox) this will be an empty
+   * string.
+   */
+  const char* value;
+
+  /**
+   * The original text of the value of the attribute. This points into
+   * the original source buffer. It includes any quotes that surround
+   * the attribute and you can look at `original_value.data[0]` and
+   * `original_value.data[original_value.length - 1]` to determine what
+   * the quote characters were. If the attribute has no value this will
+   * be a 0-length string.
+   */
+  GumboStringPiece original_value;
+
+  /** The starting position of the attribute name. */
+  GumboSourcePosition name_start;
+
+  /**
+   * The ending position of the attribute name. This is not always derivable
+   * from the starting position of the value because of the possibility of
+   * whitespace around the `=` sign.
+   */
+  GumboSourcePosition name_end;
+
+  /** The starting position of the attribute value. */
+  GumboSourcePosition value_start;
+
+  /** The ending position of the attribute value. */
+  GumboSourcePosition value_end;
+} GumboAttribute;
+
+/**
+ * Given a vector of `GumboAttribute`s, look up the one with the
+ * specified name and return it, or `NULL` if no such attribute exists.
+ * This uses a case-insensitive match, as HTML is case-insensitive.
+ */
+GumboAttribute* gumbo_get_attribute(const GumboVector* attrs, const char* name);
+
+/**
+ * Enum denoting the type of node. This determines the type of the
+ * `node.v` union.
+ */
+typedef enum {
+  /** Document node. `v` will be a `GumboDocument`. */
+  GUMBO_NODE_DOCUMENT,
+  /** Element node. `v` will be a `GumboElement`. */
+  GUMBO_NODE_ELEMENT,
+  /** Text node. `v` will be a `GumboText`. */
+  GUMBO_NODE_TEXT,
+  /** CDATA node. `v` will be a `GumboText`. */
+  GUMBO_NODE_CDATA,
+  /** Comment node. `v` will be a `GumboText`, excluding comment delimiters. */
+  GUMBO_NODE_COMMENT,
+  /** Text node, where all contents is whitespace. `v` will be a `GumboText`. */
+  GUMBO_NODE_WHITESPACE,
+  /**
+   * Template node. This is separate from `GUMBO_NODE_ELEMENT` because
+   * many client libraries will want to ignore the contents of template
+   * nodes, as the spec suggests. Recursing on `GUMBO_NODE_ELEMENT` will
+   * do the right thing here, while clients that want to include template
+   * contents should also check for `GUMBO_NODE_TEMPLATE`. `v` will be a
+   * `GumboElement`.
+   */
+  GUMBO_NODE_TEMPLATE
+} GumboNodeType;
+
+/**
+ * Forward declaration of GumboNode so it can be used recursively in
+ * GumboNode.parent.
+ */
+typedef struct GumboInternalNode GumboNode;
+
+/** https://dom.spec.whatwg.org/#concept-document-quirks */
+typedef enum {
+  GUMBO_DOCTYPE_NO_QUIRKS,
+  GUMBO_DOCTYPE_QUIRKS,
+  GUMBO_DOCTYPE_LIMITED_QUIRKS
+} GumboQuirksModeEnum;
+
+/**
+ * Namespaces.
+ * Unlike in X(HT)ML, namespaces in HTML5 are not denoted by a prefix.
+ * Rather, anything inside an `<svg>` tag is in the SVG namespace,
+ * anything inside the `<math>` tag is in the MathML namespace, and
+ * anything else is inside the HTML namespace. No other namespaces are
+ * supported, so this can be an `enum`.
+ */
+typedef enum {
+  GUMBO_NAMESPACE_HTML,
+  GUMBO_NAMESPACE_SVG,
+  GUMBO_NAMESPACE_MATHML
+} GumboNamespaceEnum;
+
+/**
+ * Parse flags.
+ * We track the reasons for parser insertion of nodes and store them in
+ * a bitvector in the node itself. This lets client code optimize out
+ * nodes that are implied by the HTML structure of the document, or flag
+ * constructs that may not be allowed by a style guide, or track the
+ * prevalence of incorrect or tricky HTML code.
+ */
+typedef enum {
+  /**
+   * A normal node -- both start and end tags appear in the source,
+   * nothing has been reparented.
+   */
+  GUMBO_INSERTION_NORMAL = 0,
+
+  /**
+   * A node inserted by the parser to fulfill some implicit insertion
+   * rule. This is usually set in addition to some other flag giving a
+   * more specific insertion reason; it's a generic catch-all term
+   * meaning "The start tag for this node did not appear in the document
+   * source".
+   */
+  GUMBO_INSERTION_BY_PARSER = 1 << 0,
+
+  /**
+   * A flag indicating that the end tag for this node did not appear in
+   * the document source. Note that in some cases, you can still have
+   * parser-inserted nodes with an explicit end tag. For example,
+   * `Text</html>` has `GUMBO_INSERTED_BY_PARSER` set on the `<html>`
+   * node, but `GUMBO_INSERTED_END_TAG_IMPLICITLY` is unset, as the
+   * `</html>` tag actually exists.
+   *
+   * This flag will be set only if the end tag is completely missing.
+   * In some cases, the end tag may be misplaced (e.g. a `</body>` tag
+   * with text afterwards), which will leave this flag unset and require
+   * clients to inspect the parse errors for that case.
+   */
+  GUMBO_INSERTION_IMPLICIT_END_TAG = 1 << 1,
+
+  // Value 1 << 2 was for a flag that has since been removed.
+
+  /**
+   * A flag for nodes that are inserted because their presence is
+   * implied by other tags, e.g. `<html>`, `<head>`, `<body>`,
+   * `<tbody>`, etc.
+   */
+  GUMBO_INSERTION_IMPLIED = 1 << 3,
+
+  /**
+   * A flag for nodes that are converted from their end tag equivalents.
+   * For example, `</p>` when no paragraph is open implies that the
+   * parser should create a `<p>` tag and immediately close it, while
+   * `</br>` means the same thing as `<br>`.
+   */
+  GUMBO_INSERTION_CONVERTED_FROM_END_TAG = 1 << 4,
+
+  // Value 1 << 5 was for a flag that has since been removed.
+
+  /** A flag for `<image>` tags that are rewritten as `<img>`. */
+  GUMBO_INSERTION_FROM_IMAGE = 1 << 6,
+
+  /**
+   * A flag for nodes that are cloned as a result of the reconstruction
+   * of active formatting elements. This is set only on the clone; the
+   * initial portion of the formatting run is a NORMAL node with an
+   * `IMPLICIT_END_TAG`.
+   */
+  GUMBO_INSERTION_RECONSTRUCTED_FORMATTING_ELEMENT = 1 << 7,
+
+  /** A flag for nodes that are cloned by the adoption agency algorithm. */
+  GUMBO_INSERTION_ADOPTION_AGENCY_CLONED = 1 << 8,
+
+  /** A flag for nodes that are moved by the adoption agency algorithm. */
+  GUMBO_INSERTION_ADOPTION_AGENCY_MOVED = 1 << 9,
+
+  /**
+   * A flag for nodes that have been foster-parented out of a table (or
+   * should've been foster-parented, if verbatim mode is set).
+   */
+  GUMBO_INSERTION_FOSTER_PARENTED = 1 << 10,
+} GumboParseFlags;
+
+/** Information specific to document nodes. */
+typedef struct {
+  /**
+   * An array of `GumboNode`s, containing the children of this element.
+   * This will normally consist of the `<html>` element and any comment
+   * nodes found. Pointers are owned.
+   */
+  GumboVector /* GumboNode* */ children;
+
+  /**
+   * `true` if there was an explicit doctype token, as opposed to it
+   * being omitted.
+   */
+  bool has_doctype;
+
+  // Fields from the doctype token, copied verbatim.
+  const char* name;
+  const char* public_identifier;
+  const char* system_identifier;
+
+  /**
+   * Whether or not the document is in QuirksMode, as determined by the
+   * values in the GumboTokenDocType template.
+   */
+  GumboQuirksModeEnum doc_type_quirks_mode;
+} GumboDocument;
+
+/**
+ * The struct used to represent TEXT, CDATA, COMMENT, and WHITESPACE
+ * elements. This contains just a block of text and its position.
+ */
+typedef struct {
+  /**
+   * The text of this node, after entities have been parsed and decoded.
+   * For comment and cdata nodes, this does not include the comment
+   * delimiters.
+   */
+  const char* text;
+
+  /**
+   * The original text of this node, as a pointer into the original
+   * buffer. For comment/cdata nodes, this includes the comment
+   * delimiters.
+   */
+  GumboStringPiece original_text;
+
+  /**
+   * The starting position of this node. This corresponds to the
+   * position of `original_text`, before entities are decoded.
+   * */
+  GumboSourcePosition start_pos;
+} GumboText;
+
+/**
+ * The struct used to represent all HTML elements. This contains
+ * information about the tag, attributes, and child nodes.
+ */
+typedef struct {
+  /**
+   * An array of `GumboNode`s, containing the children of this element.
+   * Pointers are owned.
+   */
+  GumboVector /* GumboNode* */ children;
+
+  /** The GumboTag enum for this element. */
+  GumboTag tag;
+
+  /** The name for this element. */
+  const char* name;
+
+  /** The GumboNamespaceEnum for this element. */
+  GumboNamespaceEnum tag_namespace;
+
+  /**
+   * A `GumboStringPiece` pointing to the original tag text for this
+   * element, pointing directly into the source buffer. If the tag was
+   * inserted algorithmically (for example, `<head>` or `<tbody>`
+   * insertion), this will be a zero-length string.
+   */
+  GumboStringPiece original_tag;
+
+  /**
+   * A `GumboStringPiece` pointing to the original end tag text for this
+   * element. If the end tag was inserted algorithmically, (for example,
+   * closing a self-closing tag), this will be a zero-length string.
+   */
+  GumboStringPiece original_end_tag;
+
+  /** The source position for the start of the start tag. */
+  GumboSourcePosition start_pos;
+
+  /** The source position for the start of the end tag. */
+  GumboSourcePosition end_pos;
+
+  /**
+   * An array of `GumboAttribute`s, containing the attributes for this
+   * tag in the order that they were parsed. Pointers are owned.
+   */
+  GumboVector /* GumboAttribute* */ attributes;
+} GumboElement;
+
+/**
+ * A supertype for `GumboElement` and `GumboText`, so that we can
+ * include one generic type in lists of children and cast as necessary
+ * to subtypes.
+ */
+struct GumboInternalNode {
+  /** The type of node that this is. */
+  GumboNodeType type;
+
+  /** Pointer back to parent node. Not owned. */
+  GumboNode* parent;
+
+  /** The index within the parent's children vector of this node. */
+  unsigned int index_within_parent;
+
+  /**
+   * A bitvector of flags containing information about why this element
+   * was inserted into the parse tree, including a variety of special
+   * parse situations.
+   */
+  GumboParseFlags parse_flags;
+
+  /** The actual node data. */
+  union {
+    GumboDocument document;  // For GUMBO_NODE_DOCUMENT.
+    GumboElement element;    // For GUMBO_NODE_ELEMENT.
+    GumboText text;          // For everything else.
+  } v;
+};
+
+/**
+ * Input struct containing configuration options for the parser.
+ * These let you specify alternate memory managers, provide different
+ * error handling, etc. Use `kGumboDefaultOptions` for sensible
+ * defaults and only set what you need.
+ */
+typedef struct GumboInternalOptions {
+  /**
+   * The tab-stop size, for computing positions in HTML files that
+   * use tabs. Default: `8`.
+   */
+  int tab_stop;
+
+  /**
+   * Whether or not to stop parsing when the first error is encountered.
+   * Default: `false`.
+   */
+  bool stop_on_first_error;
+
+  /**
+   * Maximum allowed number of attributes per element. If this limit is
+   * exceeded, the parser will return early with a partial document and
+   * the returned `GumboOutput` will have its `status` field set to
+   * `GUMBO_STATUS_TOO_MANY_ATTRIBUTES`. Set to `-1` to disable the limit.
+   * Default: `400`.
+   */
+  int max_attributes;
+
+  /**
+   * Maximum allowed depth for the parse tree. If this limit is exceeded,
+   * the parser will return early with a partial document and the returned
+   * `GumboOutput` will have its `status` field set to
+   * `GUMBO_STATUS_TREE_TOO_DEEP`.
+   * Default: `400`.
+   */
+  unsigned int max_tree_depth;
+
+  /**
+   * The maximum number of errors before the parser stops recording
+   * them. This is provided so that if the page is totally borked, we
+   * don't completely fill up the errors vector and exhaust memory with
+   * useless redundant errors. Set to `-1` to disable the limit.
+   * Default: `-1`.
+   */
+  int max_errors;
+
+  /**
+   * The fragment context for parsing:
+   * https://html.spec.whatwg.org/multipage/parsing.html#parsing-html-fragments
+   *
+   * If `NULL` is passed here, it is assumed to be "no
+   * fragment", i.e. the regular parsing algorithm. Otherwise, pass the
+   * tag name for the intended parent of the parsed fragment. We use the
+   * tag name, namespace, and encoding attribute which are sufficient to
+   * set all of the parsing context needed for fragment parsing.
+   *
+   * Default: `NULL`.
+   */
+  const char* fragment_context;
+
+  /**
+   * The namespace for the fragment context. This lets client code
+   * differentiate between, say, parsing a `<title>` tag in SVG vs.
+   * parsing it in HTML.
+   *
+   * Default: `GUMBO_NAMESPACE_HTML`.
+   */
+  GumboNamespaceEnum fragment_namespace;
+
+  /**
+   * The value of the fragment context's `encoding` attribute, if any.
+   * Set to `NULL` for no `encoding` attribute.
+   *
+   * Default: `NULL`.
+   */
+  const char* fragment_encoding;
+
+  /**
+   * Quirks mode for fragment parsing. The quirks mode for a given DOCTYPE can
+   * be looked up using `gumbo_compute_quirks_mode()`.
+   *
+   * Default: `GUMBO_DOCTYPE_NO_QUIRKS`.
+   */
+  GumboQuirksModeEnum quirks_mode;
+
+  /**
+   * For fragment parsing. Set this to true if the context node has a form
+   * element as an ancestor.
+   *
+   * Default: `false`.
+   */
+  bool fragment_context_has_form_ancestor;
+} GumboOptions;
+
+/** Default options struct; use this with gumbo_parse_with_options. */
+extern const GumboOptions kGumboDefaultOptions;
+
+/**
+ * Status code indicating whether parsing finished successfully or
+ * was stopped mid-document due to exceptional circumstances.
+ */
+typedef enum {
+  /**
+   * Indicates that parsing completed successfuly. The resulting tree
+   * will be a complete document.
+   */
+  GUMBO_STATUS_OK,
+
+  /**
+   * Indicates that the maximum element nesting limit
+   * (`GumboOptions::max_tree_depth`) was reached during parsing. The
+   * resulting tree will be a partial document, with no further nodes
+   * created after the point where the limit was reached. The partial
+   * document may be useful for constructing an error message but
+   * typically shouldn't be used for other purposes.
+   */
+  GUMBO_STATUS_TREE_TOO_DEEP,
+
+  /**
+   * Indicates that the maximum number of attributes per element
+   * (`GumboOptions::max_attributes`) was reached during parsing. The
+   * resulting tree will be a partial document, with no further nodes
+   * created after the point where the limit was reached. The partial
+   * document may be useful for constructing an error message but
+   * typically shouldn't be used for other purposes.
+   */
+  GUMBO_STATUS_TOO_MANY_ATTRIBUTES,
+
+  // Currently unused
+  GUMBO_STATUS_OUT_OF_MEMORY,
+} GumboOutputStatus;
+
+
+/** The output struct containing the results of the parse. */
+typedef struct GumboInternalOutput {
+  /**
+   * Pointer to the document node. This is a `GumboNode` of type
+   * `NODE_DOCUMENT` that contains the entire document as its child.
+   */
+  GumboNode* document;
+
+  /**
+   * Pointer to the root node. This is the `<html>` tag that forms the
+   * root of the document.
+   */
+  GumboNode* root;
+
+  /**
+   * A list of errors that occurred during the parse.
+   */
+  GumboVector /* GumboError */ errors;
+
+  /**
+   * True if the parser encounted an error.
+   *
+   * This can be true and `errors` an empty `GumboVector` if the `max_errors`
+   * option was set to 0.
+   */
+  bool document_error;
+
+  /**
+   * A status code indicating whether parsing finished successfully or was
+   * stopped mid-document due to exceptional circumstances.
+   */
+  GumboOutputStatus status;
+} GumboOutput;
+
+/**
+ * Parses a buffer of UTF-8 text into an `GumboNode` parse tree. The
+ * buffer must live at least as long as the parse tree, as some fields
+ * (eg. `original_text`) point directly into the original buffer.
+ *
+ * This doesn't support buffers longer than 4 gigabytes.
+ */
+GumboOutput* gumbo_parse(const char* buffer);
+
+/**
+ * Extended version of `gumbo_parse` that takes an explicit options
+ * structure, buffer, and length.
+ */
+GumboOutput* gumbo_parse_with_options (
+  const GumboOptions* options,
+  const char* buffer,
+  size_t buffer_length
+);
+
+/**
+ * Compute the quirks mode based on the name, public identifier, and system
+ * identifier. Any of these may be `NULL` to indicate a missing value.
+ */
+GumboQuirksModeEnum gumbo_compute_quirks_mode (
+  const char *name,
+  const char *pubid,
+  const char *sysid
+);
+
+/** Convert a `GumboOutputStatus` code into a readable description. */
+const char* gumbo_status_to_string(GumboOutputStatus status);
+
+/** Release the memory used for the parse tree and parse errors. */
+void gumbo_destroy_output(GumboOutput* output);
+
+/** Opaque GumboError type */
+typedef struct GumboInternalError GumboError;
+
+/**
+ * Returns the position of the error.
+ */
+GumboSourcePosition gumbo_error_position(const GumboError* error);
+
+/**
+ * Returns a constant string representation of the error's code. This is owned
+ * by the library and should not be freed by the caller.
+ */
+const char* gumbo_error_code(const GumboError* error);
+
+/**
+ * Prints an error to a string. This stores a freshly-allocated buffer
+ * containing the error message text in output. The caller is responsible for
+ * freeing the buffer. The size of the error message is returned. The error
+ * message itself may not be NULL-terminated and may contain NULL bytes so the
+ * returned size must be used.
+ */
+size_t gumbo_error_to_string(const GumboError* error, char **output);
+
+/**
+ * Prints a caret diagnostic to a string. This stores a freshly-allocated
+ * buffer containing the error message text in output. The caller is responsible for
+ * freeing the buffer. The size of the error message is returned. The error
+ * message itself may not be NULL-terminated and may contain NULL bytes so the
+ * returned size must be used.
+ */
+size_t gumbo_caret_diagnostic_to_string (
+  const GumboError* error,
+  const char* source_text,
+  size_t source_length,
+  char** output
+);
+
+/**
+ * Like gumbo_caret_diagnostic_to_string, but prints the text to stdout
+ * instead of writing to a string.
+ */
+void gumbo_print_caret_diagnostic (
+  const GumboError* error,
+  const char* source_text,
+  size_t source_length
+);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // GUMBO_H