プログラミング

Maak.el: Emacs 用の Lisp マシンコマンドランナー、無限に拡張可能で Scheme 対応

Maak.el: Lisp machine command runner in Emacs, infinitely extensible and Scheme (codeberg.org)

20 pointsby jjba232026年9月8日4 コメント

要約

Maak.el は Emacs 上で動作する Lisp マシンコマンドランナーです。無限の拡張性を持ち、Scheme 言語にも対応しています。

全文翻訳

maak.el — EmacsのためのMaak統合

［画像: https://jointhefreeworld.org/ggg/dist/emacs-lisp.svg］［画像: https://jointhefreeworld.org/ggg/dist/maak.svg］［画像: https://jointhefreeworld.org/ggg/dist/license-gpl3+.svg］［画像: https://jointhefreeworld.org/ggg/dist/license-fdl13+.svg］

maak.elは、Maak: The infinitely extensible command runner, control plane and project automator à la Make (Guile Scheme - Lisp) のシームレスな統合をあなたのEmacsワークフローにもたらします。Maakは、古風なMakefileをGNU Guile Schemeのエレガントさとパワーで置き換えます。maak.elを使えば、Emacsの快適な環境から、リッチなミニバッファ補完機能を備えたMaakタスクを発見、検査、実行できます。

ほとんどのビルドツールは、独自の限定的なドメイン固有言語を発明します。Maakは、強力なλ Lispと素晴らしいGuile Schemeプログラミング言語を採用しています。

これは、あなたのコードが少なくとも今後50年間、柔軟で、堅牢で、信頼性が高く（宣言的）であることを意味します。

自動プロジェクト検出: ドミナントファイルヒューリスティクスを使用して、ルートのmaak.scmファイルを自動的に検出します。
スマートな可視性解析: Maak設定の#:exportリストを尊重し、公開タスクのみを表示します（エクスポートがない場合はすべて表示）。
洗練された補完UI: 好みの補完フレームワーク（Vertico, Ivy, Helm, またはネイティブcompleting-read）で、タスクのシグネチャとドキュメンテーション文字列を示す、整列した列を実装します。
対話的な引数収集: タスクがパラメータを期待する場合、maak.elは実行前にミニバッファでそれらを順番にプロンプトし、Guileの完全なラムダリスト（必須、#:optional, #:key, #:restおよびドット付きレスト引数）を理解します。
ネイティブコンパイルバッファ: Emacsのネイティブcompileシステムを介してタスクを非同期に実行し、シェルエスケープを確実にし、エラーに直接ジャンプできるようにします。

［画像: https://jointhefreeworld.org/static-assets/maak/maak-in-emacs.png］

標準的なEmacsのプロパティのおかげで、タスクは補完リストで動的にフォーマットされます。テーマのデフォルトのフォントロックフェイスに合わせた、美しく整列した列でレンダリングされます。

Lispは普遍的であり、SchemeとEmacs Lispは相互に解析可能であるため、maak.elはmaak.scmをローカルかつクリーンに解析し、S式やコメントなどを認識します。

Schemeフォームを安全に解析するために、標準のEmacs Lispモード内に一時的なバッファを起動します。
モジュールの#:exportフォーム（コメントや文字列をシームレスに処理）を見つけて、ホワイトリストを作成します。
公開エクスポート（またはエクスポートがない場合はすべて）に一致する定義済みプロシージャをマッピングし、Schemeのドキュメンテーション文字列と正式なパラメータリストを抽出します。

 ,---.       ,---.
