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 82572c5 start of Node.js documentation
82572c5 is described below
commit 82572c5c3f37e9d29f6c5f3971631d1e7088cd7c
Author: Josh Tynjala <[email protected]>
AuthorDate: Wed Oct 9 14:59:11 2019 -0700
start of Node.js documentation
---
_data/toc.json | 14 +++++
features/nodejs.md | 31 ++++++++++
features/nodejs/external-modules.md | 112 ++++++++++++++++++++++++++++++++++++
features/nodejs/modules.md | 38 ++++++++++++
features/nodejs/scripting.md | 99 +++++++++++++++++++++++++++++++
5 files changed, 294 insertions(+)
diff --git a/_data/toc.json b/_data/toc.json
index 1c77d8a..6b5d1d8 100644
--- a/_data/toc.json
+++ b/_data/toc.json
@@ -109,6 +109,20 @@
"path": "features/loading-external-data/amf.md"
}
]
+ },
+ {
+ "path": "features/nodejs.md",
+ "children": [
+ {
+ "path": "features/nodejs/scripting.md"
+ },
+ {
+ "path": "features/nodejs/modules.md"
+ },
+ {
+ "path": "features/nodejs/external-modules.md"
+ }
+ ]
}
]
},
diff --git a/features/nodejs.md b/features/nodejs.md
new file mode 100644
index 0000000..a5ad5ea
--- /dev/null
+++ b/features/nodejs.md
@@ -0,0 +1,31 @@
+---
+# 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: Node.js
+description: Using Apache Royale with Node.js
+permalink: /features/nodejs
+---
+
+# Node.js and Apache Royale
+
+Compile ActionScript code to JavaScript and run on Node.js
+
+There are two main approaches to targeting the popular
[Node.js](https://nodejs.org/) JavaScript runtime with Apache Royale and the
[ActionScript](features/as3) language.
+
+[Command line scripting](features/nodejs/scripting) explains how to call
Node.js APIs from ActionScript, compile to JavaScript, and run the generated
script from the command line.
+
+[Node.js modules](features/nodejs/modules) explains how to compile a Node.js
module with ActionScript that can be loaded with `require()` and deployed to
npm.
\ No newline at end of file
diff --git a/features/nodejs/external-modules.md
b/features/nodejs/external-modules.md
new file mode 100644
index 0000000..a22e2de
--- /dev/null
+++ b/features/nodejs/external-modules.md
@@ -0,0 +1,112 @@
+---
+# 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: Load external Node.js modules
+description: Require Node.js modules installed from npm in ActionScript and
Apache Royale
+permalink: /features/nodejs/external-modules
+---
+
+# Load external Node.js modules with Apache Royale
+
+Expose Node.js modules installed from npm to ActionScript
+
+By creating [type definitions](features/externs) with special metadata,
developers can use [Node.js](features/nodejs) modules from
[ActionScript](features/as3) code.
+
+Let's try to use the [boxen](https://www.npmjs.com/package/boxen) module from
[npm](https://www.npmjs.com/) in ActionScript.
+
+Create a file named *boxen.as* and add the following code:
+
+```actionscript
+package
+{
+ /**
+ * @externs
+ */
+ [JSModule(name="boxen")]
+ public function boxen(message:String, options:Object = null):void {}
+}
+```
+
+This file will tell the Apache Royale compiler how to access the "boxen"
module in the generated JavaScript. Let's look in more detail at each part of
this file.
+
+All type definitions must include the `@externs` asdoc tag.
+
+
+```actionscript
+/**
+ * @externs
+ */
+```
+
+Additionally, type definitions for Node.js modules must include `[JSModule]`
metadata.
+
+```actionscript
+[JSModule(name="boxen")]
+```
+
+Set the `name` field inside `[JSModule]` to the string that should be passed
to a `require()` call in JavaScript to load the module.
+
+The default export of a module should either be a class, a function, or a
variable. In this case, the default export of the "boxen" module is a function.
+
+```actionscript
+public function boxen(message:String, options:Object = null):void {}
+```
+
+The name of the default export should be derived from the name of the module.
In this case, the name of the module and the name of the `function` are both
`boxen`.
+
+> If the module name contains dashes, the symbol name should be converted to
[camel case](https://en.wikipedia.org/wiki/Camel_case). For example,
`[JSModule(name="my-example-module")]` would require the symbol to be named
`myExampleModule`.
+
+## Use the module
+
+Create a file named *MyScript.as*, and add the following content:
+
+```actionscript
+package
+{
+ public class MyScript
+ {
+ public function MyScript()
+ {
+ boxen("I loaded a module!");
+ }
+ }
+}
+```
+
+## Compile and run
+
+Using Apache Royale's **asnodec** compiler, compile our project into
JavaScript that can be run with Node.js:
+
+```sh
+asnodec MyScript.as
+```
+
+Use the following command to run the compiled project:
+
+```sh
+node bin/js-release/index.js
+```
+
+The following output will appear in the console:
+
+```
+┌────────────────────────┐
+│ │
+│ I loaded a module! │
+│ │
+└────────────────────────┘
+```
\ No newline at end of file
diff --git a/features/nodejs/modules.md b/features/nodejs/modules.md
new file mode 100644
index 0000000..c3345d3
--- /dev/null
+++ b/features/nodejs/modules.md
@@ -0,0 +1,38 @@
+---
+# 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: Create a Node.js module
+description: Write Node.js modules with ActionScript and Apache Royale that
can be loaded with require()
+permalink: /features/nodejs/modules
+---
+
+# Create a Node.js module with Apache Royale
+
+Write modules with ActionScript that can be loaded with `require()` in Node.js
+
+One of the reasons why the [Node.js](features/nodejs) ecosystem is so vibrant
is the massive number of open source modules available to install from
[npm](https://www.npmjs.com/). Those modules are all deployed as JavaScript,
but they can be written in a variety of languages that can compile to
JavaScript, including [ActionScript](features/as3).
+
+## Compile with asnodec
+
+Using Apache Royale's **asnodec** compiler, compile our project into
JavaScript that can be run with Node.js.
+
+
+```sh
+asnodec -targets=JSNodeModule src/MyModule.as
+```
+
+Use the `-targets` compiler option to specify that the output should be a
module instead of a [standalone script](features/nodejs/scripting).
\ No newline at end of file
diff --git a/features/nodejs/scripting.md b/features/nodejs/scripting.md
new file mode 100644
index 0000000..9b3443e
--- /dev/null
+++ b/features/nodejs/scripting.md
@@ -0,0 +1,99 @@
+---
+# 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: Command line scripting
+description: Write a Node.js script with ActionScript and Apache Royale
+permalink: /features/nodejs/scripting
+---
+
+# Node.js scripting with Apache Royale
+
+Write command line scripts for Node.js using ActionScript
+
+Create a file named *MyServer.as*, and add the following code:
+
+```actionscript
+package
+{
+ public class MyServer
+ {
+ public function MyServer()
+ {
+ }
+ }
+}
+```
+
+Apache Royale requires an ActionScript class, like this one, as the entrypoint
for a Node.js project. The constructor will run automatically on startup.
+
+Next, let's expand this code to create a simple server using the "http" module
provided by Node.js.
+
+```actionscript
+package
+{
+ import http.IncomingMessage;
+ import http.Server;
+ import http.ServerResponse;
+
+ public class MyServer
+ {
+ private static const HOSTNAME:String = "localhost";
+ private static const PORT:int = 3000;
+
+ public function MyServer()
+ {
+ var server:Server = http.createServer(handleRequest);
+
+ server.listen(PORT, HOSTNAME, handleServerStart);
+ }
+
+ private function handleRequest(req:IncomingMessage,
res:ServerResponse):void
+ {
+ res.statusCode = 200;
+ res.setHeader("Content-Type", "text/plain");
+ res.end("Hello World\n");
+ }
+
+ private function handleServerStart():void
+ {
+ console.log("Server running at http://"; + HOSTNAME +
":" + PORT + "/");
+ }
+ }
+}
+```
+
+> Notice that there's no need to call `require("http")`, as would be necessary
in plain JavaScript. When the Apache Royale compiler detects a reference to a
Node.js module, like `http`, it automatically generates the appropriate
`require()` calls.
+
+## Compile with asnodec
+
+Using Apache Royale's **asnodec** compiler, compile our project into
JavaScript that can be run with Node.js:
+
+```sh
+asnodec src/MyServer.as
+```
+
+The generated JavaScript code will be created in the *bin/js-debug* folder for
debug builds, and the *bin/js-release* folder for release builds.
+
+## Run the project
+
+Use the following command to run the compiled project:
+
+```sh
+node bin/js-release/index.js
+```
+
+In a web browser, open **http://localhost:3000/** and verify that you can see
a webpage that simply contains the text, "Hello World".
\ No newline at end of file
