You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@royale.apache.org by jo...@apache.org on 2026/05/19 21:58:57 UTC

(royale-docs) branch master updated (44593db -> e781bde)

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

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


    from 44593db  Update strands-and-beads.md added info on removing beads
     new da17037  metadata: add section for [JSDynamicOverride]
     new e904471  metadata: add [JSX]
     new 4073a37  metadata: add [JSModule]
     new e781bde  metadata: add JSForEachOverride and JSForInOverride

The 4 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 features/as3/metadata.md | 187 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 187 insertions(+)


(royale-docs) 01/04: metadata: add section for [JSDynamicOverride]

Posted by jo...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

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

commit da17037abf80e9d5f9f78e1f8f42e0b0a73a885a
Author: Josh Tynjala <jo...@apache.org>
AuthorDate: Tue May 19 11:59:09 2026 -0700

    metadata: add section for [JSDynamicOverride]
---
 features/as3/metadata.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/features/as3/metadata.md b/features/as3/metadata.md
index 58a0934..72f062c 100644
--- a/features/as3/metadata.md
+++ b/features/as3/metadata.md
@@ -455,6 +455,77 @@ public function get data():Object;
 
 InstanceType
 
+## JSDynamicOverride
+
+_Available since Royale 1.0.0_
+
+ActionScript supports dynamically accessing object keys using square brackets, removing keys with the `delete` keyword, and checking whether a key exists with the `in` keyword. For most objects, those keys are strings. Arrays typically use integers for keys. When targeting SWF, the `flash.utils.Dictionary` class supports keys of any type.
+
+To support any type of keys when targeting JavaScript, the `[JSDynamicOverride]` metadata may be used to inform the compiler that it should translate dynamic code to method calls. There are a number of method names that may be set on this meta. All are optional, and none require any others.
+
+- `getMethod` translates `object[key]` reads
+- `setMethod` translates `object[key]` writes
+- `deleteMethod` translates `delete object[key]` removals
+- `inMethod` translates `key in object` conditions
+
+The following example demonstrates how to add this metadata to a class, and the
+expected method signatures.
+
+```as3
+[JSDynamicOverride(getMethod="getKey",setMethod="setKey",deleteMethod="deleteKey",inMethod="keyIn")]
+public interface DynamicLookup {
+    public function getKey(key:String):Object {
+        // implementation
+    }
+
+    public function setKey(key:Object, value:Object):void {
+        // implementation
+    }
+
+    public function deleteKey(key:Object):Boolean {
+        // implementation
+    }
+
+    public function keyIn(key:Object):Boolean {
+        // implementation
+    }
+}
+```
+
+The next example shows how the class above might be used:
+
+```as3
+var valueToStore:Number = 123.4;
+var key:Object = {};
+
+var obj:DynamicLookup = new DynamicLookup();
+obj[key] = valueToStore;
+
+var valueThatWasStored:Number = lookup[key];
+assertTrue(valueToStore == valueThatWasStored); // true
+
+if (key in lookup) {
+    delete lookup[key];
+}
+```
+
+When the compiler generates JavaScript from the code above, its translation will look roughly similar to the following:
+
+```js
+var valueToStore = 123.4;
+var key = {};
+
+var obj = new DynamicLookup();
+obj.setKey(key, valueToStore);
+
+var valueThatWasStored = obj.getKey(key);
+assertTrue(valueToStore == valueThatWasStored); // true
+
+if (lookup.keyIn(key)) {
+    lookup.deleteKey(key);
+}
+```
+
 ## JSIncludeAsset
 
 _Available since Royale 0.9.13_


(royale-docs) 04/04: metadata: add JSForEachOverride and JSForInOverride

Posted by jo...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

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

commit e781bdec9dc84561ae76c73865448d33ad373654
Author: Josh Tynjala <jo...@apache.org>
AuthorDate: Tue May 19 14:58:44 2026 -0700

    metadata: add JSForEachOverride and JSForInOverride
    
    Minor cleanup of JSDynamicOverride too
