tco 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1f3f0baacaecdffb8803a5a117f37befe8529022
-  data.tar.gz: 86953036041df1571299ceec298453d815be89a6
+  metadata.gz: 4472e4cc2bf0a46eddb2cd6d31f30c2dce37b386
+  data.tar.gz: c619231ff03672b43f59104873929c6608b73fb7
 SHA512:
-  metadata.gz: 07756aedae6e6316ccfb776367a40676293347247179d1c96d5ec32902f7c4ec7d02e477e3638af861d8b26646cbd974fb6064c410a2494262ae9fedfaaad139
-  data.tar.gz: 11d6a5bc9887a38bf7b90f902a2660caaa707b3e3cb28d822cf9bf5d0ccdda85eee595183fc3c12c12bc8c190af1c8cede17a98b2e1e1cf6444d3d60f7690b21
+  metadata.gz: 9d10fc13418a767089535cedf5e8923914d33a1e44006183011585c40034e51cdbfae5e9f5a675a1e183ac7625300ccbc039789aa6878bf3f815c369a37070ae
+  data.tar.gz: aecdca9ecae68ce531254be1a5d8c0198434732c09300a0e9f35fe36a3b158048d11dde24d5f9e598a6b82d6745b01ea45cc05d077a20d5dae491ca9beff9da0

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*.swp
+*.swo
+.DS_Store

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in tco.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2013, 2014 Radek Pazdera
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,241 @@
+# tco - terminal colours made simple
+
+[![Gem Version](https://badge.fury.io/rb/tco.png)](http://badge.fury.io/rb/tco)
+
+The purpose of the **tco** gem is to make colouring in the terminal as
+convenient and as simple as possible. It provides a library for your Ruby gems
+and also a standalone command line tool that you can use anywhere else.
+
+## Introduction
+
+If you've ever worked with the **extended colour palette** in the terminal, you
+probably know that it's not really easy to find the colour you want. The
+palette consists of 256 colours that are evenly sampled through the RGB space.
+As opposed to the **ANSI palette**, the colours tend to be the same across
+different terminals. They are assigned linearly to a set of escape sequences
+that are used to apply the colours. And that is the problem; searching
+through the palette is very unintuitive.
+
+On the other hand, selecting a RGB colour using your favourite
+[colour picker](http://www.colourpicker.com/) is a nice, buttery piece of cake
+with a bit of cream on top. That is everything you need to do; pass the value
+to `tco` and it will sort out all the boring bits for you. Using the
+RGB value, the library will find the **perceptually closest** option that is
+displayable in your terminal and decorate the string with the appropriate
+escape sequences, letting you focus on more interesting things in life instead.
+
+On top of that, it comes with a simple built-in templating engine that you can
+use to decorate only the parts that you want without having to split your
+string into 15 parts. Check out the following examples.
+
+### A few examples
+
+The `tco` terminal utility allows you to do the simple things you might need
+in your bash scripts:
+
+[![Using tco to colour text](http://linuxwell.com/assets/images/posts/tco-terminal.png)](http://linuxwell.com/assets/images/posts/tco-terminal.png)
+
+However, using `tco` directly from Ruby gives you much more flexibility. The
+following short piece of code will draw a rainbow inside your terminal:
+
+```ruby
+require "tco"
+
+rainbow = ["#622e90", "#2d3091", "#00aaea", "#02a552", "#fdea22", "#eb443b", "#f37f5a"]
+10.times do
+  rainbow.each { |colour| print "    ".bg colour }
+  puts
+end
+```
+
+[![tco showing a simple rainbow](http://linuxwell.com/assets/images/posts/tco-rainbow.png)](http://linuxwell.com/assets/images/posts/tco-rainbow-2.png)
+
+And if you add a bit of `rmagick` to the equation, you can even render whole
+images in your terminal with no more than 10 lines of code.
+
+```ruby
+require "tco"
+require "rmagick"
+
+Magick::Image.read("tux.png")[0].each_pixel do |pixel, col, row|
+  c = [pixel.red, pixel.green, pixel.blue].map { |v| 255*(v/65535.0) }
+  print "  ".bg c
+  puts if col >= 53
+end
+```
+
+[![Tux drawn with tco](http://linuxwell.com/assets/images/posts/tco-tux.png)](http://linuxwell.com/assets/images/posts/tco-tux.png)
+
+These were just the basic things you can do with `tco`. There are many more
+options and features available, many of them are described in the **Usage**
+section just bellow.
+
+## Usage
+
+You can use either the `tco` binary for your command line applications or the
+library directly from your Ruby scripts. Both use cases are explained bellow.
+
+### The Ruby library
+
+When it comes to colouring, there are two options available. You can either use
+the default library interface, or use the `String` extension that also comes
+with the library. Both of them offer exactly the same functionality (`fg`, `bg`,
+`bright`, `underline`). See the example of both, below:
+
+```ruby
+require "tco"
+
+# The standard interface
+puts Tco::fg("#ff0000", Tco::bg("#888888", Tco::bright("London")))
+puts Tco::underline "Underground"
+
+# The String object extension
+puts "London".fg("#ff0000").bg("#888888").bright
+puts "Underground".underline
+
+# Using predefined style
+puts "London".style "alert"
+puts Tco::style "alert", "Underground"
+```
+
+In the last bit of the example above, I'm referring to a preconfigured style
+definition. You can set them either system-wide in `/etc/tco.conf` or just for
+a single user in the `~/.tco.conf` file. They both are just simple YAML files.
+The precise format of these configuration files is explained at the end of this
+file.
+
+#### Changing the configuration on the fly
+
+A notable feature in regards of configuration is the fact, that you can easily
+change it on-the-fly. This can be useful for adding aliases for colours and
+defining your own styles just for your application, so you don't have to repeat
+the same settings all over your script. All these settings will be applied on
+top of the user and system config files.
+
+```ruby
+require "tco"
+
+tco_conf = Tco::config
+
+tco_conf["names"]["white"] = "#000"
+tco_conf["styles"]["pass"] = {
+  "fg" => "#000",
+  "bg" => "#00ff00",
+  "bright" => false,
+  "underline" => false,
+}
+
+Tco::reconfigure tco_conf
+```
+
+Apart from that, the library then contains a few more advanced things which
+aren't that useful for everyone. Please, have a look at `lib/tco/tco.rb` if
+you're interested.
+
+### The command-line tool
+
+Using the `tco` command is just as simple as using the Ruby library. It expects
+input either as a positional argument or alternatively at the standard input.
+
+Apart from the core functionality, the CLI tool adds support for simple
+templates that let you markup certain parts of your string. All templates
+are enclosed in double curly brackets `{{fg:bg:ub text}}`. Check out the
+following examples:
+
+```bash
+tco -f "#c0ffee" -b "white" "Some input text"
+tco -b "grey" -B "Some input text"
+
+tco "{{alert ERROR:}} The {{::b download}} has failed."
+echo "{{#000:#ffffff black on white}}" | tco
+```
+
+For the full list of options, please refer to the help of the `tco` command.
+
+### Specifying colours
+
+With both the Ruby library and the command line tool, there is a number of
+ways how to specify the colour you would like:
+
+* **RGB** - you can do either `#c0ffee` or `0xc0ffee`
+* **name** - e.g., `black` or `white`, you can assign names to colours in your
+  configuration file
+* **index** - you can also refer to colours through an index to the palette,
+  e.g., `@0` or `@176`.
+
+
+## Configuration
+
+There are two places, where you can store your configuration:
+
+* `/etc/tco.conf` - the system-wide configuration file
+* `~/.tco.conf` - user configuration file (takes precedence)
+
+Both of them are simple YAML text files. Pick the first one if you would like
+to apply your settings system-wide, go with the second option to set things up
+for yourself only (recommended).
+
+And now the important bit, in order to make **tco** work best in your
+environment, it is recommended to configure your **ANSI palette**. These 16
+colours are configurable in most terminals (you probably have yours customised
+too). **tco** needs to know your setup, so it can make decisions which colour
+to use. If you don't configure them, tco will not use the ANSI colours at all
+in order to avoid mistakes. You can do so like this:
+
+```yaml
+# Don't forget changing the values to match your terminal configuration
+colour_values:
+    "@0": "#3b3b3b"
+    "@1": "#cf6a4c"
+    "@2": "#99ad6a"
+    "@3": "#d8ad4c"
+    "@4": "#597bc5"
+    "@5": "#a037b0"
+    "@6": "#71b9f8"
+    "@7": "#adadad"
+
+    "@8": "#555555"
+    "@9": "#ff5555"
+    "@10": "#55ff55"
+    "@11": "#ffff55"
+    "@12": "#5555ff"
+    "@13": "#ff55ff"
+    "@14": "#55ffff"
+    "@15": "#ffffff"
+```
+
+Apart from that you can also create **aliases** for colours and define
+short-cut styles for configurations you tend to use often. A typical
+configuration file would look like this:
+
+```yaml
+# This is unnecessary (extended palette is enabled by default).
+# However, you can set this to ansi if you use an older terminal.
+palette: "extended"
+
+colour_values:
+    "@0": "#3b3b3b"
+    "@1": "#cf6a4c"
+    "@2": "#99ad6a"
+    "@3": "#d8ad4c"
+    # and so on ...
+
+names:
+    black: "#000"
+    red: "@1"
+
+styles:
+    error:
+        fg: "black"
+        bg: "red"
+        bright: "true"
+        underline: "false"
+```
+
+## Contributing
+
+1. Fork it ( http://github.com/pazdera/tco/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/bin/tco

@@ -0,0 +1,141 @@
+#!/usr/bin/env ruby
+# tco - terminal colouring application and library
+# Copyright (c) 2013, 2014 Radek Pazdera
+
+# MIT License
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'optparse'
+require 'tco'
+
+options = {:newline => true}
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: tco [options] [TEXT]"
+
+  opts.on("-f COLOUR", "--foreground COLOUR", "Foreground colour") do |fg|
+    options[:fg] = fg
+  end
+
+  opts.on("-b COLOUR", "--background COLOUR", "Background colour") do |bg|
+    options[:bg] = bg
+  end
+
+  opts.on("-B", "--bright", "Use bright/bold font") do |bright|
+    options[:bright] = bright
+  end
+
+  opts.on("-u", "--underline", "Underlined text") do |underline|
+    options[:underline] = underline
+  end
+
+  opts.on("-s STYLE", "--style STYLE",
+          "Decorate with a preset style") do |style|
+    options[:style] = style
+  end
+
+  opts.on("-n", "--no-newline",
+          "Don't append \\n to the end of the string") do |newline|
+    options[:newline] = false
+  end
+
+  opts.on("-d", "--display-palette",
+          "Show the current colour pallete") do |display|
+    options[:display] = true
+  end
+
+  opts.on("-p PALETTE", "--force-palette PALETTE",
+          "Force either ansi or extended palette") do |palette|
+    options[:palette] = palette
+  end
+
+  opts.on("-o", "--disable-parsing",
+          "Disable the {{fg:bg text}} and",
+          "{{style text}} formatting syntax") do |dp|
+    options[:disable_parsing] = true
+  end
+
+  opts.on("-r", "--raw-output", "Print the output escaped") do |raw|
+    options[:raw] = true
+  end
+
+  # TODO: This should output HTML (not implemented yet)
+  #opts.on("-w", "--web", "Output HTML") do |html|
+  #  options[:html] = html
+  #end
+end
+
+begin
+  parser.parse!
+
+  config = Tco::config
+
+  # Force palette setting
+  config.options["palette"] = options[:palette] if options.has_key? :palette
+  config.options["output"] = :raw if options.has_key? :raw
+
+  Tco::reconfigure config
+
+  if options.has_key? :display
+    Tco::display_palette
+    Kernel.exit! 0
+  end
+
+  if options.has_key? :style
+    style = Tco::get_style options[:style]
+  else
+    style = Tco::Style.new
+  end
+
+  if options.has_key? :fg
+    style.fg = options[:fg]
+  end
+
+  if options.has_key? :bg
+    style.bg = options[:bg]
+  end
+
+  if options.has_key? :bright
+    style.bright = options[:bright]
+  end
+
+  if options.has_key? :underline
+    style.underline = options[:underline]
+  end
+
+  if ARGV.length > 0
+    input = ARGV[0].gsub /\\[nt]/, "\\n" => "\n", "\\t" => "\t"
+  else
+    input = ""
+    while input_line = gets
+      input << input_line.gsub(/\\[nt]/, "\\n" => "\n", "\\t" => "\t")
+    end
+  end
+
+  if options.has_key? :disable_parsing
+    print Tco::decorate input, style
+  else
+    print Tco::parse input, style
+  end
+
+  print "\n" if options[:newline] && !(input =~ /\n$/)
+rescue Exception => e
+  puts e
+  exit
+end

data/examples/rainbow.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+require "tco"
+
+conf = Tco.config
+conf.names["purple"] = "#622e90"
+conf.names["dark-blue"] = "#2d3091"
+conf.names["blue"] = "#00aaea"
+conf.names["green"] = "#02a552"
+conf.names["yellow"] = "#fdea22"
+conf.names["orange"] = "#f37f5a"
+conf.names["red"] = "#eb443b"
+Tco.reconfigure conf
+
+rainbow = ["purple", "dark-blue", "blue", "green", "yellow", "orange", "red"]
+10.times do
+  rainbow.each { |colour| print "    ".bg colour }
+  puts
+end