README.rdoc in tailor-1.0.0.alpha2 vs README.rdoc in tailor-1.0.0

@@ -2,15 +2,18 @@
 
 * http://github.com/turboladen/tailor
 
 == DESCRIPTION:
 
-tailor recursively parses Ruby files in a directory and checks them for bad 
-style.  Rules for judging style are based on a number of style guides that are
-popular in the Ruby community.  More on this here
+tailor parses Ruby files and measures them with some style and static analysis
+"rulers".  Default values for the Rulers are based on a number of style guides
+in the Ruby community as well as what seems to be common.  More on this here
 http://wiki.github.com/turboladen/tailor.
 
+tailor's goal is to help you be consistent with your style, throughout your
+project, whatever style that may be.
+
 == FEATURES/PROBLEMS:
 
 * Checks for bad style in Ruby files
   * Recursively in a directory, or...
   * A given file, or...
@@ -31,16 +34,19 @@
     * Max code lines in a class/module
     * Max code lines in a method
   * Name cases
     * Snake case class & module names
     * Camel case method names
+  * Valid Ruby (warns by default)
 * Configurable
   * Specify style in
     * ~./tailorrc
     * PROJECT_ROOT + .tailor
     * as CLI options
-  * "File sets" allow for applying different styles to different sets of files
+  * "File sets" allow for applying different styles to different groups of files
+  * Set problems to :warn or :off instead of :fail
+* Define custom "Rulers"
 * CI/Build Integration
   * (Well, this may be stretching things a bit, but...) Exit 1 on failures
 
 == SYNOPSIS:
 
@@ -54,12 +60,12 @@
 
 At tailor's inception, there were some other static analysis tools for Ruby,
 but none which checked style stuff; tailor started off as a means to fill this
 gap.  Since then, a number of those tools have dropped by the wayside due to
 various Ruby 1.9 incompatibilities, and left a bigger tool gap for Rubyists.
-Right now it's mostly a style-checker, but might also have a future role in
-analyzing other aspects of your Ruby code.
+Right now it's mostly a style-checker, but might into a tool for analyzing other
+aspects of your Ruby code.
 
 === Since 0.x...
 
 tailor 1.x is a marked improvment over 0.x.  While 0.x provided a few (pretty
 inconsistent) style checks, its design made the code get all spaghetti-like,
@@ -83,13 +89,66 @@
 
 ...or... (defaults to lib/**/*.rb):
 
   $ tailor
 
-There are still a number of false-positives and false-negatives in detection of
-the above rules, so please don't expect perfection in this detection.  :)
+==== On style...
 
+The features list, above, shows some aspects of style that should be fairly
+straightforward (as to their meaning and reason), however, others make some big
+assumptions--particularly the indentation checking "ruler".  There are a number
+of popular indenting conventions...  In the case of multi-line parameters to a
+method, some like do this:
+
+  def a_really_freakin_long_method_name(my_really_long_first_parameter,
+    my_next_param)
+    # ...
+  end
+
+...while others prefer:
+
+  def a_really_freakin_long_method_name(my_really_long_first_parameter,
+      my_next_param)
+    # ...
+  end
+
+...and yet some others prefer:
+
+  def a_really_freakin_long_method_name(my_really_long_first_parameter,
+                                        my_next_param)
+    # ...
+  end
+
+At this point, tailor only supports the style used in the first example.  If
+this style isn't to your liking, then definitely take a look at the
+Configurable section here to see how to turn this off.  Other styles will
+probably be supported in the future.
+
+All that to say, though, that this isn't the only case where tailor makes style
+assumptions.  Another discrepancy in popular styles is with regard to aligning
+operators in different lines.  Some like:
+
+  my_hash[:first][:thing] = 1
+  my_hash[:eleventy][:thing] = 2
+
+...while others prefer:
+
+  my_hash[:first][:thing]    = 1
+  my_hash[:eleventy][:thing] = 2
+
+...and yet some others prefer:
+
+  my_hash[:first][:thing] =    1
+  my_hash[:eleventy][:thing] = 2
+
+Again, tailor only supports the first example here.
+
+The goal is certainly not to force you to use the style that tailor currently
+uses; it just might not support your style yet.  If tailor doesn't support your
+style, please feel free to take a look at the issues list and make a request.
+...or fork away!
+
 === Configurable:
 
 Not everyone prefers the same style of, well, anything really.  tailor is
 configurable to allow you to check your code against the style measurements
 that you want.
@@ -111,33 +170,33 @@
 If, for example, you want to tell tailor to warn you if any of your code lines
 are > 100 chars (instead of the default of 80):
 
   $ tailor --max-line-length 100 lib/
 
-If you want to simply disable a ruler, just pass +false+ to the option:
+If you want to simply disable a ruler, just pass +off+ to the option:
 
-  $ tailor --max-line-length false lib/
+  $ tailor --max-line-length off lib/
 
 ==== Configuration File
 
