Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 138 lines (96 sloc) 5.002 kB
ffe03d2 @YorickPeterse Cleaned up bits of the documentation.
authored
1 # ruby-lint
431cd34 @YorickPeterse Added a basic README.
authored
2
f00d3a8 @YorickPeterse Expanded the README a bit more.
authored
3 ruby-lint is a static code analysis tool for Ruby. It is inspired by tools such
4 as jshint, flake8 and similar tools. ruby-lint primarily focuses on logic
5 related errors such as the use of non existing variables instead of focusing on
6 semantics (e.g. the amount of characters per line).
7
8 The features of ruby-lint include but are not limited to the detection of
9 unused variables, the use of undefined methods and method calls with invalid
10 argument amounts and more. More in-depth analysis will be added over time.
11
12 The aim of ruby-lint is to provide analysis that is as accurate as possible.
13 However, due to the dynamic nature of Ruby and the sheer amount of meta-magic
14 in third-party code there will at times be false positives. Analysis can be
15 improved by documenting your code using [YARD][yard], in particular the
16 `@param` and `@return` tags are used by ruby-lint to obtain extra information
17 when processing methods.
431cd34 @YorickPeterse Added a basic README.
authored
18
19 ## Requirements
20
f9712e8 @YorickPeterse Updated the README.
authored
21 * a Ruby implementation running 1.9 or newer
ffe03d2 @YorickPeterse Cleaned up bits of the documentation.
authored
22 * a Unix based Operating System
431cd34 @YorickPeterse Added a basic README.
authored
23
f9712e8 @YorickPeterse Updated the README.
authored
24 The following Ruby implementations/versions are officially supported:
25
629957a @YorickPeterse Mention the exact MRI versions that are supported.
authored
26 * MRI 1.9.3, 2.0 or 2.1
4a595e6 @YorickPeterse Updated notes on supported Rubies.
authored
27 * Rubinius 2.0 and newer
28 * Jruby 1.7 and newer
f9712e8 @YorickPeterse Updated the README.
authored
29
30 Ruby implementations running a 1.8 based version of Ruby are not supported.
31
431cd34 @YorickPeterse Added a basic README.
authored
32 ## Installation
33
ffe03d2 @YorickPeterse Cleaned up bits of the documentation.
authored
34 The easiest way to install ruby-lint is to install it from RubyGems:
431cd34 @YorickPeterse Added a basic README.
authored
35
5d0b630 @YorickPeterse Fixed code formatting for Kramdown.
authored
36 gem install ruby-lint
431cd34 @YorickPeterse Added a basic README.
authored
37
ffe03d2 @YorickPeterse Cleaned up bits of the documentation.
authored
38 If you prefer to install (and build) ruby-lint from the source code you can do
39 so as following:
40
5d0b630 @YorickPeterse Fixed code formatting for Kramdown.
authored
41 git clone git://github.com/YorickPeterse/ruby-lint.git
42 cd ruby-lint
43 bundle install # you can also install the dependencies manually
44 rake build
ffe03d2 @YorickPeterse Cleaned up bits of the documentation.
authored
45
46 This builds a new version of the Gem and saves it in the pkg/ directory.
8076634 @YorickPeterse Renamed the Gem and updated the README.
authored
47
f45c805 @YorickPeterse Usage and design in the README.
authored
48 ## Usage
49
ffe03d2 @YorickPeterse Cleaned up bits of the documentation.
authored
50 Using ruby-lint from the CLI is very easy. To analyze a set of files
51 you run the following:
52
5d0b630 @YorickPeterse Fixed code formatting for Kramdown.
authored
53 ruby-lint file1.rb file2.rb
ffe03d2 @YorickPeterse Cleaned up bits of the documentation.
authored
54
55 For more information specify either the `-h` or `--help` option.
56
83431bd @YorickPeterse Example output in the README.
authored
57 ## Example
58
59 Given the following code:
60
61 class Person
62 def initialize(name)
63 # oops, not setting @name
64 end
65
66 def greet
67 return "Hello, #{@name}"
68 end
69 end
70
71 user = Person.new('Alice')
72 greeting = user.greet
73
74 user.greet(:foo)
75
76 Analysing this file using ruby-lint (with the default settings) would result in
77 the following output:
78
e96b649 @YorickPeterse Start column numbers from 1 opposed to 0.
authored
79 test.rb: error: line 7, column 22: undefined instance variable @name
80 test.rb: warning: line 12, column 1: unused local variable greeting
81 test.rb: error: line 14, column 1: wrong number of arguments (expected 0 but got 1)
83431bd @YorickPeterse Example output in the README.
authored
82
c939c2c @bbatsov Correct RuboCop name references in the README
bbatsov authored
83 ## ruby-lint versus RuboCop
d2a6d11 @YorickPeterse Section about ruby-lint vs Rubocop.
authored
84
85 A question commonly asked is what purpose ruby-lint serves compared to other
c939c2c @bbatsov Correct RuboCop name references in the README
bbatsov authored
86 tools such as [RuboCop][rubocop]. After all, upon first sight the two tools
d2a6d11 @YorickPeterse Section about ruby-lint vs Rubocop.
authored
87 look pretty similar.
88
c939c2c @bbatsov Correct RuboCop name references in the README
bbatsov authored
89 The big difference between ruby-lint and RuboCop is that ruby-lint focuses
d2a6d11 @YorickPeterse Section about ruby-lint vs Rubocop.
authored
90 primarily on technical problems such as the use of undefined methods/variables,
c939c2c @bbatsov Correct RuboCop name references in the README
bbatsov authored
91 unused variables/method arguments and more. RuboCop on the other hand focuses
d2a6d11 @YorickPeterse Section about ruby-lint vs Rubocop.
authored
92 mostly on style related issues based on a community driven Ruby style guide.
93 This means that it will for example warn you about methods written using
94 camelCase and method bodies that are considered to be too long.
95
c939c2c @bbatsov Correct RuboCop name references in the README
bbatsov authored
96 Personally I have little interest in adding style related analysis as RuboCop
d2a6d11 @YorickPeterse Section about ruby-lint vs Rubocop.
authored
97 already does that and in my opinion does a far better job at it. I also simply
98 think it's too boring to write analysis like this. Having said that, ruby-lint
99 has some basic style related analysis (e.g. the use of `BEGIN`) but this mostly
100 serves as a simple example on how to write analysis code.
101
102 In the end it depends on what your needs are. If you have a team that's having
c939c2c @bbatsov Correct RuboCop name references in the README
bbatsov authored
103 trouble following a consistent coding style then RuboCop is probably the right
d2a6d11 @YorickPeterse Section about ruby-lint vs Rubocop.
authored
104 tool for the job. On the other hand, if you're trying to debug a nasty bug then
105 ruby-lint will most likely be more useful.
106
0005207 @YorickPeterse Moved "Security" to the bottom of the README.
authored
107 ## Security
108
109 As a basic form of security ruby-lint provides a set of SHA512 checksums for
110 every Gem release. These checksums can be found in the `checksum/` directory.
111 Although these checksums do not prevent malicious users from tampering with a
112 built Gem they can be used for basic integrity verification purposes.
113
114 The checksum of a file can be checked using the `sha512sum` command. For
115 example:
116
117 $ sha512sum pkg/ruby-lint-0.9.1.gem
118 10a51f27c455e5743fff7fefe29512cff20116b805bec148e09d4bade1727e3beab7f7f9ee97b020d290773edcb7bd1685858ccad0bbd1a35cc0282c00c760c6 pkg/ruby-lint-0.9.1.gem
119
120 In the past Gems were also signed using PGP, this is no longer the case.
121
ffe03d2 @YorickPeterse Cleaned up bits of the documentation.
authored
122 ## Documentation
123
7fd270a @YorickPeterse Corrected YARD link to the contributing guide
authored
124 * {file:CONTRIBUTING Contributing}
5cefc00 @YorickPeterse Improved existing and added new documentation.
authored
125 * {file:architecture Architecture}
126 * {file:code\_analysis Code Analysis}
7e8ec80 @YorickPeterse Documentation about configuring ruby-lint.
authored
127 * {file:configuration Configuration}
7c5df09 @YorickPeterse Added definitions link to the README.
authored
128 * {file:definitions Definitions}
5cefc00 @YorickPeterse Improved existing and added new documentation.
authored
129
431cd34 @YorickPeterse Added a basic README.
authored
130 ## License
131
f1c3aa3 @YorickPeterse Change license from MIT to MPL 2.0
authored
132 All source code in this repository is subject to the terms of the Mozilla Public
133 License, version 2.0 unless stated otherwise. A copy of this license can be
134 found the file "LICENSE" or at <https://www.mozilla.org/MPL/2.0/>.
0260da0 @YorickPeterse Small section about ruby-lint integration.
authored
135
d2a6d11 @YorickPeterse Section about ruby-lint vs Rubocop.
authored
136 [rubocop]: https://github.com/bbatsov/rubocop
f00d3a8 @YorickPeterse Expanded the README a bit more.
authored
137 [yard]: http://yardoc.org/
Something went wrong with that request. Please try again.