MensBeam/HTML-Parser
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Added beginnings of documentation

Browse source
This commit is contained in:
Dustin Wilson 2021-04-05 12:43:11 -05:00
parent f660ecaad4
commit 43e312b2af
24 changed files with 2530 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -1,4 +1,5 @@
# html5-parser specific
manual
test*.php
# General

17
RoboFile.php
View file

@ -21,6 +21,23 @@ function norm(string $path): string {
}
class RoboFile extends \Robo\Tasks {
/** Generates static manual pages in the "manual" directory
*
* The resultant files are suitable for offline viewing and inclusion into release builds
*/
public function manual(array $args): Result {
$execpath = escapeshellarg(norm(BASE."vendor/bin/daux"));
$t = $this->collectionBuilder();
$t->taskExec($execpath)->arg("generate")->option("-d", BASE."manual")->args($args);
return $t->run();
}
/** Serves a live view of the manual using the built-in Web server */
public function manualLive(array $args): Result {
$execpath = escapeshellarg(norm(BASE."vendor/bin/daux"));
return $this->taskExec($execpath)->arg("serve")->args($args)->run();
}
/** Runs the typical test suite
*
* Arguments passed to the task are passed on to PHPUnit. Thus one may, for

3
composer.json
View file

@ -47,6 +47,7 @@
},
"require-dev": {
"bamarni/composer-bin-plugin": "^1.3",
"masterminds/html5": "^2.7"
"masterminds/html5": "^2.7",
"daux/daux.io": "^0.16.0"
}
}

2121
composer.lock generated
View file

File diff suppressed because it is too large Load diff

13
docs/config.json Normal file
View file

@ -0,0 +1,13 @@
{
"title": "HTML",
"tagline": "Tools for parsing and printing HTML5 documents and fragments.",
"author": "Dustin Wilson",
"languages": {
"en": "English"
},
"html": {
"float": false,
"toggle_code": false,
"search": false
}
}

1
docs/en/010_About.md Normal file
View file

@ -0,0 +1 @@
HTML is a library which provides tools for parsing and printing of HTML5 documents and fragments. Unlike PHP's DOM and other similar libraries the goal of the project is to parse HTML as accurate to the specification as possible given the limitations of PHP's DOM and of the uses of the library. Therefore, there is no scripting in this implementation, and there likely never will be.

8
docs/en/020_Installation.md Normal file
View file

@ -0,0 +1,8 @@
We try to make the installation of the MensBeam HTML library as easy and straightforward as possible.
## Requirements ##
HTML intentionally has few requirements. It only requires PHP 7.1.0 or later with the [dom](http://php.net/manual/en/book.dom.php) extension installed. It is recommended to install the [ctype](https://www.php.net/manual/en/book.ctype.php) extension for performance improvements, but it is not required.
TODO: Add Installation instructions once there are releases and a package is available on Packagist.

28
docs/en/030_Document_Object_Model/010_Document/010_Document-__construct.md Normal file
View file

@ -0,0 +1,28 @@
---
title: Document::__construct
---
Document::__construct — Creates a new Document object
## Description ##
```php
public Document::__construct ( )
```
Creates a new Document object.
## Examples ##
**Example \#1 Creating a new Document**
```php
<?php
namespace MensBeam\HTML;
$dom = new Document();
echo $dom;
?>
```

13
docs/en/030_Document_Object_Model/010_Document/020_Document-createEntityReference.md Normal file
View file

@ -0,0 +1,13 @@
---
title: Document::createEntityReference
---
Document::createEntityReference — **DISABLED**
## Description ##
```php
public Document::createEntityReference ( string $name ) : false
```
This function has been disabled and will always return `false`. Documented to show difference from [`\DOMDocument`](https://www.php.net/manual/en/class.domdocument.php). DOM4 does not have entity references or entity nodes.

46
docs/en/030_Document_Object_Model/010_Document/020_Document-load.md Normal file
View file

@ -0,0 +1,46 @@
---
title: Document::load
---
Document::load — Load HTML from a file
## Description ##
```php
public Document::load ( string $filename , null $options = null , string|null $encodingOrContentType = null ) : bool
```
Loads an HTML document from a file.
## Parameters ##
<dl>
<dt><code>filename</code></dt>
<dd>The path to the HTML document.</dd>
<dt><code>options</code></dt>
<dd>Always <code>null</code>. Was used for option constants in <a href="https://www.php.net/manual/en/class.domdocument.php"><code>\DOMDocument</code></a>.</dd>
<dt><code>encodingOrContentType</code></dt>
<dd>The encoding of the document that is being loaded. If not specified it will be determined automatically.</dd>
</dl>
## Return Values ##
Returns <code>true</code> on success or <code>false</code> on failure.
## Examples ##
**Example \#1 Creating a Document**
```php
<?php
namespace MensBeam\HTML;
$dom = new Document();
$dom->load('ook.html');
echo $dom;
?>
```

46
docs/en/030_Document_Object_Model/010_Document/020_Document-loadHTML.md Normal file
View file

@ -0,0 +1,46 @@
---
title: Document::loadHTML
---
Document::loadHTML — Load HTML from a string
## Description ##
```php
public Document::loadHTML ( string $source , null $options = null , string|null $encodingOrContentType = null ) : bool
```
The function parses the HTML contained in the string <var>source</var>.
## Parameters ##
<dl>
<dt><code>source</code></dt>
<dd>The HTML string.</dd>
<dt><code>options</code></dt>
<dd>Always <code>null</code>. Was used for option constants in <a href="https://www.php.net/manual/en/class.domdocument.php"><code>\DOMDocument</code></a>.</dd>
<dt><code>encodingOrContentType</code></dt>
<dd>The encoding of the document that is being loaded. If not specified it will be determined automatically.</dd>
</dl>
## Return Values ##
Returns <code>true</code> on success or <code>false</code> on failure.
## Examples ##
**Example \#1 Creating a Document**
```php
<?php
namespace MensBeam\HTML;
$dom = new Document();
$dom->loadHTML('<!DOCTYPE html><html><head><title>Ook!</title></head><body><h1>Eek</h1></body></html>');
echo $dom;
?>
```

9
docs/en/030_Document_Object_Model/010_Document/020_Document-loadHTMLFile.md Normal file
View file

@ -0,0 +1,9 @@
---
title: Document::loadHTMLFile
---
Document::loadHTMLFile — Alias of <a href="Document_load.html"><code>Document::load()</code></a>
## Description ##
This function is an alias of <a href="Document_load.html"><code>Document::load()</code></a>.

13
docs/en/030_Document_Object_Model/010_Document/020_Document-loadXML.md Normal file
View file

@ -0,0 +1,13 @@
---
title: Document::loadXML
---
Document::loadXML — **DISABLED**
## Description ##
```php
public Document::loadXML ( string $source , null $options = null ) : false
```
This function has been disabled and will always return `false`. Documented to show difference from [`\DOMDocument`](https://www.php.net/manual/en/class.domdocument.php).

43
docs/en/030_Document_Object_Model/010_Document/020_Document-save.md Normal file
View file

@ -0,0 +1,43 @@
---
title: Document::save
---
Document::save — Serializes the DOM tree into a file
## Description ##
```php
public Document::save ( string $filename , null $options = null ) : int|false
```
Creates an HTML document from the DOM representation.
## Parameters ##
<dl>
<dt><code>filename</code></dt>
<dd>The path to the saved HTML document</dd>
<dt><code>options</code></dt>
<dd>Always <code>null</code>. Was used for option constants in <a href="https://www.php.net/manual/en/class.domdocument.php"><code>\DOMDocument</code></a>.</dd>
</dl>
## Return Values ##
Returns the number of bytes written or <code>false</code> on failure.
## Examples ##
**Example \#1 Saving a DOM tree into a file**
```php
<?php
namespace MensBeam\HTML;
$dom = new Document();
$dom->loadHTML('<!DOCTYPE html><html><head><title>Ook!</title></head><body><h1>Eek</h1></body></html>');
echo 'Wrote: ' . $dom->save('/tmp/test.html') . ' bytes'; // Wrote: 85 bytes
?>
```

9
docs/en/030_Document_Object_Model/010_Document/020_Document-saveHTMLFile.md Normal file
View file

@ -0,0 +1,9 @@
---
title: Document::saveHTMLFile
---
Document::saveHTMLFile — Alias of <a href="Document_save.html"><code>Document::save()</code></a>
## Description ##
This function is an alias of <a href="Document_save.html"><code>Document::save()</code></a>.

13
docs/en/030_Document_Object_Model/010_Document/020_Document-saveXML.md Normal file
View file

@ -0,0 +1,13 @@
---
title: Document::saveXML
---
Document::saveXML — **DISABLED**
## Description ##
```php
public Document::saveXML ( DOMNode|null $node = null , null $options = null ) : false
```
This function has been disabled and will always return `false`. Documented to show difference from [`\DOMDocument`](https://www.php.net/manual/en/class.domdocument.php).

13
docs/en/030_Document_Object_Model/010_Document/020_Document-validate.md Normal file
View file

@ -0,0 +1,13 @@
---
title: Document::validate
---
Document::validate — **DISABLED**
## Description ##
```php
public Document::validate ( ) : true
```
This function has been disabled and will always return `true`. Documented to show difference from [`\DOMDocument`](https://www.php.net/manual/en/class.domdocument.php).

13
docs/en/030_Document_Object_Model/010_Document/020_Document-xinclude.md Normal file
View file

@ -0,0 +1,13 @@
---
title: Document::xinclude
---
Document::xinclude — **DISABLED**
## Description ##
```php
public Document::xinclude ( null $options = null ) : false
```
This function has been disabled and will always return `false`. Documented to show difference from [`\DOMDocument`](https://www.php.net/manual/en/class.domdocument.php).

97
docs/en/030_Document_Object_Model/010_Document/index.md Normal file
View file

@ -0,0 +1,97 @@
---
title: Document
---
# The Document class #
## Introduction ##
Represents an entire HTML document; serves as the root of the document tree. Unlike the PHP [`\DOMDocument`](https://www.php.net/manual/en/class.domdocument.php) class in which it inherits from it cannot be used to represent an XML document. It is strictly used to represent HTML.
<div class="info"><p><strong>Info</strong> Only new methods and methods which make outward-facing changes from <a href="https://www.php.net/manual/en/class.domdocument.php">\DOMDocument</a> will be documented here, otherwise they will be linked back to PHP's documentation.</p></div>
<pre><code class="php">MensBeam\HTML\Document extends <a href="https://www.php.net/manual/en/class.domdocument.php">\DOMDocument</a> {
/* Constants */
public const NO_QUIRKS_MODE = 0 ;
public const QUIRKS_MODE = 1 ;
public const LIMITED_QUIRKS_MODE = 2 ;
/* Properties */
public string|null $documentEncoding = null ;
public int $quirksMode = 0 ;
/* Inherited properties from <a href="https://www.php.net/manual/en/class.domdocument.php">\DOMDocument</a> */
public readonly DocumentType <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.doctype">$doctype</a> ;
public readonly Element <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.documentelement">$documentElement</a> ;
public string|null <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.documenturi">$documentURI</a> ;
public readonly \<a href="https://www.php.net/manual/en/class.domimplementation.php">DOMImplementation</a> <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.implementation">$implementation</a> ;
/* Inherited properties from <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> */
public readonly string <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.nodename">$nodeName</a> ;
public string <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.nodevalue">$nodeValue</a> ;
public readonly int <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.nodetype">$nodeType</a> ;
public readonly \<a href="https://www.php.net/manual/en/class.domnode.php">DOMNode</a>|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.parentnode">$parentNode</a> ;
public readonly \<a href="https://www.php.net/manual/en/class.domnodelist.php">DOMNodeList</a> <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.childnodes">$childNodes</a> ;
public readonly \<a href="https://www.php.net/manual/en/class.domnode.php">DOMNode</a>|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.firstchild">$firstChild</a> ;
public readonly \<a href="https://www.php.net/manual/en/class.domnode.php">DOMNode</a>|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.lastchild">$lastChild</a> ;
public readonly \<a href="https://www.php.net/manual/en/class.domnode.php">DOMNode</a>|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.previoussibling">$previousSibling</a> ;
public readonly \<a href="https://www.php.net/manual/en/class.domnode.php">DOMNode</a>|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.nextsibling">$nextSibling</a> ;
public readonly \<a href="https://www.php.net/manual/en/class.domnamednodemap.php">DOMNamedNodeMap</a>|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.attributes">$attributes</a> ;
public readonly Document|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.ownerdocument">$ownerDocument</a> ;
public readonly string|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.namespaceuri">$namespaceURI</a> ;
public string <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.prefix">$prefix</a> ;
public readonly string <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.localname">$localName</a> ;
public readonly string|null <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.baseuri">$baseURI</a> ;
public string <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.textcontent">$textContent</a> ;
/* Methods */
public <a href="Document_construct.html">__construct</a> ( )
public <a href="Document_createEntityReference.html">createEntityReference</a> ( string $name ) : false
public <a href="Document_load.html">load</a> ( string $filename , null $options = null , string|null $encodingOrContentType = null ) : bool
public <a href="Document_loadHTML.html">loadHTML</a> ( string $source , null $options = null , string|null $encodingOrContentType = null ) : bool
public <a href="Document_loadHTMLFile.html">loadHTMLFile</a> ( string $filename , null $options = null , string|null $encodingOrContentType = null ) : bool
public <a href="Document_loadHTML.html">loadXML</a> ( string $source , null $options = null ) : false
public <a href="Document_save.html">save</a> ( string $filename , null $options = null ) : int|false
public <a href="Document_saveHTMLFile.html">saveHTMLFile</a> ( string $filename , null $options = null ) : int|false
public <a href="Document_saveXML.html">saveXML</a> ( DOMNode|null $node = null , null $options = null ) : false
public <a href="Document_validate.html">validate</a> ( ) : true
public <a href="Document_xinclude.html">xinclude</a> ( null $options = null ) : false
}</code></pre>
## Constants ##
| Constant | Value | Description |
| ----------------------------------------------------- | ----- | ------------------------------------- |
| <var>MensBeam\HTML\Document::NO_QUIRKS_MODE</var> | 0 | Document not in quirks mode |
| <var>MensBeam\HTML\Document::QUIRKS_MODE</var> | 1 | Document is in quirks mode |
| <var>MensBeam\HTML\Document::LIMITEDQUIRKS_MODE</var> | 2 | Document is in limited quirks mode |
## Properties ##
<dl>
<dt id="document-props-documentencoding"><var>documentEncoding</var></dt>
<dd>Encoding of the document, as specified when parsing or when determining encoding type. Use this instead of <a href="https://php.net/manual/en/class.domdocument.php#domdocument.props.encoding"><code>\DOMDocument::encoding</code></a>.</dd>
<dt id="document-props-quirksmode"><var>quirksMode</var></dt>
<dd>Used when parsing. Specifies which mode the document was parsed in. One of the <a href="#page_Constants">predefined quirks mode constants</a>.</dd>
</dl>
The following properties inherited from `\DOMDocument` have no effect in `Mensbeam\HTML\Document`, so therefore are not listed in the schema above:
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.actualencoding"><var>actualEncoding</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.config"><var>config</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.encoding"><var>encoding</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.formatoutput"><var>formatOutput</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.preservewhitespace"><var>preserveWhiteSpace</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.recover"><var>recover</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.resolveexternals"><var>resolveExternals</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.standalone"><var>standalone</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.stricterrorchecking"><var>strictErrorChecking</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.substituteentities"><var>substituteEntities</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.validateonparse"><var>validateOnParse</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.version"><var>version</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.xmlencoding"><var>xmlEncoding</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.xmlstandalone"><var>xmlStandalone</var></a>
* <a href="https://www.php.net/manual/en/class.domdocument.php#domdocument.props.xmlversion"><var>xmlVersion</var></a>

