refactor serde interfaces and impls

[awesomized/ext-ion] / docs / tutorial / : Tutorial / :2. What is ion.md

# What Is Ion?

<!--
<?php
if (!function_exists("var_representation")) { 
        function var_representation($v) {
                return print_r($v,true);
        }
}
?>
-->

Quoting the [official Ion documentation](https://amzn.github.io/ion-docs/):

**Amazon Ion** is a [richly-typed](ion/:%20Tutorial/:1.%20Getting%20started#Rich.type.system), [self-describing](ion/:%20Tutorial/:1.%20Getting%20started#Self-describing), hierarchical data serialization format offering [interchangeable binary and text](https://amzn.github.io/ion-docs/guides/why.html#dual-format-interoperability) representations. The [text format](https://amzn.github.io/ion-docs/docs/spec.html) (a superset of [JSON](http://json.org/)) is easy to read and author, supporting rapid prototyping. 

The [binary representation](https://amzn.github.io/ion-docs/docs/binary.html) is [efficient to store, transmit, and skip-scan parse](https://amzn.github.io/ion-docs/guides/why.html#read-optimized-binary-format). 

The rich type system provides unambiguous semantics for longterm preservation of data which can survive multiple generations of software evolution.

Ion was built to address rapid development, decoupling, and efficiency challenges faced every day while engineering large-scale, service-oriented architectures.

### Some simple examples

#### Serialization:

```php
<?=
ion\serialize([
  "key" => "value",
  "more" => [
    "data" => 123
  ]
]);
?>
```

##### Output:

```json
{key:"value",more:{data:123}}
```

If you now think that this looks a lot like JSON, you're probably right, because Ion is a superset of JSON:

```php
<?=
json_encode([
  "key" => "value",
  "more" => [
    "data" => 123
  ]
]);
?>
```

##### Output:

```json
{"key":"value","more":{"data":123}}
```

So, all valid JSON is also valid Ion. Please refer to the [official spec](https://amzn.github.io/ion-docs/docs/spec.html) to learn more about this topic.

#### Unserialization:

```php
<?=
var_representation(
  ion\unserialize('{key:"value",more:{data:123}}')
);
?>
```

##### Output:

```php
[
  'key' => 'value',
  'more' => [
    'data' => 123,
  ],
]
```

If you try the same with the JSON equivalent, you'll see that it's basically valid Ion, too:

```php
<?=
var_representation(
  ion\unserialize('{"key":"value","more":{"data":123}}')
);
?>
```

##### Output:

```php
[
  'key' => 'value',
  'more' => [
    'data' => 123,
  ],
]
```

### Multiple documents

Ion supports multiple sequences of documents within a single stream; consider the following:

```php
<?=
var_representation(
  ion\unserialize('
    {"key":"value","more":{"data":123}}
    {"key":"value","more":{"data":456}}
  ', new ion\Unserializer\Unserializer(multiSequence: true)
  )
);
?>
```

#### Output:

```php
[
  [
    'key' => 'value',
    'more' => [
      'data' => 123,
    ],
  ],
  [
    'key' => 'value',
    'more' => [
      'data' => 456,
    ],
  ],
]
```

### Annotations

Any Ion value can include one or more annotation symbols denoting the semantics of the content. This can be used to:

- Annotate individual values with schema types, for validation purposes.
- Associate a higher-level datatype (e.g. a Java class) during serialization processes.
- Indicate the notation used within a `blob` or `clob` value.
- Apply other application semantics to a single value.

In the text format, type annotations are denoted by a non-null symbol token and double-colons preceding any value. Multiple annotations on the same value are separated by double-colons:

```
int32::12                                // Suggests 32 bits as end-user type
degrees::'celsius'::100                  // You can have multiple annotaions on a value
'my.custom.type' :: { x : 12 , y : -1 }  // Gives a struct a user-defined type

{ field: some_annotation::value }        // Field's name must precede annotations of its value

jpeg :: {{ ... }}                        // Indicates the blob contains jpeg data
bool :: null.int                         // A very misleading annotation on the integer null
'' :: 1                                  // An empty annotation
null.symbol :: 1                         // ERROR: type annotation cannot be null 
```

Except for a small number of predefined system and PHP annotations, Ion itself neither defines nor validates such annotations; that behavior is left to applications or tools (such as schema validators).

It’s important to understand that annotations are symbol *tokens*, not symbol *values*. That means they do not have annotations themselves. In particular, the text `a::c` is a single value consisting of three textual tokens (a symbol, a double-colon, and another symbol); the first symbol token is an *annotation* on the value, and the second is the *content* of the value.

#### System Annotations

```php
<?php

foreach (ion\Symbol\System::cases() as $e) {
  printf("%30s:: => %s\n", $e->value, $e->name);
}

/*
                          $ion:: => Ion
                      $ion_1_0:: => Ivm_1_0
             $ion_symbol_table:: => IonSymbolTable
                          name:: => Name
                       version:: => Version
                       imports:: => Imports
                       symbols:: => Symbols
                        max_id:: => MaxId
      $ion_shared_symbol_table:: => SharedSymbolTable
*/

?>
```

#### PHP Annotations

There are two handful of annotations used by PHP, which are centralized in the ion\Symbol\PHP enumeration:

```php
<?php

foreach (ion\Symbol\PHP::cases() as $e) {
  printf("%3s:: => %s\n", $e->value, $e->name);
}

/*
  PHP:: => PHP
    R:: => Reference
    r:: => Backref
    p:: => Property
    o:: => Object
    c:: => ClassObject
    O:: => MagicObject
    C:: => CustomObject
    E:: => Enum
    S:: => Serializable
*/

?>
```

---

## Next up

* [Standard Datatypes](ion/:%20Tutorial/:3.%20Standard%20Datatypes)