From f8df0d689e9ac8149f22cc7542ff850b63208cdb Mon Sep 17 00:00:00 2001 From: FineArchs <133759614+FineArchs@users.noreply.github.com> Date: Tue, 29 Oct 2024 19:07:49 +0900 Subject: [PATCH 1/5] Create host/get-started.md --- docs/host/get-started.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 docs/host/get-started.md diff --git a/docs/host/get-started.md b/docs/host/get-started.md new file mode 100644 index 00000000..dcfdb0d3 --- /dev/null +++ b/docs/host/get-started.md @@ -0,0 +1,29 @@ +# ホスト向けAiScript実装ガイド +[Read translated version (en)](/translations/en/docs/host/get-started.md) + +このページでは、自作のnode.jsパッケージ内でAiScriptを動作させたい人向けのガイドを行います。 + +## 環境要件 + + + +
名称バージョン（動作確認済みのもの）
Node.js20.x
+ +## 手順 +### インストール +```sh +# NPMの例 +npm install --save @syuilo/aiscript +``` +### 使用 +- AiScriptのコードの実行を行うには、少なくとも`Parser`と`Interpreter`をimportする必要があります。 +- 詳細は[host/api.md](./api.md)を参照してください。 +```js +// esmの場合の例 +import { Parser, Interpreter } from '@syuilo/aiscript'; + +const script = '<: "Hello, AiScript!"'; +const ast = Parser.parse(script); +const interpreter = new Interpreter({}, { out: console.log }); +await interpreter.exec(ast); +``` From cd8ad9e2135f30b2eeea61c128e30ab9577d818e Mon Sep 17 00:00:00 2001 From: FineArchs <133759614+FineArchs@users.noreply.github.com> Date: Tue, 29 Oct 2024 20:12:01 +0900 Subject: [PATCH 2/5] Create host/api.md --- docs/host/api.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/host/api.md diff --git a/docs/host/api.md b/docs/host/api.md new file mode 100644 index 00000000..956649e4 --- /dev/null +++ b/docs/host/api.md @@ -0,0 +1,65 @@ +# APIガイド +[Read translated version (en)](/translations/en/docs/host/api.md) + +このページではAiScript実装用のJavascript/Typescript APIの概要を説明します。 + +> [!IMPORTANT] +> ESM形式のみ発行しています。CJS形式の取り扱いはありません。 + +## 基本的な要素 +`import { } from '@syuilo/aiscript'`でimportすることができます。 + +### Parser +コードの構文解析を行い、ASTと呼ばれるオブジェクトに変換します。 +このASTをInterpreterに渡すことでAiScriptの実行を行うことができます。 +詳しくは→[host/parser.md](./parser.md) + +### Ast +Parserによって生成される構文木です。 +詳しくは→[host/parser.md#AST](./parser.md#AST) + +### ParserPlugin, PluginType +> [!NOTE] +> 未整備の要素であり、ホスト側が利用するには機能が足りていないと考えられています。 + +※Typescript用 +パース後にAstのバリデーションや変形を行う「プラグイン機能」のための型です。 +詳しくは→[host/parser.md#プラグイン](./parser.md#プラグイン) + +### Interpreter +ASTを順次読み取り、実行します。 +詳しくは→[host/interpreter.md](./interpreter.md) + +### Scope +> [!NOTE] +> 未整備の要素であり、ホスト側が利用するには機能が足りていないと考えられています。 + +AiScript内の変数を保持・管理するネスト可能なオブジェクトです。 +詳しくは→[host/interpreter.md#スコープ](./interpreter.md#スコープ) + +### values +AiScript内のnullや数値といった値をJavascript側から生成するための関数と、それらをTypescriptで表現するための型が含まれています。 +AiScript用ライブラリを作成するのに必要になります。 +詳しくは→[host/interpreter.md#values](./interpreter.md#values) + +### utils +様々なユーティリティ関数が含まれます。 +例えば、AiScript内の値を文字列に変換する関数や、アサーション用の関数などです。 +詳しくは→[host/interpreter.md#utils](./interpreter.md#utils) + +### errors +ParserおよびInterpreterの実行中に発生するエラーのクラスが含まれます。 +詳しくは→[host/errors.md#](./errors.md) + +### AISCRIPT_VERSION +```js +import { AISCRIPT_VERSION } from '@syuilo/aiscript'; +console.log(AISCRIPT_VERSION); +``` +AiScriptのバージョンを表す文字列です。 + +### その他の要素 +> [!WARNING] +> 厳密なサポートがされない機能です。予告なしの変更が発生する可能性があります。 + +ここに無い要素が必要になった場合、`import { } from '@syuilo/aiscript/path/to/source.js`で対応するソースファイルへのパスを指定してimportすることができます。 From 3a63c9260e515a15a93d40816d6062451bd59abf Mon Sep 17 00:00:00 2001 From: FineArchs <133759614+FineArchs@users.noreply.github.com> Date: Wed, 30 Oct 2024 11:25:29 +0900 Subject: [PATCH 3/5] Create parser.md --- docs/host/parser.md | 51 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/host/parser.md diff --git a/docs/host/parser.md b/docs/host/parser.md new file mode 100644 index 00000000..9c42f701 --- /dev/null +++ b/docs/host/parser.md @@ -0,0 +1,51 @@ +# AiScript 構文解析 +AiScriptコードの構文解析を行い、[AST](#AST)と呼ばれるオブジェクトに変換します。 +基本的にはstaticメソッドである`Parser.parse(input)`を利用していれば問題ありません。 +後述のプラグイン機能を使用する場合はParserクラスのインスタンスを作成する必要があります。 + +### Parser.parse(input) + + + + +
引数名型(Typescript)
inputstring
返り値Ast.Node[]
+ +```js +import { Parser } from '@syuilo/aiscript'; +Parser.parse("<: 'Hello AiScript!'"); +``` + +## AST +構文木と呼ばれるオブジェクトです。 + +### type AST + + +## プラグイン機能 +> [!NOTE] +> 未整備の機能であり、ホスト側が利用するには機能が足りていないと考えられています。 + +構文解析後にAstのバリデーションや変形を行う機能です。 +プラグイン機能を使用する場合は`new Parser()`でParserクラスのインスタンスの作成を行う必要があります。 +### Parser() constructor +コンストラクタ引数はありません。 +```js +import { Parser } from '@syuilo/aiscript'; +const parser = new Parser(); +``` + +### Parser.prototype.parse(input) + + + + +
引数名型(Typescript)
inputstring
返り値Ast.Node[]
+ +```js +import { Parser } from '@syuilo/aiscript'; +const parser = new Parser(); +parser.parse("<: 'Hello AiScript!'"); +``` + +### Parser.prototype.addPlugin(type, plugin) + From 44f65243bad1c078b055a7e1118615c81d142101 Mon Sep 17 00:00:00 2001 From: FineArchs <133759614+FineArchs@users.noreply.github.com> Date: Wed, 30 Oct 2024 11:32:36 +0900 Subject: [PATCH 4/5] Update api.md --- docs/host/api.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/host/api.md b/docs/host/api.md index 956649e4..7bde3cb9 100644 --- a/docs/host/api.md +++ b/docs/host/api.md @@ -15,7 +15,8 @@ 詳しくは→[host/parser.md](./parser.md) ### Ast -Parserによって生成される構文木です。 +※Typescript用 +Parserによって生成される構文木(AST)に関連する型がまとめられています。 詳しくは→[host/parser.md#AST](./parser.md#AST) ### ParserPlugin, PluginType @@ -32,7 +33,7 @@ ASTを順次読み取り、実行します。 ### Scope > [!NOTE] -> 未整備の要素であり、ホスト側が利用するには機能が足りていないと考えられています。 +> ホスト側が利用する機会はほとんど無いと考えられています。 AiScript内の変数を保持・管理するネスト可能なオブジェクトです。 詳しくは→[host/interpreter.md#スコープ](./interpreter.md#スコープ) From 8c4708210c072516bfe2a57afb38c42dbf691812 Mon Sep 17 00:00:00 2001 From: FineArchs <133759614+FineArchs@users.noreply.github.com> Date: Wed, 30 Oct 2024 11:35:10 +0900 Subject: [PATCH 5/5] Update parser.md --- docs/host/parser.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/host/parser.md b/docs/host/parser.md index 9c42f701..9fa35785 100644 --- a/docs/host/parser.md +++ b/docs/host/parser.md @@ -1,6 +1,6 @@ # AiScript 構文解析 -AiScriptコードの構文解析を行い、[AST](#AST)と呼ばれるオブジェクトに変換します。 -基本的にはstaticメソッドである`Parser.parse(input)`を利用していれば問題ありません。 +AiScriptコードの構文解析を行い、[AST](#AST)と呼ばれるオブジェクトに変換する方法について説明します。 +基本的にはstaticメソッドである`Parser.parse(input)`を利用するだけで問題ありません。 後述のプラグイン機能を使用する場合はParserクラスのインスタンスを作成する必要があります。 ### Parser.parse(input)