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
The following commit(s) were added to refs/heads/master by this push:
new 5606992 AS3: updated description and linked to new language features
5606992 is described below
commit 560699206588aa3e458d3b15e6dcb3615242e5c0
Author: Josh Tynjala <[email protected]>
AuthorDate: Thu Apr 25 14:22:45 2019 -0700
AS3: updated description and linked to new language features
Added documentation for new abstract class syntax and private constructor
syntax
---
Welcome/Features/AS3.md | 42 +++++++-
Welcome/Features/actionscript/abstract-classes.md | 115 +++++++++++++++++++++
.../Features/actionscript/private-constructors.md | 101 ++++++++++++++++++
3 files changed, 255 insertions(+), 3 deletions(-)
diff --git a/Welcome/Features/AS3.md b/Welcome/Features/AS3.md
index 2b840e0..ce1bea3 100644
--- a/Welcome/Features/AS3.md
+++ b/Welcome/Features/AS3.md
@@ -15,11 +15,47 @@
# limitations under the License.
layout: docpage
-title: AS3
+title: ActionScript 3 (AS3)
---
# ActionScript 3 (AS3)
-ActionScript is an object-oriented programming language originally developed
by Macromedia Inc. (later acquired by Adobe Systems). It is a derivation of
HyperTalk, the scripting language for HyperCard. It is now a dialect of
ECMAScript (meaning it is a superset of the syntax and semantics of the
language more widely known as JavaScript). Because both ActionScript and
JavaScript are based on ECMAScript, most code you write in AS translates well
to JS. One significant difference is that AS [...]
+ActionScript 3 is an object-oriented programming language originally created
by Macromedia Inc., which continued to evolve after being acquired by Adobe
Systems. It is a superset of the ECMAScript standard (more widely known as
JavaScript) with a stronger focus on classes, interfaces, and objects. While
originally designed for Adobe Flash Player, ActionScript 3 may be used by
developers today to build plugin-free, cross-platform, web applications with
[Apache Royale](..).
-When you get ready to compile and run your application, the Royale compiler
translates AS-specific code into JS code organized into pseudo-classes, which
then run just fine in a JavaScript world.
+The following code snippet shows some of ActionScript's core syntax:
+
+```actionscript
+package org.apache.royale
+{
+ public class WelcomeToActionScript
+ {
+ public function WelcomeToActionScript()
+ {
+ var message:String = "Hello world";
+ sayHi(message, 3);
+ }
+
+ private function sayHi(message:String, times:int):void
+ {
+ for (var i:int = 0; i < times; i++)
+ {
+ // prints message to debug console
+ trace(message);
+ }
+ }
+ }
+}
+```
+
+## New ActionScript language features in Royale
+
+The Royale compiler extends the ActionScript language with useful, new
features. These language extensions are considered optional, and to use the new
syntax, you must enable certain compiler flags.
+
+The following new ActionScript features are available with the Royale compiler:
+
+* [Abstract Classes](abstract-classes.html)
+* [Private Constructors](private-constructors.html)
+
+### Limitations of ActionScript language extensions
+
+Other ActionScript compilers, such as the one in the [Apache Flex
SDK](https://flex.apache.org/){:target='_blank'}, may not support Apache
Royale's extensions to the ActionScript language. Attemping to pass source code
or SWC libraries using these language extensions to another compiler may result
in compile-time errors or unexpected behavior at run-time. In other words, to
write 100% portable ActionScript code that works with any compiler, you should
avoid using any of Royale's extensions.
\ No newline at end of file
diff --git a/Welcome/Features/actionscript/abstract-classes.md
b/Welcome/Features/actionscript/abstract-classes.md
new file mode 100644
index 0000000..62a2905
--- /dev/null
+++ b/Welcome/Features/actionscript/abstract-classes.md
@@ -0,0 +1,115 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: Abstract classes in ActionScript
+---
+# Abstract classes in ActionScript
+
+[Apache Royale](../..) adds support for declaring `abstract` classes. An
abstract class cannot be instantiated using the `new` keyword, meaning that it
must be subclassed. Additionally, an abstract class may declare `abstract`
methods that do not have a function body. Abstract methods must be implemented
by the concrete subclass, similar to how the methods of an interface must also
be implemented.
+
+## Enable abstract classes
+
+Like other [new ActionScript language features](new-language-features.html)
that Royale adds, abstract classes are optional and disabled by default. To
enable abstract classes in your application, use the `-allow-abstract-classes`
compiler option.
+
+```sh
+mxmlc -allow-abstract-classes MyApp.mxml
+```
+
+## Code example
+
+Consider the following code that creates a class named `GraphicsObject`:
+
+```actionscript
+package
+{
+ public abstract class GraphicsObject
+ {
+ public function GraphicsObject()
+ {
+ }
+
+ public var x:Number;
+ public var y:Number;
+
+ public abstract function draw(context:IGraphicsContext):void;
+ }
+}
+```
+
+This class uses the `abstract` modifier, so if we tried to instantiate the
class directly, we'd get a compile-time error:
+
+```actionscript
+// Error: Abstract classes cannot be instantiated with the new operator.
+var object:GraphicsObject = new GraphicsObject();
+```
+
+The `GraphicsObject` class defines a method named `draw()` that also uses the
`abstract` modifier. This method does not have a body, and it will need to be
implemented in a subclass.
+
+> The `IGraphicsContext` type used by the single parameter of `draw()` is a
hypothetical interface that (for the purposes of this example) we'll say has
two methods, named `moveTo()` and `lineTo()`.
+
+The next code sample show how to extend the abstract class `GraphicsObject`
and implement its `draw()` method:
+
+
+```actionscript
+package
+{
+ public class Rectangle extends GraphicsObject
+ {
+ public function Rectangle(width:Number, height:Number)
+ {
+ this.width = width;
+ this.height = height;
+ }
+
+ public var width:Number;
+ public var height:Number;
+
+ public abstract function draw(context:IGraphicsContext):void
+ {
+ context.moveTo(x, y);
+ context.lineTo(x + width, y);
+ context.lineTo(x + width, y + height);
+ context.lineTo(x, y + height);
+ context.lineTo(x, y);
+ }
+ }
+}
+```
+
+If we extended `GraphicsObject` and did not implement its abstract method,
we'd get a compile-time error:
+
+
+```actionscript
+package
+{
+ // Error: Method draw in abstract class GraphicsObject not implemented
by class Foobar
+ public class Foobar extends GraphicsObject
+ {
+ public function Foobar()
+ {
+ }
+ }
+}
+```
+
+## Limitations of abstract classes in Royale
+
+Checking whether a class is abstract happens at compile-time only. However, by
using reflection APIs, a developer could potentially gain access to an abstract
class and instantiate it at run-time without errors.
+
+If a SWC library contains classes with abstract classes, applications using
that library must also enable abstract classes before the compiler will enforce
any restrictions.
+
+Other ActionScript compilers, such as the one in the [Apache Flex
SDK](https://flex.apache.org/){:target='_blank'}, may not recognize or enforce
private constructors. Attemping to pass source code or SWC libraries that
contain classes with private constructors to another compiler may result in
compile-time errors or unexpected behavior at run-time. In other words, to
write 100% portable ActionScript code that works with any compiler, you should
avoid using private constructors and any of [...]
\ No newline at end of file
diff --git a/Welcome/Features/actionscript/private-constructors.md
b/Welcome/Features/actionscript/private-constructors.md
new file mode 100644
index 0000000..1248054
--- /dev/null
+++ b/Welcome/Features/actionscript/private-constructors.md
@@ -0,0 +1,101 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: Private constructors in ActionScript
+---
+# Private constructors in ActionScript
+
+[Apache Royale](../..) adds support for declaring the constructor of a class
`private` instead of `public`. When a constructor is private, it cannot be
instantiated with the `new` keyword outside of the class where it is defined.
Private constructors are commonly used for implementing the *singleton* design
pattern, which is when only one instance of a particular class should ever be
created.
+
+## Enable private constructors
+
+Like other [new ActionScript language features](new-language-features.html)
that Royale adds, private constructors are optional and disabled by default. To
enable private constructors in your application, use the
`-allow-private-constructors` compiler option.
+
+```sh
+mxmlc -allow-private-constructors MyApp.mxml
+```
+
+## Code example
+
+You might implement a global logger as a singleton by using a private
constructor.
+
+```actionscript
+package
+{
+ public class Logger
+ {
+ private static var _instance:Logger;
+
+ public static function getInstance():Logger
+ {
+ if(!_instance)
+ {
+ _instance = new Logger();
+ }
+ return _instance;
+ }
+
+ private function Logger()
+ {
+ }
+
+ public function log(message:String):void
+ {
+ trace("LOG: " + message);
+ }
+ }
+}
+```
+
+If you were to attempt to instantate this `Logger` class, the compiler would
fail with an error:
+
+```actionscript
+package com.example
+{
+ public class MyApplication
+ {
+ public function MyApplication()
+ {
+ // Error: Attempted access of inaccessible constructor
through a reference with static type Logger
+ var obj:Logger = new Logger();
+ }
+ }
+}
+```
+
+However, you may call `Logger.getInstance()` to access an instance that is
created inside the `Logger` class itself:
+
+```actionscript
+package com.example
+{
+ public class MyApplication
+ {
+ public function MyApplication()
+ {
+ Logger.getInstance().log("Application started");
+ }
+ }
+}
+```
+
+## Limitations of private constructors in Royale
+
+Checking whether a constructor is private or not happens at compile-time only.
However, by using reflection APIs, a developer could potentially gain access to
a private constructor and instantiate it at run-time without errors.
+
+If a SWC library contains classes with private constructors, applications
using that library must also enable private constructors before the compiler
will enforce any restrictions.
+
+Other ActionScript compilers, such as the one in the [Apache Flex
SDK](https://flex.apache.org/){:target='_blank'}, may not recognize or enforce
private constructors. Attemping to pass source code or SWC libraries that
contain classes with private constructors to another compiler may result in
compile-time errors or unexpected behavior at run-time. In other words, to
write 100% portable ActionScript code that works with any compiler, you should
avoid using private constructors and any of [...]
\ No newline at end of file
