N6XBasicChecker.txt

N6XBasicChecker マニュアル
by eighttails
http://eighttails.seesaa.net

【 概要 】
N6XBasicCheckerは、PC-6001/6601シリーズ用のBASICリスト静的構文チェッカーです。
通常、BASICはインタプリタ言語であるため、シンタックスエラーはその打ち込みミスが
ある行を実行するまで発見できません。
つまり、プログラムに打ち間違いが無いことを保証するには、目視でくまなく確認するか、
すべての行を漏れなく実行するようカバレッジテストを行う必要があります。
これは、AVGやRPGなど、リストが長くプレイ時間が長いゲームでは大きな負担になります。
N6XBasicCheckerは、プログラムを実行せずにリスト全体をチェックして、打ち間違いを
見つけてくれるツールです。

【使い方】
■基本
このツールは、PC-6001の実機やエミュレーター上で動かすものではありません。
isioさん作の、「txt2bas」用に記述されたテキストファイルを、
Windows(またはLinux)上で解析します。

使い方は、コマンドライン上で
Usage: N6XBasicChecker ファイル名 [オプション]
と入力してください。

チェック対象のプログラムが、どのモードで動くのかを指定するスイッチはありません。
チェッカー内部の文法は、モード1〜6までのすべての命令を網羅した
スーパーセットになっています。
なので、モード1用のプログラムでＩＦ〜ＴＨＥＮ〜ＥＬＳＥとか書いても通ってしまいますが、
雑誌掲載のプログラムなら基本的にそういうことはないので、目をつぶってください。

エラーが見つからなかった場合、「Ok」とだけ表示されます。
エラーが見つかった場合、以下のようなメッセージが表示されます。
エラー:
テキスト行:8 BASIC行:80 シンタックスエラー[80 FORI=0TO10.....]
警告:
テキスト行:32 BASIC行:910 変数[R]はどこからも参照されていません
Ok

テキスト行とは、テキストファイル上の物理的な行番号です。
BASIC行とは、BASICリスト上の行番号です。
行の先頭が数字で始まっていない場合など、BASIC行番号が認識できなかった場合は
N/Aと表示されます。

時には「部分シンタックスエラー」というエラーが出る場合があります。
これはFOR〜NEXT文など、いくつかのブロックで構成されている文の場合、
分割して構文解析を行なっており、そこでエラーになった場合に出るエラーです。
基本的な対処法は通常のシンタックスエラーと変わりません。

エラーが出たらテキストエディタで修正して、またチェッカーにかけて、を
エラーが出なくなるまで繰り返します。

■オプション
オプションは以下のものが使用できます。
  -h [ --help ]         ヘルプを表示
  -v [ --version ]      バージョンを表示
  -u [ --utf8 ]                  出力をUTF-8でエンコード
  -l [ --list-variables ]        変数一覧を出力
  -p [ --play ] arg     PLAY文としてパースする行
  -t [ --talk ] arg     TALK文としてパースする行
  -x [ --hex ] arg      16進数としてパースする行
  -d [ --digit ] arg    10進数の整数(符号付き)としてパースする行
  -b [ --output-mode ] arg (=5)  テープイメージ出力モード(5または6。省略時は5)
  -o [ --output-file ] arg       テープイメージ出力ファイル
  -f [ --basic-file ] arg (=t2b) テープイメージ内のBASICリストファイル名
p,t,x,dオプションの行番号指定例: -p 100,200-300
b,o,fオプションの書式: -b 5 -o 出力ファイル名 -f BASICリストファイル名

p,t,x,dオプションは、指定した行番号の範囲内の文字列リテラルおよびDATA文を
特定のルールに基づいてチェックするための物です。

PLAY文を例にとると、
10 PLAY"CDE"
のようにPLAY文内に直接MMLが記述されている場合、
N6XBasicCheckerはMMLの文法もチェックしますが、
10 A$="CDE":PLAY A$
のように、変数やDATA文に記述されているMMLをチェックしたい場合、
明示的にこの行がMML(PLAY文)であることを指定する必要があります。
この場合、"-p10"というオプションをつけることで、10行内部の
文字列リテラルはMMLであるとみなしてチェックを行います。

x,dオプションはDATA文のチェック用(主にOCR対策)です。
マシン語やキャラクタ、マップデータ等に10進、または16進数
以外の文字が混入していないかチェックします。
dオプションは-(ハイフン)を許容します。

p,t,x,dオプションには複数の行、および範囲を指定できます。
例: -p100,200-300
この例では100行と200行から300行の間をMMLとしてチェックします。

