hansi 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a461aa8d4598e475054d9705667d8e88c810e361
-  data.tar.gz: 7eac7bb43dd1eb6b66d160d0564b1ecdb5d9fe27
+  metadata.gz: e1c99a2ac8ce470c64e37c42a2e94af03d80a0fe
+  data.tar.gz: 8c8e39771a0a0c2fab16b746d937643655b3cdd7
 SHA512:
-  metadata.gz: 5fc500637d6eb4d2ca9618f86821b9f3f4dc37cfdb755c2650818c02966b71efc0d9ac0de7dbf099d42d36fbb1695e952f5368d64d9ce90a04e2d813e248debb
-  data.tar.gz: 16ad2067360b221d219e6c13c0408b79e7c77c5bdedb24f8775184958a8c84bcddb884a4a115d57fa0f986ba7d7c0f85eadf49726505bfebd46a96216bfa395f
+  metadata.gz: a394c636b3fd0e8d4456377ad2b2c79223374612f9c71cf3a4f24b5df325bca79c01ebd1a9f0057e3155ef428af796f7d70532eb52d7796a2ba1d185347c8cd9
+  data.tar.gz: 64b7011cbd5a09b5aec138544197f86de4a703f773dcaba9c1c06ba99e6d55b1e54830fd54a0581a67aa039fb739f79f5fe85b801223ecafafcee11386619f4a

data/.gitignore

@@ -0,0 +1,2 @@
+.coverage
+Gemfile.lock

data/.rspec

@@ -0,0 +1,4 @@
+-r bundler/setup
+-r support
+--color
+--tty

data/.travis.yml

