readme.txt

AKARI as SAORI

もっしょくし氏が公開していた灯 as SAORIを
誠に勝手ながらInternet Archiveよりサルベージして
メンテナンス・再配布しております。

再配布者：Don
　サイト：https://nikolat.github.io/

Donが加えた変更部分のライセンスはパブリックドメインとします。

以下、オリジナルのreadmeです。(メールアドレスのみ消去しております)


灯 as SAORI　2016.05.24

●=責任者情報===================================================================
　名　前：もっしょくし
　サイト：http://gallnuts.webcrow.jp/
　メール：

【お願い】
　★builtin.azrについて
　　json系・sprintfのよい実装を閃いた方は教えてください。
　　それ以外にもsaoriとしてはあんまり意味のない各種関数のよい実装アイディアください。
　　それと以下の関数は自分でほとんど試してないので、動作報告お待ちしてます。
　・mail系関数
　・db系関数
　・ftp系関数

●=概要=========================================================================
　un氏制作のSHIORIである「灯」を、
　SAORIとして利用するのに便利なように準備したものです

　灯はユニークな機能を多数備えています
　単にそれらがSAORIとして使えるだけでも面白そうであり、
　また灯で書いたスクリプトを容易にモジュールとして組み込める土台があれば
　もっと面白い事ができるだろうと踏んで、勝手ながら作ってみました

　夜天燈火（「灯」開発元）
　http://le.silk.to/