---
 features/as3/metadata.md | 90 +++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 86 insertions(+), 4 deletions(-)

diff --git a/features/as3/metadata.md b/features/as3/metadata.md
index 436680f..1e8ca41 100644
--- a/features/as3/metadata.md
+++ b/features/as3/metadata.md
@@ -468,17 +468,17 @@ To support any type of keys when targeting JavaScript, the `[JSDynamicOverride]`
 - `deleteMethod` translates `delete object[key]` removals
 - `inMethod` translates `key in object` conditions
 
-The following example demonstrates how to add this metadata to a class, and the
-expected method signatures.
+The following example demonstrates how to add this metadata to a class, along
+with sample method signatures.
 
 ```as3
 [JSDynamicOverride(getMethod="getKey",setMethod="setKey",deleteMethod="deleteKey",inMethod="keyIn")]
 public interface DynamicLookup {
-    public function getKey(key:String):Object {
+    public function getKey(key:Object):Object {
         // implementation
     }
 
-    public function setKey(key:Object, value:Object):void {
+    public function setKey(key:Object, value:Object):Object {
         // implementation
     }
 
@@ -526,6 +526,88 @@ if (lookup.keyIn(key)) {
 }
 ```
 
+## JSForEachOverride
+
+_Available since Royale 1.0.0_
+
+ActionScript supports looping through the values of an array or collection using the `for-each` loop. When targeting SWF, `for-each` loops may provide special behavior for classes like `flash.utils.Dictionary`.
+
+To support iterating over the values of custom types when targeting JavaScript, the `[JSForEachOverride]` metadata may be used to inform the compiler that it should translate `for-each` loop code to method calls. There are a number of method names that may be set on this meta. All are optional, and none require any others.
+
+- `iteratorMethod` creates an iterator object
+- `iteratorNextMethod` returns the next value from the iterator object
+- `iteratorHasNextMethod` determines if the iterator has additional values
+- `iteratorDoneMethod` determines if the iterator has no additional values
+
+Generally, the metadata should define either `iteratorHasNextMethod` or `iteratorDoneMethod`, but not both. These properties exist to support both styles if checking if the iterator can continue or not. Alternately, you may omit both method names, and the compiler will check if the result of the `iteratorNextMethod` is `null` to determine when the loop has completed. However, this prevents looping over a collection that may contain `null` values.
+
+The following example demonstrates how to add this metadata to a class, along
+with sample method signatures. It uses `iteratorHasNextMethod`.
+
+```as3
+[JSForEachOverride(iteratorMethod="getIterator",iteratorNextMethod="getNext",iteratorHasNextMethod="hasNext")]
+class DynamicForEach {
+    public function getIterator():Object {
+        return new DynamicForEachIterator(this);
+    }
+}
+
+class DynamicForEachIterator {
+    public function DynamicForEachIterator(target:DynamicForEach) {
+        // implementation
+    }
+
+    public function getNext():Object {
+        // implementation
+    }
+
+    public function hasNext():Boolean {
+        // implementation
+    }
+}
+```
+
+## JSForInOverride
+
+_Available since Royale 1.0.0_
+
+ActionScript supports looping through object keys using the `for-in` loop. For most objects, those keys are strings. Arrays typically use integers for keys. When targeting SWF, the `flash.utils.Dictionary` class supports keys of any type.
+
+To support iterating over any type of keys when targeting JavaScript, the `[JSForInOverride]` metadata may be used to inform the compiler that it should translate `for-in` loop code to method calls. There are a number of method names that may be set on this meta. All are optional, and none require any others.
+
+- `iteratorMethod` creates an iterator object
+- `iteratorNextMethod` returns the next key from the iterator object
+- `iteratorHasNextMethod` determines if the iterator has additional keys
+- `iteratorDoneMethod` determines if the iterator has no additional keys
+
+Generally, the metadata should define either `iteratorHasNextMethod` or `iteratorDoneMethod`, but not both. These properties exist to support both styles if checking if the iterator can continue or not. Alternately, you may omit both method names, and the compiler will check if the result of the `iteratorNextMethod` is `null` to determine when the loop has completed. However, this prevents looping over a collection that may contain `null` values.
+
+The following example demonstrates how to add this metadata to a class, along
+with sample method signatures. It uses `iteratorHasNextMethod`.
+
+```as3
+[JSForInOverride(iteratorMethod="getIterator",iteratorNextMethod="getNext",iteratorHasNextMethod="hasNext")]
+class DynamicForIn {
+    public function getIterator():Object {
+        return new DynamicForInIterator(this);
+    }
+}
+
+class DynamicForInIterator {
+    public function DynamicForInIterator(target:DynamicForIn) {
+        // implementation
+    }
+
+    public function getNext():Object {
+        // implementation
+    }
+
+    public function hasNext():Boolean {
+        // implementation
+    }
+}
+```
+
 ## JSIncludeAsset
 
 _Available since Royale 0.9.13_