(     \     /     )
 )  (  \____/  )  (
(    \ @  @ /    )
 )    ( oo )    (
(      \__/      )
  `------------'      [ Maak ]
                      The infinitely extensible
                      command runner, control plane,
                      and project automator.

私の仕事が気に入ったら、コーヒー一杯おごる ☕ことで応援してください。そうすれば、多くのモチベーションを維持できます。

コミュニティとサポート

maakコミュニティに参加して、質問、開発に関する議論、設定の共有、スクリーンショット、問題の報告、または単に交流してください。

問題と開発: Codebergリポジトリ

チャット、サポート、ディスカッション、アナウンス（Zulip）: Maak Zulipコミュニティに参加

どこから始めればよいかわからない場合は、Zulipをお勧めします。Codebergの問題も、アイデアの追加、バグの報告、改善点の指摘に良い場所です。

インストール

このパッケージは、MELPAやELPAのような人気のEmacsリポジトリには（まだ）利用できません。Elpacaを使用したインストールの例:

  (use-package maak.el
    :ensure (:host codeberg :repo "jjba23/maak.el" :branch "trunk")
    :demand t
    :bind ("C-c m r" . maak-run-task))

使用法

タスクの実行

プライマリコマンドを呼び出します。

M-x maak-run-task

Emacsは、現在のバッファから上に検索してmaak.scmファイルを探します。
スキーム設定からエクスポートされたすべてのタスクをリストする補完メニューが表示されます。
選択したタスクがパラメータを定義している場合（例: (define (deploy server env) ...)）、ミニバッファが順番にプロンプトを表示します。
オプション引数は、空行で応答することで省略できます。その場合、コマンドラインには渡されず、タスク自体のデフォルト値が適用されます。
標準の*compilation*バッファが起動し、maak <args...>を介してタスクを実行します。

標準のEmacsプロパティを使用して、タスクは補完リストで動的にフォーマットされます。テーマのデフォルトのフォントロックフェイスに合わせた、美しく整列した列でレンダリングされます。

タスク引数

maak.elは、Guileとmaakが行うようにタスクの引数リストを読み取るため、プロンプトとコマンドラインはタスクが受け取るものと一致します。

Maakファイルでの形式	`maak.el`の動作
`(define (deploy target) ...)`	`target`をプロンプトします。何も入力しないと、何も実行される前にエラーになります。
`(define* (deploy target #:optional env) ...)`	`env`もプロンプトします。空行で応答すると、コマンドラインから除外されます。
`(define* (deploy target #:optional (env "dev")) ...)`	デフォルト値が表示されます。空行で応答すると、タスクはそのデフォルト値を使用します。
`(define* (deploy target #:optional (env "dev")) ...)`	`#:env=dev`が補完に表示されます。プロンプトは表示されません。なぜなら、maakは文字列のみを渡すからです。
`(define (echo . words) ...)` または `#:rest words`	スペース区切りの単語を一度プロンプトします。空行で応答すると、何も渡されません。

空行で応答されたオプション引数は省略され、空文字列""として渡されることはありません。これがタスク側でデフォルト値が機能する理由です。オプション引数を省略すると、その後の引数も省略されます。なぜなら、maakは位置引数を順序通りにバインドするため、2番目のオプション引数が空の場合に3番目のオプション引数に値を渡す方法はないからです。

キーワード引数はデフォルト値とともに表示されますが、プロンプトは表示されません。maakコマンドラインは位置文字列を渡しますが、文字列はキーワードではないため、キーワード引数は常にデフォルト値として到着します。maak kw helloは、キーワードを設定する方法ではなく、エラーになります。デフォルト値のないキーワード引数はまったく提供できないため、GuileがMissing keywordで失敗するのを待つのではなく、maak.elは実行前にその旨を表示します。

(define* (deploy target #:optional (env "staging"))
  "Deploy TARGET to ENV."
  ...)

deployを選択し、prodと入力してRETを押すと、以下が実行されます。

maak deploy prod

これにより、タスクはenv = "staging"として受け取ります。空文字列ではありません。ダッシュで始まる引数は--で区切られます。例えばmaak quick-math -- -23 42のように、各単語は個別にシェル引用されるため、引数内のスペースや引用符は保持されます。

カスタマイズ

Emacs Lispの設定（またはM-x customize-group RET maak RET経由）で、maak.elの動作や外観をカスタマイズできます。注目すべき変数やフェイス:

変数 / フェイス	デフォルト値	説明
`maak-annotation-padding`	`4`	補完列の引数とドキュメンテーション文字列の間に維持するスペースの数。
`maak-executable`	`"maak"`	タスクを実行するmaak実行可能ファイルの名前またはパス。
`maak-task-arguments-face`	`font-lock-variable-name-face`（イタリック）を継承	補完リストのタスク引数リストのレンダリングに使用されるフェイス。
`maak-task-documentation-face`	`font-lock-doc-face`を継承	補完リストのタスクドキュメンテーション文字列のレンダリングに使用されるフェイス。

Schemeフォームを安全に解析するために、標準のEmacs Lispモード内に一時的なバッファを起動します。
モジュールの#:exportフォーム（コメントや文字列をシームレスに処理）を見つけて、ホワイトリストを作成します。
公開エクスポート（またはエクスポートがない場合はすべて）に一致する定義済みプロシージャをマッピングし、Schemeのドキュメンテーション文字列と正式なパラメータリストを抽出します。

開発

プロジェクト自体のmaak.scmがチェックを定義しています。

maak test               # ERTスイート
maak test optional      # "optional"に一致する名前のテストのみ
maak byte-compile       # 警告をエラーとしてmaak.elをバイトコンパイル
maak ci                 # 両方

または、スイートを直接実行します。

emacs -Q --batch -L . -l test/maak-test.el -f ert-run-tests-batch-and-exit

test/fixturesの下のフィクスチャは、すべての引数形式をカバーしています。2つのテストは、パーサーを参照実装に対してチェックします。1つは各フィクスチャタスクのarityをGuileに問い合わせ、もう1つはタスクリストをmaak --listに問い合わせるため、文法の変更は、古い仮定ではなく、失敗したテストとして表示されます。

Lispからは、maak-get-tasksがタスクごとに1つの(TASK-NAME DOCSTRING ARGUMENTS)エントリを返し、各引数は:name, :kind（required, optional, keyまたはrest）と、存在する場合は:defaultおよび:default-pを持つplistです。キーワード引数は:keywordも持ちます。

ライセンス

Maakおよびそのすべてのソースコードは、フリーソフトウェアであり、GNU General Public License v3（または都合の良い新しいバージョン）の下でライセンスされています。

https://www.gnu.org/licenses/gpl-3.0.html

Maakに付属するドキュメントと例（このドキュメントを含む）はすべて、GNU Free Documentation License v1.3（または都合の良い新しいバージョン）の下でライセンスされています。

https://www.gnu.org/licenses/fdl-1.3.html

AIポリシー

このプロジェクトは、jointhefreeworld AI (Artificial Intelligence) policy を遵守しています。

私たちの中心的な原則はシンプルです：AIは人間の創造性と問題解決を支援すべきであり、人間の推論を置き換えるべきではありません。

大規模言語モデル（LLM）や対話型チャットボットのようなツールは、レビュー、小規模関数のリファクタリング、またはサウンドボードとして役立つ可能性がありますが、適度に使用する必要があります。

すべての貢献において、人間を介在させることを要求します。このプロジェクトへのプルリクエストを自動生成して送信するために、自律的なAIエージェントを使用することは固く禁じられています。

行動規範

このプロジェクトは、jointhefreeworld行動規範を遵守しています。こちらをご覧ください。

https://jointhefreeworld.org/blog/articles/personal/jointhefreeworld-code-of-conduct/index.html

要約すると、私たちはこのフリーソフトウェアプロジェクトのすべての貢献者とユーザーのために、包括的で、敬意があり、協力的な環境を育みます。GNUプロジェクトの理想に触発され、自由、平等、そしてコミュニティを指針となる原則として維持するよう努めます。相互尊重のコミュニティにおける協力が、優れたフリーソフトウェアを作成するために不可欠であると信じています。