tkscript_macro プログラム仕様

概要: tkScriptクラスとその関連機能を提供し、独自のスクリプト言語の実行を管理するモジュール。詳細説明:

このモジュールは、INIファイル形式のスクリプトを解析し、定義されたメニューやボタンのアクションを実行するための機能を提供します。変数置換、外部コマンド実行、ファイル操作、GUIダイアログの表示など、多岐にわたるコマンドをサポートします。

関連リンク:: tkscript_macro.py 技術ドキュメント

class tklib.tkscript_macro.tkScript(script_files=[], **args)[ソース]

ベースクラス: tkObject

概要: スクリプト実行エンジンの中核となるクラス。詳細説明:

マクロスクリプトファイルの読み込み、解析、およびコマンドの実行を管理します。スクリプトファイル内のセクション（メインメニューやボタン）を特定し、それらに紐づけられた一連のコマンドを実行する機能を提供します。

convert_a_var(app, var)[ソース]

概要: 単一の文字列に含まれる変数を実際の値に置換する。詳細説明:

入力文字列 var 内の $varname または $(varname) 形式の変数を、 app.s_engine.vars に格納されている対応する値に置換します。バックスラッシュでエスケープされたドル記号 $ はそのまま $ ` として扱われます。未定義の変数が存在し、`app.alert_var_error がTrueの場合、エラーダイアログが表示されます。

パラメータ:

app -- tkLauncherApp: アプリケーションのインスタンス。変数辞書とエラー表示機能を提供します。
var -- str: 変数置換を行う対象の文字列。

戻り値:

str: 変数が置換された後の文字列。

convert_vars(app, vars)[ソース]

概要: 文字列のリストに含まれるすべての変数を実際の値に置換する。詳細説明:

与えられた文字列のリスト vars の各要素に対して convert_a_var メソッドを適用し、含まれる変数表記（例: $var, $(var)) を対応する値で置換します。このメソッドは、コマンドの引数を実行前に前処理するために使用されます。

パラメータ:

app -- tkLauncherApp: アプリケーションのインスタンス。変数置換機能を提供します。
vars -- list[str]: 変数置換を行う対象の文字列のリスト。

戻り値:

list[str]: 変数が置換された後の文字列のリスト。

decompose_section(section)[ソース]

概要: スクリプトセクション文字列をメニュー名、インデックス、タスクに分解する。詳細説明:

[ButtonXX.MenuName].Task や ButtonXX.MenuName のような形式のセクション文字列を解析し、メニュー名、ボタンインデックス、および関連タスク（例: 'help', 'dbl_click'）を抽出します。これにより、スクリプト内の特定のセクションをプログラム的に参照できるようになります。

パラメータ:: section -- str: 分解するスクリプトセクションの文字列。
戻り値:: tuple[str, int | str, str]: (メニュー名, ボタンインデックス (intまたは空文字列), タスク名 (strまたは空文字列)) のタプル。

execute(app, cparams, menu, idx, action, i_mouse_button, script_files=None, event=None, max_num=None)[ソース]

概要: 指定されたメニュー/ボタンセクションに関連付けられたスクリプトを実行する。詳細説明:

menu、idx`（0から始まるボタンインデックス）、および `action に基づいて、適切なスクリプトセクションを検索し、そのセクション内のコマンドを順次実行します。実行中、各行は execute_a_command によって処理され、内部コマンドまたは外部コマンドとしてディスパッチされます。 OnErrorAction の設定に応じてエラー時の挙動が変化します。

パラメータ:

app -- tkLauncherApp: アプリケーションのインスタンス。各種機能、変数、状態を提供します。
cparams -- tkParams: アプリケーションの構成パラメータ。
menu -- str: 実行対象のメインメニュー名。
idx -- int | None: 実行対象のボタンの0から始まるインデックス。メインメニュー自体を実行する場合はNone。
action -- str: 実行対象のアクション名（例: 'help', 'dbl_click'）。アクションがない場合は空文字列。
i_mouse_button -- str | None: マウスボタンのインデックス（例: '1'）。ログ出力にのみ使用されます。
script_files -- list[str] | None, optional: 検索対象となるスクリプトファイルのパスのリスト。指定しない場合はself.script_filesまたはself.script_infのパスを使用します。
event -- tkinter.Event | None, optional: GUIイベントオブジェクト。特定のコマンドで使用されます。デフォルトはNone。
max_num -- int | None, optional: 実行するコマンドの最大数（デバッグ用）。このメソッドでは現在使用されていません。デフォルトはNone。

