ansi 1.4.3 → 1.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f64bee2019769713b2ac4762b94be9f6c2346eb4ae4baa0b0645e7a2f2371286
+  data.tar.gz: 8fdba321ec78907d1109046af0656ee9c3a0c2342f5aaff7c3611ba3ea4d2976
+SHA512:
+  metadata.gz: cb67809ddcbb4ddc3e527081a4c65ab4445c116d7eb17c0da6a31837d4cfc943c123724dd63e18ecf7812a43f5bfae6292899da2b8b2a1a6f77c70e1d336d0f8
+  data.tar.gz: da85dad4be00c385f5c019b61ea1ae358ef0208bb5c7c9d17713e64e710f72098fe7798b1e04e76c9e2030c440a7558202510a382ec3aa72a2d9f4c9d9911cb5

data/{HISTORY.rdoc → HISTORY.md}

@@ -1,6 +1,42 @@
-= RELEASE HISTORY
+# RELEASE HISTORY
 
-== 1.4.3 | 2012-06-26
+## 1.6.0 | 2026-03-30
+
+Maintenance release. Modernized project tooling and cleaned up documentation.
+
+Changes:
+
+* Replace custom Indexer system with standard gemspec.
+* Replace Travis CI with GitHub Actions.
+* Replace Assembly/detroit/ergo with Rakefile.
+* Simplify version.rb to use a plain constant.
+* Fix Fixnum reference for Ruby 3+ compatibility.
+* Fix typos and update URLs to HTTPS.
+* Move site from gh-pages to docs/.
+* Remove obsolete files.
+* Clean up .gitignore.
+
+
+## 1.5.0 | 2015-01-16
+
+ANSI 1.5 introduces one change that is not backward compatiable. The 
+`:clear_line` code no longer clears to the end of the line. Instead it
+clears the entire line. If you have used this in the past you
+will need to update your code to use `:clear_eol` or `:clear_right`
+instead. In addition this release finally fixes some long time issues
+with Windows compatability, and a few other bugs. Yeah!
+
+Changes:
+
+* Alias `:right` and `:left` as `:forward` and `:back` respectively.
+* Change `:clear_line` to clear whole line, not just to the end of line.
+* Add `:cursor_hide` and `:cursor_show` codes.
+* Fix and adjust #rgb method to work as one would expect.
+* Fix Windows compatability (old code was alwasy using stty).
+* Fix duplicated hash key in chart.rb.
+
+
+## 1.4.3 | 2012-06-26
 
 This release bring two small changes. The first improves support
 for Windows by only rescuing LoadError when 'win32console' fails
@@ -13,7 +49,7 @@ Changes:
 * Improvements for getting proper screen width.
 
 
-== 1.4.2 | 2012-01-29
+## 1.4.2 | 2012-01-29
 
 ANSI chains are a new feature inspired by Kazuyoshi Tlacaelel's Isna project.
 It is a fluid notation for the String#ansi method, e.g. `"foo".red.on_white`.
@@ -34,7 +70,7 @@ Changes:
 * Support custom padding for Columns.
 
 
-== 1.4.1 | 2011-11-09
+## 1.4.1 | 2011-11-09
 
 This release simply fixes a documentation issue, to make sure
 QED.rdoc appears in the YARD docs. And a shout-out to Chad Perrin
@@ -47,7 +83,7 @@ Changes:
 * Documentation fixes.
 
 
-== 1.4.0 | 2011-11-05
+## 1.4.0 | 2011-11-05
 
 New release adds a HexDump class for colorized byte string dumps
 and fixes some minor cell size issues with the Table class.
@@ -63,7 +99,7 @@ Changes:
 * Switch to BSD-2-Clause license.
 
 
-== 1.3.0 | 2011-06-30
+## 1.3.0 | 2011-06-30
 
 This release cleans up the Code module. It adds support for x-term
 256 color codes. Also, the Diff class is now awesome, making use of
@@ -81,7 +117,7 @@ Changes:
 * Improved Diff class with LCS algorithm.
 
 
-== 1.2.5 | 2011-05-03
+## 1.2.5 | 2011-05-03
 
 This release introduces a preliminary rendition of a Diff class
 for getting colorized comparisons of strings and other objects.
