shellmode.mac.txt

■注意：

　このマクロをインストールした場合、その性質上、悪意を持って作成されたファイルを開くだけで、ユーザの意図しない動作をすることがあります。
　基本的には、コマンドラインから開いたときはなるべくそういうことがないように注意して作っているつもりですが、完全でないかもしれません。
　また、自動起動マクロを設定している状態では、見慣れないファイルを開くときは十分に気をつけてください。

　同梱の shellmode.mac.ini.sample は、shellmode.mac.iniに改名(して所定のフォルダに保存)すれば、本マクロの設定ファイルとしてお使いいただけます。
　ただしこの場合、作者推奨値が設定されるため、意図しない動作をすることがあります。


■マクロの説明：

本マクロには以下のような機能があります。

* 現在編集中のファイルを実行する。
* shebang行の内容を読み、実行する。
* shebang次第で、範囲選択部分を実行するとか、範囲選択部分を対象に実行するとかできる。
* 上記の実行結果を逐次表示する。

...が初期の目的でしたが、「実行」つながりで以下のような機能もあります。

* 「マジックコメント」。自動起動マクロの時、コメント行内に所定の形式で記載された内容を実行する。
* ほかのエディッタで使われているマジックコメント、モードラインもなるべく解釈する。
(重複する内容はファイル末尾に近いものを優先。)
(と思ったけど、面倒くさいので、もっとも行頭に近いものだけを採用する。上の1行は今後のTODO。)


■用語の説明：

* コメント行

	　その行の1文字目から、秀丸上でコメントとして扱われている行。
	　デフォルトでは、shebang以外の、ファイル先頭末尾から連続したn（デフォルトは5）行以内に記載されているものが対象です。

	　たとえば、マクロファイルでは、4行目以外の1〜13行目までが「コメント行」だが、対象は「所定の形式」で記載されている2・3行であり、重複している"タブの文字数"については3行目の内容で設定される。4行目以降は「連続したコメント行」でないので対象外。

* 所定の形式

	　コメント行のうち、コメント指定文字以外の最初の文字が！で、直後に hm と数字と : があり、そこから : までの部分。
	　: 間の文字列がconfig文の引数になる。そのうち、最初の ; より末尾側にある文字列を秀丸マクロと見なして実行する。
	　小難しく書くと、以下のような感じ。

^[CMT]!hm[NUM[NUM]]: OPT[ ; MACRO] : [TEXT]$

  空白  タブか半角空白。省略可能。
  []    括弧内が(条件次第で)省略可能であることを示す。
  ^     行頭であることを示す。正規表現の ^ と同義。
  $     行末であることを示す。正規表現の $ と同義。
  CMT   コメント記号。省略してもコメントと見なされるのなら省略可能。
  NUM   「自動起動の対象となる数字」。
          2桁の場合は、2桁目がeventの値、1桁目がgeteventparamの引数と同義。
          1桁の場合は、eventの値と同義。
          省略された場合や有意でない数字の場合、その行は(デフォルトでは)無視される。
  OPT   config文の引数になる文字列。
  MACRO 「マジックコメントのマクロ部分」。省略可能。
        記載するなら、秀丸マクロとして解釈でき、かつOPTとの間の ; が必須。
  TEXT  任意のテキスト。省略可能。


■記載例：

　自動起動マクロに本マクロを指定し、以下のような内容が先頭5行以内（または設定により末尾5行以内）に記載されている秀丸マクロファイルを操作すると、「開いた直後に"すべて折りたたみ"」になっていたり「このファイルだけ"タブの文字数"が2」になっていたり、「終了時にこのファイルだけgitにコミットする」...とかできる。

//!hm1: t4; foldall; run "git.exe commit %f";:		← この行の「タブの文字数」は反映されない。∵↓で重複して設定。
//!hm1: t2:		← この行の内容(=タブの文字数が2)も反映される。
 //!hm31: t8:		← この行の内容は反映されない。∵先頭の1文字目からコメント扱いされていない。
//!hm31: t4:		← この行の内容は反映されない。∵コメント行が先頭から4行目で断絶している。
//


■設定ファイルの説明：

