# マクロ

コマンドのパラメータとしてマクロを使用することができる。
マクロを使うと、クリップボード/時刻/環境変数の値など、その時々や環境に応じて変化する動的な値に置き換えることができる。

マクロは`${macroName arg1 arg2 ...}` のような書式で指定する。

引数がないマクロの場合は`$macroName`という書式も可能

- マクロの一覧

- app

- basename

- clipboard

- date

- env

- explorer

- random

- afxw

- powerstatus

## app

アプリケーション名やアプリケーションのバージョン、ビルド日時を得る

### 記法

以下のいずれかを指定できる。

- `${app}`

  - アプリ名を得る

- `${app name}`

  - アプリ名を得る

- `${app version}`

  - バージョン番号を得る

- `${app builddate}`

  - ビルド日を得る

- `${app buildtime}`

  - ビルド時刻を得る

### 例

    # アプリ名を得る
    ${app}   → (アプリ名)
    ${app name}   → (アプリ名)
    # バージョン番号を得る
    ${app version}   → 0.30.0
    # ビルド日を得る
    ${app builddate}   → 2024/11/08
    # ビルド時刻を得る
    ${app builddate}   → 01:23:45

## basename

引数で与えたパスからファイル名を除去する

### 記法

`${basename パス文字列}`の形式で指定する。

### 例

    # ディレクトリパスを得る
    ${basename c:\dir\a.txt }   → c:\dir

## clipboard

クリップボードに入っている値に置き換えることができる。

### 記法

`${clipboard}`の形式で指定する。

## date

現在の日付・時刻に置き換えることができる。

日付・時刻に置き換える際の書式を指定したり、現在時刻に対して任意のオフセット(時間差分)を指定できる。

### 記法

`${date [format [offset]]}`の形式で指定する。

`format`で日付の書式を指定できる。

書式を指定しない場合は、時分秒(`%H:%M:%S`)を表示する

`offset`でオフセットを指定する。

オフセットを指定しない場合は現在時刻を表示する。

### 日付の書式

strftimeの書式をそのまま指定する。

コード | 意味 | 例
--- | --- | ---
`%a` | ロケールでの曜日 | 火
`%A` | ロケールでの曜日(完全) | 火曜日
`%b` | ロケールでの月 | 11
`%B` | ロケールでの月(完全) | 11月
`%c` | ロケールでの日付と時刻 | 2024/11/19 12:34:45
`%C` | 西暦上二桁 | 20
`%d` | 月の日付(1-31) | 19
`%D` | %m/%d/%y | 11/19/24
`%e` | 月の日付、右寄せ二桁 | 9
`%e` | 月の日付、右寄せ二桁 | 9
`%F` | %Y-%m-%d | 2024-11-19
`%g` | 西暦の年の下二桁 | 24
`%G` | 西暦の年 | 2024
`%h` | `%b`と同じ | 11
`%H` | 24 時間形式の時(00-23) | 14
`%I` | 12 時間形式の時(01-12) | 2
`%j` | 年の通算日 (001 - 366) | 324
`%m` | 月 (01 - 12) | 11
`%M` | 分 (00 - 59) | 25
`%n` | 改行文字 | -
`%p` | ロケールでの午前/午後表記 | 午前
`%r` | ロケールでのAM/PM形式の時刻 | xxx
`%R` | `%H:%M`と同じ | 14:09
`%S` | 秒(00 - 59) | 48
`%t` | タブ文字 | -
`%T` | `%H:%M:%S`と同じ | 14:10:59
`%u` | 曜日を表す数値(1 - 7、月曜日が 1) | 2
`%U` | 年の週数(0-53)。週の初日は日曜 | 46
`%V` | 年の週数(1-53)。週の初日は日曜 | 46
`%w` | 曜日を表す数値(0 - 6、日曜日が 0) | 2
`%W` | 年の週数(00-53)、週の初日は月曜 | 46
`%x` | ロケールでの日付表現 | 2024/11/19
`%X` | ロケールでの時刻表現 | 14:43:56
`%y` | 西暦下二桁(00 - 99) | 24
`%Y` | 西暦四桁(00 - 99) | 2024
`%z` | 時差。UTCからのオフセット | +0900
`%Z` | ロケールでのタイム ゾーン名称 | 東京(標準時)
`%%` | パーセント記号 | %

