mago 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 069e929006e5cab92bbebe28e6eca37476916809
-  data.tar.gz: 44440710c44bbffecc85f180bbbe96869e03e2b5
+  metadata.gz: d37b226405e663e2097987a53497f9be0203feb6
+  data.tar.gz: 3fa69b1d2749e3d9cf2f86574a85f11318ddc255
 SHA512:
-  metadata.gz: cebe0d24c4832b0a43669da316276faf4fc5204a1e1a3f79fc37ee7403a9ffd0bea4be21d0f9965bc58f30545a759f9aeb88813fa03ab952866e62f5239e7579
-  data.tar.gz: 1e7f38b8af6c6ccbc10fe85bb117f670ed5899880a2b2b69a7e3773aec2d4397d146bd5d6575f88fc2474da5f4b6ba7a3a76526d7e6f5915d37f8a489c3f35cd
+  metadata.gz: ef14e1c8a0a321b2b70ba99e29883e58850d5edb208bcb8f3921b83910e3259d2577714c18de06eb6724785f940f008f0d9d9800a58660654d78cb48799a578d
+  data.tar.gz: 882f0ca028c606039c71e5893a570be4fdc2bc1d147f1fa0a60989564a833a9bf9f36ce07e4ea1c93252e002e68c59d9da7628b3dda05bf22cdb2019715bb2bc

data/README.markdown

@@ -9,7 +9,7 @@ Tool to detect magic numbers in ruby code.
 gem install mago
 ```
 
-## Usage example
+## Usage
 
 Ruby code in `square.rb`:
 ```ruby
@@ -26,7 +26,7 @@ mago ./square.rb
 ./square.rb:4 detected magic number 2
 ```
 
-### Ignoring specific numbers
+### Ignore specific numbers
 
 Use `--ignore` or `-i` option to ignore specific numbers. By default 0 and 1 are ignored.
 
@@ -35,14 +35,24 @@ mago -i 2,3 ./square.rb
 ./square.rb:3 detected magic number 5
 ```
 
+### Show source code
+
+Use `--source` or `-s` option to show line of source code where magic number was found.
+
+```sh
+mago -s ./square.rb
+./square.rb:3| r = 5
+./square.rb:4| square = P * r ** 2
+```
+
 ### Color output
 
 Use `--color` or `-c` option to colorize output.
 
 ## TODO
 
-* Support for `--show-source`(`-s`) option to show line of source code with magic number.
-* Support for `--expl-var` (`-e`) option to ignore explaining variables.
+* Add intro about magic numbers to README.
+* Create GIF with some famous probject to show how it works.
 
 ## Copyright
 

data/lib/mago.rb

@@ -6,8 +6,8 @@ require 'mago/ruby_file'
 require 'mago/sexp_processor'
 require 'mago/detector'
 require 'mago/report'
-require 'mago/file_finder'
 require 'mago/version'
 
+# Magic numbers detector for ruby source code.
 module Mago
 end

data/lib/mago/cli.rb

@@ -1,8 +1,12 @@
 require 'mago/cli/colorize'
-require 'mago/cli/command'
+require 'mago/cli/config'
 require 'mago/cli/formatter'
+require 'mago/cli/source_formatter'
+require 'mago/cli/file_finder'
+require 'mago/cli/command'
 
 module Mago
+  # Namespace for command line stuff.
   module Cli
 
   end

data/lib/mago/cli/colorize.rb

@@ -1,22 +1,33 @@
 module Mago
   module Cli
+    # Provides methods to colorize strings with ANSI colors.
     module Colorize
+      # Colorize text using a passed code
+      #
+      # @param text [String]
+      # @param color_code [Integer]
+      #
+      # @return [String] colorized text
       def colorize(text, color_code)
         "\e[#{color_code}m#{text}\e[0m"
       end
 
+      # :nodoc:
       def red(text)
         colorize(text, 31)
       end
 