1
docs/en/030_Document_Object_Model/index.md Normal file
View file

@ -0,0 +1 @@
The MensBeam HTML library works by parsing HTML strings into PHP's existing XML DOM. It, however, has to force the antiquated PHP DOM extension into working properly with modern HTML DOM by extending many of the node types. The documentation below follows PHP's doc style guide as closely as possible. Each class should be listed separately in the menu under this section.

1
docs/index.md Normal file
View file

@ -0,0 +1 @@
Welcome to the user manual for HTML. It is included with each copy of the software, and is also [available online](https://mensbeam.com/html/en/). Please select a language above.

6
lib/DOM/Document.php
View file

@ -126,6 +126,10 @@ class Document extends \DOMDocument {
}
}
public function createEntityReference($name): bool {
return false;
}
public function load($filename, $options = null, ?string $encodingOrContentType = null): bool {
$data = Parser::fetchFile($filename, $encodingOrContentType);
if (!$data) {
@ -157,7 +161,7 @@ class Document extends \DOMDocument {
public function saveHTML(\DOMNode $node = null): string {
if ($node === null) {
$node = $this;
} elseif ($node->ownerDocument !== $this) {
} elseif (!$node->ownerDocument->isSameNode($this)) {
throw new DOMException(DOMException::WRONG_DOCUMENT);
}

12
vendor-bin/phpunit/composer.lock generated
View file

@ -527,16 +527,16 @@
},
{
"name": "phpunit/php-code-coverage",
"version": "9.2.5",
"version": "9.2.6",
"source": {
"type": "git",
"url": "https://github.com/sebastianbergmann/php-code-coverage.git",
"reference": "f3e026641cc91909d421802dd3ac7827ebfd97e1"
"reference": "f6293e1b30a2354e8428e004689671b83871edde"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/sebastianbergmann/php-code-coverage/zipball/f3e026641cc91909d421802dd3ac7827ebfd97e1",
"reference": "f3e026641cc91909d421802dd3ac7827ebfd97e1",
"url": "https://api.github.com/repos/sebastianbergmann/php-code-coverage/zipball/f6293e1b30a2354e8428e004689671b83871edde",
"reference": "f6293e1b30a2354e8428e004689671b83871edde",
"shasum": ""
},
"require": {
@ -592,7 +592,7 @@
],
"support": {
"issues": "https://github.com/sebastianbergmann/php-code-coverage/issues",
"source": "https://github.com/sebastianbergmann/php-code-coverage/tree/9.2.5"
"source": "https://github.com/sebastianbergmann/php-code-coverage/tree/9.2.6"
},
"funding": [
{
@ -600,7 +600,7 @@
"type": "github"
}
],
"time": "2020-11-28T06:44:49+00:00"
"time": "2021-03-28T07:26:59+00:00"
},
{
"name": "phpunit/php-file-iterator",

24
vendor-bin/robo/composer.lock generated
View file

@ -1086,16 +1086,16 @@
},
{
"name": "symfony/filesystem",
"version": "v5.2.4",
"version": "v5.2.6",
"source": {
"type": "git",
"url": "https://github.com/symfony/filesystem.git",
"reference": "710d364200997a5afde34d9fe57bd52f3cc1e108"
"reference": "8c86a82f51658188119e62cff0a050a12d09836f"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/symfony/filesystem/zipball/710d364200997a5afde34d9fe57bd52f3cc1e108",
"reference": "710d364200997a5afde34d9fe57bd52f3cc1e108",
"url": "https://api.github.com/repos/symfony/filesystem/zipball/8c86a82f51658188119e62cff0a050a12d09836f",
"reference": "8c86a82f51658188119e62cff0a050a12d09836f",
"shasum": ""
},
"require": {
@ -1128,7 +1128,7 @@
"description": "Provides basic utilities for the filesystem",
"homepage": "https://symfony.com",
"support": {
"source": "https://github.com/symfony/filesystem/tree/v5.2.4"
"source": "https://github.com/symfony/filesystem/tree/v5.2.6"
},
"funding": [
{
@ -1144,7 +1144,7 @@
"type": "tidelift"
}
],
"time": "2021-02-12T10:38:38+00:00"
"time": "2021-03-28T14:30:26+00:00"
},
{
"name": "symfony/finder",
@ -1836,16 +1836,16 @@
},
{
"name": "symfony/string",
"version": "v5.2.4",
"version": "v5.2.6",
"source": {
"type": "git",
"url": "https://github.com/symfony/string.git",
"reference": "4e78d7d47061fa183639927ec40d607973699609"
"reference": "ad0bd91bce2054103f5eaa18ebeba8d3bc2a0572"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/symfony/string/zipball/4e78d7d47061fa183639927ec40d607973699609",
"reference": "4e78d7d47061fa183639927ec40d607973699609",
"url": "https://api.github.com/repos/symfony/string/zipball/ad0bd91bce2054103f5eaa18ebeba8d3bc2a0572",
"reference": "ad0bd91bce2054103f5eaa18ebeba8d3bc2a0572",
"shasum": ""
},
"require": {
@ -1899,7 +1899,7 @@
"utf8"
],
"support": {
"source": "https://github.com/symfony/string/tree/v5.2.4"
"source": "https://github.com/symfony/string/tree/v5.2.6"
},
"funding": [
{
@ -1915,7 +1915,7 @@
"type": "tidelift"
}
],
"time": "2021-02-16T10:20:28+00:00"
"time": "2021-03-17T17:12:15+00:00"
},
{
"name": "symfony/yaml",