tkscript_macro.py 技術ドキュメント

ライブラリの機能や目的

tkscript_macro.py ライブラリは、tklib フレームワークを基盤として、INIファイル形式またはそれに類するカスタムスクリプトファイルを解析し、定義されたマクロコマンドを実行するためのアプリケーション基盤クラス tkScript を提供します。

このライブラリの主な目的は、GUIアプリケーション（特に tklib を利用したアプリケーション）に動的なマクロ機能や、外部ファイルで設定可能なコマンド実行機能を提供することです。これにより、アプリケーションの動作を柔軟にカスタマイズし、ユーザーが独自のタスクやワークフローを定義・実行できるようになります。

主な機能:

スクリプトファイルの解析と管理: 指定されたディレクトリ内のスクリプトファイルを読み込み、そこからメインメニューやサブメニュー（ボタン）の情報を抽出します。
変数展開機能: スクリプト内の $VAR や $(VARNAME) 形式の変数を、アプリケーションの状態や環境変数に基づいて動的に展開・置換します。
ファイルシステム操作: cd, mkdir, copy, delete といった基本的なファイルシステム操作コマンドをスクリプトから実行できます。
外部コマンド実行: PythonスクリプトやPerlスクリプトを含む任意の外部コマンドを指定された引数とともに実行します。
INI設定の読み書き: INIファイルからの設定読み込みや、設定値の書き込みをサポートします。
GUIダイアログとの連携: tklib.tkgui.tktkinter を介して、メッセージダイアログ、ファイル選択ダイアログ、色選択ダイアログなどのGUI要素と連携し、スクリプトから対話的な操作を可能にします。
メニュー構造の動的構築: スクリプトファイルからメニュー構造を抽出し、GUIアプリケーションのメニュー表示に利用できる情報を提供します。

このライブラリは、アプリケーションの拡張性、設定の柔軟性、およびユーザーによるカスタマイズ性を高めることを目的としています。

importする方法

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

tkscript_macro.py ファイルから tkScript クラスを直接インポートする場合：

from tkscript_macro import tkScript

ライブラリ全体をインポートし、tkscript_macro の名前空間を通じてアクセスする場合：

import tkscript_macro

# tkScript クラスにアクセス
my_script_executor = tkscript_macro.tkScript()

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

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

tklib: GUIアプリケーションの構築やユーティリティ機能を提供するライブラリ。
- tklib.tkobject
- tklib.tkparams
- tklib.tkutils
- tklib.tkfile
- tklib.tkgui.tktkinter

インストール方法:

tklib は pip コマンドでインストールできます。

pip install tklib

または、tklib のインストールによっては、以下が必要となる場合があります。

pip install python-tklib

importできる変数と関数

このライブラリは主に tkScript クラスを提供します。このクラスには、アプリケーションのスクリプト実行ロジックをカプセル化する多くのメソッドが含まれています。

クラス

`class tkScript(tkObject)`

スクリプトファイルからのコマンド実行を管理する基底クラス。tklib.tkobject.tkObject を継承しています。

コンストラクタ:

__init__(self, script_files = [], **args)
- 説明: tkScript クラスのインスタンスを初期化します。
- 引数:
  - script_files (list, optional): 処理対象となるスクリプトファイルのパスのリスト。デフォルトは空リスト。
  - **args: 親クラス tkObject に渡される任意のキーワード引数。
- 内部変数:
  - self.script_files: スクリプトファイルのリスト。
  - self.vars: スクリプト内で使用される変数を格納する辞書（初期値 {"check_file_mode": "auto"}）。
  - self.script_inf: 解析されたスクリプト情報（メニューとファイルパスのマップ）を格納する辞書。

メソッド:

read_cont_lines(self, fp)
- 説明: ファイルポインタ fp から、行末がバックスラッシュ (\) で終わる連続した行を読み込み、連結して返します。
- 引数:
  - fp (file object): 読み込み対象のファイルポインタ。
- 戻り値: (str) 連結された1行の文字列。
decompose_section(self, section)
- 説明: [ButtonX.MenuName].Task 形式のセクション文字列を解析し、メニュー名、ボタンインデックス、タスク名を抽出します。
- 引数:
  - section (str): 解析するセクション文字列。
- 戻り値: (tuple) (menu_name, button_index, task_name) のタプル。button_index は整数、menu_name と task_name は文字列。
find_file_from_mainmenu(self, app, main_menu, task = None, script_files = None)
- 説明: 指定されたメインメニューセクション ([MenuName]) を含むスクリプトファイルを検索します。
- 引数:
  - app (object): メインアプリケーションのインスタンス（tklib の tkLauncherApp など）。
  - main_menu (str): 検索対象のメインメニュー名。
  - task (str, optional): 特定のタスク名を指定する場合。
  - script_files (list, optional): 検索対象のスクリプトファイルのリスト。指定しない場合は self.script_files を使用。
- 戻り値: (tuple) (file_path, file_pointer, line_string) のタプル。見つからない場合は (None, None, None)。
find_file_from_button(self, app, main_menu, idx = None, task = None, script_files = None)
- 説明: 指定されたボタンセクション ([ButtonX.MenuName]) を含むスクリプトファイルを検索します。
- 引数:
  - app (object): メインアプリケーションのインスタンス。
  - main_menu (str): 検索対象のメインメニュー名。
  - idx (int or str, optional): ボタンのインデックス（1から始まる）。
  - task (str, optional): 特定のタスク名を指定する場合（例: help, dbl_click）。
  - script_files (list, optional): 検索対象のスクリプトファイルのリスト。
