diff --git a/docs/host/api.md b/docs/host/api.md new file mode 100644 index 00000000..7bde3cb9 --- /dev/null +++ b/docs/host/api.md @@ -0,0 +1,66 @@ +# 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 +※Typescript用 +Parserによって生成される構文木(AST)に関連する型がまとめられています。 +詳しくは→[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することができます。 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); +``` diff --git a/docs/host/parser.md b/docs/host/parser.md new file mode 100644 index 00000000..9fa35785 --- /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) +