+      # :nodoc:
       def green(text)
         colorize(text, 32)
       end
 
+      # :nodoc:
       def yellow(text)
         colorize(text, 33)
       end
 
+      # :nodoc:
       def pink(text)
         colorize(text, 35)
       end

data/lib/mago/cli/command.rb

@@ -1,43 +1,39 @@
 module Mago
   module Cli
-    class Config
-      attr_accessor :ignore, :files, :color
-
-      def initialize
-        @files = []
-        @color = false
-      end
-    end
-
+    # CLI command.
+    #
+    # @example
+    #   command = Mago::Cli::Command('-s', '-i', '0,1,2', './lib')
+    #   command.execute
     class Command
-      def initialize(args)
-        @args = args
-        @config = Config.new
+      # @param arguments [Array<String>] command arguments
+      def initialize(arguments)
+        @arguments = arguments
+        @config    = Config.new
       end
 
+      # Execute command.
+      #
+      # @return [void]
       def execute
-        parse_args
+        parse_arguments
         run
       end
 
-      def parse_args
-        while arg = @args.shift
+
+
+      private
+
+      # Parse arguments and build config.
+      #
+      # @return [void]
+      def parse_arguments
+        while arg = @arguments.shift
           case arg
-          when '--help', '-h'
-            show_help
-            exit 0
-          when '--version', '-v'
-            show_version
-            exit 0
-          when '--ignore', '-i'
-            val = @args.shift
-            abort "--ignore option requires comma separated numbers" unless val =~ /^[0-9]/
-            nums = val.to_s.split(',').map{ |n| n.include?('.') ? n.to_f : n.to_i }
-            @config.ignore = nums
-          when '--color', '--colour', '-c'
-            @config.color = true
+          when /^--/
+            process_option(arg)
           when /^-/
-            abort("Unknown option `#{arg}'")
+            arg[1..-1].each_char {|opt| process_option("-#{opt}") }
           else
             @config.files << arg
           end
@@ -46,36 +42,84 @@ module Mago
         @config.files << '.' if @config.files.empty?
       end
 
+      # Process option.
+      #
+      # @param option [String] option
+      #
+      # @return [void]
+      def process_option(option)
+        case option
+        when '--help', '-h'
+          print_help
+          exit 0
+        when '--version', '-v'
+          print_version
+          exit 0
+        when '--ignore', '-i'
+          val = @arguments.shift
+          abort "#{option} option requires comma separated numbers" unless val =~ /^[0-9]/
+          nums = val.to_s.split(',').map{ |n| n.include?('.') ? n.to_f : n.to_i }
+          @config.ignore = nums
+        when '--color', '--colour', '-c'
+          @config.color = true
+        when '--source', '-s'
+          @config.source = true
+        else /^-/
+          abort("Unknown option `#{option}'")
+        end
+      end
 
-      private
-
+      # Run command using settings from config.
+      #
+      # @return [void]
       def run
-        ruby_files = Mago::FileFinder.new(@config.files).find
+        ruby_files = Mago::Cli::FileFinder.new(@config.files).find
         detector   = Mago::Detector.new(ruby_files, :ignore => @config.ignore)
         report     = detector.run
-        formatter  = Mago::Cli::Formatter.new(report, :color => @config.color)
+
+        formatter_class = @config.source ? SourceFormatter : Formatter
+        formatter  = formatter_class.new(report, :color => @config.color)
 
         puts formatter.format
       end
 
