9 <meta property=
"og:title" content=
"ion/: Tutorial/:2. What is ion">
10 <meta name=
"viewport" content=
"width=1200, initial-scale=0.5">
11 <base href=
"/ext-ion/v0.1/">
12 <meta http-equiv=
"Content-Location" content=
"/ext-ion/v0.1/ion/: Tutorial/:2. What is ion">
13 <link rel=
"stylesheet" href=
"index.css">
15 <link rel=
"shortcut icon" href=
"/ext-ion/v0.1/favicon.ico">
23 <a href=
"https://github.com/awesomized/ext-ion/edit/master/ion.stub.php">Edit
</a>
28 <li>↰ <a href=
"./">Home
</a>
33 ↑ <a href=
"./ion">
39 ↑ <a href=
"./ion/: Tutorial">
45 ↻ <strong><a href=
"./ion/: Tutorial/:2. What is ion">★
2. What is ion
</a></strong>
51 <li>↲ <a href=
"./ion/: Tutorial/:1. Getting started">★
1. Getting started
</a></li>
53 <li>↲ <a href=
"./ion/: Tutorial/:3. Standard Datatypes">★
3. Standard Datatypes
</a></li>
55 <li>↲ <a href=
"./ion/: Tutorial/:4. Special Datatypes">★
4. Special Datatypes
</a></li>
57 <li>↲ <a href=
"./ion/: Tutorial/:5. Symbols, Tables and Catalogs">★
5. Symbols, Tables and Catalogs
</a></li>
67 <meta charset=
"utf-8"><h1>
68 <a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#">#
</a>What Is Ion?
</h1><!--
70 if (!function_exists("var_representation")) {
71 function var_representation($v) {
72 return print_r($v,true);
76 --><p>Quoting the
<a href=
"https://amzn.github.io/ion-docs/">official Ion documentation
</a>:
</p><p><strong>Amazon Ion
</strong> is a
<a href=
"ion/:%20Tutorial/:1.%20Getting%20started#Rich.type.system">richly-typed
</a>,
<a href=
"ion/:%20Tutorial/:1.%20Getting%20started#Self-describing">self-describing
</a>, hierarchical data serialization format offering
<a href=
"https://amzn.github.io/ion-docs/guides/why.html#dual-format-interoperability">interchangeable binary and text
</a> representations. The
<a href=
"https://amzn.github.io/ion-docs/docs/spec.html">text format
</a> (a superset of
<a href=
"http://json.org/">JSON
</a>) is easy to read and author, supporting rapid prototyping.
</p><p>The
<a href=
"https://amzn.github.io/ion-docs/docs/binary.html">binary representation
</a> is
<a href=
"https://amzn.github.io/ion-docs/guides/why.html#read-optimized-binary-format">efficient to store, transmit, and skip-scan parse
</a>.
</p><p>The rich type system provides unambiguous semantics for longterm preservation of data which can survive multiple generations of software evolution.
</p><p>Ion was built to address rapid development, decoupling, and efficiency challenges faced every day while engineering large-scale, service-oriented architectures.
</p><h3 id=
"Some.simple.examples">Some simple examples
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#Some.simple.examples">#
</a>
77 </h3><h4 id=
"Serialization:">Serialization:
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#Serialization:">#
</a>
78 </h4><pre><code><span style=
"color: inherit" class=
"html">
79 <span style=
"color: inherit" class=
"default"><?=
<br>ion\serialize
</span><span style=
"color: inherit" class=
"keyword">([
<br> </span><span style=
"color: inherit" class=
"string">"key" </span><span style=
"color: inherit" class=
"keyword">=
> </span><span style=
"color: inherit" class=
"string">"value"</span><span style=
"color: inherit" class=
"keyword">,
<br> </span><span style=
"color: inherit" class=
"string">"more" </span><span style=
"color: inherit" class=
"keyword">=
> [
<br> </span><span style=
"color: inherit" class=
"string">"data" </span><span style=
"color: inherit" class=
"keyword">=
> </span><span style=
"color: inherit" class=
"default">123<br> </span><span style=
"color: inherit" class=
"keyword">]
<br>]);
<br></span><span style=
"color: inherit" class=
"default">?
><br></span>
81 </code></pre><h5 id=
"Output:">Output:
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#Output:">#
</a>
82 </h5><pre><code><span style=
"color: inherit" class=
"html">
83 {key:
"value",more:{data:
123}}
<br></span>
84 </code></pre><p>If you now think that this looks a lot like JSON, you're probably right, because Ion is a superset of JSON:
</p><pre><code><span style=
"color: inherit" class=
"html">
85 <span style=
"color: inherit" class=
"default"><?=
<br>json_encode
</span><span style=
"color: inherit" class=
"keyword">([
<br> </span><span style=
"color: inherit" class=
"string">"key" </span><span style=
"color: inherit" class=
"keyword">=
> </span><span style=
"color: inherit" class=
"string">"value"</span><span style=
"color: inherit" class=
"keyword">,
<br> </span><span style=
"color: inherit" class=
"string">"more" </span><span style=
"color: inherit" class=
"keyword">=
> [
<br> </span><span style=
"color: inherit" class=
"string">"data" </span><span style=
"color: inherit" class=
"keyword">=
> </span><span style=
"color: inherit" class=
"default">123<br> </span><span style=
"color: inherit" class=
"keyword">]
<br>]);
<br></span><span style=
"color: inherit" class=
"default">?
><br></span>
87 </code></pre><h5 id=
"Output:">Output:
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#Output:">#
</a>
88 </h5><pre><code><span style=
"color: inherit" class=
"html">
89 {
"key":
"value",
"more":{
"data":
123}}
<br></span>
90 </code></pre><p>So, all valid JSON is also valid Ion. Please refer to the
<a href=
"https://amzn.github.io/ion-docs/docs/spec.html">official spec
</a> to learn more about this topic.
</p><h4 id=
"Unserialization:">Unserialization:
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#Unserialization:">#
</a>
91 </h4><pre><code><span style=
"color: inherit" class=
"html">
92 <span style=
"color: inherit" class=
"default"><?=
<br>var_representation
</span><span style=
"color: inherit" class=
"keyword">(
<br> </span><span style=
"color: inherit" class=
"default">ion\unserialize
</span><span style=
"color: inherit" class=
"keyword">(
</span><span style=
"color: inherit" class=
"string">'{key:
"value",more:{data:
123}}'
</span><span style=
"color: inherit" class=
"keyword">)
<br>);
<br></span><span style=
"color: inherit" class=
"default">?
><br></span>
94 </code></pre><h5 id=
"Output:">Output:
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#Output:">#
</a>
95 </h5><pre><code><span style=
"color: inherit" class=
"html">
96 [
<br> 'key' =
> 'value',
<br> 'more' =
> [
<br> 'data' =
> 123,
<br> ],
<br>]
<br></span>
97 </code></pre><p>If you try the same with the JSON equivalent, you'll see that it's basically valid Ion, too:
</p><pre><code><span style=
"color: inherit" class=
"html">
98 <span style=
"color: inherit" class=
"default"><?=
<br>var_representation
</span><span style=
"color: inherit" class=
"keyword">(
<br> </span><span style=
"color: inherit" class=
"default">ion\unserialize
</span><span style=
"color: inherit" class=
"keyword">(
</span><span style=
"color: inherit" class=
"string">'{
"key":
"value",
"more":{
"data":
123}}'
</span><span style=
"color: inherit" class=
"keyword">)
<br>);
<br></span><span style=
"color: inherit" class=
"default">?
><br></span>
100 </code></pre><h5 id=
"Output:">Output:
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#Output:">#
</a>
101 </h5><pre><code><span style=
"color: inherit" class=
"html">
102 [
<br> 'key' =
> 'value',
<br> 'more' =
> [
<br> 'data' =
> 123,
<br> ],
<br>]
<br></span>
103 </code></pre><h3 id=
"Multiple.documents">Multiple documents
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#Multiple.documents">#
</a>
104 </h3><p>Ion supports multiple sequences of documents within a single stream; consider the following:
</p><pre><code><span style=
"color: inherit" class=
"html">
105 <span style=
"color: inherit" class=
"default"><?=
<br>var_representation
</span><span style=
"color: inherit" class=
"keyword">(
<br> </span><span style=
"color: inherit" class=
"default">ion\unserialize
</span><span style=
"color: inherit" class=
"keyword">(
</span><span style=
"color: inherit" class=
"string">'
<br> {
"key":
"value",
"more":{
"data":
123}}
<br> {
"key":
"value",
"more":{
"data":
456}}
<br> '
</span><span style=
"color: inherit" class=
"keyword">, new
</span><span style=
"color: inherit" class=
"default">ion\Unserializer\Unserializer
</span><span style=
"color: inherit" class=
"keyword">(
</span><span style=
"color: inherit" class=
"default">multiSequence
</span><span style=
"color: inherit" class=
"keyword">:
</span><span style=
"color: inherit" class=
"default">true
</span><span style=
"color: inherit" class=
"keyword">)
<br> )
<br>);
<br></span><span style=
"color: inherit" class=
"default">?
><br></span>
107 </code></pre><h4 id=
"Output:">Output:
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#Output:">#
</a>
108 </h4><pre><code><span style=
"color: inherit" class=
"html">
109 [
<br> [
<br> 'key' =
> 'value',
<br> 'more' =
> [
<br> 'data' =
> 123,
<br> ],
<br> ],
<br> [
<br> 'key' =
> 'value',
<br> 'more' =
> [
<br> 'data' =
> 456,
<br> ],
<br> ],
<br>]
<br></span>
110 </code></pre><h3 id=
"Annotations">Annotations
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#Annotations">#
</a>
111 </h3><p>Any Ion value can include one or more annotation symbols denoting the semantics of the content. This can be used to:
</p><ul>
112 <li>Annotate individual values with schema types, for validation purposes.
</li>
113 <li>Associate a higher-level datatype (e.g. a Java
<em>class
</em>) during serialization processes.
</li>
114 <li>Indicate the notation used within a
<code>blob
</code> or
<code>clob
</code> value.
</li>
115 <li>Apply other application semantics to a single value.
</li>
116 </ul><p>In the text format, type annotations are denoted by a non-
<code><a href=
"https://php.net/manual/en/language.types.null">null
</a></code> symbol token and
<code><a href=
"https://php.net/manual/en/language.types.float">double
</a></code>-colons preceding any value. Multiple annotations on the same value are separated by
<code><a href=
"https://php.net/manual/en/language.types.float">double
</a></code>-colons:
</p><pre><code><span style=
"color: inherit" class=
"html">
117 int32::
12 // Suggests
32 bits as end-user type
<br>degrees::'celsius'::
100 // You can have multiple annotaions on a value
<br>'my.custom.type' :: { x :
12 , y : -
1 } // Gives a struct a user-defined type
<br><br>{ field: some_annotation::value } // Field's name must precede annotations of its value
<br><br>jpeg :: {{ ... }} // Indicates the blob contains jpeg data
<br>bool :: null.int // A very misleading annotation on the integer null
<br>'' ::
1 // An empty annotation
<br>null.symbol ::
1 // ERROR: type annotation cannot be null
<br></span>
118 </code></pre><p>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).
</p><p>It’s important to understand that annotations are symbol
<em>tokens
</em>, not symbol
<em>values
</em>. That means they do not have annotations themselves. In particular, the text
<code>a::c
</code> is a single value consisting of three textual tokens (a symbol, a
<code><a href=
"https://php.net/manual/en/language.types.float">double
</a></code>-colon, and another symbol); the first symbol token is an
<em>annotation
</em> on the value, and the second is the
<em>content
</em> of the value.
</p><h4 id=
"System.Annotations">System Annotations
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#System.Annotations">#
</a>
119 </h4><pre><code><span style=
"color: inherit" class=
"html">
120 <span style=
"color: inherit" class=
"default"><?php
<br><br></span><span style=
"color: inherit" class=
"keyword">foreach (
</span><span style=
"color: inherit" class=
"default">ion\Symbol\System
</span><span style=
"color: inherit" class=
"keyword">::
</span><span style=
"color: inherit" class=
"default">cases
</span><span style=
"color: inherit" class=
"keyword">() as
</span><span style=
"color: inherit" class=
"default">$e
</span><span style=
"color: inherit" class=
"keyword">) {
<br> </span><span style=
"color: inherit" class=
"default">printf
</span><span style=
"color: inherit" class=
"keyword">(
</span><span style=
"color: inherit" class=
"string">"%30s:: => %s\n"</span><span style=
"color: inherit" class=
"keyword">,
</span><span style=
"color: inherit" class=
"default">$e
</span><span style=
"color: inherit" class=
"keyword">-
></span><span style=
"color: inherit" class=
"default">value
</span><span style=
"color: inherit" class=
"keyword">,
</span><span style=
"color: inherit" class=
"default">$e
</span><span style=
"color: inherit" class=
"keyword">-
></span><span style=
"color: inherit" class=
"default">name
</span><span style=
"color: inherit" class=
"keyword">);
<br>}
<br><br></span><span style=
"color: inherit" class=
"comment">/*
<br> $ion:: =
> Ion
<br> $ion_1_0:: =
> Ivm_1_0
<br> $ion_symbol_table:: =
> IonSymbolTable
<br> name:: =
> Name
<br> version:: =
> Version
<br> imports:: =
> Imports
<br> symbols:: =
> Symbols
<br> max_id:: =
> MaxId
<br> $ion_shared_symbol_table:: =
> SharedSymbolTable
<br>*/
<br><br></span><span style=
"color: inherit" class=
"default">?
><br></span>
122 </code></pre><h4 id=
"PHP.Annotations">PHP Annotations
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#PHP.Annotations">#
</a>
123 </h4><p>There are two handful of annotations used by PHP, which are centralized in the
<a href=
"ion/Symbol/PHP">ion\Symbol\PHP
</a> enumeration:
</p><pre><code><span style=
"color: inherit" class=
"html">
124 <span style=
"color: inherit" class=
"default"><?php
<br><br></span><span style=
"color: inherit" class=
"keyword">foreach (
</span><span style=
"color: inherit" class=
"default">ion\Symbol\PHP
</span><span style=
"color: inherit" class=
"keyword">::
</span><span style=
"color: inherit" class=
"default">cases
</span><span style=
"color: inherit" class=
"keyword">() as
</span><span style=
"color: inherit" class=
"default">$e
</span><span style=
"color: inherit" class=
"keyword">) {
<br> </span><span style=
"color: inherit" class=
"default">printf
</span><span style=
"color: inherit" class=
"keyword">(
</span><span style=
"color: inherit" class=
"string">"%3s:: => %s\n"</span><span style=
"color: inherit" class=
"keyword">,
</span><span style=
"color: inherit" class=
"default">$e
</span><span style=
"color: inherit" class=
"keyword">-
></span><span style=
"color: inherit" class=
"default">value
</span><span style=
"color: inherit" class=
"keyword">,
</span><span style=
"color: inherit" class=
"default">$e
</span><span style=
"color: inherit" class=
"keyword">-
></span><span style=
"color: inherit" class=
"default">name
</span><span style=
"color: inherit" class=
"keyword">);
<br>}
<br><br></span><span style=
"color: inherit" class=
"comment">/*
<br> PHP:: =
> PHP
<br> R:: =
> Reference
<br> r:: =
> Backref
<br> p:: =
> Property
<br> o:: =
> Object
<br> c:: =
> ClassObject
<br> O:: =
> MagicObject
<br> C:: =
> CustomObject
<br> E:: =
> Enum
<br> S:: =
> Serializable
<br>*/
<br><br></span><span style=
"color: inherit" class=
"default">?
><br></span>
126 </code></pre><hr><h2 id=
"Next.up">Next up
<a class=
"permalink" href=
"ion/:%20Tutorial/:2.%20What%20is%20ion#Next.up">#
</a>
129 <a href=
"ion/:%20Tutorial/:3.%20Standard%20Datatypes">Standard Datatypes
</a>
132 <div class=
"comments">
133 <style>.giscus-frame {min-height:
16em;}
</style>
135 function giscus_load(button) {
136 let script = document.createElement(
"script");
137 script.setAttribute(
"data-repo", 'awesomized/ext-ion');
138 script.setAttribute(
"data-category", 'Comments on Docs');
139 script.setAttribute(
"data-repo-id", 'R_kgDOGfXEXw');
140 script.setAttribute(
"data-category-id", 'DIC_kwDOGfXEX84CBHuf');
141 script.setAttribute(
"data-mapping", 'og:title');
142 script.setAttribute(
"data-input-position", 'bottom');
143 script.setAttribute(
"data-reactions-enabled", false);
144 script.setAttribute(
"data-theme", 'light');
145 script.setAttribute(
"data-lang", 'en');
147 script.src =
"//giscus.app/client.js";
148 button.parentNode.replaceChild(script, button);
151 <button class=
"activator" onclick=
"giscus_load(this)">Show Comments from Github Discussions
</button>
158 <li><a href=
"https://github.com/m6w6/mdref">mdref-v3.0
160 <li><a href=
"LICENSE">© 2013-
2022 All rights reserved.
</a></li>
167 <script src=
"index.js" defer
></script>