Ruby版 color_echo for v3.1.0 and over

• 2つのモード
• モジュール関数リファレンス

2つのモード

require 'color_echo'もしくはrequire 'color_echo/get'でcolor_echoを読み込むとCEというモジュールが組み込まれます。 ruby からcolor_echoを使用する場合はオブジェクトを作る必要はありません。color_echoの機能はすべてモジュール関数で実装されています。

例えばCE.fg(:cyan)をコールすると組み込みの Kernel module の以下の5つモジュール関数puts,p,print,printf,putcのコマンドライン出力がcyanに変わります。

※ version 3.1.0から装飾の適用範囲にprintf,putcが加わりました。

require 'color_echo'
puts "Hello World !!"

CE.fg(:cyan)
puts "Hello World !!"

CE.bg(:gray)
puts "Hello World !!"

CE.tx(:bold,:underline)
puts "Hello World !!"

Kernel module のモジュール関数がオーバライドされ自動で装飾されることを望まない場合はrequire 'color_echo'ではなく、require 'color_echo/get'で読み込んでください。

require "color_echo/get"で読み込むとcolor_echoはKernel.#puts,Kernel.#p,Kernel.#print,Kernel.#printf,Kernel.#putcの出力を装飾しません。装飾したテキストを取得するにはCE.get("some message")を使います。

require "color_echo/get"

hello  = CE.fg(:yellow).get("Hello")
world  = CE.fg(:index199).bg(:gray).tx(:bold).get("World")
exclam = CE.rainbow.get("!!!!!!!!!!!!!!!!")

puts hello + " " +  world + " " + exclam

puts CE.fg(:blue).pickup(/color$/, :index199).pickup(/^color/, :h_green).get("color color color")

モジュール関数リファレンス

CE.pickup(pattern, foreground=:cyan, backgruond=nil, *text_attribute)

• pattern : string or regexp or array of them パターン。
• foreground : symbol or nil パターンとマッチしたワードの文字色。
• background : symbol or nil パターンとマッチしたワードの背景色。
• text_attribute : symbol or array of them パターンとマッチしたワードの装飾。
• Return -> self

パラメータpatternとマッチする文字列を指定した文字色、背景色、テキスト属性で色づけします。使用できる文字色等は、colorecho -s または colorecho -l で確認できます。CE.rainbow がコールされている場合はこの機能は無視されます。

CE.pickup(/^foo/, :index100, nil, :bold)

CE.pickupを使えば特定のワードだけを色づけすることができます。

CE.fg(:h_cyan).pickup("color_echo", :h_white, :red, :underline).pickup("COLOR_ECHO", :h_yellow)

puts <<EOS
xxxxxxxxxxxxxxxxxcolor_echoxxxxxxxxxxxxxxxxxxxxxxxx
xxxxcolor_echoxxxxxxxCOLOR_ECHOxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxcolor_echoxxxxxxxxxxcolor_echoxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
EOS

CE.highlight(foreground=nil, background=nil, *text_attribute)

• foreground : symbol or nil パターンとマッチした行の文字色。
• background : symbol or nil パターンとマッチした行の背景色。
• text_attribute : symbol or array of them パターンとマッチした行の装飾。
• Return -> self

CE.pickupでマッチした行に対して、指定した文字色、背景色、テキスト属性で色づけします。

CE.ch_fg(foreground)

• foreground : symbol
• Return -> self

文字色を指定した色に変更します。エイリアスfgでも呼び出し可能です。

• パラメータforegroundで指定できるシンボルの一覧
  • :black
  • :red
  • :green
  • :yellow
  • :blue
  • :magenta
  • :cyan
  • :white
  • :gray
  • :h_red
  • :h_green
  • :h_yellow
  • :h_blue
  • :h_magenta
  • :h_cyan
  • :h_white
  • :index[1-256]

# 文字色が赤になります。
CE.ch_fg :red

CE.ch_bg(background)

• background : symbol 指定できるシンボルの一覧は foreground と同様。
• Return -> self

背景色を指定した色に変更します。エイリアスbgでも呼び出し可能です。

CE.ch_tx(*text_attribute)

• text_attribute : symbol or array of them
• Return -> self

テキスト属性を指定した色に変更します。エイリアスtxでも呼び出し可能です。colorecho -sでそれぞれどのような装飾になるかチェックすることができます。

• パラメータtext_attributeで指定できるシンボル一覧
  • :bold … 文字を太字にします。
  • :underline … 文字に下線をつけます。
  • :blink … 文字を点滅させます。
  • :reverse_video … 文字色と背景色を反転させます。
  • :concealed … サポートされている環境が少ないため削除予定です。

