hmPSが持つ特別な関数一覧

  • ヒアドキュメント

    hmPSの機能ではなく、秀丸マクロの機能となりますが、hmPSと関係が深いものとして、
    秀丸エディタ 8.66では、C++の「R""」やC#の「@」のようなものが秀丸マクロで利用可能となっています。

    このため、秀丸マクロ内に、PowerShellをそのまま直接書き込めるようになりました。
    これは非常に大きなメリットと言えるでしょう。

    又、8.66以前のバージョンでは秀丸マクロの文字列リテラル(べた書きの文字列)の最大長は4Kバイトでしたが、
    8.66以降では、64Kバイトとなりました。
    これは、「連続1500行程度のPowerShellをマクロ内に直接張り付けることが出来る」ことを意味します。

  • デバッグ用途関数

    デバッグ用途として以下の関数を利用し、「秀丸デバッグモニター」などに値や文字列を表示することが出来ます。

    • $hm::debuginfo( 文字列 )

      対象の文字列を、システムデバッガへと文字列を転送します。
      「秀丸デバッグモニター」などに値や文字列を確認することが可能です。

  • 秀丸本体のバージョン

    秀丸本体のバージョンを数値として取得します。

    • $hm::version

      秀丸 8.7.3.β3 の場合は、873.03、
      秀丸 8.7.3.β10 の場合は、873.10、
      秀丸 8.7.3 正式版 の場合は、873.99、
      といったような値が返ってきます。

  • 編集中エディタに対する関数

    現在秀丸エディタで開いているテキストに対して、以下の関数を利用することが出来ます。

    • テキスト全体

      • $hm::Edit::TotalText

        現在編集中の秀丸エディタのテキスト全体を得る

      • $hm::Edit::TotalText = "文字列"

        現在編集中の秀丸エディタのテキスト全体を、文字列へと変更する

      #PS = loaddll( hidemarudir + @"\hmPS.dll" );
      
      #_ = dllfuncw( #PS, "DoString", R"PowerShell(
      $totaltext = $hm::Edit::TotalText;
      $hm::debuginfo($totaltext);
      
      $hm::Edit::TotalText = "あいうえお";
      )PowerShell");
      
      freedll( #PS );
      
    • 選択中のテキスト

      (単純選択のみが対象となります。ボックス選択や複数選択は対象にはなりません)

      • $hm::Edit::SelectedText

        現在編集中の秀丸エディタの「選択している」テキストを得る。

      • $hm::Edit::SelectedText = "文字列"

        現在編集中の秀丸エディタの「選択している」テキストを、"文字列"へと置き換える。

      #PS = loaddll( hidemarudir + @"\hmPS.dll" );
      
      #_ = dllfuncw( #PS, "DoString", R"PowerShell(
      # 何かを単純選択していたら、テキストが得られる
      $selectedtext = $hm::Edit::SelectedText;
      $hm::debuginfo($selectedtext);
      
      $hm::Edit::SelectedText = "選択しているテキストをこの文字列に置き換えた";
      
      )PowerShell");
      
      freedll( #PS );
      
    • カーソルがある行のテキスト

      • $hm::Edit::LineText

        現在編集中の秀丸エディタの「カーソルがある行」のテキストを得る。

      • $hm::Edit::LineText = "文字列"

        現在編集中の秀丸エディタの「カーソルがある行」のテキストを、文字列へと置き換える。

      #PS = loaddll( hidemarudir + @"\hmPS.dll" );
      
      #_ = dllfuncw(  #PS, "DoString", R"PowerShell(
      $linetext = $hm::Edit::LineText;
      $hm::debuginfo($linetext);
      
      # 行のテキストを入れ替える感じにするなら、最後に「\n」を付けること。
      $hm::Edit::LineText = "カーソル行のテキストをこれに変更\n";
      )PowerShell");
      
      freedll( #PS );
      
    • カーソルの位置

      • $hm::Edit::CursorPos.lineno

        現在選択中の秀丸エディタのカーソル位置の行番号を得る。
        秀丸マクロのlinenoと同じ値。

      • $hm::Edit::CursorPos.column

        現在選択中の秀丸エディタのカーソル位置のカラム値を得る。
        秀丸マクロのcolumnと同じ値。

      #PS = loaddll( hidemarudir + @"\hmPS.dll" );
      
      #_ = dllfuncw(  #PS, "DoString", R"PowerShell(
      $lineno = $hm::Edit::CursorPos.lineno;
      $column = $hm::Edit::CursorPos.column;
      $hm::debuginfo( [string]$lineno + "," + [string]$column );
      )PowerShell");
      
      freedll( #PS );
      
    • マウスの位置に対応するカーソルの位置(秀丸エディタ v8.73以上)

      • $hm::Edit::MousePos.lineno

        現在選択中の秀丸エディタの「マウスの位置に対応するカーソル位置」の行番号を得る。

      • $hm::Edit::MousePos.column

        現在選択中の秀丸エディタの「マウスの位置に対応するカーソル位置」のカラム値を得る。

      #PS = loaddll( hidemarudir + @"\hmPS.dll" );
      
      #_ = dllfuncw( #PS, "DoString", R"PS(
      $lineno = $hm::Edit::MousePos.lineno;
      $column = $hm::Edit::MousePos.column;
      $x = $hm::Edit::MousePos.x; # マウスのスクリーン座標
      $y = $hm::Edit::MousePos.y; # マウスのスクリーン座標
      $hm::debuginfo( $lineno, $column );
      )PS");
      
      freedll( #PS );
      
  • PowerShellから秀丸マクロへアクセスする関数

    PowerShellの機能をフルに生かしつつ、秀丸マクロの機能や各種値もほぼ全て使えるところが、
    hmPSが優れている所以です。

    • 秀丸マクロをそのまま実行
    • 「秀丸マクロの変数」⇔「PowerShellの変数」を相互にやり取り。

    の2つの手段で秀丸マクロを取り扱うことが出来ます。

    • PowerShellから秀丸マクロを実行

      秀丸エディタ 8.66以降では、Hidemaru_EvalMacroという関数が秀丸本体からエキスポートされたため、
      マクロ実行中であれば、秀丸マクロ以外の場所からでもマクロを記述し、実行することが可能となりました。

      • $hm::Macro::Eval( ヒアドキュメント文字列)

        引数の文字列を、「秀丸マクロ」として実行する。

      #PS = loaddll( hidemarudir + @"\hmPS.dll" );
      
      if ( !#PS ) {
          message("hmPS.dllが導入されていません");
          endmacro;
      }
      
      #_ = dllfuncw(#PS, "DoString", R"PowerShell(
      
      #PowerShellの中で、$hm::Macro::Eval関数を使って、秀丸のマクロを書くことが出来る
      $hm::Macro::Eval( @'
        #a = 3;
        debuginfo 1;
        showvars;
        message("あいうえお");
      
        showvars;
      '@
      );
      
      )PowerShell"
      );
      
      freedll( #PS );
      
    • PowerShellから秀丸マクロの変数の読み書き

      • $hm::Macro::Var["変数名"]

        対象の「秀丸マクロ」としてのシンボル名に対応する値を取得する。

      • $hm::Macro::Var["変数名"] = 新たな値

        対象の「秀丸マクロ」としてのシンボル名に、新たな値を設定する。
        (読み取り専用の値には設定出来ません)

      #PS = loaddll( hidemarudir + @"\hmPS.dll" );
      
      #_ = dllfuncw(  #PS, "DoString", R"PowerShell(
      
      # 秀丸マクロの「#aaa」という変数に3を設定。
      $hm::Macro::Var['#aaa'] = 3;
      
      # 秀丸マクロの「$bbb」という変数に「あいうえお」を設定。
      $hm::Macro::Var['$bbb'] = "あいうえお。"
      
      # 秀丸マクロとして一連の文字列を実行
      $hm::Macro::Eval( @'
          message($bbb);
          $$message = $bbb + $bbb;
          message($$message);
      
          // アウトプット枠へ出力
          #OP = loaddll("HmOutputPane.dll");
          #ret = dllfunc(#OP, "Output",hidemaruhandle(0), $$message);
          freedll(#OP);
      '@
      );
      
      $hm::debuginfo( $hm::Macro::Var['$bbb'] );
      $hm::debuginfo( $hm::Macro::Var['filename'] );
      
      $hmdate = $hm::Macro::Var['date'];
      $hm::debuginfo( $hmdate );
      
      )PowerShell"
      );
      
      freedll( #PS );
              

      上記の例はさほど意味がある例題ではありませんが、 実践では「フォーム系」を使ったPowerShell層で、
      「フォームを閉じることなく、イベントハンドラに呼応する形で(フォームを閉じることなく)秀丸を制御したい場合」などに威力を発揮することでしょう。
      又、ループを伴った値の伝達なども、秀丸マクロ層でやるよりも、PowerShell層でやった方が記述が簡潔に済みます。

      #PS = loaddll( hidemarudir + @"\hmPS" );
      
      #_ = dllfuncw( #PS, "DoString", R"PS(
      [System.Reflection.Assembly]::LoadWithPartialName("System.Windows.Forms")
      
      class MyForm {
          [int] $counter;
          [System.Object] $form
          [System.Object] $btn
      
          SetForm() {
              $this.form = New-Object System.Windows.Forms.Form;
              $this.form.Text = "こんにちわ";
          }
      
          SetButton() {
              $this.btn = New-Object System.Windows.Forms.Button;
              $this.btn.Text = "クリック";
              $this.btn.Left = 16;
              $this.btn.Top = 16;
              $this.btn.Width = 100;
              $this.btn.Height = 40;
              $this.btn.Tag = $this;
      
              # イベントハンドラも作れる
              $this.btn.Add_Click({
                  ($sender, $event) = ($this, $_);
                  btn_Click($sender, $event);
              });
      
              $this.form.Controls.Add($this.btn);
          }
      
          Show() {
              $this.counter = 0;
              $this.SetForm();
              $this.SetButton();
       
              $this.form.ShowDialog();
          }
      
      }
      
      
      function btn_Click($sender, $event) {
          $sender.Tag.counter++;
      
          # デバッグモニター用の関数
          $hm::debuginfo("ボタンが押されたよ!!");
          $hm::debuginfo($sender.Tag.counter);
      
          # 秀丸マクロの「変数」とのやりとりも自由自在
          ($filename2) = $hm::Macro::Var['filename2'];
          $hm::debuginfo($filename2);
      
          # 秀丸マクロの「変数」とのやりとりも自由自在
          $hm::Macro::Var['$counter'] = [string]$sender.Tag.counter
          # PowerShellの中から秀丸マクロを一連のコマンドとして実行することも出来る。
          # PowerShellには「ヒアドキュメント」が使えるのでちょうどよい
          $hm::Macro::Eval(
      @'
              // アウトプット枠へ出力
              #OP = loaddll("HmOutputPane.dll");
              #ret = dllfunc(#OP, "Output",hidemaruhandle(0), $counter);
              freedll(#OP);
      '@  );
          }
      
      
      
      $f = New-Object MyForm;
      $f.Show();
      
      )PS"
      );
      
      freedll(#PS);
              
  • $hmはグローバル

    「$hm::Edit::***」や「$hm::Macro::***」ではアクセスできない場合、 「::$hm::Edit::***」や「::$hm::Macro::***」など、頭に「::」を付け、
    大域変数へのアクセスであることを明示する必要があります。

  • DestroyScope関数

    PowerShell内に「DestroyScope」という名前の関数を用意しておくと、
    マクロ終了時に自動的にその関数が実行されます。

    #PS = loaddll( hidemarudir + @"\hmPS.dll" );
    
    #_ = dllfuncw( #PS, "DoString", R"PS(
    function DestroyScope() {
      $hm::debuginfo("マクロ終了する直前に自動的にこの関数が呼び出される。");
    }
    
    )PS"
    );
    
    freedll(#PS);
    
  • 簡易なHTMLエンコードの例

    #PS = loaddll( hidemarudir + @"\hmPS.dll" );
    
    if (! #PS) {
      message("hmPSが導入されいません。");
      endmacro;
    }
    
    #_ = dllfuncw( #PS, "DoString", R"PowerShell(
    [System.Reflection.Assembly]::LoadWithPartialName("System.Web")
    
    $html = [System.Web.HttpUtility]::HtmlEncode($hm::Edit::TotalText)
    $html = $html.Replace("\r\n", "\r")
    $html = $html.Replace("\n", "\r")
    $html = $html.Replace("\r", "<br>\r\n")
    $html = $html.Replace("  ", " &nbsp;")
    
    $hm::Edit::TotalText = $html
    
    )PowerShell"
    );
    
    freedll( #PS );