tkscript_macro.py ライブラリ ドキュメント

ライブラリの機能や目的

tkscript_macro.py は、tkScript クラスとその関連機能を提供するモジュールで、独自のスクリプト言語の実行を管理することを目的としています。

このライブラリの主な機能は以下の通りです。

  • スクリプトの解析と実行: INIファイル形式で記述されたスクリプトを読み込み、解析し、定義されたメニューやボタンに関連付けられた一連のコマンドを実行します。

  • 変数置換: スクリプト内の $varname や $(varname) 形式の変数を、アプリケーションの環境や設定に基づいて動的に実際の値に置換します。

  • 多岐にわたるコマンドのサポート:

    • 外部コマンドの実行。

    • ファイルやディレクトリの操作（作成、削除、コピー、移動）。

    • GUIダイアログの表示（メッセージ、入力、ファイル選択、色選択など）。

    • INIファイルや環境変数の読み書き。

    • 文字列処理やパス操作。

    • 条件付き実行やアプリケーション制御（終了、デバッグモード切替など）。

  • GUIとの連携: tklib のGUIコンポーネントと連携し、メニュー、ボタン、ダイアログなどのGUI要素にスクリプト機能を提供します。

このライブラリは、特にTkinterベースのランチャーアプリケーションにおいて、複雑な操作をINI形式のスクリプトで記述し、柔軟に実行するための基盤を提供することで、アプリケーションの拡張性やカスタマイズ性を高める課題を解決します。

importする方法

このライブラリを他のPythonプログラムからインポートするには、以下のいずれかの方法を使用します。

  • tkscript_macro モジュール全体をインポートする場合：

    import tkscript_macro

# tkScriptクラスを使用する例
script_engine = tkscript_macro.tkScript()

  • tkscript_macro モジュールから tkScript クラスを直接インポートする場合：

    from tkscript_macro import tkScript

# tkScriptクラスを使用する例
script_engine = tkScript()

必要な非標準ライブラリとインストール方法

tkscript_macro.py は、以下の非標準ライブラリに依存しています。

  • tklib

    • このライブラリは tklib パッケージ内の様々なモジュール (tkobject, tkparams, tkutils, tkfile, tkgui.tktkinter) を利用しています。

これらのライブラリは、通常 pip コマンドを使用してインストールできます。

pip install tklib

importできるクラスとメソッド

tkscript_macro.py モジュールから直接インポートできる主要な要素は tkScript クラスです。

class tkScript

概要: スクリプト実行エンジンの中核となるクラス。 詳細説明: マクロスクリプトファイルの読み込み、解析、およびコマンドの実行を管理します。スクリプトファイル内のセクション（メインメニューやボタン）を特定し、それらに紐づけられた一連のコマンドを実行する機能を提供します。tklib.tkobject.tkObject を継承しています。

__init__(self, script_files = [], **args)

概要: tkScript クラスのインスタンスを初期化する。 詳細説明: スクリプトファイルのリストと初期設定を基にオブジェクトを構築します。内部で変数を管理するための辞書 self.vars を初期化し、ファイル存在チェックモードを設定します。 引数:

  • script_files (list[str], オプション): 実行対象となるスクリプトファイルのパスのリスト。デフォルトは空のリスト。

  • args (dict): 親クラス tkObject に渡される追加のキーワード引数。 戻り値: なし

read_cont_lines(self, fp)

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

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

decompose_section(self, section)

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

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

find_file_from_mainmenu(self, app, main_menu, task = None, script_files = None)

概要: メインメニューセクションを定義しているスクリプトファイルと行を見つける。 詳細説明: 指定されたメインメニュー名 ([MenuName]) またはそれに付随するタスク ([MenuName].task) を含むスクリプトファイルを script_files のリストから探し、そのファイルパス、ファイルポインタ、および一致した行を返します。 引数:

  • app (tkLauncherApp): アプリケーションのインスタンス。変数の解決や警告表示に使用されます。

  • main_menu (str): 検索するメインメニューの名前。

  • task (str | None, オプション): メインメニューに関連付けられたタスク（例: 'help'）。デフォルトはNone。

  • script_files (list[str] | None, オプション): 検索対象となるスクリプトファイルのパスのリスト。指定しない場合は self.script_files を使用します。 戻り値: tuple[str | None, file object | None, str | None]: (ファイルパス, ファイルポインタ, 一致した行) のタプル。見つからない場合は (None, None, None) を返します。

find_file_from_button(self, 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, オプション): 検索するボタンのインデックス（1から始まる）。デフォルトはNone。

  • task (str | None, オプション): ボタンに関連付けられたタスク（例: 'help', 'dbl_click'）。デフォルトはNone。

  • script_files (list[str] | None, オプション): 検索対象となるスクリプトファイルのパスのリスト。指定しない場合は self.script_files を使用します。 戻り値: tuple[str | None, file object | None, str | None]: (ファイルパス, ファイルポインタ, 一致した行) のタプル。見つからない場合は (None, None, None) を返します。

