Skip to content

Commit 398d7db

Browse files
kakkokari-gtyihkakkokari-gtyih
committed
add document
1 parent 2087614 commit 398d7db

File tree

6 files changed

+269
-12
lines changed

6 files changed

+269
-12
lines changed

‎.vitepress/config/en.ts‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,24 @@ const guideNav: DefaultTheme.SidebarItem[] = [
1919
];
2020

2121
const referenceNav: DefaultTheme.SidebarItem[] = [
22-
{ text: 'Syntax', link: 'syntax' },
23-
{ text: 'Built-in Properties', link: 'builtin-props' },
24-
{ text: 'Keywords', link: 'keywords' },
25-
{ text: 'Literal Expressions', link: 'literals' },
26-
{ text: 'Built-in Functions', link: 'std' },
27-
{ text: 'Built-in Functions (Math)', link: 'std-math' },
22+
{
23+
text: 'Language Specification',
24+
items: [
25+
{ text: 'Syntax', link: 'syntax' },
26+
{ text: 'Built-in Properties', link: 'builtin-props' },
27+
{ text: 'Keywords', link: 'keywords' },
28+
{ text: 'Literal Expressions', link: 'literals' },
29+
{ text: 'Built-in Functions', link: 'std' },
30+
{ text: 'Math Functions', link: 'std-math' },
31+
],
32+
},
33+
{
34+
text: 'JavaScript Interface Specification',
35+
items: [
36+
{ text: 'Basic Runtime', link: 'interface/basic' },
37+
{ text: 'AiSON', link: 'interface/aison' },
38+
],
39+
},
2840
];
2941