### オフセット

以下の形式で指定する。

    [S](+ or -)(オフセット値)(Y or M or D or h or m or s)

- 先頭に`S`を指定した場合、その週の日曜日をベースにオフセット計算をする

- 符号`+`を指定すると、ベース時刻に対して`オフセット値`ぶんの時間を進める
  逆に、符号`-`を指定すると、時間を戻す

- 単位

  - `Y`:年

  - `M`:月

  - `D`:日

  - `h`:時

  - `m`:分

  - `s`:秒

- `+1d` → 1日後

- `-5h` → 5時間前

- `+30s` → 30秒後

- `+3M` → 3カ月後

- `-1Y` → 1年前

### 例

    # マクロ実行日時が 2024/11/18(月) 12:34:45 だったとする

    ${date}
      → 12:34:45

    ${date "%Y/%m/%d" +1D}
      → 2024/11/19 (翌日の年月日)

    ${date "%Y/%m/%d" S+1D}
      → 2024/11/18 (日曜日11/17の1日後の年月日)

### 制限

- オフセットで日付を計算する際にうるう年を考慮していない(手抜き)

- オフセットの複数単位の同時指定には対応していない(例: 1.5日`+1d+12h`)

## env

環境変数の値に置き換えることができる。

### 記法

`${env 環境変数名}`の形式で指定する。

### 例

    # ユーザーのホームディレクトリのパスを取得する
    ${env USERPROFILE}
     → C:\Users\username

    # ユーザー名を取得する
    ${env USERNAME}
     → username

## explorer

表示中のエクスプローラの現在パスや選択中のファイルパスを取得・展開することができる。

### 記法

- エクスプローラで表示中のフォルダパスに展開する場合は `${explorer location_path}`と記載する。

- エクスプローラで選択している項目のファイルパスを展開したい場合は `${explorer selection_path [index]}`と記載する。
  `index`を指定した場合、`index`番目のパスに置き換える(0～)。
  `index`を指定しなかった場合、選択中のすべての要素に置き換える。

- 該当する要素が存在しない場合は空文字列に置換される

  - 例: エクスプローラを開いていない、ファイルを選択していない、等

- 表示中のエクスプローラのウインドウが複数ある場合は、最も前面にあるウインドウの情報を取得する。

### 例

    # エクスプローラで現在表示しているフォルダパスを取得する
    ${explorer location_path}
     → "C:\Program Files(x86)"

    # エクスプローラで選択している一つ目のファイルパスを取得する
    ${explorer selection_path 0}
     → "C:\Users\usename\AppData\Local\Microsoft\WindowsApps\mspaint.exe"

    # エクスプローラで選択している全てのファイルパスを取得する
    ${explorer selection_path}
     → "C:\Users\usename\AppData\Local\Microsoft\WindowsApps\ms-teams.exe" "C:\Users\usename\AppData\Local\Microsoft\WindowsApps\mspaint.exe"

## random

乱数を生成する系の処理を行うためのマクロ。
現在はuuidの生成のみをサポートする。

### 記法

`${random 種類}`の形式で指定する。

### 例

    # UUIDを生成する
    ${random uuid}
      → 36128e01-947e-4bd2-864c-16a234c32a8d

## afxw

外部ファイラとしてあふwを利用している場合に、あふw側で表示しているカレントディレクトリを取得することができる。

このマクロを使うにあたり、あふw側の設定でオートメーションサーバ登録しておく必要がある。

### 記法

`${afxw currentdir}`と記述する。

## powerstatus

【試作】
電源状態に関する情報を取得し表示することができる。

### 記法

`${powerstatus format}`の形式で記述する。

`format`部分に表示する情報を表す指定子のいずれかを記述する。

指定子 | 意味
--- | ---
`%l` | バッテリー残量を表すパーセント(`0-100%`)、バッテリー駆動でない場合は`(不明)`
`%a` | AC電源に接続されているかの状態 `オンライン`、`オフライン`、`不明`のいずれか