Merge pull request #80 from maxonfjvipon/bug/#79/update-xmir-tutorial

bug(#79): update XMIR tutorial

Author: yegor256

_posts/2022/11/2022-11-25-xmir-guide.md

@@ -5,9 +5,11 @@ title: "XMIR, a Quick Tour"
 author: yegor256
 ---
 
+_Last updated at: 17.04.2025_
+
 XMIR is a dialect of [XML](https://en.wikipedia.org/wiki/XML),
 which we use to represent a parsed
-[EO](https://www.eolang.org) program. It is a pretty simple format,
+[EO](https://www.eolang.org) object. It is a pretty simple format,
 which has a few
 important tricks, which I share below in this blog post. You may
 also want to check our [schema](https://en.wikipedia.org/wiki/XML_schema):
@@ -17,9 +19,10 @@ which may be more readable for some of you).
 
 <!--more-->
 
-Consider this simple EO program that prints `"Hello, world!"`:
+Consider this simple EO object that prints `"Hello, world!"`:
 
 ```
+# App.
 [] > app
   [x] > foo
     QQ.io.stdout > @
@@ -34,113 +37,119 @@ If we parse it using `EoSyntax` class from [eo-parser],
 we will get this XMIR (or very similar):
 
 ```xml
-<program xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- dob="2024-12-27T11:00:08" ms="98" name="app" revision="27abe8b"
- source="app.eo" time="2025-01-13T09:32:04.455112Z" version="0.50.0"
- xsi:noNamespaceSchemaLocation="https://www.eolang.org/xsd/XMIR-0.50.0.xsd">
- <listing># Simple app.
+<object 
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ dob="2024-12-27T11:00:08" 
+ ms="98" 
+ revision="27abe8b"
+ time="2025-04-17T09:32:04.455112Z" 
+ version="0.56.0"
+ xsi:noNamespaceSchemaLocation="https://www.eolang.org/xsd/XMIR-0.56.0.xsd">
+ <listing># App.
 [] &gt; app
   [x] &gt; foo
     QQ.io.stdout &gt; @
-      QQ.txt.sprintf
+      QQ.txt.sprintf *1
         "Hello, %s\n"
-        * x
+        x
   foo &gt; @
     "world!"
 </listing>
-  <objects>
-    <o line="2" name="app" pos="0">
-      <o line="3" name="foo" pos="2">
-        <o base="∅" line="3" name="x" pos="3"/>
-        <o base=".stdout" line="4" name="@" pos="9">
-          <o base=".io" line="4" pos="6">
-            <o base="QQ" line="4" pos="4"/>
+  <o line="2" name="app" pos="0">
+    <o line="3" name="foo" pos="2">
+      <o base="∅" line="3" name="x" pos="3"/>
+      <o base=".stdout" line="4" name="@" pos="9">
+        <o base=".io" line="4" pos="6">
+          <o base="QQ" line="4" pos="4"/>
+        </o>
+        <o base=".sprintf" line="5" pos="12">
+          <o base=".txt" line="5" pos="8">
+            <o base="QQ" line="5" pos="6"/>
           </o>
-          <o base=".sprintf" line="5" pos="12">
-            <o base=".txt" line="5" pos="8">
-              <o base="QQ" line="5" pos="6"/>
-            </o>
-            <o base="string" line="6" pos="8">48-65-6C-6C-6F-2C-20-25-73-0A</o>
-            <o base="tuple" line="7" pos="8">
-              <o base=".empty">
-                <o base="tuple"/>
-              </o>
-              <o base="x" line="7" pos="10"/>
+          <o base="string" line="6" pos="8">48-65-6C-6C-6F-2C-20-25-73-0A</o>
+          <o base="tuple" line="7" pos="8">
+            <o base=".empty">
+              <o base="tuple"/>
             </o>
+            <o base="x" line="7" pos="10"/>
           </o>
         </o>
       </o>
-      <o base="foo" line="8" name="@" pos="2">
-        <o base="string" line="9" pos="4">77-6F-72-6C-64-21</o>
-      </o>
     </o>
-  </objects>
-</program>
+    <o base="foo" line="8" name="@" pos="2">
+      <o base="string" line="9" pos="4">77-6F-72-6C-64-21</o>
+    </o>
+  </o>
+</object>
 ```
 
-The `<program>` is the root element, it will always be there, with
+The `<object>` is the root element, it will always be there, with
 a few mandatory attributes:
 
-* `ms` is how much time in milliseconds it took to parse the program
+* `ms` is how much time in milliseconds it took to parse the object
 and generate this XMIR file,
-* `name` is the name of the program, as it was given to the parser,
 * `time` is the time in [ISO 8601] format when the file was generated,
 * `version` is the version of the parser.
 
-The `<listing>` element contains the source code of the EO program,
-which was parsed, without any modifiations, "as is."
+The `<listing>` element contains the source code of the EO object,
+which was parsed, without any modifications, "as is."
 
 ## Errors and Warnings
 
 The `<errors>` element may have a list of problems discovered by the
-parser or any other optimizers, as `<error>` elements.
+parser or any other optimizers, as `<error>` elements. If there are no
+errors, the `<errors>` element should not exist in `<object>`.
 For example, it may look like this:
 
 ```xml
-<program>
-  [..]
+<object>
+  [...]
   <errors>
     <error severity="warning" line="3">There is an extra bracket</error>
     <error severity="error" line="12">The object 'x' is not found</error>
+    [...]
   </errors>
-</program>
+</object>
 ```
 
 The errors with the `warning` severity may more or less safely be ignored. The
-  errors with the `error` severity will lead to failures in further compilation
-  and processing. There could also be elements with the `critical` severity,
-  which must stop the processing of the document immediately.
+errors with the `error` severity will lead to failures in further compilation
+and processing. There could also be elements with the `critical` severity,
+which must stop the processing of the document immediately.
 
 ## Sheets
 
-The `<sheets>` element will rarely be empty. It contains a list of all
-  post-processors that were applied to the document after is parsing.
-  We process our XMIR documents using dozens of XSL stylesheets. That's why
-  the name of the XML element. You may find something like this over there:
+The `<sheets>` element contains a list of all
+post-processors that were applied to the document after is parsing.
+We process our XMIR documents using dozens of XSL stylesheets. That's why
+the name of the XML element. You may find something like this over there:
 
 ```xml
-<program>
-  [..]
+<object>
+  [...]
   <sheets>
-    <sheet>not-empty-atoms</sheet>
-    <sheet>middle-varargs</sheet>
-    <sheet>duplicate-names</sheet>
-    <sheet>many-free-attributes</sheet>
+    <sheet>move-voids-up</sheet>
+    <sheet>const-to-dataized</sheet>
+    <sheet>stars-to-tuples</sheet>
+    <sheet>wrap-method-calls</sheet>
     [...]
   </sheets>
-</program>
+</object>
 ```
 
 The names you see in the `<sheet>` elements are the names of the files.
-  For example, `not-empty-atoms` represents the
-  [`not-empty-atoms.xsl`] file
-  in the [objectionary/eo](https://github.com/objectionary/eo) GitHub repository.
+For example, `wrap-method-calls` represents the
+[`wrap-method-calls.xsl`] file
+in the [objectionary/eo](https://github.com/objectionary/eo) GitHub repository.
+
+If no XSL stylesheets are applied to XMIR, the `<sheets>` element should not exist
+in `<object>`.
 
 ## Metas
 
 There may be an optional element `<metas>` with a list of `<meta>` elements.
-  For example, if my source code would have this meta at the 3rd
-  line of the source file:
+For example, if my source code would have this meta at the 3rd
+line of the source file:
 
 ```
 +alias foo com.example.foo
@@ -149,77 +158,89 @@ There may be an optional element `<metas>` with a list of `<meta>` elements.
 We would see the following in the XMIR:
 
 ```xml
-<program>
-  [..]
-   <metas>
+<object>
+  [...]
+  <metas>
     <meta line="3">
       <head>alias</head>
-      <tail>foo com.example.foo</tail>
+      <tail>foo Q.com.example.foo</tail>
       <part>foo</part>
-      <part>com.example.foo</part>
+      <part>Q.com.example.foo</part>
     </meta>
-    [..]
+    [...]
   </metas>
-</program>
+</object>
 ```
 
 Each `<meta>` element contains parts of the meta. The `<head>`
-  contains everything that goes after the `+` until the first space.
-  The `<tail>` contains everything after the first space. There could
-  be a number of `<part>` elements, each of which containing the parts
-  of the `<tail>` separated by spaces.
+contains everything that goes after the `+` until the first space.
+The `<tail>` contains everything after the first space. There could
+be a number of `<part>` elements, each of which containing the parts
+of the `<tail>` separated by spaces.
 
 ## Objects
 
-The `<objects/>` element contains object, as they were found in the source
-  code, where each object is represented by the `<o/>` element.
-  Each `<o/>` element may have a few optional attributes:
+The `<object>` element must contain only one `<o/>` element which represents an 
+object being parsed. The `<o/>` element may have a few optional attributes:
 
 * `line` and `pos` are the number of the line where the object
 was found by the parser and the position in the line;
 * `name` is the name of the object, if the object has it;
 * `base` may refer to object formation that is being copied;
-* `loc` may contain a "locator" of the object.
+* `as` is the name of the attribute which current object is bound to during the
+application
 
 There could be no other attributes.
 
-## Data Objects
-
-Data literals found in the source code are presented with `<o/>` XML elements
-  that contain text, for example:
+## Special cases
 
+1. The `<o/>` elements that have nested `<o>` element with `name` which 
+value is `λ` are **atoms**. Atoms must not have `base` attribute:
 ```xml
-<o base="string" line="6" pos="8">48-65-6C-6C-6F-2C-20-25-73-0A</o>
+<o name="try">
+  <o name="λ"/>
+</o>
 ```
 
-The value of the `base` attribute is the "type" of the data found in the
-sources. It may be one of the following three:
-`string`, `number`, and `bytes`.
-
-## Locators
-
-If you apply [`set-locators.xsl`] optimization XSL stylesheet to the following
-XMIR document:
-
+2. The `<o/>` elements with `base` attribute which value is `∅` are **void** attributes.
+Void attributes also must have `name` attribute:
 ```xml
-<o base=".times" name="x">
-  <o base="a"/>
-  <o base="b"/>
+<o name="foo">
+  <o name="bar" base="∅"/>
 </o>
 ```
 
-You will get additional attribute `loc` added to each `<o>` element:
+3. **Data literals** found in the source code are presented with nested `<o/>` XML elements
+that contain text. Only elements with `base` attribute equal to `Q.org.eolang.bytes` may contain
+nested `<o>` element with text.
 
 ```xml
-```xml
-<o base=".times" name="x" loc="Φ.x">
-  <o base="a" loc="Φ.x.ρ"/>
-  <o base="b" loc="Φ.x.α0"/>
+<o base="Q.org.eolang.bytes" line="6" pos="8">
+  <o>48-65-6C-6C-6F-2C-20-25-73-0A</o>
 </o>
 ```
 
-Locators are absolute and unique coordinates of any object
-in the entire object "Universe."
+4. The `name` attribute of `<o/>` element may be **auto generated** by EO parser. 
+In such case it's look like:
+```xml
+<o name="a🌵104"/>
+```
+
+Such `name` consists of several parts:
+- char `a` (ascii 97) that stands for "auto-generated"
+- char `🌵` that is just a pretty character prohibited by EO grammar
+- number `104` which is joined line and position of the place where 
+the object is found.
+
+Such names are unique through entire XMIR.
+
+5. If object is bound to a specific attribute not by name but by position, the
+`as` attribute may look like:
+```xml
+<o base="Q.org.eolang.number" as="α2"/>
+```
+Here the first character is `α` (alpha), the number `2` is the position of the 
+attribute.
 
 <hr/>