Permalink
Browse files

updating readme for better documentation

  • Loading branch information...
bglusman
bglusman committed Jan 28, 2012
1 parent 5d828af commit d811cf59cefe0296a041c95ba8794c2f7a9b9bc3
Showing with 63 additions and 25 deletions.
  1. +63 −25 README.md
View
@@ -1,55 +1,93 @@
#Outlaw
##Keep bad code out of your projects. Your idea of bad code, no one elses.
##Because good documentation should be executable.
###NOTE: Outlaw can evaluate any version ruby code, *BUT* it runs on only 1.9 -- set your system ruby to 1.9 to use
### Part of MendicantUniversity.org S10 class, personal project.
From the included .outlawed.example file for custom rule definition:
outlaw "@@", "Class variables are evil"
outlaw "protected", "use private or public, protected is silly in ruby"
outlaw "module :token end", "nest modules to avoid empty module declarations"
outlaw "eval", "never eval, rarely class_eval or instance_eval, but never eval"
The current version of outlaw takes a user provided configuration file
(currently named simply '.outlawed' in the project directory or user's home
directory) and parses a series of method calls to the outlaw method (defined
within the Outlaw module namespace, but module_eval'd so you don't need to
namespace the file). You can also define constants in your .outlawed file as
collections of strings for use in your laws, but that will be addressed below.
Execute outlaw on your project from the root directory by simply entering "outlaw", or specify another directory to run
on with "outlaw /path/to/dir"
Each call to the outlaw method consists of two string arguments, the first an
anti-pattern you wish to prohibit usage of in one or more projects, and the
second an explanation to be provided when the anti-pattern is detected.
### Syntax for law creation:
Some examples are include in the .outlawed.example file for reference:
outlaw "@@", "Class variables are evil"
Before using outlaw in a project you should create a .outlawed file which Outlaw will read laws from.
It comes with an example file (.outlawed.example) which is included in the gem and will be loaded if no .outlawed
file is found in current directory or home directory, and will warn you to provide a real file (and provide location
of the sample file in your system from the gem installation).
outlaw "protected", "use private or public, protected
is silly in ruby"
### Syntax for DSL:
outlaw "eval", "never eval, rarely class_eval or
instance_eval, but never eval"
A defined collection exists for core classes, such that
outlaw "module :token end", "nest modules to avoid empty module
declarations"
outlaw "class :symbol < :core_class",
"core classes implemented in c, can cause bad mojo"
outlaw "class :symbol < :core_class", "core classes implemented in c,
can cause bad mojo"
will outlaw subclassing from any core class
The first three examples are actual ruby keywords and features being outlawed
and may not require much explanation except to indicate that they are detected
via regular expression matches constructed from the strings, and attempt to use
word boundaries intelligently so that eval is detected but not module_eval.
The bottom two examples above use ruby symbols as standin variable or
parameter names for identifiers that are matched at runtime with local
variables, instance variables, class names and constants that may appear
within the ruby program being analyzed. Here, :symbol can be any ruby symbol
if it appears only once, though if used multiple times it will only match the
the same identifier on subsequent usage. :core_class as used above is a
special case where Outlaw has internally defined a constant called CORE_CLASS
as a collection of string objects each containing the name of one of ruby's
core classes. You can define your own similar collections in the .outlawed
file (to be loaded from an external data file preferably, if more than a few
values) and then reference CONST_NAME as :const_name in your outlaw anti-
patterns as above. Presently mutliple references to the same collection
are independent, but if there is interest special handling could be added to
also match specific instances of a collection much like the symbol handling.
Outlaw currently ignores whitespace, parentheses and new lines, though I have
ideas to change this behavior dynamically in certain laws if desired.
Execute outlaw on your project from the root directory by simply entering
"outlaw" into your shell, or specify another directory to run
on with "outlaw /path/to/dir"
Before using outlaw in a project you should create a .outlawed file which
Outlaw will read laws from.
Users can create defined collections like :core_class by creating new constants
called, e.g. CORE_CLASS within the "module Outlaw" namespace which are
defined as arrays of string names to match in example code the same
way :core_class is used above.
It comes with an example file (.outlawed.example) which is included in the
gem and will be loaded if no .outlawed file is found in current directory or
home directory, and will warn you to provide a real file (and provide
location of the sample file in your system from the gem installation).
###Planned features (unimplemented):
*Customize sensitivty , for instance whitespace is currently ignored, but
could enforce style conventions with some whitespace sensitive laws.
Also ignores parens, which might be required or prohibited in some
context.
*Specify AST-nodes of interest, and within them allow arbitrary amounts of code with
a :disjoint_code_seperator token.
*Specify AST-nodes of interest, and within them allow arbitrary amounts of
code with a :disjoint_code_seperator token.
This should allow, for instance, something like the following, which is not currently possible to outlaw in a useful way:
This should allow, for instance, something like the following, which is not
currently possible to outlaw in a useful way:
outlaw ":conditional_branch
outlaw ":conditional_branch
unless
:disjoint_code_seperator
else",
"If you write unless else and think it makes sense then you are a cylon"
"If you write unless else and think it makes sense then you are a
cylon"
*Integrate Rails Best Practices gem, Reek gem, and perhaps others, so that individual issue
detections they provide can be added as laws in the outlawed file while

0 comments on commit d811cf5

Please sign in to comment.