ParserInterface: add the BLANK_NODES_PRESERVE constant

There are some corner cases (e.g. parsing reference test outputs for the RDF-XML parser) where it is required to preserve blank node identifiers from the input data source. In such a case the rdfInterface\ParserInterface::BLANK_NODES_PRESERVE should be passed as the $baseUri parameter to the rdfInterface\ParserInterface::parse()/rdfInterface\ParserInterface::parseStream().

ParserInterface: allow to specify document base URI

To properly parse blank nodes the parser has to be aware of the URI of the document being parsed.
So far there was no way to provide this information.
Not the rdfInterface\ParserInterface::parse() and rdfInterface\ParserInterface::parseStream() take optional second parameter string $baseUri allowing to specify the document URI.

See also sweetrdf/quickRdfIo#11

Narrow down getPredicate() return type

rdfInterface\DatesetInterface::getPredicate() and rdfInterface\DatesetNodeInterface::getPredicate() return type narrowed down to rdfInterface\NamedNodeInterface|null.

While technically this is a backward-incompatible change and thus marks major version bump, there is no known RDF extension nor implementation which would depend on the getPredicate() method returning anything else than NamedNodeIterface|null.

DatasetInterface::delete() filter relaxed

rdfInterface\DatasetInterface::delete($filter) now accepts null as a $filter. Also, null is now a default $filter parameter value.

2.0.0

Backward-incompatible changes

• rdfInterface\DatasetCompareInterface, rdfInterface\DatasetMapReduceInterface and rdfInterface\DatasetQuadPartsInterface merged into rdfInterface\DatasetInterface.
• rdfInterface\DatasetInterface
  • copyExcept($filter) does not accept null as the $filter. If you want to copy all quads, use the copy() method.
  • delete($filter) does not accept null as the $filter. If you want an empty dataset, just create a new one.
  • offsetExists($offset), offsetGet($offset), offsetSet($offset, $value) and offsetUnset($offset) method now must throw a newly introduced rdfInterface\MultipleQuadsMatchedException if the offset matches multiple quads.

New features

• rdfInterface\DatasetNodeInterface interface added for a node-oriented RDF graph operations.
  It extends the rdfInterface\DatasetInterface, just methods are (generally) applied only to quads with a subject matching a given rdfInterface\TermInterface term.
• rdfInterface\TermIteratorInterface extended
  • contains(rdfInterface\TermCompareInterface $term): bool method added allowing to perform in_array-like check.
  • getValues(): array<string> method added.
  • intersect($terms): rdfInterface\TermIteratorInterface method added.
  • skip($terms): rdfInterface\TermIteratorInterface method added.
• rdfInterface\DatasetNode
  • Static method factory() added as a replacement for the rdfInterface\DatasetNode::__construct(). This follows the convention not to enforce constructor signatures.
  • Getter shorthands added (a reference implementation is provided by the rdfHelpers\DatasetGettersTrait class of the sweetrdf/rdf-helpers package):
    • getSubject(), getPredicate(), getObject(), getGraph() returning an rdfInterface\TermInterface | null
    • getSubjectValue(), getPredicateValue(), getObjectValue(), getGraphValue() returning mixed | null
• rdfInterface\QuadNoSubjectInterface added for convenient adding quads to the rdfInterface\DatasetNode.
• rdfInterface\DataFactory
  • quadNoSubject($predicate, $object, $graph): rdfInterface\QuadNoSubjectInterface method added.
• rdfInterface\MultipleQuadsMatchedException exception added to make it possible to easily distinguish between standard PHP array access errors (the \UnexpectedValueException when an offset does not exist) and rdfInterface-specific "multiple quads matched" error.
• rdfInterface\QuadInterface::getValue() must throw the \BadMethodCall exception.

Relaxed definitions

• rdfInterface\BlankNodeInterface, rdfInterface\NamedNodeInterface, rdfInterface\LiteralInterface and rdfInterface\QuadInterface constructor definition dropped. These constructors are anyway not meant to be called directly as terms should be instantiated trough the rdfInterface\DataFactoryInterface class so it makes no sense to enforce their signatures.
• rdfInterface\DatasetNode:
  • __construct() method dropped. This follows the convention not to enforce constructor signatures. A static factory() method signature is defined instead.
  • add() accepts QuadInterface|\Traversable<rdfInterface\QuadInterface>|array<rdfInterface\QuadInterface> (instead of rdfInterface\QuadInterface|rdfInterface\QuadIteratorInterface|rdfInterface\QuadIteratorAggregateInterface).
  • forEach($filter) accepts null as a $filter.
• rdfInterface\SerializerInterface
  • serialize() and serializeStream() accept \Traversable<QuadInterface>|array<QuadInterface> (instead of rdfInterface\QuadIteratorInterface|rdfInterface\QuadIteratorAggregateInterface).

Minor changes

• rdfInterface\TermInterface now extends rdfInterface\TermCompareInterface instead of defining equals() and __toString() methods explicitly.
• rdfInterface\TermCompareInterface, rdfInterface\QuadCompareInterface and rdfInterface\DatasetInterface extend Stringable instead of declaring __toString() explicitly.
• rdfInterface\QuadCompareInterface methods: getSubject(), getPredicate(), getObject() and getGraph() return type is rdfInterface\TermCompareInterface | null (instead of rdfInterface\TermInterface | rdfInterface\TermCompareInterface | null).

Dependencies fixes

Allow both psr/http-message ^1 and ^2

1.0.0

Backward-incompatible changes

• All interfaces have been renamed so that their name ends with Interface to follow an interface naming convention which is predominant in modern PHP.
• rdfInterface\DatasetInterface extends rdfInterface\QuadIteratorAggregateInterface (a strongly-typed IteratorAggregate with an optional filtering) instad of rdfInterface\QuadIteratorInterface (a strongly-typed Iterator) which laregely decouples implementation of the iterator from the dataset implementation.

New features

• Allowing rdfInterface\Dataset::getOffset(0) and rdfInterface\Dataset::offsetExists(0) as a syntax for getting any quad out of a dataset and checking if a dataset is not empty.
  This allows the $dataset[0] ?? $defaultQuad syntax for safely getting a single quad out of a dataset.
• rdfInterface\QuadIteratorAggregateInterface added.

1.0.0-RC1

SerializerInterface::serializeStream(): fix parameter type hint

Allow both resource and \Psr\Http\Message\StreamInterface for Serializer and Parser

0.11.0

Merge branch 'master' of github.com:zozlak/rdfInterface

Type hints fixes

0.10.1

Merge branch 'master' of github.com:zozlak/rdfInterface