Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

updating readme for better documentation

  • Loading branch information...
commit d811cf59cefe0296a041c95ba8794c2f7a9b9bc3 1 parent 5d828af
bglusman authored
Showing with 63 additions and 25 deletions.
  1. +63 −25 README.md
View
88 README.md
@@ -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
Please sign in to comment.
Something went wrong with that request. Please try again.