-Configuration files allow for some more flexibility with style rulers, file
-lists, and (eventually) report formatters.  To create one with default
-settings, do:
+While you can drive most tailor options from the command line, configuration
+files allow for some more flexibility with style rulers, file lists, and
+(eventually) report formatters.  To create one with default settings, do:
 
   $ tailor --create-config
 
 With the documentation that's provided in the file, the settings should be
 straightforward (if they're not, please let me know!).  You don't have to specify
 all of those settings in your config file--those are just rendered so you have
 a starting ground to tweak with.  If you only want to override a single value,
 you can delete the rest of the code from your config.  This would accomplish
-the same as the --max-line-length example above:
+the same as the <tt>--max-line-length</tt> example above:
 
   # .tailor
   Tailor.config do |config|
-    config.file_set 'lib/**/*.rb' do
-      max_line_length 100
+    config.file_set 'lib/**/*.rb' do |style|
+      style.max_line_length 100
     end
   end
 
 This brings us to the concept of "file sets"...
 
@@ -149,31 +208,122 @@
 more lenient with curly-brace usage... You may just want to specify a few file
 globs to use the default set of rulers...  File sets allow for those sorts of
 things.
 
 In the default config file, you see a single parameter being passed to
-<tt>config.file_set</tt>--this is the _label_ for that file set.  The label is
+<tt>config.file_set</tt>--this is the glob that defines the list of files for
+that file set.  While you don't see it, +config.file_set+ takes a second
+optional parameter that allows you to _label_ your style properties, and thus
+use different sets of style properties for differet sets of files.  The label is
 simply just a name to refer to that file set by; it will show in your report
 (in the case that problems were found, of course) so you know what set of
-rulers caused the problem to be found.  <tt>config.file_set</tt> also takes
-a second paramter: the file/directory/glob to apply the style to.
+rulers caused the problem to be found.
 
   # .tailor
   Tailor.config do |config|
-    config.file_set :rails_app, 'app/**/*.rb' do
-      max_line_length 100
+
+    # All defaults; implies "default" label
+    config.file_set 'lib/**/*.rb
+
+    config.file_set 'app/**/*.rb', :rails_app do |style|
+      style.max_line_length 100
       # All other rulers will use default values
     end
 
-    config.file_set :features, 'features/**/*.rb'     # Uses default style
+    # Uses default style, but labelled in the report with "features"
+    config.file_set 'features/**/*.rb', :features
 
-    config.file_set :rspec, 'spec/**/*.rb' do
-      spaces_after_lbrace false
-      spaces_before_lbrace false
-      spaces_before_rbrace false
+    config.file_set 'spec/**/*.rb', :rspec do |style|
+      style.spaces_after_lbrace false
+      style.spaces_before_lbrace false
+      style.spaces_before_rbrace false
       # All other rulers will use default values
     end
   end
+
+Similarly to the CLI, if you want to turn off a default Ruler, set its problem
+level to +:off+:
+
+  # .tailor
+  Tailor.config do |config|
+    config.file_set 'lib/**/*.rb do |style|
+      style.indentation_spaces 2, level: :off
+    end
+  end
+
+
+=== Define A Custom Ruler
+
+While tailor provides a number of Rulers for checking style, it also provides a
+way for you to add your own rulers without having to delve into its innards.  To
+do this, you need to do the following.
+
+==== Create the Ruler
+
+Before jumping in to this, take a look at {Tailor::Ruler} and any of the
+existing Rulers in +lib/tailor/rulers/+.  There are some key things a new Ruler
+must have:
+
+* the class name ends with "Ruler"
+* it inherits {Tailor::Ruler}
+* it's defined within the {Tailor::Rulers} module
+* +#initialize+ defines two parameters:
+  1. +config+ sets +@config+ to the "golden rule" value for what you're measuring
+  2. +options+ is a Hash, that should at least be passed the :level => you want
+     the problem to be logged as
+* +#add_lexer_observers+ gets passed a list of {Tailor::Lexer} event types that
+  the ruler should get notified on
+* it defines call-back methods for {Tailor::Lexer} to call when it comes across
+  an event of interest
+* it calls +#measure+ to assess if the criteria it's checking has been met
+* it adds a {Tailor::Problem} to +@problems+ when one is found in +#measure+
+
+==== Add the Ruler to the list of Styles
+
+Internally, this all happens in +lib/tailor/configuration/style.rb+, but you can
+add infomation about your ruler to your config file.  If you created a Ruler:
+
+  # max_lines_in_block.rb
+  class Tailor
+    module Rulers
+      class MaxLinesInBlockRuler < Tailor::Ruler
+        def initialize(config, options)
+          super(config, options)
+          add_lexer_observers :ignored_nl, :kw
+        end
+
+        def ignored_nl_update(lexed_line, lineno, column)
+          # ...
+        end
+
+        def kw_update(token, lexed_line, lineno, column)
+          # ...
+        end
+
+        def measure
+          # ...
+        end
+
+        # ...
+      end
+    end
+  end
+
+...then require this and add it to the Style list of properties:
+
+  # .tailor
+  require 'tailor/configuration/style'
+  require 'max_lines_in_block'
+
+  Tailor::Configuration::Style.define_property :max_lines_in_block
+
+  Tailor.config do |config|
+    config.file_set 'lib/**/*.rb' do |style|
+      style.max_lines_in_block 10, level: :error
+    end
+  end
+
+Next time you run tailor, your Ruler will get initialized and used.
 
 == REQUIREMENTS:
 
 * Rubies (tested)
   * 1.9.2