@@ -0,0 +1,2 @@
+rvm: [2.0.0, 2.1.5]
+script: bundle exec rspec

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Konstantin Haase
+
+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,230 @@
+# Der ANSI Hansi
+
+Welcome to *The ANSI Hansi*. This is your *Hipster ANSI color library*.
+
+It allows you to produce colorized console output.
+
+Many ANSI color libraries are already out there. However, this library tackles a few issues most of them have:
+
+* It supports **8 color**, **16 color**, **88 color**, **256 color** and **24 bit (True Color)** mode.
+* It transparently **converts colors between modes** without you having to worry about this. It uses the YUV distance (rather than the RGB distance) to closer match how our brain perceives color similarity.
+* It supports **proper color nesting**.
+* It can **automatically detect** how many colors the current terminal supports.
+* It does **not enforce a DSL** to be used (in fact, it does not include a DSL, but it makes it really easy to build your own DSL).
+* Makes it easy to define **string templates** for highlighting, but doesn't force you to use them.
+* It supports **themes**, but doesn't force you to use them. Themes make semantic coloring easier.
+* It supports converting **ANSI colors to CSS rules**. It does not support parsing an ANSI colored string into HTML, this would be outside the scope of this library.
+* It has zero dependencies and does not include a native extension.
+* It does not monkey patch anything.
+
+## General Usage
+
+The main API entry points are `Hansi.render(input)` , which will generate a colorized string, depending on the input, and `Hansi[input]`, which will give you a color object. You can use Hansi for your purposes by just using one of the two, but they give you different levels of access.
+
+The following code:
+
+``` ruby
+require 'hansi'
+
+# simple usage
+puts Hansi.render(:red, "WARNING!!")
+puts Hansi.render("Hello *world*!", "*" => :bold)
+
+# generate some colors
+steps  = (0..255).step(15)
+render = -> options { print Hansi.render(Hansi[options], ':') }
+
+steps.each do |red|
+  steps.each { |green| render[ red: red, green: green ]}
+  steps.each { |blue|  render[ red: red, green: 255 - blue, blue: blue]}
+  steps.each { |blue|  render[ red: red, blue: 255 - blue ]}
+  puts
+end
+```
+
+Will result in output similar to this screenshot (if your terminal supports true color):
+
+![](hansi.png)
+
+### Rendering Strings
+
+You can render a string in a given color:
+
+``` ruby
+puts Hansi.render(:red, "this is red")
+
+red = Hansi["#f00"]
+puts Hansi.render(red, "this is red")
+```
+
+You can render an s-expression stile nested array (good for building your own DSL on top):
+
+``` ruby
+sexp = [:red, "Hello", [:yellow, ENV["USER"]], "- how are you?"]
+puts Hansi.render(sexp, join: " ")
+```
+
+It is also possible to use template strings. These can use simple markup (anything enclosed between certain characters), or HTML style tags, or a combination of the two.
+
+``` ruby
+# a simple template
+puts Hansi.render("foo *bar* _blah_", "*" => :red, "_" => :green)
+
+# escaping a character
+puts Hansi.render('foo *bar* _blah\_blah_', "*" => :red, "_" => :green)
+
+# using tags, with interpolation
+puts Hansi.render("<gold>Hello <underline>%s</underline>!</gold>", ENV['USER'], tags: true)
+```
+
+You can also use `render` to turn a color object into its ANIS code.
+
+The `render` method takes a `mode` option to enforce a color mode.
+
+``` ruby
+color = Hansi["#f80"]
+Hansi.render(color, mode: 256) # => "\e[38;5;208m"
+Hansi.render(color, mode: 16)  # => "\e[33m"
+```
+
+### Themes
+
+The render method takes a `theme` option. This option can have one of the following values:
+
+* An instance of `Hansi::Theme`.
+* A symbol for a predefined theme (currently `:default` or `:solarized`).
+* A hash mapping rules (symbols) to other rules or color values.
+* An array of any of the above.
+
+``` ruby
+
+my_theme = Hansi::Theme.new(foo: :yellow)
+
+puts Hansi.render("<foo>hi</foo>", tags: true, theme: my_theme)               # bright yellow
+puts Hansi.render("<foo>hi</foo>", tags: true, theme: { foo: :yellow })       # bright yellow
+puts Hansi.render("<foo>hi</foo>", tags: true, theme: [:solarized, my_theme]) # solarized yellow
+puts Hansi.render("<yellow>hi</yellow>", tags: true, theme: :solarized)       # solarized yellow
+```
+
+When creating a theme, you can also pass in other themes to inherit rules from:
+
+``` ruby
+my_theme = Hansi::Theme.new(:solarized, em: :base0, b: :base1)
+puts Hansi.render("This <em>is</em> <b>important</b>!", theme: my_theme)
+```
+
+It is also possible to register your theme globally:
+
+``` ruby
+Hansi::Theme[:my_theme] = Hansi::Theme.new(:solarized, em: :base0, b: :base1)
+puts Hansi.render("This <em>is</em> <b>important</b>!", theme: :my_theme)
+```
+
+### Color Objects
+
+You can get access to a color object via `Hansi[]` or `Hansi::Theme#[]`.
+
+``` ruby
+Hansi[:yellow].red                    # => 255
+Hansi::Theme[:solarized][:yellow].red # => 181
+
+Hansi["#ff8300"].to_ansi(mode: 256)       # => "\e[38;5;208m"
+Hansi["#ff8300"].to_web_name              # => :darkorange
+Hansi["#ff8300"].to_web_name(exact: true) # => nil
+```
+
+You can also use a color object to find the closest color in a set of colors:
+
+``` ruby
+colors = [
+  Hansi[:red],
+  Hansi[:green],
+  Hansi[:blue],
+  Hansi[:orange]
+]
+
+Hansi[:yellow].closest(colors) # => Hansi[:orange]
+```
+
+## Advanced Usage
+
+### Enforcing the default color mode
+
+You can override the color mode Hansi has detected for the current terminal:
+
+``` ruby
+puts "Detected colors: %d" % Hansi.mode
+Hansi.mode = Hansi::TRUE_COLOR
+```
+
+### Create your own DSL
+
+Rather than defining a DSL, Hansi aims to be easily integrated with whatever tooling you use for building command line applications.
+
+Combining for instance the s-expression style rendering with `Hansi.color_names` makes creaking a method name based DSL straight forward:
+
+``` ruby
+module ColorDSL
+  def color(*args)
+    Struct.new(:to_ary, :to_s).new(args, Hansi.render(args))
+  end
+
+  Hansi.color_names.each do |name|
+    define_method(name) { |*args| color(name, *args) }
+  end
+end
+
+extend ColorDSL
+puts "Hello #{red("w", green("o", blue("r"), "l"), "d")}!"
+```
+
+### Generating CSS
+
+Hansi does not turn ANSI escape codes into HTML for you, this would be outside of the scope for this project. However, depending on your use case, you might be able to generate semantic HTML yourself from whichever data structure you use.
+
+In this case, Hansi can generate CSS rules for you.
+
+``` ruby
+Hansi[:red].to_css_rule # => "color: #ff0000;"
+```
+
+It can also generate a full stylesheet for a theme:
+
+``` ruby
+my_theme = Hansi::Theme.new(headline: :green, text: :springgreen, aside: :text, important: :bold)
+puts my_theme.to_css
+```
+
+``` css
+.headline {
+  color: #008000;
+}
+
+.text, .aside {
+  color: #00ff7f;
+}
+
+.important {
+  font-weight: bold;
+}
+```
+
+You can pass a block for generating the css selector for a given rule name:
+
+``` ruby
+puts my_theme.to_css { |name| ".hansi .#{name}" }
+```
+
+``` css
+.hansi .headline {
+  color: #008000;
+}
+
+.hansi .text, .hansi .aside {
+  color: #00ff7f;
+}
+
+.hansi .important {
+  font-weight: bold;
+}
+```