　各説明文中の[]で囲まれた単語は、設定ファイルにおけるセクション名です。
　各説明文中の''で囲まれた単語は、設定ファイルにおけるキー名(orその設定値)です。
　各説明文中の{}で囲まれた値は、その項目(キー)でのデフォルト値(設定ファイルで設定していないときにマクロで自動的に決める値)です。
　デフォルト値が明記されていない項目は、""か0がデフォルト値です。

[general]

shell:
	shenbang行に記載の内容を実行するシェル。
	　%sをshebangの内容に置換します。

find_cmark:
	(後述する[comment]にて)コメント指定文字が設定されていない場合、shebangやマジックコメントらしき行の行頭にある文字列をコメント指定文字と推定するか。(論理和で設定可能)

	　秀丸で「複数行コメント」を「なし」と設定している時は、実行されません。
	　推定に失敗すると、マジックコメントを探すときに影響が出る(探しきれない)恐れがあります。
	　shebang検索時には、"2"は無視されます。
	　数字の若い順で推定します。右辺値が 7 なら、1行目を探し、「マジックコメントの対象」行中から探し、なければ'common_cmark'を利用する...といったように。

	{0}	推定しない。
	1		shebangの ! 前の文字をコメント指定文字として利用する。
			1行目がコメント行であるとき、1文字目から!までに記号が1文字以上連続している(空白・タブを含まない)場合に、その連続した記号を対象とします。
	2		「マジックコメントの対象」行の先頭を利用する。
			「マジックコメントの対象」部分から、「マジックコメントの形式」に一致する部分を検索し、その行の行頭から連続する記号を対象とし、ファイル先頭に最も近い側のを利用します。
	4		'common_cmark'を利用する。

find_cmark_in_common_type:
	ファイルタイプが「共通」の時、コメント指定文字を推定する方法。(論理和で設定可能)

	　検索するときは、秀丸マクロでコメントと見なされる部分を対象にしますので、ファイルタイプが「共通」の時は意図しない部分が抽出される恐れがあります。
	　それ以外は、find_cmarkと同様です。

	{0}	何もしない。
	1〜	'find_cmark'と同様。

common_cmark:
	find_cmark、find_cmark_in_common_typeで、右辺値に 4 が含まれているときに使う文字列。

submac_dir:
	補助マクロの格納場所。

	　メイン(デフォルトのファイル名はshellmode.mac)マクロからの相対位置で指定する。
	　後述する[magiccomment]'other'の各文字と同一のファイル名を持ったマクロを保存する場所。詳細は後述する「■補助マクロについて」を参照。

verbose:
	冗舌モードにするか。

	{0}	静寂モード。なるべく問い合わせしない。
	1		冗舌モード。何かを実行する前に問い合わせをする。具体的にはそれぞれの設定値を参照。


[macrodll]
	macrodll.dllに関する設定を行います。

dir:
	macrodll.dllが存在するディレクトリ。
	　設定していない場合、マクロ起動後に設定できます。

set_log:
set_pos:
setfont_name:
setfont_size:
setsize_width:
setsize_height:
setcolor_font:
setcolor_back:
setcode_code:
start_x:
start_y:
	実行時のダイアログに関する設定。

	　たとえば、'set_log'は dllfunc("COMPILE_SET", "log", 〜)と設定されます。
	　コンパイル画面に表示するタイトル、実行する際のカレントディレクトリ(以上はマクロ中で設定します。)、コンパイル画面の強調表示、環境変数の指定は(本マクロの仕様として)設定できません。

	デフォルト値)
	setfont_size = {fontsize}
	setsize_width = {windowcx]
	setsize_height = {windowcy / 2}
	setcolor_font = {0xFFFFFF}
	setcode_code = {charset}


[event0]
	自動起動マクロとして実行されていないときの動作を指定します。

run_shebang:
	shebang行を実行するか(論理和で設定可能)。
	　冗舌モードの時は、実行する前に警告します。

	{0}	実行しない。
	1		実行する。
	2		特定のキーが押下されている場合のみ。

on_pressed:
	run_shebangに2が含まれている場合、「特定のキー」。

	　右辺値は、iskeydown関数の引数を指定してください。


[event]
	自動起動マクロとして実行するときの動作条件を指定します。