- 戻り値: (tuple) (file_path, file_pointer, line_string) のタプル。見つからない場合は (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 を内部で呼び出します。
- 引数: find_file_from_mainmenu および find_file_from_button と同じ。
- 戻り値: (tuple) (file_path, file_pointer, line_string) のタプル。見つからない場合は (None, None, None)。
get_main_menus(self, app)
- 説明: 登録されているスクリプトファイルから利用可能なすべてのメインメニューの名前を抽出し、リストとして返します。
- 引数:
  - app (object): メインアプリケーションのインスタンス。
- 戻り値: (list) メインメニュー名のリスト。
get_caption(self, app, main_menu)
- 説明: 指定されたメインメニューのキャプション（Caption = ... で定義）を取得します。
- 引数:
  - app (object): メインアプリケーションのインスタンス。
  - main_menu (str): キャプションを取得するメインメニュー名。
- 戻り値: (str) キャプション文字列。見つからない場合は 'no caption'。
get_submenus(self, app, main_menu)
- 説明: 指定されたメインメニューに関連付けられたサブメニュー（ボタン）の一覧とそれぞれのキャプション、タスクを取得します。
- 引数:
  - app (object): メインアプリケーションのインスタンス。
  - main_menu (str): サブメニューを取得するメインメニュー名。
- 戻り値: (list of dict) 各辞書は {"idx": int, "task": str, "caption": str} 形式。
update_script_vars(self, app, cparams)
- 説明: アプリケーションのスクリプト変数 (app.svars) と環境変数、コマンドライン引数などを結合し、self.vars 辞書を更新します。self.vars はキーが小文字で統一されます。
- 引数:
  - app (object): メインアプリケーションのインスタンス。
  - cparams (object): アプリケーションのパラメータオブジェクト。
- 戻り値: (dict) 更新された self.vars 辞書。
show_message(self, app, message)
- 説明: アプリケーションのメッセージ表示機能 (app.show_message) を呼び出します。
- 引数:
  - app (object): メインアプリケーションのインスタンス。
  - message (str): 表示するメッセージ文字列。
- 戻り値: なし。
convert_a_var(self, app, var)
- 説明: 1つの文字列内の変数を $VAR や $(VARNAME) の形式で展開します。
- 引数:
  - app (object): メインアプリケーションのインスタンス。
  - var (str): 変数を含む文字列。
- 戻り値: (str) 変数が展開された文字列。
convert_vars(self, app, vars)
- 説明: 文字列のリスト内のすべての変数を展開します。
- 引数:
  - app (object): メインアプリケーションのインスタンス。
  - vars (list of str): 変数を含む文字列のリスト。
- 戻り値: (list of str) 変数が展開された文字列のリスト。
execute_external_command(self, app, cmd, args, is_print = False)
- 説明: 指定された外部コマンドと引数を実行します。PythonスクリプトやPerlスクリプトの場合、適切なインタプリタパスを付加します。
- 引数:
  - app (object): メインアプリケーションのインスタンス。
  - cmd (str): 実行するコマンドのパスまたは名前。
  - args (list of str): コマンドに渡す引数のリスト。
  - is_print (bool, optional): 実行コマンドをコンソールに出力するかどうか。デフォルトは False。
- 戻り値: (int) コマンドの終了コード。実行できなかった場合は -1。
execute_a_command(self, app, cparams, line, fp = None, event = None)
- 説明: スクリプトファイルから読み取られた1行のマクロコマンドを解析し、実行します。多くの組み込みコマンド（set, chdir, echo, copy, input, call など）をサポートします。
- 引数:
  - app (object): メインアプリケーションのインスタンス。
  - cparams (object): アプリケーションのパラメータオブジェクト。
  - line (str): 実行するコマンド文字列。
  - fp (file object, optional): 現在読み込み中のファイルポインタ。call コマンドで一時的に閉じるために使用されます。
  - event (object, optional): GUIイベントオブジェクト。コンテキストメニュー表示などで使用される場合があります。
- 戻り値: (int) コマンドの実行結果を示すコード。1 は成功、0 以下は特別な処理（end コマンド、エラーなど）。
execute(self, app, cparams, menu, idx, action, i_mouse_button, script_files = None, event = None, max_num = None)
- 説明: 指定されたメニュー、ボタンインデックス、アクションに対応するスクリプトセクションを見つけて実行します。これは、GUI要素からのトリガーに応じてマクロを実行する主要なメソッドです。
- 引数:
  - app (object): メインアプリケーションのインスタンス。
  - cparams (object): アプリケーションのパラメータオブジェクト。
  - menu (str): メインメニュー名。
  - idx (int): ボタンのインデックス（0から始まる）。
  - action (str): 実行する特定のアクション（例: '' (デフォルト), help, dbl_click）。
  - i_mouse_button (str): マウスクリックのボタン番号（例: '1', '2'）。
  - script_files (list, optional): 検索対象のスクリプトファイルのリスト。
  - event (object, optional): GUIイベントオブジェクト。
  - max_num (int, optional): 処理するコマンドの最大数（現在は未使用）。
- 戻り値: (int) スクリプトセクションの実行結果を示すコード。1 は成功、-1 は失敗または中止。

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

tkscript_macro.py ファイルには、if __name__ == '__main__': ブロックが存在しません。したがって、このファイルをPythonインタプリタで直接実行しても、特別な動作は行われません。通常、このライブラリは他のアプリケーションからインポートされ、そのアプリケーションのコンテキスト内で tkScript クラスのインスタンスを作成して利用されることを想定しています。