@@ -93,7 +129,7 @@ Changes:
 * Fixed minor issue with Columns format block; col comes before row.
 
 
-== 1.2.4 | 2011-04-29
+## 1.2.4 | 2011-04-29
 
 This release improves to the ANSI::Columns class. In particular the
 layout is more consistent with intended functionality.
@@ -105,7 +141,7 @@ Changes:
 * ANSI::Columns can take a String or Array list.
 
 
-== 1.2.3 | 2011-04-08
+## 1.2.3 | 2011-04-08
 
 Minor release to add #clear method to ProgressBar and provide bug
 fix to BBCode.ansi_to_bbcode. Big thanks goes to Junegunn Choi 
@@ -117,7 +153,7 @@ Changes:
 * Fixed ANSI::BBCode.ansi_to_bbcode and ansi_to_html from omitting lines
 without any ansi code (Junegunn Choi).
 
-== 1.2.2 | 2010-06-12
+## 1.2.2 | 2010-06-12
 
 This release removes warnings about string arguments for certain
 ANSI::Code methods. While the string form is considered deprecated,
@@ -133,13 +169,13 @@ Changes:
 * Add ANSI::Mixin#display.
 
 
-== 1.2.1 | 2010-05-10
+## 1.2.1 | 2010-05-10
 
 This release was simply a quick fix to remove the incorrect embedded
 version number, until it gets fixed.
 
 
-== 1.2.0 | 2010-05-10
+## 1.2.0 | 2010-05-10
 
 This release entails numerous improvements. First and foremost
 the Code module is transitioning to a block interface only
@@ -165,7 +201,7 @@ Changes:
 * Many new tests and QED documents.
 
 
-== 1.1.0 | 2009-10-04
+## 1.1.0 | 2009-10-04
 
 This release is the first toward making the ANSI library
 more widely usable.
@@ -177,7 +213,7 @@ Changes:
 * Other minor underthehood improvements.
 
 
-== 1.0.1 | 2009-08-15
+## 1.0.1 | 2009-08-15
 
 The release fixes a single bug that should allow Ruby 1.9
 to use the ANSI library.
@@ -187,7 +223,7 @@ Changes:
 * Renamed PLATFORM to RUBY_PLATFORM
 
 
-== 1.0.0 | 2009-08-15
+## 1.0.0 | 2009-08-15
 
 This is the initial stand-alone release of ANSI, a collection
 of ANSI based classes spun-off from Ruby Facets.
@@ -195,3 +231,4 @@ of ANSI based classes spun-off from Ruby Facets.
 Changes:
 
 * Happy Birthday!
+

data/LICENSE.txt