b,o,fオプションはチェックしたBASICリストファイルをp6形式のテープイメージとして出力します。
(txt2bas相当の機能)
bオプションはBASICモードです。モード1から5用の場合は5,モード6用の場合は6を指定してください。
fオプションはテープイメージ内のファイル名です。半角英数字6文字以内で指定してください。
全角記号やかなを入力した場合の動作は無保証です。
テープイメージ出力に最低限必要なのはoオプションで、oオプションが指定されて
b,fオプションが指定されない場合デフォルトの値(モード5用、ファイル名t2b)が使用されます。

lオプションは変数ごとにその変数に代入している行、参照している行のリストを出力します。
FORループのカウンタとして使われている変数は代入だけされて参照している行がないというケースがありえます。

uオプションはWindows上でプログラムの出力をUTF-8にエンコードして出力します。
MSYS2のようなUTF-8のターミナル環境で利用する場合に指定してください。

【今後の予定】
■予定していること
とりあえずこれでひとまず完成とし、
今後はバグフィックスのみの予定です。
GUI版も作ろうかと思っていましたが、このツールの性質上
1回のプログラム打ち込みに対して2～3回しか使わないので、
UIの操作性をあげてもしょうがないかと思い、見送ることにしました。

■対応しないこと
1）値の範囲チェック
　例えばCONSOLE文の各パラメータの値の範囲は、BASICモード、SCREENモード、
　他のパラメータの値など、取りうる値を決めるための条件が複雑すぎるので、
　値の範囲チェックは行いません。
2）エラー位置の詳細な表示
　tst2basの入力ファイルはShift-JISで、全角文字が使える仕様ですが、
　構文解析器内部では前処理として、SJIS→UTF16変換、全角→半角変換を行なっており、
　エラーの出た箇所が元のファイルのどこに位置するのかを特定するのが困難です。
　また、エラーの出た箇所（構文解析器が手詰まりを起こした箇所）は
　必ずしも人間が打ち間違えた箇所とは一致しません。
　P6erなんだから、行番号だけ表示したら後は自分でチェックしてくれるでしょ？ｗ
3)エラー内容の詳細表示
　現状出るエラーはシンタックスエラーのみですが、P6ではこれ以外のエラーは
　基本的に実行時エラーなので、将来的にエラーの種類が増える見込みはあまり無いです。
　(バージョン1.1で、?UL Error相当のエラーには対応しました)
4）行の長さチェック
　1行の最大長はモードによって違うのと、前述の理由により行の長さの算出が困難なので、
　チェックをする予定はありません。

【更新履歴】
ver. 1.8.0　2021/5/30
機能追加
・UTF-8エンコーディングで結果を出力するオプションを追加

ver. 1.7.1　2019/10/9
バグ修正
・KANJI文で色コードを省略した場合にエラーとなるのを修正
・txt2basのバグ(SGNの引数が正しく処理されない)修正を取り込み

ver. 1.7.0　2019/1/16
機能追加
・変数一覧出力機能で変数の代入、参照している行を別々に出力するようにした。

ver. 1.6.0　2018/11/23
機能追加
・変数一覧出力機能を追加
バグ修正
・「IFA=&H01ANDB=&H00」といったような16進数リテラルの後にANDが入ると
　「&H01A」までが16進数リテラルと判定されてその後の構文解析に失敗する不具合を修正。
・最近の開発環境(GCC7.2,Boost1.64以降)でコンパイルが通るように修正

ver. 1.5　2014/02/21
機能追加
・isio様作のtxt2basの機能を取り込み
　-b,-o,-fオプションの組み合わせでp6形式のテープイメージを出力することができます。
　txt2basのバイナリが同梱されていますが、N6XBasicChecker単体でイメージ出力ができるので
　特に同じフォルダにおいておく必要はありません。
・txt2bas,bas2txtを同梱
　モード6のプログラムに関する不具合を修正しています。
バグ修正
・モード6のリストで’(アポストロフィ)によるコメントが行の途中にあるとエラーになるのを修正　
　
ver. 1.2　2012/11/05
機能追加
・PLAY文、TALK文のチェックを追加
　ただし、技術的な制約、マニュアルに書いてない仕様、モード5と6の仕様の違い、手抜きなどの理由により
　チェックはかなり緩いです。
　また、TALK文は"性別　速さ　本文"というフォーマットを満たしていることをチェックしているので、
　文字列変数の連結などでTALK文を組み立てている場合、正しく打ち込んでいてもエラーが出る場合があります。
・p,t,x,dオプションの追加