戻り値:

int: 実行結果。1は成功、0以下はエラーまたは終了を意味します。-1はエラー、または end コマンドによるセクション終了を示します。

execute_a_command(app, cparams, line, fp=None, event=None)[ソース]

概要: スクリプトの1行のコマンドを実行する。詳細説明:

指定されたスクリプト行 line を解析し、対応する内部コマンドまたは外部コマンドを実行します。コマンドは cmd arg1 arg2 ... の形式で、変数が含まれる場合は実行前に置換されます。サポートされる主な内部コマンドは以下の通りです。

rem / # / : / ;: コメント行として無視されます。

bye: アプリケーションを終了します。

end: 現在のスクリプトセクションの実行を終了します。

call menu.idx.action: 別のスクリプトセクションを呼び出して実行します。

debug on/off: デバッグモードのオン/オフを切り替えます。

confirm on/off: 外部コマンド実行前の確認ダイアログのオン/オフを切り替えます。

load_menu: メニューを再ロードします。

read_ini, write_ini, read_ini_all, read_ini_to_vars/load_dotenv: INIファイル操作。

print_all, echo, print: メッセージ出力。

get_cur_dir, chdir/cd, mkdir/md, rmdir/rd, copy/cp, move/mv, delete/del/rm: ファイル・ディレクトリ操作。

get_cur_menu, get_cur_menu_file, get_cur_button_idx, get_cur_button_caption: 現在のメニュー情報取得。

split_str: 文字列の分割。

show_window, set_title: ウィンドウ操作。

save_config: 設定の保存。

del_quote, remove_comment, get_first_word, get_last_word: 文字列処理。

set, list_append, list_append_if_exist, set_if_blank, set_if_not_blank, set_if_null, set_if_not_null, set_path, join_path: 変数操作。

use_os_path_sep, get_drive, get_directory, get_directory_without_drive, get_last_directory, get_upper_directory, get_filename, get_filebody, get_ext: パス操作。

get_open_file_name, get_save_file_name, get_open_dir_name, choose_if_not_exist: ファイル/ディレクトリ選択ダイアログ。

search_files, search_latest_file: ファイル検索。

escape_reg: 正規表現エスケープ。

replace: 文字列置換。

read_labels: ラベルの読み込み。

get_file_list, get_dir_list: ファイル/ディレクトリリストの取得。

set_dialog_values, set_dialog_var, set_file_list: ダイアログ値の設定。

setup, copy_config2scars, copy_svars2config: 設定同期。

color_dialog, font_dialog, input, select_dialog: ダイアログ表示。

eval: 式の評価。

add_tooltip, create_menu, add_context_menu, show_context_menu: GUI要素操作。

new_dialog, add_dialog, custom_dialog, custom_dialog_modeless, message_dialog, ask_yesno_dialog, ask_okcancel_dialog: カスタムダイアログ操作。

set_message, set_selected_file, set_command_line, set_argument, add_path: アプリケーション状態設定。

get_app_path: アプリケーションパス取得。

check_file_mode, check_exist, exit_if_defined, exit_if_not_defined, exit_if_exist, exit_if_not_exist: 条件付き終了。

wait_process: 外部プロセスの終了を待機。

上記以外のコマンドは execute_external_command を介して外部プロセスとして実行されます。

パラメータ:

app -- tkLauncherApp: アプリケーションのインスタンス。各種機能を提供します。
cparams -- tkParams: アプリケーションの構成パラメータ。
line -- str: 実行するスクリプトの1行。
fp -- file object | None, optional: 現在読み込み中のスクリプトファイルのファイルポインタ。call コマンドで再帰呼び出しする際に使用されます。デフォルトはNone。
event -- tkinter.Event | None, optional: GUIイベントオブジェクト。show_context_menu などGUI関連コマンドで使用されます。デフォルトはNone。

戻り値:

int: コマンドの実行結果。1は成功、0以下はエラーまたは終了を意味します。-1はエラー、または end コマンドによるセクション終了を示します。

