Skip to content
This repository
Browse code

updating readme for better documentation

  • Loading branch information...
commit d811cf59cefe0296a041c95ba8794c2f7a9b9bc3 1 parent 5d828af
Brian Glusman authored

Showing 1 changed file with 63 additions and 25 deletions. Show diff stats Hide diff stats

  1. +63 25 README.md
88 README.md
Source Rendered
... ... @@ -1,55 +1,93 @@
1 1 #Outlaw
2 2
3 3 ##Keep bad code out of your projects. Your idea of bad code, no one elses.
  4 +##Because good documentation should be executable.
4 5
5 6 ###NOTE: Outlaw can evaluate any version ruby code, *BUT* it runs on only 1.9 -- set your system ruby to 1.9 to use
6 7
7 8 ### Part of MendicantUniversity.org S10 class, personal project.
8   -From the included .outlawed.example file for custom rule definition:
9 9
10   - outlaw "@@", "Class variables are evil"
11   - outlaw "protected", "use private or public, protected is silly in ruby"
12   - outlaw "module :token end", "nest modules to avoid empty module declarations"
13   - outlaw "eval", "never eval, rarely class_eval or instance_eval, but never eval"
  10 +The current version of outlaw takes a user provided configuration file
  11 +(currently named simply '.outlawed' in the project directory or user's home
  12 +directory) and parses a series of method calls to the outlaw method (defined
  13 +within the Outlaw module namespace, but module_eval'd so you don't need to
  14 +namespace the file). You can also define constants in your .outlawed file as
  15 +collections of strings for use in your laws, but that will be addressed below.
14 16
15   -Execute outlaw on your project from the root directory by simply entering "outlaw", or specify another directory to run
16   -on with "outlaw /path/to/dir"
  17 +Each call to the outlaw method consists of two string arguments, the first an
  18 +anti-pattern you wish to prohibit usage of in one or more projects, and the
  19 +second an explanation to be provided when the anti-pattern is detected.
  20 +
  21 +### Syntax for law creation:
  22 +
  23 +Some examples are include in the .outlawed.example file for reference:
  24 +
  25 + outlaw "@@", "Class variables are evil"
17 26
18   -Before using outlaw in a project you should create a .outlawed file which Outlaw will read laws from.
19   -It comes with an example file (.outlawed.example) which is included in the gem and will be loaded if no .outlawed
20   -file is found in current directory or home directory, and will warn you to provide a real file (and provide location
21   -of the sample file in your system from the gem installation).
  27 + outlaw "protected", "use private or public, protected
  28 + is silly in ruby"
22 29
23   -### Syntax for DSL:
  30 + outlaw "eval", "never eval, rarely class_eval or
  31 + instance_eval, but never eval"
24 32
25   - A defined collection exists for core classes, such that
  33 + outlaw "module :token end", "nest modules to avoid empty module
  34 + declarations"
26 35
27   - outlaw "class :symbol < :core_class",
28   - "core classes implemented in c, can cause bad mojo"
  36 + outlaw "class :symbol < :core_class", "core classes implemented in c,
  37 + can cause bad mojo"
29 38
30   - will outlaw subclassing from any core class
  39 +The first three examples are actual ruby keywords and features being outlawed
  40 +and may not require much explanation except to indicate that they are detected
  41 +via regular expression matches constructed from the strings, and attempt to use
  42 +word boundaries intelligently so that eval is detected but not module_eval.
  43 +
  44 +The bottom two examples above use ruby symbols as standin variable or
  45 +parameter names for identifiers that are matched at runtime with local
  46 +variables, instance variables, class names and constants that may appear
  47 +within the ruby program being analyzed. Here, :symbol can be any ruby symbol
  48 +if it appears only once, though if used multiple times it will only match the
  49 +the same identifier on subsequent usage. :core_class as used above is a
  50 +special case where Outlaw has internally defined a constant called CORE_CLASS
  51 +as a collection of string objects each containing the name of one of ruby's
  52 +core classes. You can define your own similar collections in the .outlawed
  53 +file (to be loaded from an external data file preferably, if more than a few
  54 +values) and then reference CONST_NAME as :const_name in your outlaw anti-
  55 +patterns as above. Presently mutliple references to the same collection
  56 +are independent, but if there is interest special handling could be added to
  57 +also match specific instances of a collection much like the symbol handling.
  58 +
  59 +Outlaw currently ignores whitespace, parentheses and new lines, though I have
  60 +ideas to change this behavior dynamically in certain laws if desired.
  61 +
  62 +Execute outlaw on your project from the root directory by simply entering
  63 +"outlaw" into your shell, or specify another directory to run
  64 +on with "outlaw /path/to/dir"
31 65
  66 +Before using outlaw in a project you should create a .outlawed file which
  67 +Outlaw will read laws from.
32 68
33   -Users can create defined collections like :core_class by creating new constants
34   -called, e.g. CORE_CLASS within the "module Outlaw" namespace which are
35   -defined as arrays of string names to match in example code the same
36   -way :core_class is used above.
  69 +It comes with an example file (.outlawed.example) which is included in the
  70 +gem and will be loaded if no .outlawed file is found in current directory or
  71 +home directory, and will warn you to provide a real file (and provide
  72 +location of the sample file in your system from the gem installation).
37 73
38 74 ###Planned features (unimplemented):
39 75 *Customize sensitivty , for instance whitespace is currently ignored, but
40 76 could enforce style conventions with some whitespace sensitive laws.
41 77 Also ignores parens, which might be required or prohibited in some
42 78 context.
43   -*Specify AST-nodes of interest, and within them allow arbitrary amounts of code with
44   -a :disjoint_code_seperator token.
  79 +*Specify AST-nodes of interest, and within them allow arbitrary amounts of
  80 +code with a :disjoint_code_seperator token.
45 81
46   -This should allow, for instance, something like the following, which is not currently possible to outlaw in a useful way:
  82 +This should allow, for instance, something like the following, which is not
  83 +currently possible to outlaw in a useful way:
47 84
48   -outlaw ":conditional_branch
  85 + outlaw ":conditional_branch
49 86 unless
50 87 :disjoint_code_seperator
51 88 else",
52   - "If you write unless else and think it makes sense then you are a cylon"
  89 + "If you write unless else and think it makes sense then you are a
  90 + cylon"
53 91
54 92 *Integrate Rails Best Practices gem, Reek gem, and perhaps others, so that individual issue
55 93 detections they provide can be added as laws in the outlawed file while

0 comments on commit d811cf5

Please sign in to comment.
Something went wrong with that request. Please try again.