This module provides a UNIX-like command `dirdim'. 

 Copyright (c) 2022-2023 Toshiyuki SHIMONO. All rights reserved.
 This program is free software; you can redistribute it and/or
 modify it under the same terms as Perl itself.


■■ 概要 ■■

このモジュールをインストールすると、コマンド dirdim が使えるようになる。

このコマンドは、下記の様に使うと、引数に指定したそれぞれのディレクトリの直下に、
何個の非ディレクトリのファイルと、何個のディレクトリのファイルが存在するかを
表形式(TSV形式;タブ文字区切り形式)で出力する。

> dirdim blib .git   # コマンドの引数に blib と .git というディレクトリを指定

nondir  subdir  given_dir
0   6   blib/
8   5   .git/
8   11  total

(タブ文字で区切っているだけなので、表示の仕方により縦位置がずれて見えることに注意。
縦揃えをするには、App::expandtab をインストールすると使えるコマンド expandtab
を使うと良い。)

■■ 目的 ■■

多数のディレクトリがある場合に、それぞれのディレクトリに何個のファイルがあるかを
即座に知る方法(たとえばシェル芸)は困難である。そのため、10文字以内のコマンドと
いくつかのオプションで様々な追加機能で、便利な機能を実現するため、このコマンドを
作成した。

■■ 利用上の注意点 ■■

このコマンドは、何も破壊的な動きはしないので、どのディレクトリからでも
安全に実行が可能である。従って、気軽に dirdim とコマンドラインから入力して
試すことができる。多数のファイルを持つディレクトリを引数に指定した場合、
計算完了までに時間が掛かる場合がある。途中で止める場合には Ctrl + C を
押下すると良い。このコマンドのインストールにより200kB(キロバイト)程度を
使用するかもしれないが、それらを消去するには cpanm -U によりアンインストールが
可能である(cpanm でインストールした場合)。

■■ オプションの例 ■■

オプションとしては、たとえば -v を与えることにより、具体的なファイルを出力する。
(具体例を出すことで、コマンドの動作の正しさの確信を高める効用がある。)

> dirdim -v blib .git  

nondir  subdir  given_dir   fileName_minstr fileName_maxstr
0   6   blib/   arch/   script/
8   5   .git/   COMMIT_EDITMSG  refs/
8   11  total

オプションの別の例として、 -d を与えることにより、指定したディレクトリファイルの
直下のファイルのみでなくて、最も深いディレクトリ階層にあるファイルの例とその深さを
知ることが出来る。depthは最大の深さを示し、5とあるので、起点となるディレクトリ
(blibまたは.git)から5個下った所にディレクトリが存在し、それより下には無いことが
分かる。alltree は起点のディレクトリ以外に何個のファイルが(ディリクトリも含め)
何個あったかを示す。たとえば .git の下には全部で218個のファイルがあり、直下の
8+5個のファイルよりも十数倍あることが分かる。

> dirdim -d blib .git  

nondir  subdir  depth   alltree given_dir   An example at the deepest
0   6   5   25  blib/   lib/auto/App/dirdim/.exists
8   5   5   218 .git/   logs/refs/remotes/origin/master
8   11  5   243 total

上記の例は、いずれも、このソフトウェアを開発したディレクトリで作成者の環境で
試している。UNX系コマンドやシェルに使い慣れていれば、環境が違っても何も問題無く
すぐ使えるであろう。

■■ 利用シーンの例 ■■

- 多数のデータファイルが日次で毎日到着していて、毎日の各日付に相当するディレクトリに
  決められた個数のファイルが存在するか確かめたい場合。
   その毎日来る多数のディレクトリを持つ親ディクレトリにて dirdim * を実行する
  ことになるだろう。

- 自分が普段の業務で使っている書類のファイルで、ファイル数や深さを知りたい時。

- バージョン管理システムの中のディレクトリ階層の深さを知りたい場合は、
  たとえば  dirdim -d .git を実行する。

- 多数のソフトウェアを格納しているディレクトリにて、dirdim -d * を実行する。

■■ 補足 ■■

このコマンドの出力は ANSIエスケープシーケンスにより、テキストに黄色などの色が
着いている。この着色を消すには、App::colorplusをインストールすると使える
colorplus のコマンドを使って、 colorplus -0 に dirdim の出力を渡すと良い。

例:  
> dirdim * | colorplus -0

なお、上記の説明で > は全てコマンドラインのプロンプト文字列を表しており、
実際のコマンド、それより後の文字列である。

dirdimの名前の由来はディレクトリ(dirctory)の寸法(dimension)に由来する。
このようなコマンドを作成する場合は 英語2単語で計10文字以内にすることにしている。
また、他にdirを使ったコマンドを作成してるので、dirを先に持ってくることで、
このコマンドが必要な場面で思い出しやすくしたり、アルファベット順にリストアップした
ときにまとまるようにしたりした。