execute_external_command(app, cmd, args, is_print=False)[ソース]

概要: 外部コマンドを実行する。詳細説明:

指定されたコマンドと引数を使用して外部プログラムを実行します。コマンドがPython (.py) または Perl (.pl) スクリプトの場合、それぞれのインタープリタのパスを前置して実行します。コマンドライン引数は適切に引用符で囲まれ、os.system() を使用して同期的に実行されます。デバッグモードの場合や is_print がTrueの場合、実行されるコマンドラインが表示されます。実行前にユーザーに確認を求めるダイアログが表示されることもあります。

パラメータ:

app -- tkLauncherApp: アプリケーションのインスタンス。変数、設定、GUI機能を提供します。
cmd -- str: 実行するコマンド。
args -- list[str]: コマンドに渡す引数のリスト。
is_print -- bool, optional: 実行するコマンドラインをコンソールに表示するかどうか。デフォルトはFalse。

戻り値:

int: コマンドの終了コード。エラーが発生した場合は -1 を返します。

find_file_from_button(app, main_menu, idx=None, task=None, script_files=None)[ソース]

概要: ボタンセクションを定義しているスクリプトファイルと行を見つける。詳細説明:

指定されたメインメニュー名とボタンインデックス ([ButtonXX.MenuName]) またはそれに付随するタスク ([ButtonXX.MenuName].task) を含むスクリプトファイルを script_files のリストから探し、そのファイルパス、ファイルポインタ、および一致した行を返します。

パラメータ:

app -- tkLauncherApp: アプリケーションのインスタンス。変数の解決や警告表示に使用されます。
main_menu -- str: 検索するボタンのメインメニュー名。
idx -- int | None, optional: 検索するボタンのインデックス（1から始まる）。デフォルトはNone。
task -- str | None, optional: ボタンに関連付けられたタスク（例: 'help', 'dbl_click'）。デフォルトはNone。
script_files -- list[str] | None, optional: 検索対象となるスクリプトファイルのパスのリスト。指定しない場合はself.script_filesを使用します。

戻り値:

tuple[str | None, file object | None, str | None]: (ファイルパス, ファイルポインタ, 一致した行) のタプル。見つからない場合は (None, None, None) を返します。

find_file_from_mainmenu(app, main_menu, task=None, script_files=None)[ソース]

概要: メインメニューセクションを定義しているスクリプトファイルと行を見つける。詳細説明:

指定されたメインメニュー名 ([MenuName]) またはそれに付随するタスク ([MenuName].task) を含むスクリプトファイルを script_files のリストから探し、そのファイルパス、ファイルポインタ、および一致した行を返します。

パラメータ:

app -- tkLauncherApp: アプリケーションのインスタンス。変数の解決や警告表示に使用されます。
main_menu -- str: 検索するメインメニューの名前。
task -- str | None, optional: メインメニューに関連付けられたタスク（例: 'help'）。デフォルトはNone。
script_files -- list[str] | None, optional: 検索対象となるスクリプトファイルのパスのリスト。指定しない場合はself.script_filesを使用します。

戻り値:

tuple[str | None, file object | None, str | None]: (ファイルパス, ファイルポインタ, 一致した行) のタプル。見つからない場合は (None, None, None) を返します。

find_file_from_menu(app, main_menu, idx=None, task=None, script_files=None)[ソース]

概要: 指定されたメニュー、ボタンインデックス、タスクに対応するスクリプトファイルとセクション行を見つける。詳細説明:

find_file_from_mainmenu と find_file_from_button を内部的に呼び出し、メインメニュー、または特定のボタンセクションを検索します。スクリプト実行時にどのファイル内のどのセクションを参照するかを決定する際に使用されます。

パラメータ:

app -- tkLauncherApp: アプリケーションのインスタンス。変数の解決や警告表示に使用されます。
main_menu -- str: 検索するメインメニューまたはボタンのメインメニュー名。
idx -- int | None, optional: 検索するボタンのインデックス（1から始まる）。メインメニュー検索の場合はNone。
task -- str | None, optional: メニューやボタンに関連付けられたタスク。デフォルトはNone。
script_files -- list[str] | None, optional: 検索対象となるスクリプトファイルのパスのリスト。指定しない場合はself.script_filesを使用します。