(royale-docs) 02/04: metadata: add [JSX]

Posted by jo...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

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

commit e9044715566ef58a5912554653e666de9d25cb59
Author: Josh Tynjala <jo...@apache.org>
AuthorDate: Tue May 19 12:06:47 2026 -0700

    metadata: add [JSX]
---
 features/as3/metadata.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/features/as3/metadata.md b/features/as3/metadata.md
index 72f062c..6eb1e61 100644
--- a/features/as3/metadata.md
+++ b/features/as3/metadata.md
@@ -569,6 +569,20 @@ public class MyClass
 
 In the output directory, typically _bin/js-debug_ or _bin/js-release_, the _index.html_ file will be generated in the root, and _.js_ files will be copied into a _scripts_ sub-directory.
 
+### JSX
+
+_Available since Royale 0.9.7_
+
+ActionScript has traditionally supported an inline XML syntax named E4X. JSX is another form of inline XML that was created for JavaScript frameworks like React, and its syntax largely overlaps with E4X. `[JSX]` metadata may be added to a method to treat any inline XML that the method contains as JSX instead of E4X.
+
+```as3
+[JSX]
+public function methodWithJSX():void
+{
+    return <MyComponent/>;
+}
+```
+
 ### Managed
 
 Managed


(royale-docs) 03/04: metadata: add [JSModule]

Posted by jo...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

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

commit 4073a37ac1e396dad61d0f7da0949935e8d0acfc
Author: Josh Tynjala <jo...@apache.org>
AuthorDate: Tue May 19 12:12:41 2026 -0700

    metadata: add [JSModule]
---
 features/as3/metadata.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/features/as3/metadata.md b/features/as3/metadata.md
index 6eb1e61..436680f 100644
--- a/features/as3/metadata.md
+++ b/features/as3/metadata.md
@@ -569,6 +569,26 @@ public class MyClass
 
 In the output directory, typically _bin/js-debug_ or _bin/js-release_, the _index.html_ file will be generated in the root, and _.js_ files will be copied into a _scripts_ sub-directory.
 
+### JSModule
+
+_Available since Royale 0.9.7_
+
+When targeting a JavaScript runtime that supports CommonJS modules, like Node.js, you may need to access external modules. You can define classes with `@externs` to indicate that they will be available in global scope at run-time, rather than compiled from ActionScript to JavaScript. To indicate that that an extern is located in a module, use `[JSModule]` metadata. The `name` property may be used to indicate the name of the module to require.
+
+```as3
+[JSModule(name="mymodule")]
+/**
+ * @externs
+ */
+public class MyClass {}
+```
+
+When the compiler generates JavaScript code, it will import the module using `require()`.
+
+```js
+var MyClass = require("mymodule");
+```
+
 ### JSX
 
 _Available since Royale 0.9.7_