Reader docs

Author: veewee

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+VeeWee/XML is an open source, community-driven project. If you'd like to contribute,
+feel free to do this, but remember to follow this few simple rules:
+
+## Branching strategy
+
+- __Always__ base your changes on the `master` branch (all new development happens here),
+- When you create Pull Request, always select `master` branch as target, otherwise it
+will be closed (this is selected by default).
+
+## Coverage
+
+- All classes and functions that are added to the project .should be covered by Tests.
+- All classes and functions need to be documented
+
+## Code style / Formatting
+
+- All code in the `src` folder must follow the PSR-2 standard that is enforced by code styling tools.

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021-MAX_INT VeeWee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,3 +1,40 @@
-# WIP - currently just a playground
+# <XML />
 
-![Here be dragons](https://media.giphy.com/media/Zb0asRm15HqCbgShD4/giphy.gif)
+*XML without worries*
+
+This package aims to provide all tools for dealing with XML in PHP without worries.
+You will find a type-safe, declarative API that deals with errors for you!
+
+
+## Installation
+
+```
+composer require veewee/xml
+```
+
+## Components
+
+* [DOM](docs/dom.md): Operate on XML documents through the DOM API
+* [Reader](docs/reader.md): Memory-safe XML reader.
+* [XSLT](docs/xslt.md): Transform XML documents into something else.
+
+## Roadmap
+
+These components are not implemented yet, but have been thought about.
+Stay tuned if you want to use these!
+
+* Advanced XSLT setup (XSLT2, XSLT3 ?)
+* Writer
+* SimpleXML
+* Saxon/C?
+
+## About
+
+### Submitting bugs and feature requests
+
+Bugs and feature request are tracked on [GitHub](https://github.com/veewee/xml/issues).
+Please take a look at our rules before [contributing your code](CONTRIBUTING.md).
+
+### License
+
+veewee/xml is licensed under the [MIT License](LICENSE).

docs/dom.md

@@ -0,0 +1,123 @@
+# Reader Component
+
+The Reader component can be used to detect patterns in a memory-safe way inside a big XML document.
+It uses matchers to determine if you care about specific elements or not.
+As a result, the reader provides a generator of XML strings that match your matchers!
+
+## Example
+
+```php
+use VeeWee\Xml\Dom\Document;
+use VeeWee\Xml\Reader\Reader;
+use VeeWee\Xml\Reader\Matcher;
+
+$reader   = Reader::fromXmlFile('large-data.xml');
+$provider = $reader->provide(
+    Matcher\all(
+        Matcher\node_name('item'),
+        Matcher\node_attribute('locale', 'nl-BE')
+    )
+);
+
+foreach ($provider as $nlItem) {
+    $dom = Document::fromXmlString($nlItem);
+    // Do something with it
+}
+```
+
+## Reader
+
+The Reader consists out of following composable blocks:
+
+- [Configurators](#configurators)
+- [Loaders](#loaders)
+- [Matchers](#matchers)
+
+### Configurators
+
+You can configure how a reader behaves based on configurators.
+This package provides following configurators:
+
+* TODO : currently no configurators are added...
+
+### Loaders
+
+#### xml_file_loader
+
+```php
+use VeeWee\Xml\Reader\Reader;
+
+$reader = Reader::fromXmlFile('some-file.xml', ...$configurators);
+```
+
+#### xml_string_loader
+
+```php
+use VeeWee\Xml\Reader\Reader;
+
+$reader = Reader::fromXmlString('<xml />', ...$configurators);
+```
+
+#### Writing your own loader
+
+A loader can be any callable that is able to create an `XMLReader`;
+
+```php
+namespace VeeWee\Xml\Reader\Loader;
+
+use XMLReader;
+
+interface Loader
+{
+    public function __invoke(): XMLReader;
+}
+```
+
+### Matchers
+
+#### all
+
+All provided matchers need to match in order for this matcher to succceed:
+
+```php
+Matcher\all(
+    Matcher\node_name('item'),
+    Matcher\node_attribute('locale', 'nl-BE')
+);
+```
+
+#### node_attribute
+
+Matches current element on attribute `locale="nl-BE"`.
+
+```php
+Matcher\node_attribute('locale', 'nl-BE');
+```
+
+#### node_name
+
+Matches current element on node name `<item />`.
+
+```php
+Matcher\node_name('item');
+```
+
+#### Writing your own matcher
+
+A matcher can be any callable that takes a `NodeSequence` as input and returns a `bool` that specifies if it matches or not:
+
+```php
+namespace VeeWee\Xml\Reader\Matcher;
+
+use VeeWee\Xml\Reader\Node\NodeSequence;
+
+interface Matcher
+{
+    publict function __invoke(NodeSequence $sequence): bool;
+}
+```
+
+The `NodeSequence` class can be seen as the breadcrumbs of current XML.
+It points to current element and all of its attributes.
+You can select the current element, its parent or a complete sequence of elements until the current one in order to match.
+

docs/reader.md

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Xml\Reader\Loader;
+
+use XMLReader;
+
+interface Loader
+{
+    public function __invoke(): XMLReader;
+}

docs/xslt.md

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Xml\Reader\Matcher;
+
+use VeeWee\Xml\Reader\Node\NodeSequence;
+
+interface Matcher
+{
+    public function __invoke(NodeSequence $nodeSequence): bool;
+}