@@ -0,0 +1,23 @@
+BSD-2-Clause License (http://spdx.org/licenses/BSD-2-Clause)
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+

data/NOTICE.md

@@ -0,0 +1,170 @@
+# COPYRIGHT NOTICES
+
+## ANSI
+
+Copyright © 2009 [Rubyworks](http://rubyworks.github.com) ·
+License [BSD-2-Clause](http://spdx.org/licenses/BSD-2-Clause) ·
+Website http://rubyworks.github.com/ansi
+
+    Copyright 2009 Rubyworks.
+
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without modification, are
+    permitted provided that the following conditions are met:
+
+       1. Redistributions of source code must retain the above copyright notice, this list of
+          conditions and the following disclaimer.
+
+       2. Redistributions in binary form must reproduce the above copyright notice, this list
+          of conditions and the following disclaimer in the documentation and/or other materials
+          provided with the distribution.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY EXPRESS OR IMPLIED
+    WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+    FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS
+    OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+    ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+    ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+    (https://raw.github.com/rubyworks/ansi/master/LICENSE.txt)
+
+
+## ProgressBar
+
+Copyright © 2001 *Satoru Takabayashi* ·
+License [Ruby](http://spdx.org/licenses/Ruby) ·
+Website http://0xcc.net/ruby-progressbar
+
+ProgressBar class is based on the original ProgressBar by Satoru Takabayashi.
+
+    Ruby/ProgressBar - a text progress bar library
+
+    Copyright (C) 2001-2005 Satoru Takabayashi <satoru@namazu.org>
+        All rights reserved.
+        This is free software with ABSOLUTELY NO WARRANTY.
+
+    You can redistribute it and/or modify it under the terms
+    of Ruby's license.
+
+
+## HighLine (Terminal Extensions)
+
+Copyright &copy; 2006 *Gray Productions* &middot;
+License [Ruby](http://spdx.org/licenses/Ruby) &middot;
+Website http://highline.rubyforge.org
+
+The terminal extensions are based on HighLine's SystemExtensions
+by James Edward Gray II.
+
+    Copyright 2006 Gray Productions
+
+    Distributed under the user's choice of the {GPL Version 2}[http://www.gnu.org/licenses/old-licenses/gpl-2.0.html]
+    (see GPL-2.0.txt for details) or the {Ruby software license}[http://www.ruby-lang.org/en/LICENSE.txt]
+    by James Edward Gray II and Greg Brown.
+
+    Please email James[mailto:james@grayproductions.net] with any questions.
+
+    (https://github.com/JEG2/highline/blob/master/LICENSE)
+
+
+## BBCode
+
+Copyright &copy; 2002 *Thomas-Ivo Heinen* &middot;
+License [Ruby](http://spdx.org/licenses/Ruby)
+
+BBCode module is a derivative of BBCode by Thomas-Ivo Heinen.
+
+    Copyright (c) 2002 Thomas-Ivo Heinen
+
+    This module is free software. You may use, modify, and/or redistribute this
+    software under the same terms as Ruby.
+
+    This program is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+    FOR A PARTICULAR PURPOSE.
+
+
+## Rainbow (XTerm Color Support)
+
+Copyright &copy; *Marcin Kulik* &middot;
+License [MIT](http://spdx.org/licenses/MIT) &middot;
+Website http://github.com/sickill/rainbow
+
+Rainbox provided the bases for building the XTerm 256 color code
+support into the ANSI::Code module.
+
+    Copyright (c) Marcin Kulik
+
+    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.
+
+    (https://raw.github.com/sickill/rainbow/master/LICENSE)
+
+
+## Paint (ANSI Code Names)
+
+Copyright &copy; 2011 *Jan Lelis* &middot;
+License [MIT](http://spdx.org/licenses/MIT) &middot;
+Website https://github.com/janlelis/paint
+
+Some of the latest ANSI code names, and inspiration to check out Rainbow
+and include XTerm 256 color codes, came from Paint.
+
+    Copyright (c) 2011 Jan Lelis
+
+    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.
+
+    (https://raw.github.com/janlelis/paint/master/LICENSE.txt)
+
+
+## ANSIColor
+
+_Acknowlegement_
+
+Copyright &copy; 2002 *Florian Frank* &middot;
+Website http://flori.github.com/term-ansicolor
+
+Albeit the code no long bares much, if any, resemblance to it, the ANSI Code
+module (and subsequently the Constants module) originated with the
+ANSIColor library by Florian Frank.
+
+    Copyright (c) 2002 Florian Frank
+
+

data/{README.rdoc → README.md}

@@ -1,14 +1,14 @@
-= ANSI
+# ANSI
 
-{Home}[http://rubyworks.github.com/ansi] /
-{API}[http://rubydoc.info/gems/ansi/frames] /
-{Code}[http://github.com/rubyworks/ansi] /
-{Mail}[http://googlegroups.com/group/rubyworks-mailinglist]
+[HOME](https://rubyworks.github.io/ansi) ·
+[API](https://rubydoc.info/gems/ansi) ·
+[ISSUES](https://github.com/rubyworks/ansi/issues) ·
+[SOURCE](https://github.com/rubyworks/ansi)
 
-{<img src="http://travis-ci.org/rubyworks/ansi.png" />}[http://travis-ci.org/rubyworks/ansi]
+[![Gem Version](https://img.shields.io/gem/v/ansi.svg?style=flat)](https://rubygems.org/gems/ansi)
+[![Build Status](https://github.com/rubyworks/ansi/actions/workflows/test.yml/badge.svg)](https://github.com/rubyworks/ansi/actions/workflows/test.yml)
 
-
-== DESCRIPTION
+<br/>
 
 The ANSI project is a collection of ANSI escape code related libraries
 enabling ANSI code based colorization and stylization of output.
@@ -21,7 +21,7 @@ Terminal which provides information about the current output
 device.
 
 
-== FEATURES
+## Features
 
 * ANSI::Code provides ANSI codes as module functions.
 * String#ansi makes common usage very easy and elegant.
@@ -30,58 +30,58 @@ device.
 * Additional clases for colorized columns, tables, loggers and more.
 
 
-== RELEASE NOTES
-
-Please see HISTORY file.
-
-
-== SYNOPSIS
+## Synopsis
 
 There are a number of modules and classes provided by the ANSI
 package. To get a good understanding of them it is best to pursue 
-the QED documents[http://github.com/rubyworks/ansi/tree/master/qed/]
-or the API documentation[http://rubyworks.github.com/ansi/api/index.html].
+the [QED documents](https://github.com/rubyworks/ansi/tree/master/demo/)
+or the [API documentation](https://rubydoc.info/gems/ansi).
 
 At the heart of all the provided libraries lies the ANSI::Code module
 which defines ANSI codes as constants and methods. For example:
 
-  require 'ansi/code'
+    require 'ansi/code'
 
-  ANSI.red + "Hello" + ANSI.blue + "World"
-  => "\e[31mHello\e[34mWorld"
+    ANSI.red + "Hello" + ANSI.blue + "World"
+    => "\e[31mHello\e[34mWorld"
 
 Or in block form.
 
-  ANSI.red{ "Hello" } + ANSI.blue{ "World" }
-  => "\e[31mHello\e[0m\e[34mWorld\e[0m"
+    ANSI.red{ "Hello" } + ANSI.blue{ "World" }
+    => "\e[31mHello\e[0m\e[34mWorld\e[0m"
 
 The methods defined by this module are used throughout the rest of
 the system.
 
 
-== INSTALLATION
+## Installation
 
-To install with RubyGems simply open a console and type:
+### Bundler
 
-  $ sudo gem install ansi
+Add the usual `gem` line to your project's `Gemfile`.
+
+    gem 'ansi'
+
+And run then `bundle` command.
+
+### RubyGems
+
+To install with RubyGems simply open a console and type:
 
-Local installation requires Setup.rb (gem install setup),
-then download[http://github.com/rubyworks/ansi/download] the tarball package and type:
+    $ sudo gem install ansi
 
-  $ tar -xvzf ansi-1.0.0.tgz
-  $ cd ansi-1.0.0
-  $ sudo setup.rb all
+## Release Notes
 
-Windows users use 'ruby setup.rb all'.
+Please see HISTORY.md file.
 
 
-== LICENSE & COPYRIGHTS
+## License & Copyrights
 
 Copyright (c) 2009 Rubyworks
 
-This program is redistributable under the terms of the *FreeBSD* license.
+This program is redistributable under the terms of the *BSD-2-Clause* license.
 
 Some pieces of the code are copyrighted by others.
 
-See COPYING.rdoc file for details.
+See LICENSE.txt and NOTICE.md files for details.
 

data/demo/01_ansicode.md

@@ -0,0 +1,65 @@
+# ANSI::Code
+
+Require the library.
+
+    require 'ansi/code'
+
+ANSI::Code can be used as a functions module.
+
+    str = ANSI::Code.red + "Hello" + ANSI::Code.blue + "World"
+    str.assert == "\e[31mHello\e[34mWorld"
+
+If a block is supplied to each method then yielded value will
+be wrapped in the ANSI code and clear code. 
+
+    str = ANSI::Code.red{ "Hello" } + ANSI::Code.blue{ "World" }
+    str.assert == "\e[31mHello\e[0m\e[34mWorld\e[0m"
+
+More conveniently the ANSI::Code module extends ANSI itself.
+
+    str = ANSI.red + "Hello" + ANSI.blue + "World"
+    str.assert == "\e[31mHello\e[34mWorld"
+
+    str = ANSI.red{ "Hello" } + ANSI.blue{ "World" }
+    str.assert == "\e[31mHello\e[0m\e[34mWorld\e[0m"
+
+ANSI also supports XTerm 256 color mode using red, blue and green values
+with the `#rgb` method.
+
+    str = ANSI::Code.rgb(0, 255, 0)
+    str.assert == "\e[38;5;46m"
+
+Or using CSS style hex codes as well.
+
+    str = ANSI::Code.rgb("#00FF00")
+    str.assert == "\e[38;5;46m"
+
+Both of these methods can take blocks to wrap text in the color and clear codes.
+
+    str = ANSI::Code.rgb("#00FF00"){ "Hello" }
+    str.assert == "\e[38;5;46mHello\e[0m"
+
+In the appropriate context the ANSI::Code module can also be
+included, making its methods directly accessible.
+
+    include ANSI::Code
+
+    str = red + "Hello" + blue + "World"
+    str.assert == "\e[31mHello\e[34mWorld"
+
+    str = red{ "Hello" } + blue{ "World" }
+    str.assert == "\e[31mHello\e[0m\e[34mWorld\e[0m"
+
+Along with the single font colors, the library include background colors.
+
+    str = on_red + "Hello"
+    str.assert == "\e[41mHello"
+
+As well as combined color methods.
+
+    str = white_on_red + "Hello"
+    str.assert == "\e[37m\e[41mHello"
+
+The ANSI::Code module supports most standard ANSI codes, though
+not all platforms support every code, so YMMV.
+

data/demo/{02_core.rdoc → 02_core.md}

@@ -1,11 +1,11 @@
-= String Extensions
+# String Extensions
 
 In addition the library offers an extension to String class
 called #ansi, which allows some of the ANSI::Code methods
 to be called in a more object-oriented fashion.
 
-  require 'ansi/core'
+    require 'ansi/core'
 
-  str = "Hello".ansi(:red) + "World".ansi(:blue)
-  str.assert == "\e[31mHello\e[0m\e[34mWorld\e[0m"
+    str = "Hello".ansi(:red) + "World".ansi(:blue)
+    str.assert == "\e[31mHello\e[0m\e[34mWorld\e[0m"
 

data/demo/03_logger.md

@@ -0,0 +1,30 @@
+# ANSI::Logger
+
+Require the ANSI::Logger library.
+
+    require 'ansi/logger'
+
+Create a new ANSI::Logger
+
+    log = ANSI::Logger.new(STDOUT)
+
+Info logging appears normal.
+
+    log.info{"Info logs are green.\n"}
+
+Warn logging appears yellow.
+
+    log.warn{"Warn logs are yellow.\n"}
+
+Debug logging appears cyan.
+
+    log.debug{"Debug logs are cyan.\n"}
+
+Error logging appears red.
+
+    log.error{"Error logs are red.\n"}
+
+Fatal logging appears bright red.
+
+    log.fatal{"Fatal logs are bold red!\n"}
+

data/demo/04_progressbar.md

@@ -0,0 +1,62 @@
+# ANSI::Progressbar
+
+Pretty progress bars are easy to construct.
+
+    require 'ansi/progressbar'
+
+    pbar = ANSI::Progressbar.new("Test Bar", 100)
+
+Running the bar simply requires calling the #inc method during
+a loop and calling `#finish` when done.
+
+    100.times do |i|
+      sleep 0.01
+      pbar.inc
+    end
+    pbar.finish
+
+We will use this same rountine in all the examples below, so lets
+make a quick macro for it. Notice we have to use `#reset` first
+before reusing the same progress bar.
+
+    def run(pbar)
+      pbar.reset
+      100.times do |i|
+        sleep 0.01
+        pbar.inc
+      end
+      pbar.finish
+      puts
+    end
+
+The progress bar can be stylized in almost any way.
+The `#format` setter provides control over the parts
+that appear on the line. For example, by default the
+format is:
+
+    pbar.format("%-14s %3d%% %s %s", :title, :percentage, :bar, :stat)
+
+So lets vary it up to demonstrate the case.
+
+    pbar.format("%-14s %3d%% %s %s", :title, :percentage, :stat, :bar)
+    run(pbar)
+
+The progress bar has an extra build in format intended for use with
+file downloads called `#transer_mode`.
+
+    pbar.transfer_mode
+    run(pbar)
+
+Calling this methods is the same as calling:
+
+    pbar.format("%-14s %3d%% %s %s",:title, :percentage, :bar, :stat_for_file_transfer)
+    run(pbar)
+
+The `#style` setter allows each part of the line be modified with ANSI codes. 
+And the `#bar_mark` writer can be used to change the character used to make the bar.
+
+    pbar.standard_mode
+    pbar.style(:title => [:red], :bar=>[:blue])
+    pbar.bar_mark = "="
+    run(pbar)
+