nadesiko3 3.2.27

package/doc/SETUP.md

@@ -0,0 +1,172 @@
+# なでしこ3 - 開発環境のセットアップ方法
+
+[![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://standardjs.com/)
+
+なでしこ3自身を開発する手順をまとめたもの。なでしこ3を使うだけならば、以下の手順は不要。
+
+[Node.js](https://nodejs.org/ja/)をインストールしておく。
+
+コマンドラインから以下を実行して、必要なライブラリをシステムにインストール。
+
+このとき、npm installするときに、なでしこのモジュールで、Native Add-onを使うものがあるため、ビルド環境を整える必要がある。
+
+## 【Windows】
+
+コンパイル環境が必要になるので、ビルドツールをインストールする。PowerShellから以下のコマンドを実行すると、自動的に必要なツールが入る。(Windowsのユーザー名に日本語が使われているとうまくコンパイルできないという情報もあるので注意)
+
+また、Gitなどのツールをインストールするために、Chocolatey( <https://chocolatey.org/> )をインストールしておく。
+
+```bach
+# Chocolatey でGitをインストール
+cinst git
+
+# npm のビルドツール (build tools+python2)
+npm install -g node-gyp
+npm install -g windows-build-tools
+```
+
+## 【macOS】
+
+Homebrew( <https://brew.sh/index_ja> ) (そしてXcode)をインストールしておく。
+
+## 【共通】
+
+コマンドラインから以下を実行して、nadesiko3のリポジトリをcloneし、必要なライブラリをインストール。ただし、Node.jsのバージョンv10以上が必要。もし、Ubuntuで古いのNode.jsをインストールした場合など、nモジュールを利用して最新安定版のNode.jsを利用してください。
+
+```bash
+git clone https://github.com/kujirahand/nadesiko3
+cd nadesiko3
+npm install --no-optional
+```
+
+コマンドラインから以下のコマンドを実行することで、ソースコードをビルドできる。
+srcディレクトリの中のコードを編集すると、releaseディレクトリに結果が出力される。
+
+```bash
+# Node.js用のソースコードをWeb用のJSに変換
+npm run build
+```
+
+ビルド後に以下のコマンドを実行することで、 バンドルファイル内の各パッケージがどのぐらいの容量を占めているかを可視化できる。
+
+```bash
+# バンドルファイル内の各パッケージがどのぐらいの容量を占めているかを可視化
+$ npm run analyze
+```
+
+開発時、以下のコマンドを実行すれば、監視ビルドさせることができる。
+
+```bash
+npm run watch
+```
+
+また、コマンドラインから以下のコマンドを実行することで、ソースコードをテストできる。
+
+```bash
+npm run test
+```
+
+## 開発時の約束
+
+### コーディング規約について
+
+コーディング規約は、[JavaScript Standard Style](https://standardjs.com/)に準拠するものとする。
+
+ATOMエディタを使っている場合は、以下のプラグインを導入すると非常に便利。
+
+```bash
+apm install linter
+apm install linter-js-standard
+```
+
+また、EditorConfigに対応しています。
+(詳しくは[どんなエディタでもEditorConfigを使ってコードの統一性を高める - Qiita](https://qiita.com/naru0504/items/82f09881abaf3f4dc171)を参照)
+これに対応したエディタを使用することで、開発者側が意識することなくインデントやタブに関する規則に対応することが可能。
+
+## コマンドラインからなでしこを使う方法
+
+なでしこ3ではコマンドラインからなでしこを実行できるcnako3(Windowsは、cnako3.bat)というスクリプトを用意。今後、なでしこの各種バッチファイルはなでしこ自身で記述される。
+
+ちなみに、`npm install -g nadeisko3` を実行すると、npmコマンドでcnako3コマンドが利用できるようになるが、その場合は安定版のなでしこがインストールされることになる。
+
+環境変数に本ファイルのパスをNAKO_HOMEとして登録し、パスをNAKO_HOME/srcに通す。以下、macOS/Linuxでの `.bashrc` の記述例。(ユーザー名がkujiraの場合)
+
+```bash
+HOME=/Users/kujira
+export NAKO_HOME=$HOME/nadesiko3
+export PATH=$PATH:$NAKO_HOME/src
+```
+
+### コマンドライン版なでしこの利用方法
+
+例えば、なでしこのコマンド一覧ファイルを生成するバッチを実行する方法。
+
+```bash
+cnako3 $NAKO_HOME/batch/pickup_command.nako
+```
+
+テストを実行する場合には、 `-t` (`--test`) オプションを付けてcnako3を実行します。
+
+### デモプログラムを動かす方法
+
+demoディレクトリに、なでしこをブラウザから使うデモがある。
+
+大抵の機能はブラウザにHTMLファイルをドラッグ&ドロップすれば動くが、一部の機能はローカルサーバーを動かさないと利用できない。
+
+なでしこでは、簡易サーバーを用意。コマンドラインで以下のように入力すると、[http://localhost:3000/](http://localhost:3000/)でサーバーが起動。
+
+```bash
+npm start
+```
+
+### 対応機器/ブラウザの生成
+
+コマンドラインから以下を実行して、以下のファイルを生成。
+
+* [doc/browsers.md](browsers.md): 対応機器/ブラウザ (マークダウン形式)
+* [src/browsers.md](../src/browsers.md): 対応機器/ブラウザ (マークダウン形式, cnako3用)
+* [demo/browsers.html](../demo/browsers.html): 対応機器/ブラウザ (HTML形式, なでしこ3エディタ用)
+
+```bash
+npm run build:browsers
+```
+
+### Node.jsのパッケージの更新方法
+
+コマンドラインから以下を実行して、Node.jsのパッケージを更新。
+
+```bash
+npm-check-updates -u
+npm update --no-optional
+```
+
+### Electron
+
+モジュールをインストールする。
+
+```bash
+npm install electron
+npm install electron-packager
+```
+
+以下のコマンドを実行することで、Electronによるなでしこが起動。
+
+```bash
+npm run electron
+```
+
+ビルドは以下のコマンドで行う。
+
+```bash
+npm run build:electron
+```
+
+## Gitからリポジトリを取得して利用する場合
+
+最低限のライブラリで良い場合には、``npm install --production``を実行するだけ。
+
+```bash
+git clone https://github.com/kujirahand/nadesiko3.git
+cd nadesiko3
+npm install --production
+```

package/doc/about.md

@@ -0,0 +1,34 @@
+# なでしこ3とは
+
+日本語のプログラミング言語「なでしこ」（第三版）は、現在、鋭意開発中です。 HTML/JavaScriptをベースとしているので、PC/スマホ/タブレットなど、さまざまな環境で動作させることができます。
+
+-[URL][なでしこ3/マニュアル](https://nadesi.com/doc3/)
+
+## 開発目標
+
+- (日本語の母語話者を対象とした) 母国語に特化したプログラミング言語
+- 教育用途に特化
+- ブラウザで手軽に試せること
+
+## どこまでできているのか
+
+- 簡単なWebエディタがあり、最小限の文字入力でプログラミングできる
+- 条件分岐、繰り返しなど、基本的な制御構文が実装されている
+
+## 対応機器/ブラウザ
+
+- HTML5対応ブラウザ (Internet Explorer / Safari / Chrome / Firefox等)
+- スマホブラウザ (iOS Safari / Android標準ブラウザ)
+- PC (Windows/macOS/Linux - Node.jsが動く環境)
+
+## 今後の開発物の予定
+
+- Web上で本格的なプログラムができるようにする
+- 動物やキャラクターを動かしたり、お絵かきしたりできるようにする
+- ラズパイ上で動かし、電子工作が楽しめるようにする
+- ライブラリやAPIなどモジュールを追加する
+- 教育・プレゼン用途
+- グラフの作成
+- 音を出す
+- PC向けバッチ処理ツールとして
+- なでしこv1で得たノウハウを、macOS/Linuxでも活用できるようにする

package/doc/browsers.md

@@ -0,0 +1,60 @@
+# 対応機器/ブラウザ
+
+* ブラウザ
+  * モバイル
+    * Chrome for Android
+      * 80
+    * Firefox for Android
+      * 68
+    * QQ Browser
+      * 1.2
+    * UC Browser for Android
+      * 12.12
+    * Android Browser
+      * 80
+    * Baidu Browser
+      * 7.12
+    * iOS Safari
+      * 13.3
+      * 13.2
+      * 13.0-13.1
+      * 12.2-12.4
+      * 12.0-12.1
+      * 11.3-11.4
+      * 10.3
+      * 9.3
+    * KaiOS Browser
+      * 2.5
+    * Opera Mini
+      * all
+    * Opera Mobile
+      * 46
+    * Samsung Internet
+      * 11.1
+      * 10.1
+  * PC
+    * Chrome
+      * 80
+      * 79
+      * 49
+    * Edge
+      * 80
+      * 79
+      * 18
+    * Firefox
+      * 74
+      * 73
+      * 72
+      * 68
+    * Internet Explorer
+      * 11
+    * Opera
+      * 66
+      * 65
+    * Safari
+      * 13
+      * 12.1
+* PC (Windows/macOS/Linux)
+  * Node
+    * 12.16.0
+    * 10.19.0

package/doc/docgen.md

@@ -0,0 +1,21 @@
+# なでしこ3のマニュアルについて
+
+なでしこ3の[マニュアル](https://nadesi.com/v3/doc/)はkonawiki3形式になっており、[こちら](https://github.com/kujirahand/nadesiko3doc)で保守されている。
+
+## 命令一覧ページ
+
+なお、[命令一覧ページ](https://nadesi.com/v3/doc/index.php?%E5%91%BD%E4%BB%A4%E4%B8%80%E8%A6%A7%2F%E6%A9%9F%E8%83%BD%E9%A0%86)の目次と概要は、マニュアル生成スクリプトにより生成されている。リポジトリ内のソースコードのマニュアルの自動生成は以下のコマンドで生成できる。
+
+```sh
+npm build:command
+```
+
+## 独自のプラグインの目次を生成するには
+
+独自のプラグインを作った場合、マニュアル生成機能を利用して、独自のマニュアルを生成できる。
+
+```sh
+cnako3 batch/jsplugin2text.nako3 /plugin/path/nadesiko3-xxx
+```
+
+生成したテキストは、konawiki3形式となっている。

package/doc/editor.md

@@ -0,0 +1,44 @@
+# エディタの仕様
+
+## 通常のエディタ
+
+HTMLに以下のコードを挿入することでエディタを実装できる。
+
+```html
+...
+<head>
+  <link rel="stylesheet" type="text/css" href="basic.css">
+  <link rel="stylesheet" href="../src/wnako3_editor.css">
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.12/ace.js"
+    integrity="sha512-GZ1RIgZaSc8rnco/8CXfRdCpDxRCphenIiZ2ztLy3XQfCbQUSCuk8IudvNHxkRA3oUg6q0qejgN/qqyG1duv5Q=="
+    crossorigin="anonymous"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.12/ext-language_tools.min.js"
+    integrity="sha512-8qx1DL/2Wsrrij2TWX5UzvEaYOFVndR7BogdpOyF4ocMfnfkw28qt8ULkXD9Tef0bLvh3TpnSAljDC7uyniEuQ=="
+    crossorigin="anonymous"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.12/ext-options.min.js"
+    integrity="sha512-oHR+WVzBiVZ6njlMVlDDLUIOLRDfUUfRQ55PfkZvgjwuvGqL4ohCTxaahJIxTmtya4jgyk0zmOxDMuLzbfqQDA=="
+    crossorigin="anonymous"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.12/ext-code_lens.min.js"
+    integrity="sha512-gsDyyKTnOmSWRDzUbpYcPjzVsEyFGSWeWefzVKvbMULPR2ElIlKKsOtU3ycfybN9kncZXKLFSsUiG3cgJUbc/g=="
+    crossorigin="anonymous"></script>
+</head>
+<body>
+  ...
+  <div class="editor-component">
+    <script type="application/json">
+      {
+        "title": "{タイトル (エディタのtitle属性)}",
+        "code": "{エディタに入力するコードの初期値}"
+      }
+    </script>
+  </div>
+  ...
+  <script src="../release/wnako3.js"></script>
+  <script src="../release/editor.js"></script>
+  ...
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/mocha/8.3.0/mocha.min.js"
+    integrity="sha512-LA/TpBXau/JNubKzHQhdi5vGkRLyQjs1vpuk2W1nc8WNgf/pCqBplD8MzlzeKJQTZPvkEZi0HqBDfRC2EyLMXw=="
+    crossorigin="anonymous"></script>
+</body>
+...
+```

package/doc/files.md

@@ -0,0 +1,37 @@
+# なでしこを構成するファイルたち
+
+## src/nako3.js
+
+なでしこコンパイラ本体。なでしこのソースコードをJSに変換する。変換処理は、以下のように行われる。
+
+- なでしこソース
+- 構文木(中間表現)
+- JavaScriptソース
+
+## src/nako_prepare.js
+
+なでしこのソースコードの前置処理を行うもの。主に全角半角の変換処理を行う。
+
+## src/nako_parser3.js
+
+なでしこ構文から構文木を生成するもの。
+
+## src/nako_gen.js
+
+構文木を元に、JavaScriptのコードを生成するもの。
+
+## src/plugin_xxx.js
+
+なでしこの命令を定義したプラグイン。
+
+## src/cnako3.js
+
+バッチファイル実行用。コマンドラインのインタフェースを実装するモノ。
+
+## src/wnako3.js
+
+ブラウザ用。
+
+## src/enako3.js
+
+Electronによるアプリ本体。

package/doc/plugins.md

@@ -0,0 +1,195 @@
+# プラグインのAPIの仕様
+
+なでしこ3には、以下の二種類のプラグインがある。
+
+- (1) なでしこ3自身で開発したなでしこプラグイン
+- (2) JavaScriptで開発したJSプラグイン
+
+なお、(1)のプラグインはなでしこ自身で関数を定義するだけである。
+以下では、(2)のJavaScriptで開発したプラグインについて解説する。
+
+## Webプラグインを利用する手順
+
+HTMLファイル内でなでしこ本体(wnako3.js)よりも後ろで`<script src="(JSプラグイン).js">`と記述して読み込む。
+
+なお「wnako3.js」を読み込むと、ブラウザの「navigator」オブジェクトにプロパティ「nako3」(navigator.nako3)にコンパイラのインスタンスが作成される。
+
+## プラグイン側の実装方法
+
+プラグインの実体は、Objectである。
+
+```js
+{
+  '定数名': { 定義 },
+  '命令名': { 定義 },
+  ...
+}
+```
+
+### 定義：関数
+
+プラグインの実体は、Object。実際の関数定義は、fnプロパティに行う。実際の関数の引数に加えて、システムを表すsysを用意する。
+
+```js
+{
+  '関数名': { // @関数の説明 // @ヨミガナ
+    type: 'func', // 関数であれば func にする
+    josi: [['を', 'から'], ['まで']], // 助詞を配列で宣言する (可変長引数として扱いたい助詞は末尾で宣言する)
+    isVariableJosi: false, // 末尾の助詞を可変長引数として扱う場合 true にする
+    uses: [], // この関数から別の関数を呼ぶ場合に記述する // (TODO: #282)
+    fn: function (aFrom, aTo, sys) { ... }, // 関数の実態
+    return_none: false // 戻り値を返すかどうか
+  },
+  ...
+}
+```
+
+なお、コメントを記述した場合、`npm run build:command`を実行すると自動的にコマンドマニュアルが生成される。
+
+### 定義：定数
+
+typeプロパティに「const」を指定して、valueプロパティに値を指定する。
+
+```js
+{ type: 'const', value: 100 } // @ヨミガナ
+```
+
+### 定義：変数
+
+typeプロパティに「var」を指定して、valueプロパティに値を指定する。
+
+```js
+{ type: 'var', value: 100 } // @ヨミガナ
+```
+
+### プラグインの自動登録
+
+プラグインの末尾に以下のコードを仕込むとscriptタグで読み込んだときシステムに登録できる。
+
+```js
+if (typeof (navigator) === 'object') {
+  navigator.nako3.addPluginObject(プラグイン名, オブジェクト)
+}
+```
+
+## 初期化メソッド
+
+以下のようなエントリを用意しておくと、プラグインを取り込み、初回実行するときに初期化メソッドが実行される。
+(ただし、プラグイン取り込み時に、 `!{プラグイン名}:初期化` というメソッド名にリネームされる)
+
+```js
+{
+  '初期化': {
+    type: 'func',
+    josi: [],
+    fn: function (sys) { ... }
+  }
+  ...
+}
+```
+
+## クリアメソッド
+
+以下のようなエントリを用意しておくと、プログラム終了時（あるいはクリア時）にプラグインごとプログラムが実行される。
+
+```js
+{
+  '!クリア': {
+    type: 'func',
+    josi: [],
+    fn: function (sys) { ... }
+  }
+  ...
+}
+```
+
+## プラグイン側からシステム変数へのアクセス
+
+関数を定義したとき、プラグイン関数側からシステムにアクセスしなければならない場合がある。
+以下は引数のない関数を定義した例だが、必ず必要とされる引数の末尾に実行したシステムのthisを保持するオブジェクトが渡される。
+このオブジェクトを参照することで、システム変数にアクセスできる。
+
+```js
+{
+  type: 'func',
+  josi: [],
+  fn: function (sys) {
+    console.log(sys)
+  }
+}
+```
+
+例えば、なでしこで管理されている変数「A」にアクセスしたいときは、以下のようなコードを記述する。なお、ローカル変数を参照するときpure: trueの関数は正しく動作しない。
+
+```js
+{
+  type: 'func',
+  josi: [],
+  fn: function (sys) {
+    const a = sys.__findVar('A')
+    console.log(a)
+  }
+}
+```
+
+そのほかに、なでしこ側で定義した関数「HOGE」を実行したいときは、以下のように記述する。
+
+```js
+{
+  type: 'func',
+  josi: [],
+  fn: function (sys) {
+    const result = sys.__exec('HOGE', [arg1, arg2, arg3, sys])
+    console.log(result)
+  }
+}
+```
+
+また、関数の引数に与える、sysはなでしこ自身を表す。
+もし、代入的関数呼び出し(setter)であれば、sys.isSetterにtrueの値が入る。
+
+なお、プラグインでは、以下のメソッドが使えるようになる。(すべてsrc/plugin_system.jsで定義されている。システム関数の初期化時に、これらの関数が追加される)
+
+- sys.__findVar(name)
+- sys.__exec(name, params)
+
+関数内で、システム・グローバル変数にアクセスするには、``sys.__v0['変数名']``でアクセスできる。
+
+なお、最後の助詞を可変長引数として扱う場合、システム変数は末尾の引数の末尾の要素として挿入される。
+
+```js
+{
+  type: 'func',
+  josi: [['は'], ['で']],
+  isVariableJosi: true,
+  fn: function (a, ...b) {
+    const sys = b.pop()
+    const result = sys.__exec('HOGE', [arg1, arg2, arg3, sys])
+    console.log(result)
+  }
+}
+```
+
+## 非同期モードに対応した関数を作る場合
+
+v3.2.22で導入された非同期モードに対応した関数を作るには、以下のように記述する。
+
+```js
+  fn: function (n, sys) {
+      if (sys.__genMode == '非同期モード') {
+        sys.async = true // 非同期モードを使うことを明示
+        setTimeout(() => {
+          sys.nextAsync(sys) // ここで非同期処理が完了した時にこの関数を呼ぶ
+        }, n * 1000)
+      } else {
+        // 非同期モードに対応していない時の処理
+        throw new Error('「!非同期モード」で使ってください')
+      }
+  }
+```
+
+- (参考)[秒待機](https://github.com/kujirahand/nadesiko3/blob/f3d51519aff77df04b0d9b1e29ed16914a3f0e74/src/plugin_system.js#L1808)
+
+## マニュアルを自動生成する
+
+- [doc/docgen.md](docgen.md) にマニュアル自動生成のスクリプトが紹介されている。

package/doc/release.md

@@ -0,0 +1,78 @@
+# なでしこv3のリリース手順
+
+なでしこv3の最新版を、Webにアップするまでの備忘録です。いつも、手順飛ばしてしまうので、忘れないようにメモ。特に、npm publishの部分とか。
+
+## 1.GitHubのリリース機能を使う
+
+ただし、リリース前（コミット前）には必ずテストを実行して、テストが成功するか確認する。
+
+```shell
+npm test
+```
+
+なお、よくエラーが出る部分で「ナデシコバージョン」で問題があれば、package.jsonのversion値とsrc/plugin_system.jsの変数番号が合っているかを確認する。
+
+## 2.必要なファイルをビルドする
+
+まず、リリース用にwebpackでパックしたソースを生成する(/releaseに生成物が作られる)。
+
+```shell
+npm run build
+```
+
+対応ブラウザを更新する。
+
+```shell
+npm run build:browsers
+```
+
+## 3.npmにpublish
+
+package.jsonのバージョン番号を更新したことを確認する。npm publishでnpmに公開する。
+
+```shell
+npm publish
+```
+
+## 4.Webにアップロード
+
+必要なら、WEB(nadesi.com/doc3)の簡易エディタを最新版に更新する。
+
+## 5.Webサイトで最新版を告知
+
+リリース内容を告知する。
+
+## 6.Windowsバイナリ版のアップロード
+
+Windows用のリポジトリ生成のためにファイルをnadesiko3win32へコピーする。ただし、事前準備として、 `git clone` でnadesiko3win32のリポジトリを取得しておく必要がある。
+
+```shell
+npm run build:win32
+bash ./win32.bash
+```
+
+nadesiko3win32のフォルダに移動。
+
+```shell
+cd ../nadesiko3win32
+```
+
+なお、Windowsで実行してモジュールの最新版を取得。
+
+```shell
+nodejs\npm install --production
+nodejs\npm audit fix
+```
+
+次に、7zipでモジュールを固める。
+
+```shell
+bin\7z  -mx=9 a node_modules.7z node_modules
+```
+
+最後にGitへアップする。
+
+```shell
+git commit -a
+git push
+```