3042
export const en = defineConfig({

‎.vitepress/config/ja.ts‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,24 @@ const guideNav: DefaultTheme.SidebarItem[] = [
1919
];
2020

2121
const referenceNav: DefaultTheme.SidebarItem[] = [
22-
{ text: '構文', link: 'syntax' },
23-
{ text: '組み込みプロパティ', link: 'builtin-props' },
24-
{ text: '予約語', link: 'keywords' },
25-
{ text: 'リテラル式', link: 'literals' },
26-
{ text: '組み込み関数', link: 'std' },
27-
{ text: '組み込み関数（Math）', link: 'std-math' },
22+
{
23+
text: '言語仕様',
24+
items: [
25+
{ text: '構文', link: 'syntax' },
26+
{ text: '組み込みプロパティ', link: 'builtin-props' },
27+
{ text: '予約語', link: 'keywords' },
28+
{ text: 'リテラル式', link: 'literals' },
29+
{ text: '組み込み関数', link: 'std' },
30+
{ text: '組み込み関数（Math）', link: 'std-math' },
31+
],
32+
},
33+
{
34+
text: 'JavaScript Interface',
35+
items: [
36+
{ text: '基本の処理系', link: 'interface/basic' },
37+
{ text: 'AiSON', link: 'interface/aison' },
38+
],
39+
},
2840
];
2941

3042
export const jaSearchLocale: NonNullable<DefaultTheme.LocalSearchOptions['translations']> = {

‎docs/en/references/interface/aison.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# JavaScript Implementation: AiSON
2+
3+
**AiSON** (AiScript Object Notation) is a data interchange syntax based on AiScript's [metadata syntax](../syntax.md#metadata-syntax).
4+
5+
Only pure [literals](../literals.md) are allowed as elements. Including functions or any other type of dynamic expression will result in a syntax error.
6+
7+
It's designed to be a more delightful to write compared to JSON. For example, object keys don't require `"` (double quotes), and trailing commas `,` are permitted. This makes writing simple data structures easier.
8+
9+
More strictly:
10+
11+
* Only **one top-level object** is permitted.
12+
* **Dynamic expressions**, such as functions or dynamic bindings for object values, are not allowed.
13+
* **Namespaces and metadata** are not supported.
14+
15+
```aiscript
16+
{
17+
name: "example"
18+
version: 42
19+
keywords: ["foo", "bar", "baz"]
20+
// A trailing comma is allowed on the last item
21+
}
22+
```
23+
24+
## JavaScript API
25+
26+
The `@syuilo/aiscript` package includes a built-in function for parsing AiSON. You can use `AiSON.parse` to convert an AiSON string directly into a JavaScript value.
27+
28+
:::tip
29+
Currently, only parsing from AiSON to JavaScript is supported. A function to serialize a JavaScript object into an AiSON string (`AiSON.stringify`) has not yet been implemented.
30+
:::
31+
32+
```ts
33+
import { AiSON } from '@syuilo/aiscript';
34+
35+
const data = AiSON.parse('{ key: "value" }');
36+
```

‎docs/en/references/interface/basic.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# JavaScript Implementation: Core Runtime
2+
3+
:::tip
4+
For basic usage, please see the [Guide: "Embedding into Your Application"](/en/guides/implementation).
5+
:::
6+
7+
## Parser
8+
9+
### `Parser.parse(script: string)`
10+
11+
Converts a string of AiScript code into an Abstract Syntax Tree (AST).
12+
13+
```ts
14+
import { Parser } from '@syuilo/aiscript';
15+
16+
const program = "<: \"Hello, World!\"";
17+
18+
let parser: Parser;
19+
20+
async function run() {
21+
parser = new Parser();
22+
const ast = parser.parse(program);
23+
}
24+
25+
run();
26+
```
27+
28+
### `Parser.addPlugin(type: PluginType, plugin: ParserPlugin)`
29+
30+
Adds a plugin to the current instance that receives the AST to perform validation (`validate`) or modification (`transform`).
31+
32+
-----
33+
34+
## Interpreter
35+
36+
AiScript Values must be converted to JavaScript primitive types as needed.
37+
38+
### Constructor
39+
40+
`Interpreter(consts: Record<string, Value>, opts: ...)`
41+
42+
#### `consts`
43+
44+
Specifies properties to be injected at runtime. Provide an object where the keys are property names and the values are the AiScript values to inject.
45+
46+
#### `opts`
47+
48+
Specifies execution options. All are optional.
49+
50+
- `in(q: string): Promise<string>`: This function is called to accept input. `q` is the value to display in the prompt, and the return value is a Promise that resolves with the string of user input.
51+
- `out(value: Value): void`: This function is called to produce output. `value` is the AiScript Value to be output.
52+
- `err(e: AiScriptError): void`: This function is called when a problem occurs during AiScript execution. `e` is an `AiScriptError` that extends JavaScript's `Error` class.
53+
- `log(type: string, params: LogObject): void`: This function is called when there is a log from the runtime.
54+
- `maxStep: number`: To limit the execution depth, enter the maximum number of steps here.
55+
- `abortOnError: boolean`: Whether to stop all other executions handled by the interpreter (including future ones) when an error occurs during execution.
56+
- `irqRate: number`: Allows you to specify the Interrupt Request (IRQ) rate.
57+
- `irqSleep() => Promise<void>`: Allows you to define the IRQ wait.
58+
59+
### `Interpreter.exec(script?: Ast.Node[])`
60+
61+
Asynchronously executes the AiScript AST specified in `script`. **This is the recommended method for normal use.**
62+
63+
### `Interpreter.execSync(script?: Ast.Node[])`
64+
65+
Synchronously executes the AiScript AST specified in `script`. Use with caution.
66+
67+
:::danger
68+
- When running synchronously, it is **strongly recommended** to adjust limits such as the maximum number of steps. Unlike the asynchronous `exec`, `execSync` can have a severe impact on the host JavaScript environment if a malicious script (e.g., an infinite loop) is executed with poor configuration.
69+
- When running synchronously, functions injected via `consts` that return a Promise (in other words, async functions) cannot be executed and will result in an error.
70+
:::
71+
72+
### `Interpreter.execFn(fn: VFn, args: Value[])`
73+
74+
Asynchronously executes the AiScript function passed in `fn`. The `args` array contains the arguments for the function. To execute synchronously, use `Interpreter.execFnSync`.
75+
76+
### `Interpreter.execFnSimple(fn: VFn, args: Value[])`
77+
78+
Asynchronously executes the AiScript function passed in `fn`. Unlike `execFn`, which calls the interpreter's callback (`opts.err`) if an error occurs within the function, `execFnSimple` will always throw an `Error`.
79+
80+
### `Interpreter.collectMetadata(script?: Ast.Node[])`
81+
82+
Retrieves the content of the [metadata syntax](../syntax.md#metadata-syntax) as a JavaScript value.

‎docs/ja/references/interface/aison.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# JavaScript Implementation: AiSONについて
2+
3+
AiSON (AiScript Object Notation) は、AiScriptの[メタデータ構文](../syntax.html#メタデータ構文)を基に作られたデータ交換用の構文です。
4+
5+
要素として関数を除く純粋な[リテラル](../literals.html)のみが許可されており、それ以外の式を含むと構文エラーとなります。
6+
7+
JSONに比べ、オブジェクトのkeyに`"`（ダブルクォーテーション）が必要ない・最終項の末尾に`,`（カンマ）がついていても許容されるなど、より柔軟で書きやすいものとなっています。
8+
9+
より厳密には：
10+
11+
- トップレベルのオブジェクトはひとつしか許可されません。
12+
- 動的な式（関数・オブジェクトのvalueにたいする動的なバインディングなど）は許可されません。
13+
- 名前空間・メタデータはサポートされていません。
14+
15+
```aiscript
16+
{
17+
name: "example"
18+
version: 42
19+
keywords: ["foo", "bar", "baz"]
20+
}
21+
```
22+
23+
## JavaScript API
24+
25+
AiSONをパースするための関数は`@syuilo/aiscript`に内包されています。`AiSON.parse`でAiSONの文字列からJavaScript Valueへの変換が可能です。
26+
27+
:::tip
28+
現時点ではパースのみ可能です。AiSONへ変換する（`AiSON.stringify`）は実装されていません。
29+
:::
30+
31+
```ts
32+
import { AiSON } from '@syuilo/aiscript';
33+
34+
const data = AiSON.parse('{key: "value"}');
35+
```

‎docs/ja/references/interface/basic.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# JavaScript Implementation: 基本の処理系
2+
3+
:::tip
4+
基本的な使用方法は[ガイド「アプリに組み込む」](/ja/guides/implementation)をご覧ください。
5+
:::
6+
7+
## Parser
8+
9+
### `Parser.parse(script: string)`
10+
11+
AiScriptが記述された文字列をASTに変換します。
12+
13+
```ts
14+
import { Parser } from '@syuilo/aiscript';
15+
16+
const program = "<: \"Hello, World!\"";
17+
18+
let parser: Parser;
19+
20+
async function run() {
21+
parser = new Parser();
22+
const ast = parser.parse(program);
23+
}
24+
25+
run();
26+
```
27+
28+
### `Parser.addPlugin(type: PluginType, plugin: ParserPlugin)`
29+
30+
現在のインスタンスに、ASTを受け取りバリデーション（`validate`）や変更（`transform`）を行うプラグインを追加します。
31+
32+
## Interpreter
33+
34+
AiScript Value は適宜JavaScriptのプリミティブ型に変換する必要があります。
35+
36+
### Constructor
37+
38+
`Interpreter(consts: Record<string, Value>, opts: ...)`
39+
40+
#### `consts`
41+
42+
実行時に注入するプロパティを指定します。プロパティ名をkey、注入するAiScript値をvalueとするオブジェクトを指定します。
43+
44+
#### `opts`
45+
46+
実行のオプションを指定します。すべて任意です。
47+
48+
- `in(q: string): Promise<string>`: 入力を受け付ける際にこの関数を呼び出します。`q`はプロンプトに表示する値、返り値はユーザーからの入力の文字列を返すPromiseです。
49+
- `out(value: Value): void`: 出力する際にこの関数を呼び出します。`value`は出力されるAiScript Valueです。
50+
- `err(e: AiScriptError): void`: AiScript実行中に問題が発生した場合はこの関数を呼び出します。`e`はJavaScriptのErrorクラスを継承するAiScriptErrorです。
51+
- `log(type: string, params: LogObject): void`: ランタイムからのログがある場合はこの関数を呼び出します。
52+
- `maxStep: number`: 実行の深さを制限する場合はここにその最大ステップ数を入力します。
53+
- `abortOnError: boolean`: 実行中にエラーが発生した際に、インタプリタが担うその他の実行（今後の実行）も含めてすべてを停止するかどうか。
54+
- `irqRate: number`: IRQレートを指定できます。
55+
- `irqSleep() => Promise<void>`: IRQの待ちを定義できます。
56+
57+
### `Interpreter.exec(script?: Ast.Node[])`
58+
59+
`script`に指定されたAiScript ASTを非同期で実行します。**通常はこちらを使用してください。**
60+
61+
### `Interpreter.execSync(script?: Ast.Node[])`
62+
63+
`script`に指定されたAiScript ASTを同期的に実行します。
64+
65+
:::danger 警告
66+
- 同期的に実行する場合は最大ステップ数などの制限を調整することを強くお勧めします。非同期の`exec`に対し、`execSync`は悪意のあるスクリプト（無限ループなど）が実行された場合ホストのJavascript環境に重大な影響を与えます。
67+
- 同期的に実行する場合、`consts`で注入した関数にてPromiseを返すもの（非同期な関数）は実行できず、エラーとなります。
68+
:::
69+
70+
### `Interpreter.execFn(fn: VFn, args: Value[])`
71+
72+
`fn`に渡されたAiScript関数を非同期で実行します。`args`には関数の引数を渡します。同期的に実行する場合は`Interpreter.execFnSync`を使用します。
73+
74+
### `Interpreter.execFnSimple(fn: VFn, args: Value[])`
75+
76+
`fn`に渡されたAiScript関数を非同期で実行します。`execFn`は関数内でエラーが発生するとInterpreterのコールバック（`opts.err`）がある場合はそちらを呼ぶのに対し、`execFnSimple`は常にErrorをthrowします。
77+
78+
### `Interpreter.collectMetadata(script?: Ast.Node[])`
79+
80+
[メタデータ構文](../syntax.html#メタデータ構文)の中身をJavaScriptの値として取得します。

0 commit comments

Comments
 (0)