X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=ion.stub.php;h=c41b77ace00616d715aa06dc685f481c24a5c711;hb=8b06d79d59d6a9a6082a40a06f07f0f2bb6c1d7f;hp=6fc9a4b5c0a54992a783ceee82e72d330fb05aa1;hpb=3870cfa96caf92c4e7852b91154f747857bf7620;p=awesomized%2Fext-ion diff --git a/ion.stub.php b/ion.stub.php index 6fc9a4b..c41b77a 100644 --- a/ion.stub.php +++ b/ion.stub.php @@ -23,38 +23,39 @@ namespace ion; * * int * * float * * string - * * references - * * arrays - * * objects (incl. \Serializable, and classes implementing magic and custom __serialize) + * * reference + * * array + * * object (incl. \Serializable, and classes implementing magic and custom __serialize) * * @param mixed $data PHP value(s). - * @param Serializer|null $serializer Custom serializer. + * @param Serializer|array|null $serializer Custom Serializer (options). * @return string serialized ION data - * @throws ion\Exception + * @throws \ion\Exception */ -function serialize(mixed $data, ?Serializer $serializer = null) : string {} +function serialize(mixed $data, Serializer|array|null $serializer = null) : string {} /** * Unserialize ION data (stream) as PHP value(s). * - * @param string|resource $data Serialized ION data, either as string buffer or stream,. + * @param string|resource $data Serialized ION data, either as string buffer or stream. + * @param Unserializer|array|null $unserializer Custom Unserializer (options). * @return mixed unserialized PHP values - * @throws ion\Exception + * @throws \ion\Exception */ -function unserialize($data, ?Unserializer $unserializer = null) : mixed {} +function unserialize($data, Unserializer|array|null $unserializer = null) : mixed {} /** * Serializer interface, used to customize ion\serialize()'s behavior. */ interface Serializer { - public function serialize(mixed $data) : string; + public function serialize(mixed $data, Writer|array|null $writer = null) : mixed; } /** * Unserializer interface, used to customize ion\unserialize()'s behavior. */ interface Unserializer { - /** @param string|resource $data */ + /** @param Reader|string|resource $data */ public function unserialize($data) : mixed; } @@ -152,7 +153,6 @@ class Catalog implements \Countable { * Add a shared symbol table to the catalog. * * @param Symbol\Table $table The new table to add. - * @return void */ public function add(Symbol\Table $table) : void {} @@ -257,7 +257,7 @@ class Decimal { /** * An ION Timestamp. - * @see https://amzn.github.io/ion-docs/docs/spec.html#timestamp the ION sepc's timestamp definintion + * @see https://amzn.github.io/ion-docs/docs/spec.html#timestamp the ION spec's timestamp definition * @see https://php.net/date PHP's date documentation */ class Timestamp extends \DateTime { @@ -276,13 +276,13 @@ class Timestamp extends \DateTime { * @param Timestamp\Precision|int $precision The timestamp's precision. * @param Timestamp\Format|string|null $format The timestamp's format. * @param string|null $datetime The timestamp's value. - * @param \DateTimeZone|null $timezone The timestamp's timezone. + * @param \DateTimeZone|string|null $timezone The timestamp's timezone. */ public function __construct( Timestamp\Precision|int $precision, Timestamp\Format|string|null $format = null, ?string $datetime = null, - ?\DateTimeZone $timezone = null, + \DateTimeZone|string|null $timezone = null, ) {} public function __toString() : string {} @@ -375,7 +375,7 @@ interface Writer { namespace ion\Symbol; /** - * The import location (referring to a shared table= of a symbol. + * The import location (referring to a shared table) of a symbol. */ class ImportLocation { /** @@ -448,24 +448,6 @@ interface Table { public function findLocal(string|int $id) : ?\ion\Symbol; } -namespace ion\Symbol\Table; - -/** - * Get the built-in PHP shared symbol table. - * - * @see \ion\Symbol\Table\PHP - * @return \ion\Symbol\Table The builtin PHP shared symbol table. - */ -function PHP() : \ion\Symbol\Table {} - -/** - * Get the built-in ION system shared symbol table. - * - * @see \ion\Symbol\Table\System - * @return \ion\Symbol\Table The builtin ION system shared symbol table. - */ -function System() : \ion\Symbol\Table {} - /** * The built-in ION system symbols. */ @@ -486,6 +468,13 @@ enum System : string implements \ion\Symbol\Enum { public function toSID() : int {} /** @alias ion\Symbol\Enum::toString */ public function toString() : string {} + + /** + * Get the built-in ION system shared symbol table. + * + * @return Table\Shared The system symbol table. + */ + public static function asTable() : Table\Shared {} } /** @@ -509,8 +498,17 @@ enum PHP : string implements \ion\Symbol\Enum { public function toSID() : int {} /** @alias ion\Symbol\Enum::toString */ public function toString() : string {} + + /** + * Get the built-in PHP shared symbol table. + * + * @return Table\Shared The builtin PHP shared symbol table. + */ + public static function asTable() : Table\Shared {} } +namespace ion\Symbol\Table; + /** * A local symbol table. * @@ -691,10 +689,14 @@ enum Format : string { namespace ion\Reader; /** - * Reader options. + * Base implementation of ION readers. */ -class Options { +abstract class Reader implements \ion\Reader { + /** + * @param string|resource $data The string or resource to read from. + */ public function __construct( + $data, /** * ION catalog to use for symbol lookup. */ @@ -732,16 +734,6 @@ class Options { */ public readonly bool $skipCharacterValidation = false, ) {} -} - -/** - * Base implementation of ION readers. - */ -abstract class Reader implements \ion\Reader { - /** - * Reader options. - */ - public readonly ?Options $options; public function hasChildren() : bool {} public function getChildren() : \ion\Reader {} @@ -796,7 +788,7 @@ abstract class Reader implements \ion\Reader { */ interface Buffer extends \ion\Reader { /** - * Get the buffer read from. + * Get the buffer being read from. * * @return string The buffer read from. */ @@ -808,7 +800,7 @@ interface Buffer extends \ion\Reader { */ interface Stream extends \ion\Reader { /** - * Get the stream read from. + * Get the stream being read from. * * @return resource The stream read from. */ @@ -833,19 +825,9 @@ interface Stream extends \ion\Reader { namespace ion\Reader\Buffer; /** - * ION string buffer reader. + * ION buffer reader. */ class Reader extends \ion\Reader\Reader implements \ion\Reader\Buffer { - /** - * Create a new string buffer reader. - * - * @param string $buffer The buffer to read from. - * @param \ion\Reader\Options|null $options Reader options. - */ - public function __construct( - string $buffer, - ?\ion\Reader\Options $options = null, - ) {} public function getBuffer() : string {} } @@ -856,16 +838,6 @@ namespace ion\Reader\Stream; * ION stream reader. */ class Reader extends \ion\Reader\Reader implements \ion\Reader\Stream { - /** - * Create a new stream reader. - * - * @param resource $stream The stream to read from. - * @param \ion\Reader\Options|null $options Reader options. - */ - public function __construct( - $stream, - ?\ion\Reader\Options $options = null, - ) {} /** * Get the stream read from. @@ -883,11 +855,11 @@ class Reader extends \ion\Reader\Reader implements \ion\Reader\Stream { namespace ion\Writer; /** - * ION writer options. + * Base implementation of common functionality of ION writers. */ -class Options { +abstract class Writer implements \ion\Writer { /** - * Create custom ION writer options. + * Create custom ION writer. */ public function __construct( /** @@ -939,12 +911,7 @@ class Options { */ public readonly int $tempBufferSize = 0x4000, ) {} -} -/** - * Base implementation of common functionality of ION writers. - */ -abstract class Writer implements \ion\Writer { public function writeNull() : void {} public function writeTypedNull(\ion\Type $type) : void {} public function writeBool(bool $value) : void {} @@ -1007,17 +974,9 @@ interface Stream extends \ion\Writer { namespace ion\Writer\Buffer; /** - * IO buffer writer. + * ION buffer writer. */ class Writer extends \ion\Writer\Writer implements \ion\Writer\Buffer { - /** - * Create a new buffer writer. - * - * @param \ion\Writer\Options|null $options Writer options. - */ - public function __construct( - ?\ion\Writer\Options $options = null, - ) {} public function getBuffer() : string {} public function resetBuffer() : void {} @@ -1033,11 +992,57 @@ class Writer extends \ion\Writer\Writer implements \ion\Writer\Stream { * Create a new stream writer. * * @param resource $stream The stream to write to. - * @param \ion\Writer\Options|null $options Writer options. */ public function __construct( $stream, - ?\ion\Writer\Options $options = null, + /** + * ION catalog to use for symbol lookup. + */ + public readonly ?\ion\Catalog $catalog = null, + /** + * Decimal context to use. + */ + public readonly ?\ion\Decimal\Context $decimalContext = null, + /** + * Whether to output binary ION. + */ + public readonly bool $outputBinary = false, + /** + * Whether to write doubles which fit in 32 bits as floats. + */ + public readonly bool $compactFloats = false, + /** + * Whether to slash-escape all non ASCII bytes. + */ + public readonly bool $escapeNonAscii = false, + /** + * Whether to produce pretty-printed output. + */ + public readonly bool $prettyPrint = false, + /** + * Whether to indent with tabs, when pretty-printing. + */ + public readonly bool $indentTabs = true, + /** + * The number of spaces to use for indentation instead of tabs, when pretty-printing. + */ + public readonly int $indentSize = 2, + /** + * Whether to immediately flush every value written. + */ + public readonly bool $flushEveryValue = false, + /** + * Maximum depth of nested containers. + */ + public readonly int $maxContainerDepth = 10, + /** + * The maximum number of annotations allowed on a single value. + */ + public readonly int $maxAnnotations = 10, + /** + * Temporary buffer size. + */ + public readonly int $tempBufferSize = 0x4000, ) {} /** * @return resource @@ -1046,19 +1051,14 @@ class Writer extends \ion\Writer\Writer implements \ion\Writer\Stream { } namespace ion\Serializer; - /** - * Specialization of the serializer for PHP. + * Serializer implementation */ -class PHP implements \ion\Serializer { +class Serializer implements \ion\Serializer { /** - * Create a new PHP ION serializer. + * Create a new ION serializer. */ public function __construct( - /** - * Writer options. - */ - public readonly ?\ion\Writer\Options $writerOptions = null, /** * Whether to write the top level array as multiple ION sequences. */ @@ -1073,23 +1073,19 @@ class PHP implements \ion\Serializer { public readonly ?string $callCustomSerialize = null, ) {} - public function serialize(mixed $data) : string {} + public function serialize(mixed $data, \ion\Writer|array|null $writer = null) : mixed {} } namespace ion\Unserializer; /** - * Specialization of the unserializer for PHP. + * Unserializer implementation */ -class PHP implements \ion\Unserializer { +class Unserializer implements \ion\Unserializer { /** - * Create a new ION PHP unserializer. + * Create a new ION unserializer. */ public function __construct( - /** - * Reader options. - */ - public readonly ?\ion\Reader\Options $readerOptions = null, /** * Whether to continue reading multiple ION sequences after the first one. */ @@ -1104,6 +1100,6 @@ class PHP implements \ion\Unserializer { public readonly ?string $callCustomUnserialize = null, ){} - /** @param string|resource $data */ + /** @param \ion\Reader|string|resource $data */ public function unserialize($data) : mixed {} }