You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/customization/project-templates.md
+65-5Lines changed: 65 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -4,10 +4,70 @@ sidebar_position: 2
4
4
5
5
# Project Templates
6
6
7
-
```cli
8
-
apex new https://[email protected]/apexlang/codegen.git -p templates/go greeter \
9
-
--var module=github.com/apexlang/greeter \
10
-
--var package=greeter
7
+
The `apex new` command can be used to create a new project from either a basic github repository or from a TypeScript template generator. Programmatic templates are useful when your project needs outgrow a simple `git clone` or directory copy.
8
+
9
+
To create a new project from a template, use `apex new`:
10
+
11
+
```sh
12
+
apex new <template><project-name>
11
13
```
12
14
13
-
TODO
15
+
When cloning from git repositories, you can use `-p` or `--path` to specify a subdirectory to use as the template source. This lets you keep examples and boilerplate in the same repositories as their main projects.
16
+
17
+
The following command uses the template located in the `templates/nodejs` directory of the repository housed at [github.com/apexlang/codegen](https://github.com/apexlang/codegen).
18
+
19
+
```sh
20
+
apex new https://github.com/apexlang/codegen.git -p templates/nodejs my-project
21
+
```
22
+
23
+
## Template files and data
24
+
25
+
Any file ending with a `.tmpl` extension will be processed as a template with data substituted from the user or environment.
26
+
27
+
This example `package.json` from the nodejs template uses the `name`, `version`, `description`, and `author` variables to fill in the package metadata.
The `apex run` command runs tasks defined in the `tasks` block of an `apex.yaml` configuration file.
8
+
9
+
The following `apex.yaml` gives us a `greeter` task.
10
+
11
+
```yaml
12
+
tasks:
13
+
greeter:
14
+
- echo Hello World
15
+
- echo Have a great day!
16
+
```
17
+
18
+
Running `apex run greeter` will execute each command in sequence.
19
+
20
+
```sh
21
+
$ apex run greeter
22
+
echo Hello World
23
+
Hello World
24
+
echo Have a great day!
25
+
Have a great day!
26
+
```
27
+
28
+
## Environment variables
29
+
30
+
You can access environment variables from tasks with the familiar `$NAME` syntax, e.g.
31
+
32
+
```yaml
33
+
tasks:
34
+
greeter:
35
+
- echo $GREETING World
36
+
```
37
+
38
+
Output when run with `GREETING` set:
39
+
40
+
```
41
+
$ GREETING="Bonjour" apex run greeter
42
+
echo $GREETING World
43
+
Bonjour World
44
+
```
45
+
46
+
## Local configuration
47
+
48
+
Sometimes environment variables aren't a good fit or you want to reuse apex configuration. In that case, `apex` exposes all of its configuration in variables that follow an `$apex_config_[key]` pattern. This example shows how to use the `greetingPrefix` configuration variable in a task.
Copy file name to clipboardExpand all lines: docs/embedding.md
+20-20Lines changed: 20 additions & 20 deletions
Original file line number
Diff line number
Diff line change
@@ -2,34 +2,34 @@
2
2
sidebar_position: 7
3
3
---
4
4
5
-
# Embedding Apex into Apps
5
+
# Embedding Apexlang into Apps
6
6
7
-
Apex is most commonly used as a code generator for your projects. In some cases, your system may need to read in the information contained in an Apex specification. This could be useful for platforms or tools to inspect specifications dynamically. Some scenarios include:
7
+
Apexlang is most commonly used as a code generator for your projects. In some cases, your system may need to read in the information contained in an Apexlang specification. This could be useful for platforms or tools to inspect specifications dynamically. Some scenarios include:
8
8
9
9
* Validating or sanitizing input data
10
10
* Comparing two versions to detect a breaking change
11
11
* Discovering data elements that are sensitive (PCI/DSS) or encrypted
12
12
13
13
## Libraries
14
14
15
-
Apex natively supports TypeScript and Go.
15
+
Apexlang libraries exist for TypeScript and Go.
16
16
17
-
*[@apexlang/core](https://github.com/apexlang/apex-js) - TypeScript Apex parser used by the CLI and VS Code extension
18
-
*[@apexlang/codegen](https://github.com/apexlang/codegen) - TypeScript code generation modules loaded by the Apex CLI (e.g. `apex generate`)
19
-
*[github.com/apexlang/apex-go](https://github.com/apexlang/apex-go) - Go Apex parser for embedding in Go platforms
17
+
*[@apexlang/core](https://github.com/apexlang/apex-js) - TypeScript Apexlang parser used by the CLI and VS Code extension
18
+
*[@apexlang/codegen](https://github.com/apexlang/codegen) - TypeScript code generation modules loaded by the `apex` CLI (e.g. `apex generate`)
19
+
*[github.com/apexlang/apex-go](https://github.com/apexlang/apex-go) - Go Apexlang parser for embedding in Go platforms
20
20
21
21
## WebAssembly module
22
22
23
-
To reach a broader set of languages, the Apex Go parser is also released as a WebAssembly module and loadable via a Wasm runtime such as [Wasmtime](https://wasmtime.dev). The module parses and validates an Apex specification and returns a JSON representation that is easier to interpret in languages with JSON support.
23
+
To reach a broader set of languages, the Apexlang Go parser is also released as a WebAssembly module and loadable via a Wasm runtime such as [Wasmtime](https://wasmtime.dev). The module parses and validates an Apexlang specification and returns a JSON representation that is easier to interpret in languages with JSON support.
24
24
25
25
### Download
26
26
27
-
Two implementations of the Wasm module can be downloaded from the [Apex Go releases page](https://github.com/apexlang/apex-go/releases).
27
+
Two implementations of the Wasm module can be downloaded from the [Apexlang Go releases page](https://github.com/apexlang/apex-go/releases).
28
28
29
-
***[waPC](https://github.com/apexlang/apex-go/releases/latest/download/apex-wapc.wasm)** - Uses the [waPC protocol](https://wapc.io/docs/spec/) to invoke the Apex parser. This is the easiest method for integration, however you must be using a programming language that has a [waPC host implementation](https://github.com/wapc).
29
+
***[waPC](https://github.com/apexlang/apex-go/releases/latest/download/apex-wapc.wasm)** - Uses the [waPC protocol](https://wapc.io/docs/spec/) to invoke the Apexlang parser. This is the easiest method for integration, however you must be using a programming language that has a [waPC host implementation](https://github.com/wapc).
30
30
***[Core Wasm](https://github.com/apexlang/apex-go/releases/latest/download/apex-parser.wasm)** - Loadable by any programming language with a WebAssembly runtime (e.g. [Wasmtime](https://wasmtime.dev)); however, puts the responsibility of passing in the specification on your application.
31
31
32
-
Each parser accepts an Apex specification as a string and returns the JSON string represention. The JSON follows [this schema](https://github.com/apexlang/apex-go/blob/main/model.apexlang).
32
+
Each parser accepts an Apexlang specification as a string and returns the JSON string represention. The JSON follows [this schema](https://github.com/apexlang/apex-go/blob/main/model.apexlang).
33
33
34
34
### waPC <small>(apex-wapc.wasm)</small>
35
35
@@ -41,15 +41,15 @@ Input formatted as [MsgPack](https://msgpack.org)
41
41
42
42
```json
43
43
{
44
-
"source": "... Apex specification as string ..."
44
+
"source": "... Apexlang specification as string ..."
45
45
}
46
46
```
47
47
48
48
Output formatted as [MsgPack](https://msgpack.org)
49
49
50
50
```json
51
51
{
52
-
"namespace": { /* The parsed Apex namespace. See model spec. */ },
52
+
"namespace": { /* The parsed Apexlang namespace. See model spec. */ },
53
53
/* or */
54
54
"errors": [
55
55
{
@@ -86,7 +86,7 @@ Input formatted as [MsgPack](https://msgpack.org)
86
86
87
87
The Wasm module exposes 3 functions:
88
88
89
-
*`_malloc(size u32) u32` - Allocate memory to pass in Apex specifications
89
+
*`_malloc(size u32) u32` - Allocate memory to pass in Apexlang specifications
90
90
*`_free(ptr u32)` - Free memory allocated by `_malloc`
91
91
*`parse(ptr u32, size u32) u64` - The main parse function that returns a valid JSON representation
Embedding Apex parsing in your application follows these steps:
104
+
Embedding Apexlang parsing in your application follows these steps:
105
105
106
-
1. calls `_malloc` to receive a buffer for the byte count of the Apex specification
107
-
2. copies or directly load the Apex specification into the allocated buffer
106
+
1. calls `_malloc` to receive a buffer for the byte count of the Apexlang specification
107
+
2. copies or directly load the Apexlang specification into the allocated buffer
108
108
3. calls `parse` with the buffer pointer and size
109
109
4. extract the JSON (or error) string from the buffer returned
110
110
5. call `_free` to release the memory allocated by `_malloc` in step 1
111
111
112
-
If the returned string starts with `error:` then the string represents and error in the parser. Otherwise, it contains a valid JSON representation of your Apex specification.
112
+
If the returned string starts with `error:` then the string represents and error in the parser. Otherwise, it contains a valid JSON representation of your Apexlang specification.
113
113
114
114
#### Resolving imports
115
115
116
116
If a specification contains imports, the module makes a host call to `apex::resolve` to retrieve the contents of the imported specification.
`location` and `from` are string values. `location` is the specification to load and `from` is the specification performing the import. The Apex CLI installs importable definitions in `~/.apex/definitions` your implementation could load them from alternate locations.
120
+
`location` and `from` are string values. `location` is the specification to load and `from` is the specification performing the import. The `apex` CLI installs importable definitions in `~/.apex/definitions` your implementation could load them from alternate locations.
121
121
122
122
#### Example
123
123
124
-
[Here is an example](https://github.com/apexlang/apex-go/blob/main/cmd/host/main.go) using [wazero](https://wazero.io/) to invoke the Apex parser.
124
+
[Here is an example](https://github.com/apexlang/apex-go/blob/main/cmd/host/main.go) using [wazero](https://wazero.io/) to invoke the Apexlang parser.
| [`ImportsVisitor`](https://github.com/apexlang/codegen/blob/main/src/go/imports_visitor.ts) | Writes the imports required by the `.go` file. | `importsVisitor` |
54
-
| [`InterfaceVisitor`](https://github.com/apexlang/codegen/blob/main/src/go/interface_visitor.ts) | Writes an Go interface for all `@service` and `@dependency` Apex interfaces. | `serviceVisitor`, `dependencyVisitor` |
55
-
| [`StructVisitor `](https://github.com/apexlang/codegen/blob/main/src/go/struct_visitor.ts) | Writes a simple Go struct for Apex types. | `structVisitor` |
54
+
| [`InterfaceVisitor`](https://github.com/apexlang/codegen/blob/main/src/go/interface_visitor.ts) | Writes an Go interface for all `@service` and `@dependency` Apexlang interfaces. | `serviceVisitor`, `dependencyVisitor` |
55
+
| [`StructVisitor `](https://github.com/apexlang/codegen/blob/main/src/go/struct_visitor.ts) | Writes a simple Go struct for Apexlang types. | `structVisitor` |
56
56
| [`EnumVisitor`](https://github.com/apexlang/codegen/blob/main/src/go/enum_visitor.ts) | Writes an enum using `const` and various `func`s. | `enumVisitor` |
57
-
| [`UnionVisitor`](https://github.com/apexlang/codegen/blob/main/src/go/union_visitor.ts) | Writes an Apex union as a Go struct with optional fields for each declared type. | `unionVisitor` |
57
+
| [`UnionVisitor`](https://github.com/apexlang/codegen/blob/main/src/go/union_visitor.ts) | Writes an Apexlang union as a Go struct with optional fields for each declared type. | `unionVisitor` |
58
58
| [`AliasVisitor`](https://github.com/apexlang/codegen/blob/main/src/go/alias_visitor.ts) | Writes an alias type to map to an internal or third-party Go type (e.g. UUID) | `aliasVisitor` |
Copy file name to clipboardExpand all lines: docs/getting-started.mdx
+15-13Lines changed: 15 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -16,8 +16,8 @@ First, make sure you have [Deno](https://github.com/denoland/deno_install) insta
16
16
17
17
### CLI
18
18
19
-
The command line interface is a single binary that generates code from Apex documents.
20
-
The Apex CLI is installed from the terminal/command prompt by executing the command below.
19
+
The command line interface is a single binary that generates code from Apexlang documents.
20
+
The `apex` CLI is installed from the terminal/command prompt by executing the command below.
21
21
22
22
```shell
23
23
deno install -A --unstable -f -n apex https://deno.land/x/apex_cli/apex.ts
@@ -33,7 +33,7 @@ Output:
33
33
Usage: apex
34
34
Version: 0.0.2
35
35
Description:
36
-
A code generation tool using Apex, an interface definition language (IDL) for modeling software.
36
+
A code generation tool using Apexlang, an interface definition language (IDL) for modeling software.
37
37
Options:
38
38
-h, --help - Show this help.
39
39
Commands:
@@ -47,14 +47,14 @@ Output:
47
47
completions - Generate shell completions.
48
48
```
49
49
50
-
### VS Code extension
50
+
### VS Code extension for the Apexlang IDL
51
51
52
-
Installing this extension is **recommended** but not required. It enables the following features while editing Apex documents:
52
+
Installing this extension is **recommended** but not required. It enables the following features while editing Apexlang documents:
53
53
54
-
* Syntax highlighting
55
-
* Completions
56
-
* Parsing and validation checks
57
-
* Go to definition
54
+
- Syntax highlighting
55
+
- Completions
56
+
- Parsing and validation checks
57
+
- Go to definition
58
58
59
59
Search for `apexlang` in the extension marketplace and click "Install". You can also build from source from this [GitHub repo](https://github.com/apexlang/vscode-extension).
0 commit comments