Coda プラグインを作成する
Coda にこれまで以上のことをさせたい、とお考えのあなたに朗報です。
Coda 1.6 以降では新たに Coda プラグインをサポートしました。これは Cocoa プログラムの知識がなくても Coda によるテキスト編集を拡張できるようにするものです。
プラグインは現在の書類にアクセスし、要求に応じた変更を実行します。例えば、書類に現在の日付と時刻を挿入したり、選択されたテキスト部分を置き換えたり、カスタムバリデータを走らせたり、特定のタグでコードを囲んだりするプラグインを書くことが可能です。
プラグインがインストールされると Coda にメニューが現れます。また、ショートカットも利用可能です。
プラグインを書くには、スクリプト言語を用いてスクリプトを書き、Coda Plug-In Creator アプリケーションで書かれたスクリプトを Coda プラグインにバンドルする方法と、Coda プラグイン API を用いて直接記述する方法の2種類があります。
それでは詳しく解説していきましょう！
Coda Plug-in Creator を使用する
Cocoa になじみ深くはないものの、Coda のためのシンプルなテキスト処理プラグインをハイレベルなスクリプト言語で書きたがっている方に、我々は Coda Plug-in Creator アプリケーションを提供します。このツールはハイレベルなスクリプトコードをネイティブな Cocoa バンドルにし、Coda で利用可能にするものです。
すでに TextMate バンドルの "コマンド" になじみ深いなら、Coda スクリプトプラグインについてもご理解いただけると思います。
Perl や Ruby、シェルスクリプト言語などお好きなコマンドラインインタプリタでプラグインを書くことが可能です。
コマンドとサブメニュー
ひとつのプラグインには 1つだけでなく複数のスクリプトをコマンドとして提供することが可能です。さらに、コマンドはサブメニューを使用してクループ化させることもでき、ツールバーの "コマンドを追加" および "サブメニューを追加" を使用して Coda のプラグインメニューの構成をカスタマイズします。
スクリプトファイルを選択する
プラグインに含めたいスクリプトを Finder から "スクリプト" フィールドにドラッグするか、"作成" ボタンをクリックして新たにスクリプトを書いてください。
インタプリタ
スクリプトは以下の様なスクリプト実行パスが先頭に記述されたインタプリタである必要があります:
#!/usr/bin/perl
スクリプト実行前後のアクション
オプションとして、指定されたスクリプトの実行時と成功時に Coda が現在の書類の保存か、すべての書類の保存を実行することが可能です。それぞれ "実行時" および "成功時" ポップアップから選択します。
入力タイプ
スクリプトベースのプラグインは書類の異なる部分を入力として受け取ることが可能です。"入力タイプ" ポップアップからプラグインに入力させたいタイプを選択してください。入力は標準入力（stdin）としてスクリプトに送られます。"選択部分" タイプを選択した場合、何も選択されずにスクリプトが実行されることを考慮し "空の場合" ポップアップから代わりに送られる入力を選択する必要があります。
なし
一切の入力を必要としないプラグインの場合はこれを選択します。
選択部分
スクリプトは選択されたテキスト部分を受け取ります。選択されていない場合は "空の場合" 入力タイプでの設定に従って送られます。
行
スクリプトは挿入ポイントの行全体を受け取ります。
文字
スクリプトは挿入ポイントのすぐ右の文字を受け取ります。
単語
スクリプトは挿入ポイントの中にある単語を受け取ります。
書類
挿入しようとしている書類全体をスクリプトに送ります。
出力タイプ
プラグインはその実行結果をユーザに出力することが可能です。"出力タイプ" ポップアップを使用してプラグインの実行の結果をどのように処理するかを設定します。プラグインからの出力は標準出力（stdout）に配置されるべきで、以下のタイプから選択可能です:
破棄
Coda はプラグインによって生成されたあらゆる出力を無視します。
選択部分と置換
エディタでの選択部分とプラグインからの出力とを置換します。選択されていない場合は挿入ポイントに挿入されます。
選択部分の後
現在の選択箇所の後にプラグインからの出力を挿入します。選択されていない場合は挿入ポイントに挿入されます。
現在の書類と置換（Coda 1.6.1 以降）
現在のエディタで開かれている書類と置換してプラグインからの出力を挿入します。
新規書類で表示（Coda 1.6.1 以降）
新規タブを新たに開きプラグインからの出力を挿入します。
HTML で表示
プラグインの出力を HTML にレンダリングし、Coda の新規プレビュータブで表示します。
"選択部分と置換"、"選択部分の後"、"現在の書類と置換" そして "新規書類で表示"が出力タイプとして選択されている場合、プラグインの出力結果をエディタに挿入する位置を設定するオプションが利用可能です。プラグインの出力内容に $$IP$$ という文字列を含め "挿入ポイント $$IP$$ を使用する" にチェックが入っている場合、Coda はその位置を挿入ポイントとみなし出力します。
サポートファイル
スクリプトがいくつかの追加ファイルを必要とするならば "サポートファイル" リストに追加することが可能です。追加されたファイルはプラグインにバンドルされます。
スクリプトに渡される環境変数
スクリプトは実行環境の一部として以下の情報を受け取ります。スクリプト作者の便宜を考え、同じ環境変数は CODA_ もしくは TM_ 接頭語のどちらかが利用可能です。
CODA_BUNDLE_PATH
プラグインバンドルへのパスです。
CODA_BUNDLE_SUPPORT
プラグインバンドルに含まれるサポートディレクトリへのパスです（サポートファイルを使用した場合）。
CODA_FILEPATH
編集された書類のファイル名を含むフルパスです。未保存の書類の場合は空となります。
CODA_LINE_ENDING
ソース書類の末端で使用されている文字です。それは CR、LF、CR+LF、U+2028 または U+2029 を含む文字列が一般的です。文字列には改行コードが含まれています。例えば、文字 LF は "L" と "F" という単独の文字ではありません。
CODA_LINE_INDEX
選択されている行のキャラクタインデックスです。
CODA_LINE_NUMBER
現在の行番号です。
CODA_SELECTED_TEXT
選択されているテキスト部分です。
CODA_SITE_LOCAL_PATH
書類が含まれているサイトへのフルローカルパスです。サイト設定を利用していない場合、またはサイト設定のローカルパスが未設定の場合は空になります。
HOME
現在のユーザのホームディレクトリへのパスです。
TextMate コマンドを読み込む
Coda Plug-In Creator アプリケーションは TextMate バンドルのコマンドを読み込むことが可能です。ファイル > TextMate コマンドを読み込む... をメニューから選択し、読み込みたい TextMate バンドルを選択します。我々は TextMate コマンドとの互換性を保てるよう努力しました。その結果ほとんどの場合は読み込み後、そのままご利用いただけます。しかし、若干の変更が必要になる場合もありますので、実際に Coda での出力結果をご確認ください。
キーボードショートカットを設定する
コマンドカラムの隣をダブルクリックすると、あなたの作成したコマンドへショートカットを設定することができます。入力状態になった後、ショートカットとして設定したいキーコンビネーションを実際に押してください。もし入力されたキーコンビネーションが既に他のプラグインや Coda アプリケーション内で使われている場合は、ショートカットの右にそのことを現す警告アイコンが表示されます。
プラグインをビルドする
設定が構成され、保存されると Coda Plug-in Creator は拡張子 .codaplugin のバンドルを生成します。これを Coda のプラグインフォルダに設置することで、プラグイン利用のための準備が完了します。Coda は起動時にプラグインを読み込むので、今作成されたプラグインを利用するために Coda を再起動する必要があるかも知れません。プラグインの読み込みに失敗するか、動作が適切でない場合は、コンソールアプリケーションのエラーメッセージを参照してください。
Cocoa プラグイン API を使用する
もし Cocoa プログラミングのスキルをお持ちなら、ダイレクトにネイティブな Coda プラグインを書くことが可能です。これらのプラグインはより速く動作し、ウインドウを開いたり、独自のインタフェースを表示するなど追加機能が利用可能です。
Coda プラグインは、ファイル拡張子 .codaplugin の Cocoa バンドルである必要があります。
Coda は home > Library > Application Support > Coda > Plug-ins フォルダからプラグインを参照します。プラグインが見つかると読み込まれ、プリンシパルクラスのインスタンスが作成されます。
このインスタンスは以下のメッセージを送ります:
- (id)initWithPlugInController:(CodaPlugInsController*)inController bundle:(NSBundle*)yourBundle;
CodaPlugInsController は Coda とプラグインとがコミュニケーションする手段を提供します。また、プラグインには以下のメソッドが実装されている必要があります:
- (NSString*)name;
このメソッドは単に望ましいプラグイン名を返すべきです。これはメニュー項目などのユーザインタフェースの要素として使用される可能性があるので、短くしてください。
CodaPlugInsController クラス
CodaPlugInsController は以下のメッセージをプラグインから返します:
- (int)apiVersion;
apiVersion はバージョンにより以下が返されます:
| Coda のバージョン | API のバージョン |
|---|---|
| Coda 1.6 | 2 |
| Coda 1.6.1 | 3 |
| Coda 1.6.3 | 4 |
- (NSString*)codaVersion:(id)sender;
codaVersion はプラグインをホストしている Coda のバージョンを "1.6.1" のような文字列で返します。API の有用性を決定する apiVersion メソッドの使用がより簡単かも知れません。
- (void)displayHTMLString:(NSString*)html;
displayHTMLString は新規プレビュータブを作成し Coda はそこに HTML レンダリングされた内容を表示します。エディタのテキストに対しプラグインによって変更を加えた結果を表示するのに有用です。
- (CodaTextView*)focusedTextView:(id)sender;
focusedTextView は現在フォーカスされている Coda のエディタテキストビューで表示される抽出オブジェクトをプラグインに返します。
- (CodaTextView*)makeUntitledDocument;
makeUntitledDocument は最前面に 新規 Coda ウインドウを作成し、CodaTextView を返します。テキストビューは自動的にリリースされて返されます。そのため明確にリリースを宣言する必要はありません。
- (void)registerActionWithTitle:(NSString*)title target:(id)target selector:(SEL)selector;
registerActionWithTitle:target:selector: は与えられたタイトルでプラグインアクション（メニュー項目）をユーザに表示し、ターゲットの選択部分を実行します。
- (void)registerActionWithTitle:(NSString*)title underSubmenuWithTitle:(NSString*)submenuTitle target:(id)target selector:(SEL)selector representedObject:(id)repOb keyEquivalent:(NSString*)keyEquivalent;
これは前出の registerActionWithTitle: メソッドと同義ですが、単純な2階層のサブメニュー項目を作成可能にします。作成されたメニュー項目には representedObject および keyEquivalent の設定が可能です。
keyEquivalent は文字でキーを簡略表記するのに使われます。$ は shift キーを返し、~ は option キーを、@ は command (Apple) キーを、そして ^ は control キーを返します。従って、^@C を例にすると、control-command-C が返されます。
- (void)saveAll;
saveAll は最前面の Coda ウインドウの変更内容をすべて保存します。
CodaTextView クラス
ユーザの現在テキストエディタの CodaTextView オブジェクトを取得するために focusedTextView メッセージを CodaPlugInsController に送ります。このオブジェクトは代用であることに注意してください。NSTextView のサブクラスではありません。
API バージョン 2（Coda 1.6）以降では、以下のメソッドが利用可能です:
- (void)beginUndoGrouping;
もし取り消しアクションの一連の処理操作を実行したい場合、beginUndoGrouping を送り、実行の後 endUndoGrouping を送ります。
- (NSString*)currentLine;
currentLine は挿入ポイントがある行の全体の内容を文字列で返します。
- (unsigned int)currentLineNumber;
currentLineNumber は挿入ポイントがある行番号を返します。
- (NSRange)currentWordRange;
currentWordRange は挿入ポイントを含む単語の範囲を返します。API バージョン 3 以降が必要です。
- (void)deleteSelection;
deleteSelection は選択された範囲のテキストを削除します
- (void)endUndoGrouping;
もし取り消しアクションの一連の処理操作を実行したい場合、beginUndoGrouping を送り、実行の後 endUndoGrouping を送ります。
- (void)insertText:(NSString*)inText;
insertText: は挿入ポイントに与えられた文字列を挿入します。
- (NSString*)lineEnding;
lineEnding は書類で使用されている改行コードを返します。
- (NSString*)path;
path はテキストビューで表示されている書類のファイルシステムパスを返します。未保存の書類では何も返されません。
- (NSRange)previousWordRange;
previousWordRange は挿入ポイントの直前の単語の範囲を返します
- (NSRange)rangeOfCurrentLine;
挿入ポイントがある行の全体の文字の範囲を返します。
- (void)replaceCharactersInRange:(NSRange)aRange withString:(NSString*)aString;
与えられた範囲の文字を与えられた文字列で置き換えます。
- (void)save;
書類のあらゆる変更を保存します。
- (BOOL)saveToPath:(NSString*)aPath;
saveToPath: は指定されたローカルパスの書類を保存します。成功すると YES の値を返します。
- (NSRange)selectedRange;
selectedRange は選択されている文字の範囲を返します。範囲は空である場合もあります。
- (NSString*)selectedText;
selectedText は現在選択されているテキストもしくは nil を返します。
- (void)setSelectedRange:(NSRange)range;
setSelectedRange: は与えられた文字の範囲を選択します。
- (NSString*)siteLocalPath;
siteLocalPath はアクティブなサイトのローカルルートパスを返します。アクティブなサイトが無かったり、指定されていない場合は何も返されません。
- (NSString*)siteLocalURL;
siteLocalURL はアクティブなサイトが存在する場合はそのローカル URL を返します。アクティブなサイトが無い場合やその他の場合は何も返されません。この API を利用するには API バージョン 4 以降が必要です。
- (NSString*)siteNickname;
siteNickname は現在アクティブなサイトの名前を返します。アクティブなサイトが無い場合は何も返されません。この API を利用するには API バージョン 4 以降が必要です。
- (NSString*)siteRemotePath;
siteRemotePath は現在アクティブなサイトのリモートルートパスを返します。アクティブなサイトが無い場合はその他の場合は何も返されません。この API を利用するには API バージョン 4 以降が必要です。
- (NSString*)siteURL;
siteURL は現在アクティブなサイトのリモート URL を返します。アクティブなサイトが無い場合はその他の場合は何も返されません。この API を利用するには API バージョン 4 以降が必要です。
- (unsigned int)startOfLine;
startOfLine は挿入ポイントの行の先頭のキャラクタインデックスを（書類の先頭と比較して）返します。
- (NSString*)string;
string は書類全体をプレーンな文字列として返します。
- (NSString*)stringWithRange:(NSRange)range;
stringWithRange: は書類全体の特定のサブストリングを返します。
- (int)tabWidth;
tabWidth はタブコードの幅を返します。
- (BOOL)usesTabs;
usesTabs が YES の時、書類はインデントにタブコードを使用しており、NO の場合はスペースが使用されていることを返します。
- (NSWindow*)window;
テキストビューに含まれるウインドウにポインタを返します。作成されるプラグインが使用しなければならない場合にのみ、シートまたは基本的な UI に限定して使用することを強く推奨します。
Info.plist で API バージョンを指定する
作成されるプラグインがあるバージョン以降の Coda プラグイン API を必要とする場合、CodaPlugInMinimumAPIVersion キーをプラグインの Info.plist に追加します。このキーの値は -apiVersion メソッドで返される値と同様に整数です。
この様な API バージョンの指定が特に必要ない場合、Coda は自身のバージョンでサポートしている API で動作可能なプラグインと認識します。にも関わらず特定のバージョン以上が必要な API が呼び出された場合、Coda は例外エラーを表示します。
このキーは Coda 1.6.1 以降でサポートされます。