type:
	起動する種類。

	　種類ごとに、半角スペースで区切ってください。
	　2桁の場合、10位がevent、1位がgeteventparamです。(マクロヘルプ中の各項目を参照。)

	　たとえば"1 21 23"と設定した場合、「ファイルを開いた直後」ではいずれの条件でも起動されますが、「新規作成直後」では「外部から開いた」or「常駐秀丸エディッタから開いた」場合しか起動しません。
	　また、本マクロを自動起動マクロに登録していても、それに対応した数字をこの項目で設定していないと、実行しません。

run_macro:
	「マジックコメントのマクロ部分」を実行するか。(論理和で設定可能)

	{0}	しない。
	1		する。冗舌モードの時は、実行する前に警告します。


[magiccomment]
	マジックコメントの対象を指定する。実際に実行する条件は[event]で指定する。
	注意:秀丸で「複数行コメント」を「なし」と設定している時は、検索されません。

place:
	マジックコメントの対象となる場所。(論理和で設定可能)

	{0}	対象なし。マクロ終了。
	1		ファイル先頭。
	2		ファイル末尾。冗舌モードの時は、実行する前に警告します。

lines:
	マジックコメントの対象となる行数。

 {0}	対象なし。マクロ終了。
 1〜	ファイル先頭(and/or末尾)から設定行以内の部分を検索する。

default_event:
	マジックコメント中の「自動起動の対象となる数字」が省略されたときのデフォルト値。

	　「自動起動の対象となる数字」が省略された場合その行を無視しますが、1以上に設定すると、無視せずにその設定値が省略されていると見なして動作します。
	　「自動起動の対象となる数字」の意味は、同梱の説明ファイルを検索してください。

	　たとえば右辺値を 1 と設定した場合、「!hm:」は「!hm1:」と等価です。

	{0}	「自動起動の対象となる数字」がない場合、該当部分を無視する。
	1〜	数字がない場合でも無視せずに、右辺値が省略されていると見なして動作する。
			冗舌モードの時は、実行する前に警告します。
			意味をなさない数字(8や34など)を設定した場合、0 と同義。

other:
	本マクロ独自形式以外に検索する、他のマジックコメント形式。

	　形式ごとに、半角スペースで区切ってください。"e v r"みたいに。
	　設定した順で検索します。"e v r"と設定したら、"-*- 〜 -*-"形式を検索して、"vim: 〜 :"などの形式を検索して...という感じです。
	　各形式の詳細(正規表現)は、後述する'regex_〜'や'tagnum_〜'で設定できます。というか、必ず設定してください。
	　ユーザが任意の形式を追加できます。必ず一意の(ほかと重複しない)文字を設定してください。また、その文字に対する正規表現も、'regex_〜'や'tagnum_〜'の右辺にて設定してください。
	　さらに、[general]'submac_dir'で指定してフォルダに、ここで設定した文字と同じファイル名を持ったマクロ("e v r"と設定したら、e.macやv.macなど)を保存してください。マクロの詳細は、後述する「■補助マクロについて」を参照。

	同梱の設定ファイルサンプルでは以下の形式を設定しています。
	e		"-*- 〜 -*-"形式。
	v		vi(m)の"vim: 〜 :"などの形式。モードラインって呼ぶのかな？
	r		Rubyなどで使われる形式。

regex_〜:
	「他のマジックコメント形式」の詳細(正規表現)。

	config文の引数になる部分を () で囲ってください。
	　マクロ内で各右辺値の前に (コメント記号)? ? が付加されます。従って、前方一致・前方不一致は使えません。

	設定例)
	regex_e = -*- ?(.+) ?-*-
	regex_v = (vim?|ex): ?(set?)? ?([^:]+):?

tagnum_〜:
	「他のマジックコメント形式」の詳細でヒットした扱いにする場所。
	'regex_〜'でconfig文の引数になる部分を囲った () が、何番目の () か。

	詳細は、秀丸マクロの「目次− 検索系コマンド− 正規表現−ヒットした扱いにするタグ指定」を参照してください。

	設定例)
	tagnum_e = 1
	tagnum_v = 3

	補足:たとえば、
		regex_v = (vim?|ex): ?(set?)? ?([^:]+):?
		tagnum_v = 3
	と設定した場合、マクロが検索する文字列は次行のようになります。(MARKをコメント指定文字とする。)
		(MARK)? ?(vim?|ex): ?(set?)? ?([^:]+):?(?\4)
	このとき、([^:]+) に該当する部分が「ヒットした扱い」になり、この部分を利用して以降の処理を継続(補助マクロを利用して該当部分をconfig文が解釈しうるように変換)します。

