[royale-docs] branch master updated: Finished XML page

[ha...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

harbs pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/royale-docs.git


The following commit(s) were added to refs/heads/master by this push:
     new 0f00253  Finished XML page
     new ff99c11  Merge branch 'master' of https://github.com/apache/royale-docs into master
0f00253 is described below

commit 0f00253ae913e03a7890ead7ec12157079bb2875
Author: Harbs <ha...@in-tools.com>
AuthorDate: Fri Jan 7 02:45:33 2022 +0200

    Finished XML page
---
 features/as3/xml.md | 50 +++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 45 insertions(+), 5 deletions(-)

diff --git a/features/as3/xml.md b/features/as3/xml.md
index 06a7c12..b79e536 100644
--- a/features/as3/xml.md
+++ b/features/as3/xml.md
@@ -24,15 +24,55 @@ permalink: /features/as3/xml
 
 XML in ActionScript 3
 
-*Warning: This document is a work-in-progress/undergoing review.*
-## XML: a first class citizen
+## XML: A first class citizen
 ActionScript has support for XML as a native type.
 
+## Some history
+In 2004 and 2005, [Ecma published ECMA-357](https://www.ecma-international.org/publications-and-standards/standards/ecma-357/) which was a spec for handling XML in Javascript. The spec was called E4X (Ecmascript for XML). This was adopted by Firefox (SpiderMonkey) and ActionScript. Unfortunately [it was not adopted by Chrome](https://bugs.chromium.org/p/v8/issues/detail?id=235), so it never became a Javascript standard.
+
+Today, E4X lives on in ActionScript, Adobe's ExtendScript and [Rhino Javascript](http://mozilla.github.io/rhino/).
+
+## Types
+The XML spec defines 4 additonal types
+- Namespace -- which has a uri and a prefix
+- QName -- a qualified name which can reference a local name to either a prefix or uri
+- XML -- A native type which holds the XML. XML nodes can be elements, attributes, text, etc.
+- XMLList --  A special XML-like type which holds a list of XML objects. If the XMLList contains a single child, it can be used as if it is XML.
+
+XML and XMLList has special properties so they can be used as if they are text (when they are text nodes).
+
 ## E4X
-Some info about E4X...
+The goal of E4X is to give an intuitive interface to read, traverse and filter XML.
+### Operators
+E4X adds three basic operators. The dot (`.`) operator in E4X means "child" and the `.@` operator means "attribute". The `..` operator means descendent. So you can get all children with the name `child` by using `root.child` or an attribute by using `root.child.@name` `root..child` will return all descendents named "child" no matter how far down the hierarchy they are.
+
+### Filtering
+E4X also allows filtering. Let's say you want to get only child who's name is "Bob". You can do that by using `root.(child.@name == "Bob)`. To help grasp the syntax, you can think of `.()` as a "filter function". The above expression in English would be "give me all children of root whose name attribute equals Bob". As you can see, the syntax is very concise, intuitive and quite powerful.
 
 ## Limitations
-About inferring XML types...
+Because XML and E4X is not supported natively by the browser, some E4X code needs to be rewritten by the compiler. For this to work, the compiler needs to know that an object is XML. For this reason it's very important to be consistent about declaring XML types in Royale. Particular care should be taken if you have an array of XML objects to either use `Vector`, declare a local variable (i.e. `var item:XML = arr[i]`) or use function access instead of E4X syntax. To further clarify: `myUn [...]
 
 ## Optimization
-Details about performance considerations when using XML...
\ No newline at end of file
+We have done a lot of work to make XML and E4X as performant as possible. It's being used in production of applications with a lot of XML data without issues. However the E4X spec can sometimes lend itself to code which creates a lot of extra work for the Javascript engine.
+
+It's also possible to end up in situations where large amounts of XML are stored in memory. If there's a reference to a single XML node anywhere, the entire tree cannot be garbage collected.
+
+For these cases, the browser profiling tools are your friend.
+
+### Use with caution
+For the first issue, use the profiler to see if XML processing is taking measurable time. If yes, you can optimize your code by using two methods we added to XML in Royale: `getChildrenArray()` and `getAttributeArray()`. Use these methods with care and *only* use them if you need to optimize your code. These will return the underlying list of children and attributes respectively. Please note that this returns the *actual* arrays and *not* a copy. The reason they don't return copies is to [...]
+
+For the second issue, make sure to use `copy()` if you need to keep specific XML nodes around. Or you can save the serialized XML as a string and rewrite it as XML later. You can use the memory profiling tools to see if there's excessive XML usage.
+## Alternative
+Full XML and E4X support does carry with it some performance implications. Royale also offers a lightweight [JXON](https://royale.apache.org/asdoc/#!org.apache.royale.utils/JXON) class which can be useful for simple reading of XML.
+
+Some limitations of the JXON implementation are:
+- No E4X
+- No writing of XML. It's for consuming XML only.
+- No namespace support
+- Doesn't handle whitespace
+
+## Where to go from here
+- MDN had very good documentation of E4X. Unfortunately it has been removed. It's still viewable using [WayBackMachine](http://web.archive.org/web/20160304033553/https://developer.mozilla.org/en-US/docs/Archive/Web/E4X_tutorial/Introduction).
+- StackOverflow has [lots of good information on E4X](https://stackoverflow.com/questions/tagged/e4x).
+- Web articles. There are various articles on E4X scattered around the web. The content is sure to be old, but relevant.
\ No newline at end of file