12.75 text.progress - テキスト端末上で進捗を表示する

Module: text.progress ¶

このモジュールはバーチャートを文字を用いて表示し、テキスト端末上に処理 の進行状況を出すためのユーティリティです。

進捗を示すプログレスバーの汎用的なフォーマットは1行のテキストで構成されます。 この1行はいくつかの部分に分解できます。タイトルを表示するヘッダ部、その後に プログレスバーがあって、数値部、時間部と続きます。以下がその例です(foo からはじまる1行だけが実際に表示されます。

<-header-> <-------bar---------> <-num-><-time->      <---info---->
foo       |#############        |123/211   01:21 ETA  compiling...
          ^
          separator

バーチャートに使う文字などのいろいろなバリエーションや、数値で表わす 進捗のフォーマットなども設定可能です。

内部的にはプログレスバーは2つの数値、最大値(ゴール)と現在の値を保持し ています。バーは最大値に対する現在の値の比を示すものです。数値で表わす 進捗はデフォルトでは最大値の上に現在の値を表示します。しかし、たとえば、 現在の値だけを表示するとか、100分率で表示するなどの設定が可能です。

プログレスバーは2つの状態「進捗中」および「終了」のどちらかの状態を保 持しています。「進捗中」なら、どの時点でも表示されるテキストには #\returnが続きます。これにより次の表示が前の表示を上書きするこ とになります。時間部はETA(残り時間)を表示します。終了してしまえば、最 後の行の後に#\newlineが続きます。時間部には終了までにかかった時 間が表示されます。

このモジュールはmake-text-progress-barという手続きを1つだけ提供 します。この手続きはプログレスバーの機能をクロージャに包んでそれを返し ます。

Function: make-text-progress-bar :key header header-width bar-char bar-width num-width num-format time-width info info-width separator-char max-value port ¶

{text.progress} プログレスバー上の操作を包んだ手続きを返します。返された手続きに操作を 示すシンボルとオプションで数値を引数として渡して使います。

proc 'show

プログレスバーを再表示する。他のどの操作も状態の再表示を行います。 したがって、現在のステータスを再表示しなければない特別な理由がないかぎ りこれを使う必要はありません。

proc 'set value

現在の値をvalueにセットし、プログレスバーを再表示します。 valueが最大値を超えていたら、超過分を切り捨て最大値にします。

proc 'inc value

value分だけ現在の値を増し、プログレスバーを再表示します。現在の 値が最大値を超えたら、超過分を切り捨て最大値にします。

proc 'finish

プログレスバーを「終了」状態にし、再表示します。時間部はトータルの経過 時間を表示します。また、表示行末は#\newlineとし、上書きされない ようにします。プログレスバーはいったん「終了」状態になれば、「進捗中」 状態に戻す方法はありません。

proc 'set-info text

“info”部に表示されるテキストを変更します。 info部を使うには、make-text-progress-barのinfo-widthキーワード 引数に正の値が指定されている必要があります。

proc 'set-header text

“header”部に表示されるテキストを変更します。

キーワード引数を使って表示をカスタマイズできます。

header

ヘッダ部に表示するテキスト。このテキストは、作られたプログレスバーに set-headerメッセージを送ることで後で変更可能です。

header-width

ヘッダ部の幅、文字数で指定します。ヘッダ部のテキストは左詰めです。ヘッ ダ部に置くテキストが幅よりも長い場合には超過分の文字は切り捨てられます。 デフォルトは14文字です。

bar-char

バーチャートを描くのに使う文字。デフォルトは#\#です。

bar-width

バーチャート部の幅で、文字数で指定します。デフォルトでは40文字です。

num-width

数値部の幅で、文字数で指定します。デフォルトでは9で、これを0に設定する と数値部を隠せます。

num-format

数値部を整形する手続き。引数が2つ渡されます。ひとつは現在の値、もうひ とつは最大値です。この手続きは文字列を返さなければなりません。デフォル トでは以下の手続きです。

(lambda (cur max)
  (format "~d/~d" cur max))

time-width

時間部の幅で、文字数で指定します。デフォルトでは7文字で、これを0に設定 すると時間部を隠せます。

info

info部に表示されるテキストです。このテキストは、作られたプログレスバーに set-infoメッセージを送ることで後から変更できます。 info部を表示するには、info-widthキーワード引数に正の値を 与えておく必要があります。

info-width

info部の表示幅です。デフォルトは0で、info部は表示されません。

separator-char

バー部分の前後に置く文字です。デフォルトでは#\|です。 セパレータを表示したくなければ、#fを渡します。

max-value

プログレスバーの最大値です。正の実数でなければなりません。デフォルトでは100です。

port

プログレスバーを表示する出力ポートです。デフォルト値は make-text-progress-barが呼ばれた時点での現在の出力ポートです。

以下は簡単なカスタマイズをした例です。

(use text.progress)

(define (main args)
  (define (num-format cur max)
    (format "~d/~d(~3d%)" cur max
            (round->exact (/. (* cur 100) max))))

  (let ((p (make-text-progress-bar :header "Example"
                                   :header-width 10
                                   :bar-char #\o
                                   :num-format num-format
                                   :num-width 13
                                   :max-value 256)))
    (do ((i 0 (+ i 1)))
        ((= i 256) (p 'finish))
      (p 'inc 1)
      (sys-select #f #f #f 50000))))