戻り値:

tuple[str | None, file object | None, str | None]: (ファイルパス, ファイルポインタ, 一致した行) のタプル。見つからない場合は (None, None, None) を返します。

get_caption(app, main_menu)[ソース]

概要: 指定されたメインメニューのキャプション文字列を取得する。詳細説明:

main_menu に対応するスクリプトセクションを検索し、そのセクション内で定義されている Caption= コマンドの値を読み取って返します。キャプションが見つからない場合は 'no caption' を返します。

パラメータ:

app -- tkLauncherApp: アプリケーションのインスタンス。変数の解決などに使用されます。
main_menu -- str: キャプションを取得するメインメニューの名前。

戻り値:

str | None: メインメニューのキャプション文字列。見つからない場合はNone。

get_main_menus(app)[ソース]

概要: 登録されているすべてのメインメニューを読み込み、その情報を取得する。詳細説明:

self.script_files に指定されたすべてのスクリプトファイルを走査し、 [ButtonXX.MenuName] 形式のセクションを抽出してメインメニューのリストを作成します。また、各メニューがどのファイルに定義されているかの情報も self.script_inf に格納します。スクリプトファイル内に 'exit_if_not_exist' コマンドが存在する場合、条件に応じて処理を中断することがあります。

パラメータ:: app -- tkLauncherApp: アプリケーションのインスタンス。警告表示などに使用されます。
戻り値:: list[str]: 検出されたメインメニュー名のリスト。

get_submenus(app, main_menu)[ソース]

概要: 指定されたメインメニューに関連するすべてのサブメニュー（ボタン）の情報を取得する。詳細説明:

main_menu に対応するスクリプトセクションを検索し、そのセクションに含まれる [ButtonXX.MenuName] 形式のサブセクションを解析します。各サブメニューについて、インデックス、タスク、キャプションなどの情報を抽出し、リストとして返します。この処理中、set, join_path, use_os_path_sep, check_exist などのコマンドが実行され、アプリケーションの状態や変数が更新されることがあります。特に check_exist は、ボタンのキャプションに '!!!' を追加する形でファイルの存在状況を反映します。

パラメータ:

app -- tkLauncherApp: アプリケーションのインスタンス。変数の解決やコマンド実行に使用されます。
main_menu -- str: サブメニューを取得するメインメニューの名前。

戻り値:

list[dict]: サブメニュー情報のリスト。各辞書は {"idx": int, "task": str, "caption": str} の形式です。

read_cont_lines(fp)[ソース]

概要: バックスラッシュで連結された複数行のスクリプト行を読み込む。詳細説明:

ファイルポインタ fp から一行ずつ読み込み、行末がバックスラッシュ ('') で終わる場合は次の行と連結します。これにより、スクリプトファイル内で論理的に一行として扱われる複数行のコマンドを正しく処理できます。

パラメータ:: fp -- file object: 読み込み対象のファイルポインタ。
戻り値:: str: 連結された一行の文字列。ファイル終端に達した場合は空文字列を返します。

show_message(app, message)[ソース]

概要: 指定されたメッセージをアプリケーションのメッセージ表示領域に表示する。詳細説明:

アプリケーションのGUIにメッセージを表示するために、app インスタンスの show_message メソッドを呼び出します。これは、スクリプト実行中にユーザーへの通知やデバッグ情報を提供するのに使用されます。

パラメータ:

app -- tkLauncherApp: アプリケーションのインスタンス。メッセージ表示機能を提供します。
message -- str: 表示するメッセージ文字列。

戻り値:

None

update_script_vars(app, cparams)[ソース]

概要: アプリケーション変数と環境変数をスクリプトエンジンにロードする。詳細説明:

app.svars からパラメーター辞書を取得し、これに環境変数やアプリケーション固有のパス情報を追加します。また、コマンドライン引数も $0, $1, ..., $a の形で変数として利用可能にします。これらの変数は、後続のスクリプトコマンドで参照できるように self.vars にすべて小文字のキーで格納されます。

パラメータ:

app -- tkLauncherApp: アプリケーションのインスタンス。各種変数情報を提供します。
cparams -- tkParams: アプリケーションの構成パラメータ。

戻り値:

dict: 更新されたスクリプト変数辞書 (self.vars)。