vendor/wikimedia/purtle/src/RdfWriter.php

   1 <?php
   2
   3 namespace Wikimedia\Purtle;
   4
   5 /**
   6  * Writer interface for RDF output. RdfWriter instances are generally stateful,
   7  * but should be implemented to operate in a stream-like manner with a minimum of state.
   8  *
   9  * This is intended to provide a "fluent interface" that allows programmers to use
  10  * a turtle-like structure when generating RDF output. E.g.:
  11  *
  12  * @code
  13  * $writer->prefix( 'acme', 'http://acme.test/terms/' );
  14  * $writer->about( 'http://quux.test/Something' )
  15  *   ->say( 'acme', 'name' )->text( 'Thingy' )->text( 'Dingsda', 'de' )
  16  *   ->say( 'acme', 'owner' )->is( 'http://quux.test/' );
  17  * @endcode
  18  *
  19  * To get the generated RDF output, use the drain() method.
  20  *
  21  * @note: The contract of this interface follows the GIGO principle, that is,
  22  * implementations are not required to ensure valid output or prompt failure on
  23  * invalid input. Speed should generally be favored over safety.
  24  *
  25  * Caveats:
  26  * - no relative iris
  27  * - predicates must be qnames
  28  * - no inline/nested blank nodes
  29  * - no comments
  30  * - no collections
  31  * - no automatic conversion of iris to qnames
  32  *
  33  * @license GPL-2.0+
  34  * @author Daniel Kinzler
  35  */
  36 interface RdfWriter {
  37
  38         //TODO: split: generic RdfWriter class with shorthands, use RdfFormatters for output
  39
  40         /**
  41          * Returns the local name of a blank node, for use with the "_" prefix.
  42          *
  43          * @param string|null $label node label, will be generated if not given.
  44          *
  45          * @return string A local name for the blank node, for use with the '_' prefix.
  46          */
  47         public function blank( $label = null );
  48
  49         /**
  50          * Start the document. May generate a header.
  51          */
  52         public function start();
  53
  54         /**
  55          * Finish the document. May generate a footer.
  56          *
  57          * This will detach all sub-writers that had earlier been returned by sub().
  58          */
  59         public function finish();
  60
  61         /**
  62          * Generates an RDF string from the current buffers state and returns it.
  63          * The buffer is reset to the empty state.
  64          * Before the result string is generated, implementations should close any
  65          * pending syntactical structures (close tags, generate footers, etc).
  66          *
  67          * @return string The RDF output
  68          */
  69         public function drain();
  70
  71         /**
  72          * Declare a prefix for later use. Prefixes should be declared before being used.
  73          * Should not be called after start().
  74          *
  75          * @param string $prefix
  76          * @param string $iri a IRI
  77          */
  78         public function prefix( $prefix, $iri );
  79
  80         /**
  81          * Start an "about" (subject) clause, given a subject.
  82          * Can occur at the beginning odf the output sequence, but can later only follow
  83          * a call to is(), text(), or value().
  84          * Should fail if called at an inappropriate time in the output sequence.
  85          *
  86          * @param string $base A QName prefix if $local is given, or an IRI if $local is null.
  87          * @param string|null $local A QName suffix, or null if $base is an IRI.
  88          *
  89          * @return RdfWriter $this
  90          */
  91         public function about( $base, $local = null );
  92
  93         /**
  94          * Start a predicate clause.
  95          * Can only follow a call to about() or say().
  96          * Should fail if called at an inappropriate time in the output sequence.
  97          *
  98          * @note Unlike about() and is(), say() cannot be called with a full IRI,
  99          * but must always use qname form. This is required to cater to output
 100          * formats that do not allow IRIs to be used as predicates directly,
 101          * like RDF/XML.
 102          *
 103          * @param string $base A QName prefix if $local is given, or a shorthand. MUST NOT be an IRI.
 104          * @param string|null $local A QName suffix, or null if $base is a shorthand.
 105          *
 106          * @return RdfWriter $this
 107          */
 108         public function say( $base, $local = null );
 109
 110         /**
 111          * Produce a resource as the object of a statement.
 112          * Can only follow a call to say() or a call to one of is(), text(), or value().
 113          * Should fail if called at an inappropriate time in the output sequence.
 114          *
 115          * @param string $base A QName prefix if $local is given, or an IRI or shorthand if $local is null.
 116          * @param string|null $local A QName suffix, or null if $base is an IRI or shorthand.
 117          *
 118          * @return RdfWriter $this
 119          */
 120         public function is( $base, $local = null );
 121
 122         /**
 123          * Produce a text literal as the object of a statement.
 124          * Can only follow a call to say() or a call to one of is(), text(), or value().
 125          * Should fail if called at an inappropriate time in the output sequence.
 126          *
 127          * @param string $text the text to be placed in the output
 128          * @param string|null $language the language the text is in
 129          *
 130          * @return RdfWriter $this
 131          */
 132         public function text( $text, $language = null );
 133
 134         /**
 135          * Produce a typed or untyped literal as the object of a statement.
 136          * Can only follow a call to say() or a call to one of is(), text(), or value().
 137          * Should fail if called at an inappropriate time in the output sequence.
 138          *
 139          * @param string $value the value encoded as a string
 140          * @param string|null $typeBase The data type's QName prefix if $typeLocal is given,
 141          *        or an IRI or shorthand if $typeLocal is null.
 142          * @param string|null $typeLocal The data type's  QName suffix,
 143          *        or null if $typeBase is an IRI or shorthand.
 144          *
 145          * @return RdfWriter $this
 146          */
 147         public function value( $value, $typeBase = null, $typeLocal = null );
 148
 149         /**
 150          * Shorthand for say( 'a' )->is( $type ).
 151          *
 152          * @param string $typeBase The data type's QName prefix if $typeLocal is given,
 153          *        or an IRI or shorthand if $typeLocal is null.
 154          * @param string|null $typeLocal The data type's  QName suffix,
 155          *        or null if $typeBase is an IRI or shorthand.
 156          *
 157          * @return RdfWriter $this
 158          */
 159         public function a( $typeBase, $typeLocal = null );
 160
 161         /**
 162          * Returns a document-level sub-writer.
 163          * This can be used to generate parts statements out of sequence.
 164          * Output generated by the sub-writer will be present in the
 165          * return value of drain(), after any output generated by this
 166          * writer itself.
 167          *
 168          * @note: calling drain() on sub-writers results in undefined behavior!
 169          * @note: using sub-writers after finish() has been called on this writer
 170          *        results in undefined behavior!
 171          *
 172          * @return RdfWriter
 173          */
 174         public function sub();
 175
 176         /**
 177          * Returns the MIME type of the RDF serialization the writer produces.
 178          *
 179          * @return string a MIME type
 180          */
 181         public function getMimeType();
 182
 183 }