after_shebang:
	shebang行のマジックコメントも対象とするか。
	　ただし、いかなる設定でもコメント記号の推定時には対象外となります。

	{0}	しない。
	1		shebang行の(コメント記号の)後ろも対象にする。

type:
	補助マクロの形式。
	　マクロ中で書き換えますので、手入力で設定しても意味がありません。


[comment]
	各「ファイルタイプ別の設定」ごとに、コメント指定文字を設定する。
	　ファイルタイプが「共通」または右辺値が""の場合は、[general]にて設定する。

「ファイルタイプ別の設定」の設定名:
	「ファイルタイプ別の設定」に対するコメント指定文字。

	右辺値は、そのタイプでのコメント指定文字。(その文字以降がコメントになる文字列)。
	右辺値は必ず () でくくる。

	設定例)
	秀丸マクロ = (//)?
	C言語ｿｰｽﾌｧｲﾙ = (/[/*])?
	Ruby = (#)?
	Bash = (#)?
	HTML = (<--!)?


■補助マクロについて
(書きかけの項目)

・補助マクロとは
	* メインマクロ(デフォルトではshellmode.macというファイル名のマクロ)が取得したマジックコメントの内容を、秀丸マクロのconfig文が解釈しうる形式に変換するマクロ(群)。

・補助マクロ保存フォルダ
	* メインマクロを基準とした、設定ファイル内の[general]'submac_dir'で相対的に設定されているフォルダ。

・補助マクロのファイル名
	* <設定ファイル内の[magiccomment]'other'で設定する各文字>.mac
	　たとえば、"e v r"と設定する場合は、e.mac、v.mac、r.macがそれぞれ必要。

・制限
	* 補助マクロ用設定ファイルは、補助マクロ保存フォルダ内の「submac.ini」である。
	* 補助マクロを起動する前に、macrodll.dllが読み込まれている。
	* 補助マクロを起動する前に、submac.ini中の[_]'arg'が、マジックコメントの内容として設定されている。
	* 補助マクロを終了する前に、秀丸マクロのconfig文が解釈できるような形式で、submac.ini中の[_]'ret'を設定する。
	* 上記の設定値については、メインマクロではエラーチェックされない。
	* 例外的に、設定値が""の時だけチェックされる。この場合、メインマクロを終了する。
	* 補助マクロはendmacroで終了する。endmacroallで終了しない。


■仕様

* 自動起動マクロの時は、shebangの内容を実行しない。
* コマンドラインオプション/xで指定されたときは、何もしない。というよりは、秀丸の仕様として、
 　オプションが指定されているとき、replayになる。
 　指定されているとき、自動起動マクロ（の「開いた直後」）は起動しない。
 　指定されているとき、同じマクロを手動で実行してもreplayにならない。
 　コマンドラインからファイルを開いたときは、自動起動マクロであってもreplayになる。
* ファイルタイプ別設定が「一時的な設定」では特にすることはない。というか、本マクロ自身がマジックコメントの内容で書き換え(=一時的な設定にす)ることがあるので、考慮しない。
 　ちなみに、「一時的な設定」であってもcurrentconfigsetは適切な値を取得できる。
* 設定ファイルでは、コンパイル画面に表示するタイトル、実行する際のカレントディレクトリ（以上はマクロ中で設定します。）、コンパイル画面の強調表示、環境変数の指定は（本マクロの仕様として）設定できない。
* 自動起動マクロに登録していても、設定ファイルでその種類を設定していない場合もしくは0や意味をなさない値のみを設定してある場合、起動しない。
* shebang行の判定アルゴリズムは「1行目が、#!で始まるor（ファイルタイプ別設置が「共通」でないときは）行頭からコメント行で記号の後ろに!で始まるor（「共通」の時は）記号（asciiコードの0x22〜0x7Eのうち数字とアルファベット以外）1文字以上と(その後ろに）!で始まる」。