-      def show_help
-        puts "Magic numbers detector for Ruby programming language.\n\n" \
-             "  Syntax:\n" \
-             "    mago [OPTIONS] [FILES]\n\n" \
-             "  Options:\n" \
-             "    -i, --ignore NUMS\n" \
-             "        Comma separated numbers, which will be ignored. Default is 0,1\n\n" \
-             "  Usage:\n" \
-             "    mago                     # inspect ruby files in current directory\n" \
-             "    mago ./my_code.rb        # inspect ./my_code.rb file\n" \
-             "    mago ./my_project/       # inspect ruby files in ./my_project/"
+      # Show help message.
+      #
+      # @return [void]
+      def print_help
+        puts <<-HELP
+Magic numbers detector for Ruby programming language.
+
+  Syntax:
+    mago [OPTIONS] [FILES]
+
+  Options:
+    -i, --ignore NUMS
+        Comma separated numbers, which will be ignored. Default is 0,1
+
+    -c, --color
+        Colorize output
+
+    -s, --source
+        Show a line of source code with a magic number
+
+  Usage:
+    mago
+    mago -i 2,5 ./my_code.rb
+    mago -cs ./my_project/
+        HELP
       end
 
 
-      def show_version
-        puts "Mago #{Mago::VERSION}\n" \
-             "Tool to detect magic numbers in ruby files.\n" \
-             "Copyright (c) 2013 Sergey Potapov"
+      # Show program version.
+      #
+      # @return [void]
+      def print_version
+        puts <<-TEXT
+Mago #{Mago::VERSION}
+Tool to detect magic numbers in ruby files.
+Copyright (c) 2013 Sergey Potapov
+        TEXT
       end
 
     end

data/lib/mago/cli/config.rb

@@ -0,0 +1,26 @@
+module Mago
+  module Cli
+    # Command config. Build by option parser and is used to execute command.
+    class Config
+      # @attribute files [Array<String>] ruby files to process
+      attr_accessor :files
+
+      # @attribute ignore [Array<Numeric>, nil] numbers which must be ignored
+      attr_accessor :ignore
+
+      # @attribute color [Boolean] whether colorize output or not
+      attr_accessor :color
+
+      # attribute source [Boolean] whether show lines of source
+      #   code with magic number or not
+      attr_accessor :source
+
+      def initialize
+        @files  = []
+        @color  = false
+        @source = false
+        @ignore = nil
+      end
+    end
+  end
+end

data/lib/mago/cli/file_finder.rb

@@ -0,0 +1,29 @@
+module Mago
+  module Cli
+    # Finds ruby files in local file system.
+    class FileFinder
+      # @param paths [Array<String>] files and directories
+      def initialize(paths)
+        @paths = paths
+      end
+
+      # Find ruby files.
+      #
+      # @return [Array<String>] ruby files
+      def find
+        ruby_files = []
+
+        @paths.each do |path|
+          if File.directory?(path)
+            pattern = File.join(path, '/**/*.rb')
+            ruby_files.concat(Dir[pattern])
+          else
+            ruby_files << path
+          end
+        end
+
+        ruby_files
+      end
+    end
+  end
+end

data/lib/mago/cli/formatter.rb

@@ -1,14 +1,21 @@
 module Mago
   module Cli
+    # Formats report to be printed
     class Formatter
       include Colorize
 
+      # @param report [Mago::Report]
+      # @param opts [Hash]
+      #
+      # @option opts :color [Boolean] whether colorize output or no
       def initialize(report, opts = {})
         @report = report
-
-        @color = opts[:color]
+        @color  = opts[:color]
       end
 
+      # Format report.
+      #
+      # @return [String] formated report
       def format
         out = ''
 
@@ -23,6 +30,15 @@ module Mago
         out
       end
 
+
+      private
+
+      # Format file with magic numbers.
+      #
+      # @param file [Mago::File]
+      # @param out [String] string to write result
+      #
+      # @return [void]
       def format_file(file, out)
         file.magic_numbers.each do |num|
           if @color
@@ -39,6 +55,12 @@ module Mago
         end
       end
 
+      # Format error.
+      #
+      # @param error [String] error message
+      # @param out [String] string to write result
+      #
+      # @return [void]
       def format_error(error, out)
         out << "ERROR: %s\n" % [error]
       end

data/lib/mago/cli/source_formatter.rb