data/hansi.gemspec

@@ -0,0 +1,22 @@
+$:.unshift File.expand_path("../lib", __FILE__)
+require "hansi/version"
+
+Gem::Specification.new do |s|
+  s.name                  = "hansi"
+  s.version               = Hansi::VERSION
+  s.author                = "Konstantin Haase"
+  s.email                 = "konstantin.mailinglists@googlemail.com"
+  s.homepage              = "https://github.com/rkh/hansi"
+  s.summary               = %q{Hipster ANSI color library}
+  s.description           = %q{Der ANSI Hansi - create colorized console output.}
+  s.license               = 'MIT'
+  s.files                 = `git ls-files`.split("\n")
+  s.test_files            = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables           = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.required_ruby_version = '>= 2.0.0'
+
+  s.add_development_dependency 'tool', '~> 0.2'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'coveralls'
+end

data/lib/hansi.rb

@@ -0,0 +1,53 @@
+module Hansi
+  TRUE_COLOR = 256**3
+
+  def self.[](*args)
+    ColorParser.parse(*args)
+  end
+
+  def self.mode
+    @mode ||= mode_for(ENV)
+  end
+
+  def self.mode=(value)
+    @mode = value
+  end
+
+  def self.mode_for(env, **options)
+    ModeDetector.new(env, **options).mode
+  end
+
+  def self.render(*input, **options)
+    renderer_for(input.first).render(*input, **options)
+  end
+
+  def self.renderer_for(input)
+    case input
+    when String        then StringRenderer
+    when Symbol, Array then SexpRenderer
+    when AnsiCode      then ColorRenderer
+    else raise ArgumentError, "don't know how to render %p" % input
+    end
+  end
+
+  def self.reset
+    Hansi[:reset].to_ansi
+  end
+
+  def self.color_names
+    PALETTES['web'].keys
+  end
+
+  require 'hansi/ansi_code'
+  require 'hansi/color'
+  require 'hansi/special'
+
+  require 'hansi/color_parser'
+  require 'hansi/color_renderer'
+  require 'hansi/mode_detector'
+  require 'hansi/palettes'
+  require 'hansi/sexp_renderer'
+  require 'hansi/string_renderer'
+  require 'hansi/theme'
+  require 'hansi/themes'
+end

data/lib/hansi/ansi_code.rb

