README.txt

   1 augment
   2     by Phil Hagelberg (c) 2007
   3     http://augment.rubyforge.org
   4
   5 == Description
   6
   7 Augment is a framework for gathering metadata from code and displaying
   8 it. This metadata would include test failures, test coverage levels,
   9 complexity metrics, and others. Display frontends will be pluggable so
  10 as to interface with many editors.
  11
  12 == Usage
  13
  14 The +augment+ executable gathers metadata in the form of layers for a
  15 given file via a backend. Some backends gather data for a file other
  16 than the original one passed in. (The test backend will store data for
  17 the test if you pass in the implementation.)
  18
  19 Example:
  20
  21 $ augment test lib/foo.rb # will store metadata for test/test_foo.rb
  22
  23 You can also use the +augment+ executable to display stored
  24 metadata. The simplest frontend is +color+ which outputs the
  25 layers via ANSI color codes to the shell:
  26
  27 $ augment color test/test_foo.rb
  28
  29 Most other frontends are editor-specific.
  30
  31 == Design
  32
  33 Augment is designed to be generalized; if you want to collect
  34 different kinds of data you can just write a new backend. If you want
  35 to display the data in an unsupported editor or output format, you can
  36 write a new frontend.
  37
  38 === Backends
  39
  40 Each backend takes a filename or glob and outputs the metadata about
  41 that file into the .augment directory, created in the project root.
  42 Metadata is stored as layer information in JSON. Each backend also
  43 needs an initiator command to kick off the process that gathers the
  44 metadata, with the exception of auto-initiating backends like autotest.
  45
  46 === Frontends
  47
  48 Most frontends are implemented within an editor or IDE. They watch
  49 the .augment directory for changes and apply them to the open buffers
  50 when they happen.  The user can choose what augmentations he wants
  51 displayed either globally or on a per-file basis. He can also control
  52 when backend initiators should be started, though usually these will
  53 be kicked off automatically upon saving a file.
  54
  55 === Layers
  56
  57 A layer consists of a single piece of metadata about a file. This is
  58 expressed in terms of the range it applies to in the file, its color,
  59 and the message associated with it.
  60
  61 == Support
  62
  63 Backends:
  64
  65 * Tests (miniunit)
  66 * Rspec (planned)
  67 * Heckle (planned)
  68 * Rcov (planned)
  69 * Flog (planned)
  70 * Performance (planned)
  71
  72 Frontends:
  73
  74 * ANSI color codes (for shells)
  75 * HTML
  76 * Emacs
  77 * Textmate (planned)
  78 * Vim (planned, need help)
  79
  80 == Issues
  81
  82 * A bit short on frontends and backends.
  83
  84 == License
  85
  86 This is free software; you can redistribute it and/or modify it under
  87 the terms of the GNU General Public License as published by the Free
  88 Software Foundation; either version 3, or (at your option) any later
  89 version.
  90
  91 This file is distributed in the hope that it will be useful, but
  92 WITHOUT ANY WARRANTY; without even the implied warranty of
  93 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  94 General Public License for more details.
  95
  96 You should have received a copy of the GNU General Public License
  97 along with this software; see the file COPYING. If not, write to the
  98 Free Software Foundation at this address:
  99
 100   Free Software Foundation
 101   51 Franklin Street, Fifth Floor
 102   Boston, MA 02110-1301
 103   USA