Zenn
🐧

WSL開発環境: whatコマンドによるスクリプト管理

2024/01/09に公開
Linux
shell
コメント
what
whatdoc
tech

はじめに

スクリプトの管理に役立つwhatコマンドの使い方を紹介します。
whatコマンドは、whatdocコメントという特定のフォーマットのコメントをもとに、スクリプトのバージョンや説明を出力します。
whatコマンドとwhatdocコメントを活用することで、スクリプトの理解が容易になります。

キーワード

以下で、使用する重要なキーワードを説明します。

  • whatコマンド:
    ファイルのメタデータ (バージョン、説明など)を出力するコマンド。メタデータは、ファイル内のwhatdocコメントで記述される。

  • whatdocコメント:
    スクリプト内に記述される特定のフォーマットのコメント。メタデータ (バージョン・作成日・説明など) の提供に利用される。

  • SCCS (Source Code Control System):
    旧来の UNIX系OS で使われていたバージョン管理システム。whatコマンドの起源となっている。

  • メタデータ:
    スクリプト、設定ファイルのバージョンや説明などを指す。

  • シェルスクリプト:
    コマンドラインで実行するスクリプト言語であり、Unix/Linux系OS で広く利用される。

1. whatコマンドの概要

whatコマンドは、シェルスクリプトや設定ファイルのメタデータ (バージョン、説明など) を出力するコマンドです。
whatdocコメントという特定のフォーマットで書かれたコメントをもとに、スクリプトのバージョンや説明を出力します。

注意
whatdocコメントに関しては、4. whatdocコメントの基本を参照してください。

2. whatコマンドのインストール方法

WSL上の Debian にwhatコマンドをインストールする方法を説明します。

2.1 whatコマンドのインストール手順

whatコマンドは、次の手順でインストールします:

  1. whatコマンドのダウンロード
    下記のコマンドを実行して、what コマンドをダウンロードする。

    wget https://raw.githubusercontent.com/atsushifx/agla-shell-utils/main/agla/what

  2. whatコマンドのインストール
    ダウンロードしたwhatコマンドをpathの通ったディレクトリにコピーする。

    sudo cp what /opt/bin

  3. 実行権限の追加:
    コピーした whatコマンドに実行権限を追加する。

    sudo chmod +x /opt/bin/what

以上で、whatコマンドが使えるようになります。

3. whatコマンド の基本機能

whatコマンドは、指定したファイルに関するメタデータ (バージョン、説明など) を出力します。
このセクションでは、whatコマンドの使用方法を説明します。

3.1 whatコマンドの基本操作

whatコマンドの基本的な使い方は以下のとおりです。

what <ファイル名>

で、指定したファイルのバージョンと 1行説明を出力します。

下記のようなwhatdocコメントがファイルの場合では、

sample.sh
#!/usr/bin/env bash
#
# @(#) : Sample script to demonstrate whatdoc
# 注意: このスクリプトは`whatdoc`のデモンストレーションです
#
# @version  1.0.0
#

whatコマンドの実行結果は、次のようになります。

$ what sample.sh
sample.sh: (v 1.0.0) :  Sample script to demonstrate whatdoc

このように、シェルスクリプトに関する情報を簡単に得ることができます。

3.2 whatコマンドの応用操作

'-d'オプションで、スクリプトの詳細な説明を表示します。
これにより、より深い理解が可能になります。

このときのコマンドは:

what -d <ファイル名>

となります。

what コマンドの場合は:

$ what -d what

what <file>
print shell script usage

-d    print usage created by header
-v    print version
-h -? print this usage

THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND.
THE ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE USER.

となります。

4. whatdocコメントの基本

whatコマンドでコマンドの説明を出力するには、ファイル内に適切なwhatdocコメントを追加する必要があります。
whatdocコメントを適切に使用することで、スクリプトの目的、使用方法などが簡単に把握できます。
これにより、スクリプトのメンテナンスが格段に容易になります。

4.1 whatdocコメントの基本フォーマット

whatdoc コメントは、以下のようなフォーマットで記述します:

#!/usr/bin/env bash
#
# @(#) : display shell script usage
#
# @version 1.0.0
# @author  Furukawa Atsushi <atsushifx@aglabo.com>
# @date    2023-12-27
# @license MIT
#
# @desc
#
# what <file>
#  print shell script usage
#
# -d    print usage created by header
# -v    print version
# -h -? print this usage
#
#
###
#
# THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND.
# THE ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE USER.
#
#

注意事情:
whatdoc コメントはヘッダー部に記述します。shebangのあとに#コメントを続ける必要があります。

whatdoc コメントは、@(#)からはじまります。
@(#)は、SCCSという UNIX系OS で使われてたバージョン管理システム用のヘッダーです。
ここから、ヘッダーコメントの最終行までが whatdoc コメントになります。

4.2 whatdocコメントのヘッダー (short desc)

@(#)ではじまるコメントは、コマンドの簡単な説明となります。
what <ファイル名>で出力される説明は、ここのコメントとなります。

4.3 コメントタグの一覧

whatdoc コメントでは、@から始まるキーワードをコメントタグとして認識します。
現在、what コマンドでは@versionしか使っていません。
シェルスクリプトの管理のためには、@authorなどのほかのタグも書いておくといいでしょう。

コメントタグの一覧を下記に載せておきます:

コメントタグ 記法 説明 備考
@(#) @(#) : <短い説明> シェルスクリプトの簡単な説明 whatコマンドで、スクリプトの簡単な説明として利用される
@version @version <バージョン番号> バージョン番号をセマンティックバージョニングで記述する what の short descにバージョン番号を出力
@author @author <氏名> スクリプトの作成者を記述
@date @date <日時> スクリプトの作成日時を記述
@license @license <ライセンス> スクリプトのライセンスを略号で記述
@desc @desc ... スクリプトの長い説明を複数行のコメントで記述 詳細は、後述

4.4 @descタグ (long descの使用 )

@descタグは特殊で、複数行に渡ってコメントを記述します。
@descタグ以降の、行頭に#をつけたコメントをヒアドキュメントとして認識し、残りのヘッダコメント
が@descタグによるドキュメントとなります。

  # @author  Furukawa, Atsushi <atsushifx@aglabo.com>
  # @date    2023-12-27
  # @license MIT
  #
  # @desc
+-#
| # what <file>
| #  print shell script usage
| #
+-##
    .
    .
   <以下、shellscript本文>

上記の、+ ... +の行が、long descです。

注意:
@descタグは、whatdoc コメントの最後につける必要があります。

おわりに

この記事では、whatコマンドの使い方と、コマンドを使うためのコメントの書き方を紹介しました。
各種スクリプトや、bashrcなどの設定ファイルにwhatdocコメントを記述すると、理解が容易になります。

この記事を活用して、あなたの Linux 環境のスクリプトや設定ファイルを効率的に管理しましょう。

それでは、Happy Hacking!

参考資料

GitHubで編集を提案

Discussion