@@ -0,0 +1,16 @@
+module Hansi
+  class AnsiCode
+    def to_ansi_code(**options)
+    end
+
+    def to_css_rule
+      "/* cannot convert #{inspect} to css */"
+    end
+
+    def to_css(*names, &block)
+      block ||= -> key { ".#{key}" }
+      name = names.map(&block).join(', ')
+      "#{name} {\n  #{to_css_rule.gsub(/;\n?\s+(\S)/, ";\n  \\1")}\n}\n"
+    end
+  end
+end

data/lib/hansi/color.rb

@@ -0,0 +1,115 @@
+module Hansi
+  class Color < AnsiCode
+    attr_reader :red, :green, :blue, :distance_cache
+    protected :distance_cache
+
+    def initialize(red, green, blue)
+      @red, @green, @blue = red, green, blue
+      @distance_cache     = {}
+    end
+
+    def hash
+      to_i.hash
+    end
+
+    def ==(other)
+      other.class == self.class and other.to_i == self.to_i
+    end
+
+    def eql?(other)
+      other.class.eql?(self.class) and other.to_i.eql?(self.to_i)
+    end
+
+    def distance(other)
+      distance_cache[other.to_i] ||= other.distance_cache[to_i] || begin
+        y1, u1, v1 = to_yuv
+        y2, u2, v2 = other.to_yuv
+        dy, du, dv = y1 - y2, u1 - u2, v1 - v2
+        Math.sqrt(dy**2 + du**2 + dv**2)
+      end
+    end
+
+    def closest(set)
+      if set.respond_to? :to_hash
+        hash = set.to_hash
+        hash.key(closest(hash.values))
+      elsif set.include? self
+        self
+      else
+        set.grep(Color).min_by { |c| distance(c) }
+      end
+    end
+
+    def to_yuv
+      @yuv ||= begin
+        y =  (0.257 * red) + (0.504 * green) + (0.098 * blue) + 16
+        u = -(0.148 * red) - (0.291 * green) + (0.439 * blue) + 128
+        v =  (0.439 * red) - (0.368 * green) - (0.071 * blue) + 128
+        [y, u, v].freeze
+      end
+    end
+
+    def to_i
+      (red << 16) + (green << 8) + blue
+    end
+
+    def inspect
+      "#<%p:%d,%d,%d>" % [self.class, red, green, blue]
+    end
+
+    def to_s
+      "#%06x" % to_i
+    end
+
+    def to_css_rule
+      "color: #{self};"
+    end
+
+    def to_ansi(mode: Hansi.mode, **options)
+      case Integer === mode ? mode : Integer(mode.to_s[/\d+/])
+      when 256            then to_ansi_256colors(**options)
+      when 24, TRUE_COLOR then to_ansi_24bit(**options)
+      when 88             then to_ansi_88colors(**options)
+      when 16             then to_ansi_16colors(**options)
+      when 8              then to_ansi_8colors(**options)
+      when 1, 0           then ""
+      else raise ArgumentError, "unknown mode %p" % mode
+      end
+    end
+
+    def to_ansi_24bit(**options)
+      "\e[38;2;%d;%d;%dm" % [red, green, blue]
+    end
+
+    def to_ansi_256colors(**options)
+      from_palette('xterm-256color', 'xterm', **options)
+    end
+
+    def to_ansi_88colors(**options)
+      from_palette('xterm-88color', 'xterm', **options)
+    end
+
+    def to_ansi_16colors(**options)
+      from_palette('xterm', **options)
+    end
+
+    def to_ansi_8colors(**options)
+      from_palette('ansi', **options)
+    end
+
+    def to_web_name(**options)
+      from_palette('web', **options)
+    end
+
+    def from_palette(main, *fallback, exact: false)
+      @from_palette ||= { true => {}, false => {} }
+      cached          = @from_palette[exact]
+      cached[main]  ||= PALETTES[main].key(self)
+      cached[main]  ||= closest(PALETTES[main]) unless exact
+      cached[main]  ||= from_palette(*fallback, exact: exact) if fallback.any?
+      cached[main]
+    end
+
+    private :from_palette
+  end
+end