Minimal ANSI terminal colour codes, for Ruby
woad provides the smallest useful set of fixed ANSI SGR colour sequences for library authors. It is not a console or TUI framework.
woad.Ruby is the Ruby implementation. It supports Ruby 2.0+.
It has no dependencies on any other non-standard library.
Ruby 2.0+ is already enough. There are no gems to install beyond woad itself.
gem install woad
The smallest useful call prints a sequence only when the writer supports colour:
require 'woad'
green = Woad.seq_for($stdout, Woad::FG_GREEN)
reset = Woad.seq_for($stdout, Woad::RESET)
puts "#{green}ok#{reset}"That is examples/conditional.rb. Fixed sequences (BOLD, BLINKING, FG_*, BG_*) always contain the SGR bytes. colour_policy, supports_colour, and seq_for apply the cached environment policy. refresh drops that cache.
From a checkout, bundle exec rake test runs the unit and component suites. Installation detail is in INSTALL.md.
Install via gem as in:
gem install woad
or add it to your Gemfile.
Use via require, as in:
require 'woad'
puts "#{Woad::FG_GREEN}ok#{Woad::RESET}"woad.Ruby ships fixed SGR sequences (BLINKING, BOLD, RESET, FG_*, BG_*, including bright variants) and the portable colour policy: colour_policy, refresh, supports_colour, and seq_for. On Unix a terminal supports colour when the policy is automatic and TERM is not dumb. Windows virtual-terminal mode and mintty PTY recognition are not implemented.
Woad.colour_policy returns COLOUR_POLICY_AUTO (0), COLOUR_POLICY_FORCE (1), or COLOUR_POLICY_INHIBIT (2). The result is cached until Woad.refresh is invoked.
A variable that is unset or empty is absent. Values are not trimmed. The first present variable in this order wins:
- Non-empty
WOAD_COLOUR, otherwise non-emptyWOAD_COLOR. Compared case-insensitively. Truey forces:1,always,force,on,true,yes. Falsey inhibits:0,false,never,no,none,off. Anything else, includingauto, selects auto and does not fall through; - Non-empty
NO_COLORinhibits, whatever its text is; - Non-empty
CLICOLOR_FORCEother than the exact bytes0forces. Exact0does not force and does not inhibit; - Non-empty
FORCE_COLORother than exact0orfalse(any capitalisation) forces. Exact0andfalsedo not force and do not inhibit; CLICOLORequal to the exact bytes0inhibits. Any other value is ignored;- Otherwise auto.
TERM equal to dumb, in any capitalisation, is cached beside the policy. It is not a policy value. It suppresses colour only when the policy is auto. force ignores the terminal and TERM. inhibit never emits colour.
On Unix, auto plus a terminal plus a TERM that is not dumb means colour. There is no console probe. WOAD_SET_CONSOLE_MODE is not read in this alpha.
Examples are provided in the examples directory, along with a markdown description for each. A detailed list TOC of them is provided in EXAMPLES.md.
Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/woad.Ruby.
Libraries upon which woad.Ruby depends:
- <none>. Windows virtual-terminal mode and mintty PTY recognition are not implemented, so this gem does not bind a console API;
Projects that depend on woad.Ruby:
- <none>;
- <none>;
- woad (C, C++);
- woad.Python;
- woad.Rust;
woad.Ruby is released under the 3-clause BSD license. See LICENSE for details.