find_file_from_menu(self, 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, オプション): 検索するボタンのインデックス（1から始まる）。メインメニュー検索の場合はNone。

  • task (str | None, オプション): メニューやボタンに関連付けられたタスク。デフォルトはNone。

  • script_files (list[str] | None, オプション): 検索対象となるスクリプトファイルのパスのリスト。指定しない場合は self.script_files を使用します。 戻り値: tuple[str | None, file object | None, str | None]: (ファイルパス, ファイルポインタ, 一致した行) のタプル。見つからない場合は (None, None, None) を返します。

get_main_menus(self, app)

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

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

get_caption(self, app, main_menu)

概要: 指定されたメインメニューのキャプション文字列を取得する。 詳細説明: main_menu に対応するスクリプトセクションを検索し、そのセクション内で定義されている Caption= コマンドの値を読み取って返します。キャプションが見つからない場合は 'no caption' を返します。 引数:

  • app (tkLauncherApp): アプリケーションのインスタンス。変数の解決などに使用されます。

  • main_menu (str): キャプションを取得するメインメニューの名前。 戻り値: str | None: メインメニューのキャプション文字列。見つからない場合はNone。

get_submenus(self, 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} の形式です。

update_script_vars(self, app, cparams)

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

  • app (tkLauncherApp): アプリケーションのインスタンス。各種変数情報を提供します。

  • cparams (tkParams): アプリケーションの構成パラメータ。 戻り値: dict: 更新されたスクリプト変数辞書 (self.vars)。

show_message(self, app, message)

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

  • app (tkLauncherApp): アプリケーションのインスタンス。メッセージ表示機能を提供します。

  • message (str): 表示するメッセージ文字列。 戻り値: なし

convert_a_var(self, app, var)

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

  • app (tkLauncherApp): アプリケーションのインスタンス。変数辞書とエラー表示機能を提供します。

  • var (str): 変数置換を行う対象の文字列。 戻り値: str: 変数が置換された後の文字列。

convert_vars(self, app, vars)

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

  • app (tkLauncherApp): アプリケーションのインスタンス。変数置換機能を提供します。

  • vars (list[str]): 変数置換を行う対象の文字列のリスト。 戻り値: list[str]: 変数が置換された後の文字列のリスト。

execute_external_command(self, 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, オプション): 実行するコマンドラインをコンソールに表示するかどうか。デフォルトはFalse。 戻り値: int: コマンドの終了コード。エラーが発生した場合は -1 を返します。

execute_a_command(self, app, cparams, line, fp = None, event = None)

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

  • コメント: rem, #, :, ;

  • アプリケーション制御: bye, end, call, debug, confirm, load_menu

  • INI/環境変数操作: read_ini, write_ini, read_ini_all, read_ini_to_vars, load_dotenv

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

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

  • GUI情報取得: get_cur_menu, get_cur_menu_file, get_cur_button_idx, get_cur_button_caption

  • 文字列処理: split_str, del_quote, remove_comment, get_first_word, get_last_word, escape_reg, replace

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

  • 設定保存: save_config

  • 変数操作: 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_cur_dir

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

  • ファイル検索: search_files, search_latest_file

  • ラベル/リスト操作: 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, new_dialog, add_dialog, custom_dialog, custom_dialog_modeless, message_dialog, ask_yesno_dialog, ask_okcancel_dialog

  • 評価: eval

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

  • アプリケーション状態設定: 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, オプション): 現在読み込み中のスクリプトファイルのファイルポインタ。call コマンドで再帰呼び出しする際に使用されます。デフォルトはNone。

  • event (tkinter.Event | None, オプション): GUIイベントオブジェクト。show_context_menu などGUI関連コマンドで使用されます。デフォルトはNone。 戻り値: int: コマンドの実行結果。1は成功、0以下はエラーまたは終了を意味します。-1はエラー、または end コマンドによるセクション終了を示します。

execute(self, 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, オプション): 検索対象となるスクリプトファイルのパスのリスト。指定しない場合は self.script_files または self.script_inf のパスを使用します。

  • event (tkinter.Event | None, オプション): GUIイベントオブジェクト。特定のコマンドで使用されます。デフォルトはNone。

  • max_num (int | None, オプション): 実行するコマンドの最大数（デバッグ用）。このメソッドでは現在使用されていません。デフォルトはNone。 戻り値: int: 実行結果。1は成功、0以下はエラーまたは終了を意味します。-1はエラー、または end コマンドによるセクション終了を示します。

main scriptとして実行したときの動作

tkscript_macro.py ファイルをPythonインタープリタで直接実行した場合 (python tkscript_macro.py)、if __name__ == "__main__": ブロック内の pass ステートメントにより、特に何も処理は実行されません。このファイルは、他のアプリケーションやモジュールからインポートされ、tkScript クラスを利用することを想定して設計されています。