git.m6w6.name Git - awesomized/ext-ion/blob - docs/v0.1/ion/: Tutorial/:2. What is ion.html

   1 <!doctype html>
   2 <html>
   3         <head>
   4                 <meta charset="utf-8">
   5                 <title>
   6                                                         ★2. 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.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">
  14
  15                 <link rel="shortcut icon" href="/ext-ion/v0.1/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><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>
  69 </h3><h4 id="Serialization:">Serialization:<a class="permalink" href="ion/:%20Tutorial/:2.%20What%20is%20ion#Serialization:">#</a>
  70 </h4><pre><code><span style="color: inherit" class="html">
  71 <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>
  72 </span>
  73 </code></pre><h5 id="Output:">Output:<a class="permalink" href="ion/:%20Tutorial/:2.%20What%20is%20ion#Output:">#</a>
  74 </h5><pre><code><span style="color: inherit" class="html">
  75 {key:"value",more:{data:123}}<br></span>
  76 </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">
  77 <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>
  78 </span>
  79 </code></pre><h5 id="Output:">Output:<a class="permalink" href="ion/:%20Tutorial/:2.%20What%20is%20ion#Output:">#</a>
  80 </h5><pre><code><span style="color: inherit" class="html">
  81 {"key":"value","more":{"data":123}}<br></span>
  82 </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>
  83 </h4><pre><code><span style="color: inherit" class="html">
  84 <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>
  85 </span>
  86 </code></pre><h5 id="Output:">Output:<a class="permalink" href="ion/:%20Tutorial/:2.%20What%20is%20ion#Output:">#</a>
  87 </h5><pre><code><span style="color: inherit" class="html">
  88 [<br>  'key' =&gt; 'value',<br>  'more' =&gt; [<br>    'data' =&gt; 123,<br>  ],<br>]<br></span>
  89 </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">
  90 <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>
  91 </span>
  92 </code></pre><h5 id="Output:">Output:<a class="permalink" href="ion/:%20Tutorial/:2.%20What%20is%20ion#Output:">#</a>
  93 </h5><pre><code><span style="color: inherit" class="html">
  94 [<br>  'key' =&gt; 'value',<br>  'more' =&gt; [<br>    'data' =&gt; 123,<br>  ],<br>]<br></span>
  95 </code></pre><h3 id="Multiple.documents">Multiple documents<a class="permalink" href="ion/:%20Tutorial/:2.%20What%20is%20ion#Multiple.documents">#</a>
  96 </h3><p>Ion supports multiple sequences of documents within a single stream; consider the following:</p><pre><code><span style="color: inherit" class="html">
  97 <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\PHP</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>
  98 </span>
  99 </code></pre><h4 id="Output:">Output:<a class="permalink" href="ion/:%20Tutorial/:2.%20What%20is%20ion#Output:">#</a>
 100 </h4><pre><code><span style="color: inherit" class="html">
 101 [<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>
 102 </code></pre><h3 id="Annotations">Annotations<a class="permalink" href="ion/:%20Tutorial/:2.%20What%20is%20ion#Annotations">#</a>
 103 </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>
 104 <li>Annotate individual values with schema types, for validation purposes.</li>
 105 <li>Associate a higher-level datatype (e.g. a Java <em>class</em>) during serialization processes.</li>
 106 <li>Indicate the notation used within a <code>blob</code> or <code>clob</code> value.</li>
 107 <li>Apply other application semantics to a single value.</li>
 108 </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">
 109 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>
 110 </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>
 111 </h4><pre><code><span style="color: inherit" class="html">
 112 <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>
 113 </span>
 114 </code></pre><h4 id="PHP.Annotations">PHP Annotations<a class="permalink" href="ion/:%20Tutorial/:2.%20What%20is%20ion#PHP.Annotations">#</a>
 115 </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">
 116 <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>
 117 </span>
 118 </code></pre><hr><h2 id="Next.up">Next up<a class="permalink" href="ion/:%20Tutorial/:2.%20What%20is%20ion#Next.up">#</a>
 119 </h2><ul>
 120 <li>
 121 <a href="ion/:%20Tutorial/:3.%20Standard%20Datatypes">Standard Datatypes</a>
 122 </li>
 123 </ul>
 124                         <div class="comments">
 125                                                                                 <style>.giscus-frame {min-height: 16em;}</style>
 126         <script>
 127                 function giscus_load(button) {
 128                         let script = document.createElement("script");
 129                                                 script.setAttribute("data-repo", 'awesomized/ext-ion');
 130                                                 script.setAttribute("data-category", 'Comments on Docs');
 131                                                 script.setAttribute("data-repo-id", 'R_kgDOGfXEXw');
 132                                                 script.setAttribute("data-category-id", 'DIC_kwDOGfXEX84CBHuf');
 133                                                 script.setAttribute("data-mapping", 'og:title');
 134                                                 script.setAttribute("data-input-position", 'bottom');
 135                                                 script.setAttribute("data-reactions-enabled", false);
 136                                                 script.setAttribute("data-theme", 'light');
 137                                                 script.setAttribute("data-lang", 'en');
 138
 139                         script.src = "//giscus.app/client.js";
 140                         button.parentNode.replaceChild(script, button);
 141                 }
 142         </script>
 143         <button class="activator" onclick="giscus_load(this)">Show Comments from Github Discussions</button>
 144
 145                         </div>
 146
 147                         <footer>
 148
 149 <ul>
 150         <li><a href="https://github.com/m6w6/mdref">mdref-v3.0
 151 </a></li>
 152         <li><a href="LICENSE">&copy; 2013-2022          All rights reserved.</a></li>
 153         <li>
 154 </li>
 155 </ul>
 156
 157                         </footer>
 158
 159                         <script src="index.js" defer></script>
 160
 161                 </div>
 162         </body>
 163 </html>