　色々とYAYA as SAORIを参考に（≒丸パクリ）しています
　使い勝手も意図的に近づけている部分があります
　[YAYA as SAORI　⇒　http://navy.nm.land.to/post/]

●=このセットに含まれるファイル=================================================
・akari.dll	灯本体（灯 as SAORIが対応しているバージョンのもの）
・main.azr	灯 as SAORI　システム辞書
・builtin.azr	灯ビルトイン関数転用モジュール
・akasaori.csv	モジュール辞書設定用CSVファイル
・readme.txt	現在お読みの説明書き

　※akari.dll以外はメモ帳などのテキストエディタで開けます

●=使い方の基本=================================================================
1,akari.dllを、ゴーストのSHIORIに応じた適切な方法でSAORIとして使えるようにする
　※参考：里々の場合
　　http://soliton.sub.jp/satori/index.php?SAORI#tee642d7
2,akari.dllと同じディレクトリに、
　「main.azr」「akasaori.csv」「builtin.azr※」を設置する
　※灯ビルトイン関数をSAORI機能として使わない場合は不要
3,ゴーストのSHIORIに応じた適切な方法で機能を呼び出して使う
　呼び出しの際は
　・Argument0に「呼び出す関数の名前」
　・Argument1以降に「その関数に渡す引数」
　を指定する
　※参考：里々で（akari）でakari.dllを呼ぶように設定してある場合
　（akari,hoge,引数1,引数2）
　（akari,ftp_login,ftp.huga.com,user,secret,21）
　というような具合になります

●=builtin.azrについて==========================================================
　灯のビルトイン関数をSAORI機能として利用するためのモジュールです
　灯ビルトイン関数名の先頭のアンダーバーを抜いたものがそれぞれ対応するSAORI機能です
　関数の一覧およびその機能については、下記公式マニュアルもお読みください
　http://le.silk.to/akari.php


▼諸注意
・SSP以外で動作を確認していません
・SAORIとしての引数や戻り値は全て単に文字列として扱われます
　本来辞書型や配列型の値を扱う関数については、
　モジュール側で変換を行っていますので、注意してください
・SAORI機能としては無意味な物・用途が非常に限られるものも含みます
・ダイアログボックスやポップアップメニューを展開する関数では、
　SAORI側で入力待ちの状態になるため、SSPのinfoレベルのエラーが発生します
　影響について精査していませんが、SAORIを呼び出すイベントの性質によっては
　思わぬ影響がある可能性があります
・builtin.azr内各関数のコメントにも、参考にできる情報がある場合があります

●=特殊なSAORI機能==============================================================
　以下の関数がSAORI機能として予め用意されています
・AKASAORI.SYSFUNC.LOADEDCSV
　設定ファイルにinclude先として指定されており、
　load時に読み込まれたCSVファイル名が、カンマ区切りで返却されます
・AKASAORI.SYSFUNC.NFCSV
　設定ファイルにinclude先として指定されているが
　発見できなかったCSVファイル名が、カンマ区切りで返却されます
　全て読み込まれていれば空が返ります
・AKASAORI.SYSFUNC.LOADEDMOD
　設定ファイルにmoduleとして指定されており、
　load時に読み込まれた灯辞書ファイルが、カンマ区切りで返却されます
・AKASAORI.SYSFUNC.NFMOD
　設定ファイルにmoduleとして指定されているが
　発見できなかった灯辞書ファイルが、カンマ区切りで返却されます
　全て読み込まれていれば空が返ります

●=追加モジュール===============================================================
　灯辞書ファイルを、モジュールとして追加できます
　追加したい灯辞書ファイルは、akasaori.csvに追記する必要があります
　書式は以下の通りです

module,[モジュールファイル名]

　※拡張子は除いてください（.azr固定）
　※絶対パスおよびakari.dllからの相対パスが指定可能です
　※文字コードはShift-JISのみ有効です

　また、以下のようにakasaori.csvから他のcsvを指定して、
　そのcsvについてakasaori.csvと同様に読み込む事も可能です

include,[csvファイル名]

　※拡張子は除いてください（.csv固定）
　※絶対パスおよびakari.dllからの相対パスが指定可能です
　※読込先csvにさらにincludeを書いても構いません
　※include先のモジュール辞書の読み込み順序は、
　　書いた位置に関わらず現在読み込み中のcsvファイルにあるものの後になります
　※文字コードはShift-JISのみ有効です
▼凡例
/********************************************************/
// 与えられたSAORI引数0番をオウム返しするだけの関数
// 引数が空だとエラーを返す
int ECHO()
{
	if(REQ["ARGS"][0] == nil) return -1 ;
	RES["RESULT"]=REQ["ARGS"][0];

	return 1 ;
}
/********************************************************/
▼関数としての戻り値
・ここでいうのはSAORIの実行結果としての戻り値ではなく、
　各モジュール関数が灯asSAORIシステム部に対してreturnする値についてです
・呼び出された関数が正常に処理された場合は、「1」を返してください
　"200 OK"というステータスと、後述するSAORI戻り値をSHIORIに返却します
・もし「-1」が返ると、SAORIは今回の要求が不正なものであったとして
　"404 Bad Request"というステータスをSHIORIに返却します
　関数の実行上適さない引数が渡された場合等は、-1を返してください
・もし「0」が返ると、SAORIは今回要求された内容について返却すべき内容はないとして
　"204 No Content"というステータスをSHIORIに返却します
・戻り値に帰結しないような処理はステータスに関わらず実行される場合があります
　例えば関数中で灯ビルトイン関数_mouserightclick()が正常に実行されれば
　最終的なステータスに関わらずその場でマウス右クリックが実行されます
▼SAORI引数
・呼び出された関数の引数は、関数内で変数「REQ["ARGS"][N]」として利用できます
　Nは0以上の整数です
・逆に言うと、通常の形式では引数が渡されませんので注意してください
・引数は全て文字列型で渡されますので、関数ごとに適宜変換してください
▼SAORI戻り値
・SAORIからの戻り値は、モジュール内で辞書型変数「RES」の要素として設定します
　戻り値には単数戻り値（Result）と複数戻り値（ValueN）の二種類があります
　それぞれ「RES["RESULT"]」「RES["VALUE"][N]」という辞書型変数の要素が対応します
　状況に応じて使い分けてください
・複数戻り値RES["VALUE"][N]への代入は、単に
　RES["VALUE"][0] = 値0
　ではできません。順番に
　RES["VALUE"] += 値0
　RES["VALUE"] += 値1
　:
　とするか、
　RES["VALUE"] = {値0,値1,...}
　とします。
・それぞれの戻り値は全て文字列型に変換される点に注意してください
・関数が0や-1をreturnすると、これらの戻り値はSHIORIに返却されません
　※前出の「▼関数としての戻り値」参照
▼モジュールロード・アンロード
　関数名を○○.××というように、ドットで区切られた名前にすると
　同一の○○.から始まる関数がakari.dllロード後初めて呼ばれたタイミングで
　「○○.ModLoad」
　という関数の呼び出しを試みます
　またakari.dllのアンロード時に、今回呼び出された全ての種類の「○○.」について
　「○○.ModUnload」
　という関数の呼び出しを試みます
　モジュール内関数共通の初期化・後始末等が必要な場合に利用してください
▼使用できない関数名
　load,unload,_customrequestの3つおよび、「AKASAORI」から始まる関数名は
　灯 as SAORIのシステムで使用するためモジュール側では使えません
　これらの関数名が呼ばれた場合、モジュール内にあったとしても、
　SAORI呼び出しに対して"204 No Content"を返却します（※）
　※前出の「特殊なSAORI機能」の章で触れる関数は例外的に呼び出せます
▼使用できない変数名
　以下の変数名はシステムでグローバル変数として定義しているため、
　前出のSAORI戻り値の設定以外では、
　基本的に値を破壊しないように注意してください

　AKASAORI
　REQ
　RES

　他、灯の予約語にも気を付けてください
▼その他
　main.azr内には以下のような関数があります
　状況によってはモジュール側でも利用できるかもしれません
・string AKASAORI.TOOL.Join(array 配列 , string 区切り字（省略時「,」）)
　配列型の値の各要素間を指定した区切り字で連結した文字列にして返します
　要素の中身として配列型・辞書型の値は使えません
　⇒それぞれ　要素からランダムに択一/空文字列化　されます
・string AKASAORI.TOOL.JoinDict(array 配列 , string 辞書要素間の区切り字（省略時「,」） , 辞書のキーと値の間の区切り字（省略時「:」）)
　辞書型の値の各要素間およびキー・値間を指定した区切り字で連結した文字列にして返します
　要素の並びは灯の_dickeyget関数に依存（たぶんunicode辞書順）します
　値として配列型・辞書型の値は使えません
　⇒それぞれ　要素からランダムに択一/空文字列化　されます
・AKASAORI.TOOL.PopMes(string 表示するメッセージ)
　SAORIモジュール内で、灯の_popmes関数を使うと、
　処理がベースウェアに戻らなくなりSSPがinfoレベルのエラーを通知し続けてしまうので、
　別スレッドで_popmesを実行するようにしただけのもの

●=更新履歴=====================================================================
　2016.05.24　同梱dllを灯ver2.003に変更
　　　　　　　builtin.azrを同verまでに追加の大体の関数に対応（一部SAORIとしては無意味な関数含）
　　　　　　　json系およびsprintfは対応見送り
　2013.09.25　ライセンス的に問題ないと判断し、akari.dllをパッケージに同梱
　　　　　　　GET Versionで灯の現versionをResultとして返却するように
　　　　　　　version,に対応
　　　　　　　（sprintfとjson系はどんな形式がよいか思いつかないので保留……）
△---ver1.977対応
　2013.04.08	βテストと題して公開
△---ver1.9733対応