# テキスト属性は同時に複数の指定が可能です。
CE.ch_tx [:bold, :underline]

CE.ch(foreground, background=nil, *text_attribute)

• foreground : symbol or nil 文字色。nil を許可。
• background : symbol or nil 背景色。nil を許可。
• text_attribute : symbol or array of them テキスト属性。
• Return -> self

文字色、背景色、テキスト属性を指定したものに変更します。

# 文字色、テキスト属性の指定のみ行いたい場合は背景色に nil を指定します。
CE.ch :red, nil, :bold

CE.reset(scope=:all)

• scope : symbol or array of them リセット対象のスコープ。下記参照。
• Return -> self

指定した色やテキスト属性をリセットします。リセットする範囲はスコープで決まります。 デフォルトは :all ですのですべての設定がリセットされます。エイリアスoff, disableでも呼び出し可能です。

• パラメータscopeで指定できるシンボル一覧
  • :all … すべての指定をリセットします。
  • :fg … 文字色に関する指定をリセットします。
  • :bg … 背景色に関する指定をリセットします。
  • :tx … テキスト属性に関する指定をリセットします。
  • :pickup … CE.pickupで指定したパターンに関する指定をリセットします。
  • :highlight … CE.highlightで指定したパターンとマッチした行に関する装飾の指定をリセットします。
  • :rainbow … CE.rainbowを呼び出したことによる装飾をリセットします。

# このように配列で複数のシンボルを同時に指定することも可能です。
CE.reset [:fg. :tx]

CE.once

• Return -> self

一度だけ設定した装飾を適用します。これはCE.times(1)と同様です。

CE.times(cnt)

• cnt : integer
• Return -> self

cntで指定した回数だけ設定した装飾を適用します。標準出力（もしくはCE.get）するたびに回数がインクリメントされます。

CE.once.ch :h_yellow, :h_red, :underline
puts "first"
puts "second"

puts "\n"

CE.times(3).rainbow
puts "first"
puts "second"
puts "third"
puts "fourth"

CE.enable_refresh(scope=:all)

• scope : symbol
• Return -> self

与えられた入力に対して可能な限りシーケンスコードを取り除きます。

• パラメータscopeで指定できるシンボル一覧
  • :all … いかなる時もシーケンスコードを取り除きます。
  • :prematch … CE.pickupで指定したパターンにマッチした時だけシーケンスコードを取り除きます。

CE.disable_refresh

• Return -> self

与えられた入力に対してシーケンスコードを取り除きません。デフォルトはこの挙動です。

CE.unuse

• Return -> void

このメソッドがコールされた時点でcolor_echoの機能を無効にします。

CE.rainbow

• Return -> self

出力をレインボーにします。

CE.get(string)

• string : string 装飾したい文字列。
• Return -> string

stringを装飾して返します。require 'color_echo/get'を読み込んだ時だけ使えるメソッドです。

このメソッドが呼び出されたあとは装飾に関するこれまでの指定はリセットされます。 この機能を望まない場合はversion 3.0.0で新しく追加されたCE.statefulをこのメソッドの前で一度だけコールしてください。

CE.stateful

• Return -> self

CE.get を呼び出したあともそれまでに定義された CE.ch, CE.pickup などの装飾に関するすべての指定を保持し続けます。 CE.get を使用しない場合は意味のないメソッドです。

CE.stateless

• Return -> self

CE.get を呼び出すとそれまで設定した装飾に関する指定がすべてクリアされます。デフォルトはこの挙動です。 CE.get を使用しない場合は意味のないメソッドです。

CE.withdraw(target [,...])

• target : symbol
• Return -> array

引数に指定したメソッドに対して装飾を適用しません。 例えばCE.withdraw(:printf)とすればprintfの出力は装飾されません。 カンマ区切りで一度に複数指定できます。 返り値は解除に成功したシンボルの配列です。

version 3.1.0から追加されたメソッドです。

• パラメータtargetで指定できるシンボル一覧
  • :puts … Kernel.#putsへの装飾を解除します。
  • :p … Kernel.#pへの装飾を解除します。
  • :print … Kernel.#printへの装飾を解除します。
  • :printf … Kernel.#printfへの装飾を解除します。
  • :putc … Kernel.#putcへの装飾を解除します。

CE.get_assigned

• Return -> array

装飾を適用する Kernel module のモジュール関数のシンボルの配列を返します。 減点方式なのでなにもCE.withdrawしていないときは[:puts, :p, :print, :printf, :putc]が返り値です。

version 3.1.0から追加されたメソッドです。