@@ -0,0 +1,36 @@
+module Mago
+  module Cli
+    # Formats report showing lines of source code where magic number was detected.
+    class SourceFormatter < Formatter
+      # :nodoc:
+      def format_file(file, out)
+        source_lines = File.readlines(file.path)
+
+        file.magic_numbers.each do |num|
+          if @color
+            line = yellow(num.line)
+            path = pink(file.path)
+            source_line = make_red(source_lines[num.line-1], num.value.to_s)
+          else
+            line = num.line
+            path = file.path
+            source_line = source_lines[num.line-1]
+          end
+
+          out << "#{path}:#{line}| #{source_line}"
+        end
+      end
+
+      # Find a substing in a string and make it red.
+      #
+      # @param str [String]
+      # @param substr [String]
+      #
+      # @return [String] string with red substring
+      def make_red(str, substr)
+        chunks = str.split(substr)
+        chunks.join(red(substr))
+      end
+    end
+  end
+end

data/lib/mago/detector.rb

@@ -1,14 +1,26 @@
 module Mago
+  # Magic numbers detector.
+  #
+  # @example
+  #   detector = Mago::Detector.new('./Rakefile', './lib')
+  #   detector.run # => #<Mago::Report ...>
   class Detector
     # Numbers which are ignored by default
     DEFAULT_IGNORE = [0, 1]
 
+    # @param file_paths [String] ruby files
+    # @param options [Hash]
+    #
+    # @option options :ignore [Array<Numeric>] numbers which must be ignored
     def initialize(file_paths = [], options = {})
       @file_paths = file_paths
       @report = Report.new
       @ignore = options[:ignore] || DEFAULT_IGNORE
     end
 
+    # Process files and build a report.
+    #
+    # @return [Mago::Report]
     def run
       @file_paths.each do |path|
         process_file(path)
@@ -16,14 +28,21 @@ module Mago
       @report
     end
 
+
+    private
+
+    # Process a file and add a result to the report.
+    #
+    # @param path [String]
+    #
+    # @return [void]
     def process_file(path)
-      code = File.read(path)
+      code      = File.read(path)
       sexp_node = RubyParser.new.parse(code)
-
-      file = Mago::RubyFile.new(path)
+      file      = Mago::RubyFile.new(path)
 
       sexp_processor = Mago::SexpProcessor.new(file, @ignore)
-      sexp_processor.process sexp_node
+      sexp_processor.process(sexp_node)
 
       @report.files << file
     rescue Errno::ENOENT => err

data/lib/mago/magic_number.rb

@@ -1,14 +1,16 @@
 module Mago
+  # Magic number. Contains value of number and line number of source code.
   class MagicNumber
+    # @attribute value [Numeric] magic number itself
     attr_accessor :value
+
+    # @attribute line [Integer] line of source file where the magic number is located
     attr_accessor :line
-    attr_accessor :file
 
+    # @param attrs [Hash]
     def initialize(attrs = {})
-      attrs.each do |attr, value|
-        send("#{attr}=", value)
-      end
+      @value = attrs[:value]
+      @line  = attrs[:line]
     end
-
   end
 end

data/lib/mago/report.rb

@@ -1,9 +1,14 @@
 module Mago
+  # Work report built by {Mago::Detector}.
   class Report
-    attr_reader :files, :errors
+    # @attribute files [Array<Mago::File>]
+    attr_reader :files
+
+    # @attribute errors [Array<String>]
+    attr_reader :errors
 
     def initialize
-      @files = []
+      @files  = []
       @errors = []
     end
   end

data/lib/mago/ruby_file.rb

@@ -1,7 +1,13 @@
 module Mago
+  # Represents a ruby file with magic numbers.
   class RubyFile
-    attr_reader :path, :magic_numbers
+    # @attribute path [String] file path
+    attr_reader :path
 
