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-or-later
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	}