ver. 1.1　2012/08/11
機能追加
・警告の追加
　　エラーの他に「警告」というメッセージ種類を追加しました。
・変数の代入、参照チェック
　　例えば、S=STICK(0)という文を打ち間違えて、
　　S=STOCK(0)と打ち込んでしまった場合、これは数値型の配列変数として解釈され、エラーになりません。
　　今回のバージョンで、代入だけされて参照されていない変数、またはその逆を検出できるようにしました。
　　例外として、FOR文のループカウンタとしてしか使われていない変数は、どこからも参照されていなくても
　　警告を出しません。
　　USR()とRND()関数については、戻り値を受けるためのダミーの変数を用意するケースが多いですが、
　　現時点では、これらは全て警告が出ます。ご了承ください。
　　また、3文字以上の変数名で、2文字目までが一致しているものが複数ある場合、警告を出すようにしました。
・行番号の整合性チェックを追加(?UL Error相当エラーの検出)
・GOTO,GOSUBの後に余分な記述があった場合に警告を出すようにした。
　(実行時エラーにならないので、この挙動を利用してコメントなどを入れる人がいるが、
  GOTOの後のコロンが抜けた場合、次のステートメントが実行されない事態になるため)

バグ修正
・半角カナ記号の一部に対応していなかったのを修正。
・内部トレースが出力されることがあったのを修正。
・正常なIF文でエラーが出ることがあったのを修正。


ver. 1.01　2012/07/24
バグ修正
・内部文字コードをUTF-8からUTF-16に変更。
　(WindowsXPで、全角文字がリストに含まれているとエラーになるのを修正)
・ファイル名を複数指定するとクラッシュするのを修正。

ver. 1.0　2012/07/18
初版

【ライセンス、免責事項】
このプログラムのソースコード及びバイナリは無保証です。
このプログラムを使用したことによるいかなる損害も作者のeighttailsは責任を持ちません。
その点だけ了解していただければ、ソースコードは自由に使っていただいて構いません。
改造して他機種用のチェッカーを作ったり（他にテキストファイルが入力できるエミュレーターが
あるのかは知りませんが）、こいつを拡張してBASICコンパイラを作ったりしてもOKです。ていうか作って…。

【開発者情報】
本プログラムはgccまたはMinGWでのコンパイルを想定しています。
VisualC++でのコンパイル確認はしていません。
プログラム本体にはBOOSTライブラリを使用しています。
開発環境およびユニットテストにQtを使用していますが、プログラム本体は
Qtには依存していません。
以下にビルド手順を記します。

■Windows
最低限必要なのがGCC,QtSDK,Boostです。
これらを個別にダウンロードしてもビルドできますが、MSYS2環境を利用するのが簡単です。 

https://github.com/msys2/msys2-installer/releases からMSYS2をダウンロードしてインストールしてください。
VC++はサポートしていません。

MSYS2はパッケージのバージョンアップが早く、またバージョンアップによるデグレードが非常に多いため、パッケージのアップデート(`pacman -Sy`)を行わず、バージョンを固定して使うことをおすすめします。作者がビルド、動作を確認しているのは以下のインストーラーで構築した環境です。(64ビット用)
https://github.com/msys2/msys2-installer/releases/download/2021-01-05/msys2-x86_64-20210105.exe
MSYSをインストールしたフォルダのmingw32.exe(32ビット版をビルドする場合)またはmingw64.exe(64ビット版をビルドする場合)を実行。

ダウンロードしたN6XBasicCheckerのソースをMSYS上のホームフォルダに解凍。
`cd N6XBasicChecker/win32` を実行し、ソースフォルダのwin32フォルダにカレントを移動。
`./buildrelease.sh` を実行すると、N6XBasicChecker-build-(i686|x86_64)-w64-mingw32というフォルダにEXEがビルドされます。

■Linux
2018年11月時点でのDebian sidでの手順です。
rootで
apt-get install qtcreator libboost-all-dev
を実行し、開発環境をインストールします。
N6XBasicCheckerのソースを解凍して、N6XBasicChecker.proをQt Creatorで開きます。
後は普通にビルドすればOKです。

【謝辞】
文字コードの変換には、道化師様のBABELというライブラリを使わせていただきました。
この場を借りてお礼申し上げます。
http://tricklib.com/cxx/ex/babel/

txt2bas,bas2txtを作成されたisio様にお礼を申し上げます。
http://retropc.net/isio/

その他、P6のBASICマニュアルに載ってない仕様についてご教示くださったP6erの皆様にも
お礼申し上げます。