git.m6w6.name Git - awesomized/ext-ion/blob - ion.stub.php

   1 <?php
   2
   3 /**
   4  * Amazon ION serialization format.
   5  *
   6  * @link https://github.com/awesomized/ext-ion
   7  *
   8  * @see https://github.com/amzn/ion-c amzn/ion-c
   9  * @see https://amzn.github.io/ion-docs/ Amazon ION spec
  10  *
  11  * @generate-class-entries static
  12  * @generate-function-entries static
  13  */
  14
  15 namespace ion;
  16
  17 /**
  18  * Serialize a PHP value as ION data.
  19  *
  20  * Serializes supported PHP values with the optionally provided \ion\Serializer:
  21  *  * NULL
  22  *  * bool
  23  *  * int
  24  *  * float
  25  *  * string
  26  *  * reference
  27  *  * array
  28  *  * object (incl. \Serializable, and classes implementing magic and custom __serialize)
  29  *
  30  * @param mixed $data PHP value(s).
  31  * @param Serializer|array|null $serializer Custom serializer.
  32  * @return string serialized ION data
  33  * @throws \ion\Exception
  34  */
  35 function serialize(mixed $data, Serializer|array|null $serializer = null) : string {}
  36
  37 /**
  38  * Unserialize ION data (stream) as PHP value(s).
  39  *
  40  * @param string|resource $data Serialized ION data, either as string buffer or stream.
  41  * @return mixed unserialized PHP values
  42  * @throws \ion\Exception
  43  */
  44 function unserialize($data, Unserializer|array|null $unserializer = null) : mixed {}
  45
  46 /**
  47  * Serializer interface, used to customize ion\serialize()'s behavior.
  48  */
  49 interface Serializer {
  50     public function serialize(mixed $data) : string;
  51 }
  52
  53 /**
  54  * Unserializer interface, used to customize ion\unserialize()'s behavior.
  55  */
  56 interface Unserializer {
  57     /** @param string|resource $data */
  58     public function unserialize($data) : mixed;
  59 }
  60
  61 /**
  62  * Base exception for the ION extension.
  63  */
  64 class Exception extends \Exception {
  65 }
  66
  67 /**
  68  * ION data type.
  69  *
  70  * The following special PHP classes are provided for some data types:
  71  * * ion\Decimal
  72  * * ion\Timestamp
  73  * * ion\Symbol
  74  * * ion\Lob
  75  */
  76 enum Type : int {
  77     case Null       = 0x000;
  78     case Bool       = 0x100;
  79     case Int        = 0x200;
  80     case Float      = 0x400;
  81     case Decimal    = 0x500;
  82     case Timestamp  = 0x600;
  83     case Symbol     = 0x700;
  84     case String     = 0x800;
  85     case CLob       = 0x900;
  86     case BLob       = 0xa00;
  87     case List       = 0xb00;
  88     case SExp       = 0xc00;
  89     case Struct     = 0xd00;
  90     case Datagram   = 0xf00;
  91
  92     case EOF        =-0x100;
  93     case NONE       =-0x200;
  94 }
  95
  96 /**
  97  * @see https://amzn.github.io/ion-docs/docs/spec.html#symbol ION spec's symbol definition
  98  * @see https://amzn.github.io/ion-docs/guides/symbols-guide.html ION spec's symbol guide
  99  */
 100 class Symbol {
 101     /**
 102      * Create an ION symbol.
 103      */
 104     public function __construct(
 105         /**
 106          * The symbol's text representation.
 107          */
 108         public readonly ?string $value = null,
 109         /**
 110          * The symbols ID, referencing its location within a shared symbol table.
 111          */
 112         public readonly int $sid = -1,
 113         /**
 114          * The import location referencing a shared symbol table.
 115          */
 116         public readonly ?Symbol\ImportLocation $importLocation = null,
 117     ) {}
 118
 119     /**
 120      * Compare two symbols for equality.
 121      *
 122      * Two symbols are considered equal, if either:
 123      * * both are the same object or NULL
 124      * * both values are NULL (unknown text), and both $importLocations match
 125      * * both values match, regardless of $sid and $importLocation
 126      *
 127      * @param Symbol $symbol
 128      * @return bool whether the two Symbols equal
 129      */
 130     public function equals(Symbol $symbol): bool {}
 131     public function __toString() : string {}
 132     /** @alias ion\Symbol::__toString */
 133     public function toString() : string {}
 134 }
 135
 136 /**
 137  * The Catalog holds a collection of ion\Symbol\Table instances queried from ion\Reader and ion\Writer instances.
 138  *
 139  * @see https://amzn.github.io/ion-docs/docs/symbols.html#the-catalog the ION spec's symbol guide chapter on catalog.
 140  */
 141 class Catalog implements \Countable {
 142     /** Internal cache. */
 143     private array $symbolTables = [];
 144
 145     /** Create a new Catalog. */
 146     public function __construct() {}
 147
 148     /** Count how many symbol tables the catalog holds. */
 149     public function count() : int {}
 150
 151     /**
 152      * Add a shared symbol table to the catalog.
 153      *
 154      * @param Symbol\Table $table The new table to add.
 155      */
 156     public function add(Symbol\Table $table) : void {}
 157
 158     /**
 159      * Remove a shared symbol table from the catalog.
 160      *
 161      * @param Symbol\Table|string $table The symbol table to renmove.
 162      * @return bool Success.
 163      */
 164     public function remove(Symbol\Table|string $table) : bool {}
 165
 166     /**
 167      * Find a shared symbol table within the catalog.
 168      *
 169      * @param string $name The name of the symbol table.
 170      * @param int $version The version the symbol table should match.
 171      * @return Symbol\Table|null The symbol table found, if any.
 172      */
 173     public function find(string $name, int $version = 0) : ?Symbol\Table {}
 174
 175     /**
 176      * Find a "best match" for a shared symbol table within the catalog.
 177      *
 178      * @param string $name The name of the symbol table,
 179      * @param int $version The minimum version of the symbol table.
 180      * @return Symbol\Table|null The symbol table found, if any.
 181      */
 182     public function findBest(string $name, int $version = 0) : ?Symbol\Table {}
 183 }
 184
 185 /**
 186  * A large object.
 187  *
 188  * @see ion\Type
 189  * @see https://amzn.github.io/ion-docs/docs/spec.html#blob the ION spec's BLob definition
 190  * @see https://amzn.github.io/ion-docs/docs/spec.html#clob the ION sepc's CLob definition
 191  */
 192 class LOB {
 193     /**
 194      * Create an ION large object.
 195      */
 196     public function __construct(
 197         /**
 198          * The value of the large object.
 199          */
 200         public readonly string $value,
 201         /**
 202          * The type (CLob/BLob).
 203          */
 204         public readonly Type $type = Type::CLob,
 205     ) {}
 206 }
 207
 208 /**
 209  * An arbitrary precision fixed point decimal.
 210  *
 211  * @see ion\Decimal\Context
 212  * @see https://amzn.github.io/ion-docs/docs/decimal.html the ION spec's decimal docs
 213  */
 214 class Decimal {
 215     /**
 216      * Create a new fixed point decimal.
 217      */
 218     public function __construct(
 219         /**
 220          * The decimal number.
 221          */
 222         public readonly string|int $number,
 223         /**
 224          * The decimal context.
 225          */
 226         public readonly ?Decimal\Context $context = null,
 227     ) {}
 228
 229     /**
 230      * Check two decimals for equality.
 231      *
 232      * @param Decimal $decimal The decimal to compare to.
 233      * @return bool Whether both decimals equal.
 234      */
 235     public function equals(Decimal $decimal) : bool {}
 236
 237     /**
 238      * Check whether the decimal is actually a big integer.
 239      * @return bool Whether the decimal is actually an integer.
 240      */
 241     public function isInt() : bool {}
 242
 243     public function __toString() : string {}
 244     /**
 245      * Get the string representation of the decimal.
 246      * @alias ion\Decimal::__toString
 247      */
 248     public function toString() : string {}
 249
 250     /**
 251      * Get the integer represention of the decimal.
 252      * @throws \ion\Exception If the decimal is actually not an integer.
 253      */
 254     public function toInt() : int {}
 255 }
 256
 257 /**
 258  * An ION Timestamp.
 259  * @see https://amzn.github.io/ion-docs/docs/spec.html#timestamp the ION spec's timestamp definition
 260  * @see https://php.net/date PHP's date documentation
 261  */
 262 class Timestamp extends \DateTime {
 263     /**
 264      * The timestamp's precision. See ion\Timestamp\Precision.
 265      */
 266     public readonly int $precision;
 267     /**
 268      * The timestamp's format. See ion\Timestamp\Format.
 269      */
 270     public readonly string $format;
 271
 272     /**
 273      * Create a new ION timestamp.
 274      *
 275      * @param Timestamp\Precision|int $precision The timestamp's precision.
 276      * @param Timestamp\Format|string|null $format The timestamp's format.
 277      * @param string|null $datetime The timestamp's value.
 278      * @param \DateTimeZone|string|null $timezone The timestamp's timezone.
 279      */
 280     public function __construct(
 281         Timestamp\Precision|int $precision,
 282         Timestamp\Format|string|null $format = null,
 283         ?string $datetime = null,
 284         \DateTimeZone|string|null $timezone = null,
 285     ) {}
 286
 287     public function __toString() : string {}
 288 }
 289
 290 /**
 291  * ION reader API.
 292  */
 293 interface Reader extends \RecursiveIterator {
 294     public function getType() : Type;
 295     public function hasAnnotations() : bool;
 296     public function hasAnnotation(string $annotation) : bool;
 297     public function isNull() : bool;
 298     public function isInStruct() : bool;
 299     public function getFieldName() : string;
 300     public function getFieldNameSymbol() : Symbol;
 301     public function getAnnotations() : array;
 302     public function getAnnotationSymbols() : array;
 303     public function countAnnotations() : int;
 304     public function getAnnotation(int $index) : string;
 305     public function getAnnotationSymbol(int $index) : Symbol;
 306
 307     public function readNull() : Type;
 308     public function readBool() : bool;
 309     public function readInt() : int|string;
 310     public function readFloat() : float;
 311     public function readDecimal() : Decimal;
 312     public function readTimestamp() : Timestamp;
 313     public function readSymbol() : Symbol;
 314     public function readString() : string;
 315     /** @param ref $string */
 316     public function readStringPart(&$string, int $length = 0x1000) : bool;
 317     public function readLob() : string;
 318     /** @param ref $string */
 319     public function readLobPart(&$string, int $length = 0x1000) : bool;
 320
 321     public function getPosition() : int;
 322     public function getDepth() : int;
 323
 324     public function seek(int $offset, int $length = -1) : void;
 325     /*
 326     public function getSymbolTable() : SymbolTable;
 327     public function setSymbolTable(SymbolTable $table) : void;
 328     */
 329     public function getValueOffset() : int;
 330     public function getValueLength() : int;
 331 }
 332
 333 /**
 334  * ION writer API.
 335  */
 336 interface Writer {
 337     public function writeNull() : void;
 338     public function writeTypedNull(Type $type) : void;
 339     public function writeBool(bool $value) : void;
 340     public function writeInt(int|string $value) : void;
 341     public function writeFloat(float $value) : void;
 342     public function writeDecimal(Decimal|string $value) : void;
 343     public function writeTimestamp(Timestamp|string $value) : void;
 344     public function writeSymbol(Symbol|string $value) : void;
 345     public function writeString(string $value) : void;
 346     public function writeCLob(string $value) : void;
 347     public function writeBLob(string $value) : void;
 348
 349     public function startLob(Type $type) : void;
 350     public function appendLob(string $data) : void;
 351     public function finishLob() : void;
 352
 353     public function startContainer(Type $type) : void;
 354     public function finishContainer() : void;
 355
 356     public function writeFieldName(string $name) : void;
 357
 358     public function writeAnnotation(Symbol|string ...$annotation) : void;
 359
 360     public function getDepth() : int;
 361     public function flush() : int;
 362     public function finish() : int;
 363
 364     // public function writeOne(Reader $reader) : void;
 365     // public function writeAll(Reader $reader) : void;
 366
 367     // public function getCatalog() : Catalog;
 368     // public function setCatalog(Catalog $catalog) : void;
 369
 370     // public function getSymbolTable() : Symbol\Table;
 371     // puvlic function setSymbolTable(Symbol\Table $table) : void;
 372 }
 373
 374 namespace ion\Symbol;
 375
 376 /**
 377  * The import location (referring to a shared table) of a symbol.
 378  */
 379 class ImportLocation {
 380     /**
 381      * Create a new import location.
 382      */
 383     public function __construct(
 384         /**
 385          * The name of the shared symbol table.
 386          */
 387         public readonly string $name,
 388         /**
 389          * The location (sid) of the symbol within the table.
 390          */
 391         public readonly int $location,
 392     ) {}
 393 }
 394
 395 /**
 396  * Base interface of built-in shared symbol tables.
 397  */
 398 interface Enum {
 399     /**
 400      * @return \ion\Symbol Instance of the symbol.
 401      */
 402     public function toSymbol() : \ion\Symbol;
 403
 404     /**
 405      * @return int The symbol id.
 406      */
 407     public function toSID() : int;
 408
 409     /**
 410      * @return string The symbol's textual representation.
 411      */
 412     public function toString() : string;
 413 }
 414
 415 /**
 416  * Base interface of an ION symbol table.
 417  */
 418 interface Table {
 419     /**
 420      * Get the maximum symbol ID within the symbol table.
 421      * @return int The maximum symbol ID.
 422      */
 423     public function getMaxId() : int;
 424
 425     /**
 426      * Add a symbol to the table.
 427      *
 428      * @param \ion\Symbol|string $symbol The symbol (value) to add.
 429      * @return int The symbol ID.
 430      */
 431     public function add(\ion\Symbol|string $symbol) : int;
 432
 433     /**
 434      * Find a symbol within the symbol table, including imports.
 435      *
 436      * @param string|int $id The ID or text of the symbol to find.
 437      * @return \ion\Symbol|null The symbol found, if any.
 438      */
 439     public function find(string|int $id) : ?\ion\Symbol;
 440
 441     /**
 442      * Find a symbol within **only this** symbol table, ignoring imports.
 443      *
 444      * @param string|int $id The ID or text of the symbol to find.
 445      * @return \ion\Symbol|null The symbol found, if any.
 446      */
 447     public function findLocal(string|int $id) : ?\ion\Symbol;
 448 }
 449
 450 /**
 451  * The built-in ION system symbols.
 452  */
 453 enum System : string implements \ion\Symbol\Enum {
 454     case Ion                = '$ion';
 455     case Ivm_1_0            = '$ion_1_0';
 456     case IonSymbolTable     = '$ion_symbol_table';
 457     case Name               = 'name';
 458     case Version            = 'version';
 459     case Imports            = 'imports';
 460     case Symbols            = 'symbols';
 461     case MaxId              = 'max_id';
 462     case SharedSymbolTable  = '$ion_shared_symbol_table';
 463
 464     /** @alias ion\Symbol\Enum::toSymbol */
 465     public function toSymbol() : \ion\Symbol {}
 466     /** @alias ion\Symbol\Enum::toSID */
 467     public function toSID() : int {}
 468     /** @alias ion\Symbol\Enum::toString */
 469     public function toString() : string {}
 470
 471     /**
 472      * Get the built-in ION system shared symbol table.
 473      *
 474      * @return Table\Shared The system symbol table.
 475      */
 476     public static function asTable() : Table\Shared {}
 477 }
 478
 479 /**
 480  * The built-in PHP symbols.
 481  */
 482 enum PHP : string implements \ion\Symbol\Enum {
 483     case PHP            = 'PHP';
 484     case Reference      = 'R';
 485     case Backref        = 'r';
 486     case Property       = 'p';
 487     case Object         = 'o';
 488     case ClassObject    = 'c';
 489     case MagicObject    = 'O';
 490     case CustomObject   = 'C';
 491     case Enum           = 'E';
 492     case Serializable   = 'S';
 493
 494     /** @alias ion\Symbol\Enum::toSymbol */
 495     public function toSymbol() : \ion\Symbol {}
 496     /** @alias ion\Symbol\Enum::toSID */
 497     public function toSID() : int {}
 498     /** @alias ion\Symbol\Enum::toString */
 499     public function toString() : string {}
 500
 501     /**
 502      * Get the built-in PHP shared symbol table.
 503      *
 504      * @return Table\Shared The builtin PHP shared symbol table.
 505      */
 506     public static function asTable() : Table\Shared {}
 507 }
 508
 509 namespace ion\Symbol\Table;
 510
 511 /**
 512  * A local symbol table.
 513  *
 514  * @see https://amzn.github.io/ion-docs/guides/symbols-guide.html the ION spec's symbol guide
 515  * @see https://amzn.github.io/ion-docs/guides/cookbook.html#using-a-local-symbol-table the ION doc's cookbook
 516  */
 517 class Local implements \ion\Symbol\Table {
 518     /** Internal cache. */
 519     private array $imports = [];
 520     /** Internal cache. */
 521     private array $symbols = [];
 522
 523     /**
 524      * Create a local symbol table.
 525      */
 526     public function __construct() {}
 527
 528     /**
 529      * Import a symbol table.
 530      *
 531      * @param \ion\Symbol\Table $table The symbol table to import.
 532      * @return void
 533      */
 534     public function import(\ion\Symbol\Table $table) : void {}
 535
 536     /** @alias ion\Symbol\Table::getMaxId */
 537     public function getMaxId() : int {}
 538
 539     /** @alias ion\Symbol\Table::add */
 540     public function add(\ion\Symbol|string $symbol) : int {}
 541     /** @alias ion\Symbol\Table::find */
 542     public function find(string|int $id) : ?\ion\Symbol {}
 543     /** @alias ion\Symbol\Table::findLocal */
 544     public function findLocal(string|int $id) : ?\ion\Symbol {}
 545 }
 546
 547 /**
 548  * A shared symbol table.
 549  *
 550  * @see https://amzn.github.io/ion-docs/guides/symbols-guide.html the ION spec's symbol guide
 551  * @see https://amzn.github.io/ion-docs/guides/cookbook.html#using-a-shared-symbol-table the ION doc's cookbook
 552  */
 553 class Shared implements \ion\Symbol\Table {
 554     /**
 555      * Create a shared symbol table.
 556      */
 557     public function __construct(
 558         /**
 559          * The name of the shared symbol table.
 560          */
 561         public readonly string $name,
 562         /**
 563          * The version of the shared symbol table.
 564          */
 565         public readonly int $version = 1,
 566         /**
 567          * Predefined list of symbols as array of strings.
 568          */
 569         ?array $symbols = null,
 570     ) {}
 571
 572     /** Internal cache. */
 573     private array $symbols = [];
 574
 575     /** @alias ion\Symbol\Table::getMaxId */
 576     public function getMaxId() : int {}
 577
 578     /** @alias ion\Symbol\Table::add */
 579     public function add(\ion\Symbol|string $symbol) : int {}
 580     /** @alias ion\Symbol\Table::find */
 581     public function find(string|int $id) : ?\ion\Symbol {}
 582     /** @alias ion\Symbol\Table::findLocal */
 583     public function findLocal(string|int $id) : ?\ion\Symbol {}
 584 }
 585
 586 namespace ion\Decimal;
 587
 588 /**
 589  * An ion\Decimal's context.
 590  */
 591 class Context {
 592     /**
 593      * Create a new decimal context.
 594      */
 595     public function __construct(
 596         /**
 597          * Maximum digits.
 598          */
 599         public readonly int $digits,
 600         /**
 601          * Maximum exponent.
 602          */
 603         public readonly int $eMax,
 604         /**
 605          * Minimum exponent.
 606          */
 607         public readonly int $eMin,
 608         /**
 609          * Rounding mode.
 610          */
 611         public readonly Context\Rounding|int $round,
 612         /**
 613          * Whether to clamp.
 614          */
 615         public readonly bool $clamp,
 616     ) {}
 617
 618     /**
 619      * Create a context suitable for 32bit decimals.
 620      */
 621     public static function Dec32() : Context {}
 622
 623     /**
 624      * Create a context suitable for 64bit decimals.
 625      */
 626     public static function Dec64() : Context {}
 627
 628     /**
 629      * Create a context suitable for 128bit decimals.
 630      */
 631     public static function Dec128() : Context {}
 632
 633     /**
 634      * Create a context with maximum settings.
 635      * @param Context\Rounding|int $round Rounding mode.
 636      */
 637     public static function DecMax(Context\Rounding|int $round = Context\Rounding::HalfEven) : Context {}
 638 }
 639
 640 namespace ion\Decimal\Context;
 641
 642 /**
 643  * Rounding mode.
 644  */
 645 enum Rounding : int {
 646     case Ceiling    = 0;
 647     case Up         = 1;
 648     case HalfUp     = 2;
 649     case HalfEven   = 3;
 650     case HalfDown   = 4;
 651     case Down       = 5;
 652     case Floor      = 6;
 653     case Down05Up   = 7;
 654 }
 655
 656 namespace ion\Timestamp;
 657
 658 /**
 659  * Timestamp precision.
 660  */
 661 enum Precision : int {
 662     case Year           = 0x1;
 663     case Month          = 0x1|0x2;
 664     case Day            = 0x1|0x2|0x4;
 665     case Min            = 0x1|0x2|0x4|0x10;
 666     case Sec            = 0x1|0x2|0x4|0x10|0x20;
 667     case Frac           = 0x1|0x2|0x4|0x10|0x20|0x40;
 668     case MinTZ          = 0x1|0x2|0x4|0x10|0x80;
 669     case SecTZ          = 0x1|0x2|0x4|0x10|0x20|0x80;
 670     case FracTZ         = 0x1|0x2|0x4|0x10|0x20|0x40|0x80;
 671 }
 672
 673 /**
 674  * Timestamp format.
 675  */
 676 enum Format : string {
 677     case Year           = "Y\T";
 678     case Month          = "Y-m\T";
 679     case Day            = "Y-m-d\T";
 680     case Min            = "Y-m-d\TH:i";
 681     case Sec            = "Y-m-d\TH:i:s";
 682     case Frac           = "Y-m-d\TH:i:s.v";
 683     case MinTZ          = "Y-m-d\TH:iP";
 684     case SecTZ          = "Y-m-d\TH:i:sP";
 685     case FracTZ         = "Y-m-d\TH:i:s.vP";
 686 }
 687
 688 namespace ion\Reader;
 689
 690 /**
 691  * Reader options.
 692  */
 693 class Options {
 694     public function __construct(
 695         /**
 696          * ION catalog to use for symbol lookup.
 697          */
 698         public readonly ?\ion\Catalog $catalog = null,
 699         /**
 700          * Decimal context to use.
 701          */
 702         public readonly ?\ion\Decimal\Context $decimalContext = null,
 703         /**
 704          * Callback as function(\ion\Reader):void called upon local symbol table context change.
 705          */
 706         public readonly ?\Closure $onContextChange = null,
 707         /**
 708          * Whether to return otherwise hidden system values.
 709          */
 710         public readonly bool $returnSystemValues = false,
 711         /**
 712          * The maximum depth of nested containers.
 713          */
 714         public readonly int $maxContainerDepth = 10,
 715         /**
 716          * The maximum number of annotations allowed on a single value.
 717          */
 718         public readonly int $maxAnnotations = 10,
 719         /**
 720          * The maximum number of bytes of all annotations on a single value.
 721          */
 722         public readonly int $annotationBufferSize = 0x4000,
 723         /**
 724          * The maximum number of bytes of a symbol/value/chunk.
 725          */
 726         public readonly int $tempBufferSize = 0x4000,
 727         /**
 728          * Whether to skip UTF-8 validation.
 729          */
 730         public readonly bool $skipCharacterValidation = false,
 731     ) {}
 732 }
 733
 734 /**
 735  * Base implementation of ION readers.
 736  */
 737 abstract class Reader implements \ion\Reader {
 738     /**
 739      * Reader options.
 740      */
 741     public readonly ?Options $options;
 742
 743     public function hasChildren() : bool {}
 744     public function getChildren() : \ion\Reader {}
 745
 746     public function rewind() : void {}
 747     public function next() : void {}
 748     public function valid() : bool {}
 749     public function key() : mixed {}
 750     public function current() : mixed {}
 751
 752     public function getType() : \ion\Type {}
 753     public function hasAnnotations() : bool {}
 754     public function hasAnnotation(string $annotation) : bool {}
 755     public function isNull() : bool {}
 756     public function isInStruct() : bool {}
 757     public function getFieldName() : string {}
 758     public function getFieldNameSymbol() : \ion\Symbol {}
 759     public function getAnnotations() : array {}
 760     public function getAnnotationSymbols() : array {}
 761     public function countAnnotations() : int {}
 762     public function getAnnotation(int $index) : string {}
 763     public function getAnnotationSymbol(int $index) : \ion\Symbol {}
 764
 765     public function readNull() : \ion\Type {}
 766     public function readBool() : bool {}
 767     public function readInt() : int|string {}
 768     public function readFloat() : float {}
 769     public function readDecimal() : \ion\Decimal {}
 770     public function readTimestamp() : \ion\Timestamp {}
 771     public function readSymbol() : \ion\Symbol {}
 772     public function readString() : string {}
 773     /** @param ref $string */
 774     public function readStringPart(&$string, int $length = 0x1000) : bool {}
 775     public function readLob() : string {}
 776     /** @param ref $string */
 777     public function readLobPart(&$string, int $length = 0x1000) : bool {}
 778
 779     public function getPosition() : int {}
 780     public function getDepth() : int{}
 781
 782     public function seek(int $offset, int $length = -1) : void {}
 783     /*
 784     public function getSymbolTable() : SymbolTable {}
 785     public function setSymbolTable(SymbolTable $table) : void {}
 786     */
 787     public function getValueOffset() : int {}
 788     public function getValueLength() : int {}
 789 }
 790
 791 /**
 792  * ION string buffer reader API.
 793  */
 794 interface Buffer extends \ion\Reader {
 795     /**
 796      * Get the buffer read from.
 797      *
 798      * @return string The buffer read from.
 799      */
 800     public function getBuffer() : string;
 801 }
 802
 803 /**
 804  * ION stream reader API.
 805  */
 806 interface Stream extends \ion\Reader {
 807     /**
 808      * Get the stream read from.
 809      *
 810      * @return resource The stream read from.
 811      */
 812     public function getStream();
 813
 814     /**
 815      * Reset the stream read from.
 816      *
 817      * @param resource $stream The new stream to from.
 818      */
 819     public function resetStream($stream) : void;
 820
 821     /**
 822      * Reset the stream read from, limiting length to read.
 823      *
 824      * @param resource $stream The stream to read from.
 825      * @param int $length The maximum length to read from $stream.
 826      */
 827     public function resetStreamWithLength($stream, int $length) : void;
 828 }
 829
 830 namespace ion\Reader\Buffer;
 831
 832 /**
 833  * ION buffer reader.
 834  */
 835 class Reader extends \ion\Reader\Reader implements \ion\Reader\Buffer {
 836     /**
 837      * Create a new string buffer reader.
 838      *
 839      * @param string $buffer The buffer to read from.
 840      * @param \ion\Reader\Options|null $options Reader options.
 841      */
 842     public function __construct(
 843         string $buffer,
 844         ?\ion\Reader\Options $options = null,
 845     ) {}
 846
 847     public function getBuffer() : string {}
 848 }
 849
 850 namespace ion\Reader\Stream;
 851
 852 /**
 853  * ION stream reader.
 854  */
 855 class Reader extends \ion\Reader\Reader implements \ion\Reader\Stream {
 856     /**
 857      * Create a new stream reader.
 858      *
 859      * @param resource $stream The stream to read from.
 860      * @param \ion\Reader\Options|null $options Reader options.
 861      */
 862     public function __construct(
 863         $stream,
 864         ?\ion\Reader\Options $options = null,
 865     ) {}
 866
 867     /**
 868      * Get the stream read from.
 869      *
 870      * @return resource The stream read from.
 871      */
 872     public function getStream() {}
 873
 874     /** @param resource $stream */
 875     public function resetStream($stream) : void {}
 876     /** @param resource $stream */
 877     public function resetStreamWithLength($stream, int $length) : void {}
 878 }
 879
 880 namespace ion\Writer;
 881
 882 /**
 883  * ION writer options.
 884  */
 885 class Options {
 886     /**
 887      * Create custom ION writer options.
 888      */
 889     public function __construct(
 890         /**
 891          * ION catalog to use for symbol lookup.
 892          */
 893         public readonly ?\ion\Catalog $catalog = null,
 894         /**
 895          * Decimal context to use.
 896          */
 897         public readonly ?\ion\Decimal\Context $decimalContext = null,
 898         /**
 899          * Whether to output binary ION.
 900          */
 901         public readonly bool $outputBinary = false,
 902         /**
 903          * Whether to write doubles which fit in 32 bits as floats.
 904          */
 905         public readonly bool $compactFloats = false,
 906         /**
 907          * Whether to slash-escape all non ASCII bytes.
 908          */
 909         public readonly bool $escapeNonAscii = false,
 910         /**
 911          * Whether to produce pretty-printed output.
 912          */
 913         public readonly bool $prettyPrint = false,
 914         /**
 915          * Whether to indent with tabs, when pretty-printing.
 916          */
 917         public readonly bool $indentTabs = true,
 918         /**
 919          * The number of spaces to use for indentation instead of tabs, when pretty-printing.
 920          */
 921         public readonly int $indentSize = 2,
 922         /**
 923          * Whether to immediately flush every value written.
 924          */
 925         public readonly bool $flushEveryValue = false,
 926         /**
 927          * Maximum depth of nested containers.
 928          */
 929         public readonly int $maxContainerDepth = 10,
 930         /**
 931          * The maximum number of annotations allowed on a single value.
 932          */
 933         public readonly int $maxAnnotations = 10,
 934         /**
 935          * Temporary buffer size.
 936          */
 937         public readonly int $tempBufferSize = 0x4000,
 938     ) {}
 939 }
 940
 941 /**
 942  * Base implementation of common functionality of ION writers.
 943  */
 944 abstract class Writer implements \ion\Writer {
 945     public function writeNull() : void {}
 946     public function writeTypedNull(\ion\Type $type) : void {}
 947     public function writeBool(bool $value) : void {}
 948     public function writeInt(int|string $value) : void {}
 949     public function writeFloat(float $value) : void {}
 950     public function writeDecimal(\ion\Decimal|string $value) : void {}
 951     public function writeTimestamp(\ion\Timestamp|string $value) : void {}
 952     public function writeSymbol(\ion\Symbol|string $value) : void {}
 953     public function writeString(string $value) : void {}
 954     public function writeCLob(string $value) : void {}
 955     public function writeBLob(string $value) : void {}
 956
 957     public function startLob(\ion\Type $type) : void {}
 958     public function appendLob(string $data) : void {}
 959     public function finishLob() : void {}
 960
 961     public function startContainer(\ion\Type $type) : void {}
 962     public function finishContainer() : void {}
 963
 964     public function writeFieldName(string $name) : void {}
 965
 966     public function writeAnnotation(\ion\Symbol|string ...$annotation) : void {}
 967
 968     public function getDepth() : int {}
 969     public function flush() : int {}
 970     public function finish() : int {}
 971
 972     // public function writeOne(\ion\Reader $reader) : void {}
 973     // public function writeAll(\ion\Reader $reader) : void {}
 974 }
 975
 976 /**
 977  * ION buffer writer API.
 978  */
 979 interface Buffer extends \ion\Writer {
 980     /**
 981      * Get the buffer written to.
 982      *
 983      * @reeturn string The buffer written so far.
 984      */
 985     public function getBuffer() : string;
 986
 987     /**
 988      * Reset the buffer written to.
 989      */
 990     public function resetBuffer() : void;
 991 }
 992
 993 /**
 994  * ION stream writer API.
 995  */
 996 interface Stream extends \ion\Writer {
 997     /**
 998      * Get the stream being written to.
 999      * @return resource
1000      */
1001     public function getStream();
1002 }
1003
1004 namespace ion\Writer\Buffer;
1005
1006 /**
1007  * IO buffer writer.
1008  */
1009 class Writer extends \ion\Writer\Writer implements \ion\Writer\Buffer {
1010     /**
1011      * Create a new buffer writer.
1012      *
1013      * @param \ion\Writer\Options|null $options Writer options.
1014      */
1015     public function __construct(
1016         ?\ion\Writer\Options $options = null,
1017     ) {}
1018
1019     public function getBuffer() : string {}
1020     public function resetBuffer() : void {}
1021 }
1022
1023 namespace ion\Writer\Stream;
1024
1025 /**
1026  * ION stream writer.
1027  */
1028 class Writer extends \ion\Writer\Writer implements \ion\Writer\Stream {
1029     /**
1030      * Create a new stream writer.
1031      *
1032      * @param resource $stream The stream to write to.
1033      * @param \ion\Writer\Options|null $options Writer options.
1034      */
1035     public function __construct(
1036         $stream,
1037         ?\ion\Writer\Options $options = null,
1038     ) {}
1039     /**
1040      * @return resource
1041      */
1042     public function getStream() {}
1043 }
1044
1045 namespace ion\Serializer;
1046
1047 /**
1048  * Specialization of the serializer for PHP.
1049  */
1050 class PHP implements \ion\Serializer {
1051     /**
1052      * Create a new PHP ION serializer.
1053      */
1054     public function __construct(
1055         /**
1056          * Writer options.
1057          */
1058         public readonly \ion\Writer\Options|array|null $writerOptions = null,
1059         /**
1060          * Whether to write the top level array as multiple ION sequences.
1061          */
1062         public readonly bool $multiSequence = false,
1063         /**
1064          * Whether to call magic __serialize() methods on objects to serialize.
1065          */
1066         public readonly bool $callMagicSerialize = true,
1067         /**
1068          * Whether and which custom serialize method to call on objects to serialize.
1069          */
1070         public readonly ?string $callCustomSerialize = null,
1071     ) {}
1072
1073     public function serialize(mixed $data) : string {}
1074 }
1075
1076 namespace ion\Unserializer;
1077
1078 /**
1079  * Specialization of the unserializer for PHP.
1080  */
1081 class PHP implements \ion\Unserializer {
1082     /**
1083      * Create a new ION PHP unserializer.
1084      */
1085     public function __construct(
1086         /**
1087          * Reader options.
1088          */
1089         public readonly \ion\Reader\Options|array|null $readerOptions = null,
1090         /**
1091          * Whether to continue reading multiple ION sequences after the first one.
1092          */
1093         public readonly bool $multiSequence = false,
1094         /**
1095          * Whether to call magic __unserialize() methods on objects to unserialize.
1096          */
1097         public readonly bool $callMagicUnserialize = true,
1098         /**
1099          * Whether and which custom unserialize method to call on objects to unserialize.
1100          */
1101         public readonly ?string $callCustomUnserialize = null,
1102     ){}
1103
1104     /** @param string|resource $data */
1105     public function unserialize($data) : mixed {}
1106 }