ce45c76b215cbb6cc20c682a0325b50f9f149536
[awesomized/ext-ion] / docs / v0.2 / ion / : Tutorial / :2. What is ion.html
1 <!doctype html>
2 <html>
3 <head>
4 <meta charset="utf-8">
5 <title>
62. What is ion -
7 mdref
8 </title>
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.2/">
12 <meta http-equiv="Content-Location" content="/ext-ion/v0.2/ion/: Tutorial/:2. What is ion">
13 <link rel="stylesheet" href="index.css">
14
15 <link rel="shortcut icon" href="/ext-ion/v0.2/favicon.ico">
16 </head>
17 <body>
18 <div class="page">
19
20 <div class="sidebar">
21
22 <div class="edit">
23 <a href="https://github.com/awesomized/ext-ion/edit/master/ion.stub.php">Edit</a>
24 </div>
25
26
27 <ul>
28 <li>&lsh; <a href="./">Home</a>
29
30 <ul>
31 <li>
32
33 &uarr; <a href="./ion">
34 ion
35 </a>
36 <ul>
37 <li>
38
39 &uarr; <a href="./ion/: Tutorial">
40 ★ Tutorial
41 </a>
42 <ul>
43 <li>
44
45 &circlearrowright; <strong><a href="./ion/: Tutorial/:2. What is ion">2. What is ion</a></strong>
46
47
48
49 </ul>
50
51 <li>&ldsh; <a href="./ion/: Tutorial/:1. Getting started">1. Getting started</a></li>
52
53 <li>&ldsh; <a href="./ion/: Tutorial/:3. Standard Datatypes">3. Standard Datatypes</a></li>
54
55 <li>&ldsh; <a href="./ion/: Tutorial/:4. Special Datatypes">4. Special Datatypes</a></li>
56
57 <li>&ldsh; <a href="./ion/: Tutorial/:5. Symbols, Tables and Catalogs">5. Symbols, Tables and Catalogs</a></li>
58
59 </ul>
60
61 </li>
62 </ul>
63
64 </li>
65 </ul>
66 </div>
67 <meta charset="utf-8"><h1>
68 <a class="permalink" href="ion/:%20Tutorial/:2.%20What%20is%20ion#">#</a>What Is Ion?</h1><!--
69 <?php
70 if (!function_exists("var_representation")) {
71 function var_representation($v) {
72 return print_r($v,true);
73 }
74 }
75 ?>
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">&lt;?=<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">=&gt; </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">=&gt; [<br>    </span><span style="color: inherit" class="string">"data" </span><span style="color: inherit" class="keyword">=&gt; </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">?&gt;<br></span>
80 </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">&lt;?=<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">=&gt; </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">=&gt; [<br>    </span><span style="color: inherit" class="string">"data" </span><span style="color: inherit" class="keyword">=&gt; </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">?&gt;<br></span>
86 </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">&lt;?=<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">?&gt;<br></span>
93 </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' =&gt; 'value',<br>  'more' =&gt; [<br>    'data' =&gt; 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">&lt;?=<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">?&gt;<br></span>
99 </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' =&gt; 'value',<br>  'more' =&gt; [<br>    'data' =&gt; 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">&lt;?=<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">?&gt;<br></span>
106 </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' =&gt; 'value',<br>    'more' =&gt; [<br>      'data' =&gt; 123,<br>    ],<br>  ],<br>  [<br>    'key' =&gt; 'value',<br>    'more' =&gt; [<br>      'data' =&gt; 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">&lt;?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:: =&gt; %s\n"</span><span style="color: inherit" class="keyword"></span><span style="color: inherit" class="default">$e</span><span style="color: inherit" class="keyword">-&gt;</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">-&gt;</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:: =&gt; Ion<br>                      $ion_1_0:: =&gt; Ivm_1_0<br>             $ion_symbol_table:: =&gt; IonSymbolTable<br>                          name:: =&gt; Name<br>                       version:: =&gt; Version<br>                       imports:: =&gt; Imports<br>                       symbols:: =&gt; Symbols<br>                        max_id:: =&gt; MaxId<br>      $ion_shared_symbol_table:: =&gt; SharedSymbolTable<br>*/<br><br></span><span style="color: inherit" class="default">?&gt;<br></span>
121 </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">&lt;?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:: =&gt; %s\n"</span><span style="color: inherit" class="keyword"></span><span style="color: inherit" class="default">$e</span><span style="color: inherit" class="keyword">-&gt;</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">-&gt;</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:: =&gt; PHP<br>    R:: =&gt; Reference<br>    r:: =&gt; Backref<br>    p:: =&gt; Property<br>    o:: =&gt; Object<br>    c:: =&gt; ClassObject<br>    O:: =&gt; MagicObject<br>    C:: =&gt; CustomObject<br>    E:: =&gt; Enum<br>    S:: =&gt; Serializable<br>*/<br><br></span><span style="color: inherit" class="default">?&gt;<br></span>
125 </span>
126 </code></pre><hr><h2 id="Next.up">Next up<a class="permalink" href="ion/:%20Tutorial/:2.%20What%20is%20ion#Next.up">#</a>
127 </h2><ul>
128 <li>
129 <a href="ion/:%20Tutorial/:3.%20Standard%20Datatypes">Standard Datatypes</a>
130 </li>
131 </ul>
132 <div class="comments">
133 <style>.giscus-frame {min-height: 16em;}</style>
134 <script>
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');
146
147 script.src = "//giscus.app/client.js";
148 button.parentNode.replaceChild(script, button);
149 }
150 </script>
151 <button class="activator" onclick="giscus_load(this)">Show Comments from Github Discussions</button>
152
153 </div>
154
155 <footer>
156
157 <ul>
158 <li><a href="https://github.com/m6w6/mdref">mdref-v3.0
159 </a></li>
160 <li><a href="LICENSE">&copy; 2013-2022 All rights reserved.</a></li>
161 <li>
162 </li>
163 </ul>
164
165 </footer>
166
167 <script src="index.js" defer></script>
168
169 </div>
170 </body>
171 </html>