+    # @attribute magic_numbers [Array<Mago::MagicNumber>] magic numbers
+    attr_reader :magic_numbers
+
+    # @param path [String] file path
     def initialize(path)
       @path = path
       @magic_numbers = []

data/lib/mago/sexp_processor.rb

@@ -1,6 +1,9 @@
 module Mago
+  # The core of Mago.
+  # Iterates through AST returned by RubyParser and finds numeric literals.
   class SexpProcessor < ::SexpProcessor
-
+    # @param file [Mago::File] file where found numbers will be stored
+    # @param ignore [Array<Numeric>] array of numbers to ignore
     def initialize(file, ignore = [])
       super()
       self.warn_on_default = false
@@ -10,10 +13,22 @@ module Mago
       @ignore = ignore
     end
 
+    # Process constant declaration node. It's the case where we
+    # numeric literals, because they are not magic numbers.
+    #
+    # @param exp [Sexp]
+    #
+    # @return [Sexp]
     def process_cdecl(exp)
       process_default(exp)
     end
 
+    # Process literal node. If a literal is a number and add it to the
+    # collection of magic numbers.
+    #
+    # @param exp [Sexp]
+    #
+    # @return [Sexp]
     def process_lit(exp)
       exp.shift
       value = exp.shift
@@ -25,13 +40,17 @@ module Mago
       s()
     end
 
+    # Handler for all other nodes. They doesn't interest us, so we just skip.
+    #
+    # @param exp [Sexp]
+    #
+    # @return [Sexp]
     def process_default(exp)
       until exp.size == 0
         exp.shift
       end
       s()
     end
-
   end
 end
 

data/lib/mago/version.rb

@@ -1,3 +1,4 @@
 module Mago
-  VERSION = '0.0.4'
+  # :nodoc:
+  VERSION = '0.0.5'
 end

data/spec/integration/cli_spec.rb

@@ -40,7 +40,7 @@ describe 'mago command' do
       end
     end
 
-    describe '--ignore option' do
+    describe '--ignore' do
       it 'should ignore passed numbers' do
         expected = "./square.rb:3 detected magic number 5\n"\
                    "./square.rb:3 detected magic number 1\n"
@@ -50,4 +50,14 @@ describe 'mago command' do
       end
     end
   end
+
+  describe '--source' do
+    it 'should show lines of source code with magic numbers' do
+      expected = "./square.rb:3| radius = 5 - 1\n" \
+                 "./square.rb:4| square = P * radius ** 2\n"
+
+      mago('--source ./square.rb').should == expected
+      mago('-s ./square.rb').should == expected
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mago
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Sergey Potapov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-10 00:00:00.000000000 Z
+date: 2013-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_parser
@@ -50,13 +50,16 @@ extra_rdoc_files:
 files:
 - ./lib/mago.rb
 - ./lib/mago/report.rb
-- ./lib/mago/file_finder.rb
 - ./lib/mago/version.rb
 - ./lib/mago/ruby_file.rb
 - ./lib/mago/sexp_processor.rb
 - ./lib/mago/detector.rb
 - ./lib/mago/cli.rb
+- ./lib/mago/cli/file_finder.rb
 - ./lib/mago/cli/formatter.rb
+- ./lib/mago/cli/config.rb
+- ./lib/mago/cli/option_parser.rb
+- ./lib/mago/cli/source_formatter.rb
 - ./lib/mago/cli/command.rb
 - ./lib/mago/cli/colorize.rb
 - ./lib/mago/magic_number.rb

data/lib/mago/file_finder.rb

@@ -1,22 +0,0 @@
-module Mago
-  class FileFinder
-    def initialize(paths)
-      @paths = paths
-    end
-
-    def find
-      ruby_files = []
-
-      @paths.each do |path|
-        if File.directory?(path)
-          pattern = File.join(path, '/**/*.rb')
-          ruby_files.concat(Dir[pattern])
-        else
-          ruby_files << path
-        end
-      end
-
-      ruby_files
-    end
-  end
-end