ffast 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8acf0aec31914d5a9819f27ea422d293702e5f2bdeee36ae2d0bebcc8fc37b1
-  data.tar.gz: b0b5b4fcf5a2aa3e8138acd7ffc8ba0ce6799aabd7dd9d88fc51ae5f5e2308e9
+  metadata.gz: 49dd19ccc728102aba01cf03b72c5a4ce194e036bb7a489abee40bf488bd9821
+  data.tar.gz: 390d27be9261ea3333fe91d8561965ee9127965bf9fd1080134e08fba1914410
 SHA512:
-  metadata.gz: 4f6027ca24d6b1107957c7b09ffe7ccadf34c0121aabbfd8d0b374bf72801bcbf65f418fe4f78cefb18c4415c4315b5bdf01f11c6b60d3c73698afa4c6feebe0
-  data.tar.gz: 48fc1cf1b6d4c821cfd8910b0d1c24ece46194376d0c5d88023cfc29808e558956a3cdb589ae28a2f714ec0da380c041a92527201786bad05cbdd59090c130ca
+  metadata.gz: 4b73de237734f1799832f4f724b8a2ebf4dfcf116ade615469af205cb61204d777a4e9f05b8483e7647251f20daeef28edf61e72cec2172319b3b1261beee4b0
+  data.tar.gz: 330f5f62da86cfa18508f53c13231bcf55993e44d0bea4a9e4fd59427fae1d1aabd22a27b352adac78d6fe24a8abe1ebaf21ea33ef0c63dbafb7a4fdf3883e12

data/.projections.json

@@ -0,0 +1,4 @@
+{
+  "README.md": { "type": "readme" },
+  "lib/*.rb": { "type": "lib", "alternate": "spec/{}_spec.rb" }
+}

data/.rubocop.yml

@@ -40,3 +40,9 @@ RSpec/ExampleLength:
 
 RSpec/MultipleExpectations:
   Enabled: false
+
+RSpec/DescribedClass:
+  Enabled: false
+
+RSpec/ImplicitSubject:
+  Enabled: false

data/Fastfile

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Fastfile is loaded when you start an expression with a dot.
+#
+# You can introduce shortcuts or methods that can be embedded during your
+# command line interactions with fast.
+#
+# Let's say you'd like to show the version that is over the version file
+Fast.shortcut(:version, '(casgn nil VERSION (str _))', 'lib/fast/version.rb')
+
+# You can run shortcuts appending a dot to the shortcut.
+#   $ fast .version
+#   # lib/fast/version.rb:4
+#   VERSION = '0.1.2'
+
+# Simple shortcut that I used often to show how the expression parser works
+Fast.shortcut(:parser, '(class (const nil ExpressionParser)', 'lib/fast.rb')
+
+# Use `fast .bump_version` to rewrite the version file
+Fast.shortcut :bump_version do
+  rewrite_file('lib/fast/version.rb', '(casgn nil VERSION (str _)') do |node|
+    target = node.children.last.loc.expression
+    pieces = target.source.split('.').map(&:to_i)
+    pieces.reverse.each_with_index do |fragment, i|
+      if fragment < 9
+        pieces[-(i + 1)] = fragment + 1
+        break
+      else
+        pieces[-(i + 1)] = 0
+      end
+    end
+    replace(target, "'#{pieces.join('.')}'")
+  end
+end
+
+# And now a shortcut to print the other shortcuts :)
+Fast.shortcut :shortcuts do
+  report(shortcuts.keys)
+end

data/README.md

@@ -426,6 +426,64 @@ The CLI tool takes the following flags
 - Use `-c` to search from code example
 - Use `-s` to search similar code
 
+### Define your `Fastfile`
+
+Fastfile is loaded when you start a pattern with a `.`.
+
+You can also define extra Fastfile in your home dir or setting a directory with
+the `FAST_FILE_DIR`.
+
+You can define a `Fastfile` in any project with your custom shortcuts.
+
+```ruby
+Fast.shortcut(:version, '(casgn nil VERSION (str _))', 'lib/fast/version.rb')
+```
+
+Let's say you'd like to show the version of your library. Your normal
+command line will look like:
+
+    $ fast '(casgn nil VERSION)' lib/*/version.rb
+
+Or generalizing to search all constants in the version files:
+
+    $ fast casgn lib/*/version.rb
+
+It will output but the command is not very handy. In order to just say `fast .version`
+you can use the previous snipped in your `Fastfile`.
+
+And it will output something like this:
+
+```ruby
+# lib/fast/version.rb:4
+VERSION = '0.1.2'
+```
+
+Create shortcuts with blocks that are able to introduce custom coding in
+the scope of the `Fast` module
+
+To bump a new version of your library for example you can type `fast .bump_version`
+and add the snippet to your library fixing the filename.
+
+```ruby
+Fast.shortcut :bump_version do
+  rewrite_file('lib/fast/version.rb', '(casgn nil VERSION (str _)') do |node|
+    target = node.children.last.loc.expression
+    pieces = target.source.split(".").map(&:to_i)
+    pieces.reverse.each_with_index do |fragment,i|
+      if fragment < 9
+        pieces[-(i+1)] = fragment +1
+        break
+      else
+        pieces[-(i+1)] = 0
+      end
+    end
+    replace(target, "'#{pieces.join(".")}'")
+  end
+end
+```
+
+You can find more examples in the [Fastfile](./Fastfile).
+
 ### Fast with Pry
 
 You can use `--pry` to stop on a particular source node, and run Pry at that

data/docs/command_line.md

@@ -1,7 +1,7 @@
 # Command line
 
-It will also inject a executable named `fast` and you can use it to search and
-find code using the concept:
+When you install the ffast gem, it will also create an executable named `fast` 
+and you can use it to search and find code using the concept:
 
 ```
 $ fast '(def match?)' lib/fast.rb
@@ -87,9 +87,9 @@ The option `-s` build an expression from the code ignoring final values.
 object.method
 ```
 
-See also [Code Similarity](simi)ilarity_tutorial.md) tutorial.
+See also [Code Similarity](similarity_tutorial.md) tutorial.
 
-# `-c` to search from code example
+## `-c` to search from code example
 
 You can search  for the exact expression with `-c`
 
@@ -110,3 +110,105 @@ The generated expression from AST was:
   (send nil :object) :method)
 ```
 
+## Fastfile
+
+`Fastfile` will loaded when you start a pattern with a dot. It means the pattern
+will be a shortcut predefined on these Fastfiles.
+
+It will make three attempts to load `Fastfile` defined in `$PWD`, `$HOME` or
+checking if the `$FAST_FILE_DIR` is configured.
+
+You can define a `Fastfile` in any project with your custom shortcuts and easy
+check some code or run some task.
+
+
+## Shortcuts
+
+Create shortcuts with blocks enables introduce custom coding in
+the scope of the `Fast` module.
+
+## Example: Print library version.
+
+Let's say you'd like to show the version of your library. Your regular params
+in the command line will look like:
+
+    $ fast '(casgn nil VERSION)' lib/*/version.rb
+
+It will output but the command is not very handy. In order to just say `fast .version`
+you can use the previous snippet in your `Fastfile`.
+
+```ruby
+Fast.shortcut(:version, '(casgn nil VERSION)', 'lib/fast/version.rb')
+```
+
+And calling `fast .version` it will output something like this:
+
+```ruby
+# lib/fast/version.rb:4
+VERSION = '0.1.2'
+```
+
+We can also always override the files params passing some other target file
+like `fast .version lib/other/file.rb` and it will reuse the other arguments
+from command line but replace the target files.
+
+### Example: Bumping a gem version
+
+While releasing a new gem version, we always need to mechanical go through the
+`lib/<your_gem>/version.rb` and change the string value to bump the version
+of your library. It's pretty mechanical and here is an example that allow you 
+to simple use `fast .bump_version`:
+
+```ruby
+Fast.shortcut :bump_version do
+  rewrite_file('lib/fast/version.rb', '(casgn nil VERSION (str _)') do |node|
+    target = node.children.last.loc.expression
+    pieces = target.source.split(".").map(&:to_i)
+    pieces.reverse.each_with_index do |fragment,i|
+      if fragment < 9
+        pieces[-(i+1)] = fragment +1
+        break
+      else
+        pieces[-(i+1)] = 0
+      end
+    end
+    replace(target, "'#{pieces.join(".")}'")
+  end
+end
+```
+
+!!! note "Note the shortcut scope"
+    The shortcut calls `rewrite_file` from `Fast` scope as it use
+    `Fast.instance_exec` for shortcuts that yields blocks.
+
+Checking the version:
+
+```bash
+$ fast .version                                                                                                                                                                                                                            13:58:40
+# lib/fast/version.rb:4
+VERSION = '0.1.2'
+```
+Bumping the version:
+
+```bash
+$ fast .bump_version                                                                                                                                                                                                                       13:58:43
+```
+
+No output because we don't print anything. Checking version again:
+
+```bash
+$ fast .version                                                                                                                                                                                                                            13:58:54
+# lib/fast/version.rb:4
+VERSION = '0.1.3'
+```
+
+And now a fancy shortcut to report the other shortcuts :)
+
+```ruby
+Fast.shortcut :shortcuts do
+  report(shortcuts.keys)
+end
+```
+
+You can find these examples in the [Fastfile](https://github.com/jonatas/fast/tree/master/Fastfile).
+

data/docs/index.md

@@ -338,7 +338,7 @@ You can use `search_file` and pass the path for search for expressions inside
 files.
 
 ```ruby
-Fast.search_file('file.rb', expression)
+Fast.search_file(expression, 'file.rb')
 ```
 
 It's simple combination of `Fast.ast_from_file` with `Fast.search`.

data/lib/fast.rb

@@ -104,11 +104,12 @@ module Fast
     #   end # => variable_renamed = 1
     # @return [String] with the new source code after apply the replacement
     # @see Fast::Rewriter
-    def replace(ast, pattern, &replacement)
+    def replace(ast, pattern, source = nil, &replacement)
       buffer = Parser::Source::Buffer.new('replacement')
-      buffer.source = ast.loc.expression.source
+      buffer.source = source || ast.loc.expression.source
       to_replace = search(ast, pattern)
       types = to_replace.grep(Parser::AST::Node).map(&:type).uniq
+
       rewriter = Rewriter.new
       rewriter.buffer = buffer
       rewriter.search = pattern
@@ -117,18 +118,26 @@ module Fast
       rewriter.rewrite(buffer, ast)
     end
 
+    # Search with pattern directly on file
+    # @return [Array<Astrolabe::Node>] that matches the pattern
+    def search_file(pattern, file)
+      node = ast_from_file(file)
+      search node, pattern
+    end
+
     # Replaces the source of an {Fast#ast_from_file} with
     # and the same source if the pattern does not match.
     def replace_file(file, pattern, &replacement)
       ast = ast_from_file(file)
-      replace(ast, pattern, &replacement)
+      replace(ast, pattern, IO.read(file), &replacement)
     end
 
-    # Search with pattern directly on file
-    # @return [Array<Astrolabe::Node>] that matches the pattern
-    def search_file(pattern, file)
-      node = ast_from_file(file)
-      search node, pattern
+    # Combines #replace_file output overriding the file if the output is different
+    # from the original file content.
+    def rewrite_file(file, pattern, &replacement)
+      previous_content = IO.read(file)
+      content = replace_file(file, pattern, &replacement)
+      File.open(file, 'w+') { |f| f.puts content } if content != previous_content
     end
 
     # Capture elements from searches in files. Keep in mind you need to use `$`
@@ -244,8 +253,7 @@ module Fast
   #    ast = Fast.ast("a = 1")
   #    buffer = Parser::Source::Buffer.new('replacement')
   #    buffer.source = ast.loc.expression.source
-  #    rewriter = Rewriter.new
-  #    rewriter.buffer = buffer
+  #    rewriter = Rewriter.new buffer
   #    rewriter.search ='(lvasgn _ ...)'
   #    rewriter.replacement =  -> (node) { replace(node.location.name, 'variable_renamed') }
   #    rewriter.replace_on(:lvasgn)

data/lib/fast/cli.rb

@@ -6,7 +6,9 @@ require 'coderay'
 require 'optparse'
 require 'ostruct'
 
-# Command Line Interface powered by CodeRay
+# Fast is a powerful tool to search through the command line for specific Ruby code.
+# It defines #report and #highlight functions that can be used to pretty print
+# code and results from the search.
 module Fast
   module_function
 
@@ -27,18 +29,19 @@ module Fast
   # @param result [Astrolabe::Node]
   # @param show_sexp [Boolean] Show string expression instead of source
   # @param file [String] Show the file name and result line before content
+  # @param headless [Boolean] Skip printing the file name and line before content
   # @example
   #   Fast.highlight(Fast.search(...))
-  def report(result, show_sexp: nil, file: nil)
+  def report(result, show_sexp: false, file: nil, headless: false)
     if file
       line = result.loc.expression.line if result.is_a?(Parser::AST::Node)
-      puts Fast.highlight("# #{file}:#{line}")
+      puts(Fast.highlight("# #{file}:#{line}")) unless headless
     end
     puts Fast.highlight(result, show_sexp: show_sexp)
   end
 
   # Command Line Interface for Fast
-  class Cli
+  class Cli # rubocop:disable Metrics/ClassLength
     attr_reader :pattern, :show_sexp, :pry, :from_code, :similar, :help
 
     # rubocop:disable Metrics/MethodLength
@@ -54,6 +57,14 @@ module Fast
           @show_sexp = true
         end
 
+        opts.on('--captures', 'Print only captures of the patterns and skip node results') do
+          @captures = true
+        end
+
+        opts.on('--headless', 'Print results without the file name in the header') do
+          @headless = true
+        end
+
         opts.on('--pry', 'Jump into a pry session with results') do
           @pry = true
         end
@@ -80,23 +91,34 @@ module Fast
         opts.on_tail('-h', '--help', 'Show help. More at https://jonatas.github.io/fast') do
           @help = true
         end
+      end
 
-        @pattern, *@files = args.reject { |arg| arg.start_with? '-' }
+      if args.first&.start_with?('.') # shortcut! :tada:
+        shortcut = find_shortcut args.first[1..-1]
+        if shortcut.single_run_with_block?
+          shortcut.run
+          exit
+        else
+          args = args.one? ? shortcut.args : shortcut.merge_args(args[1..-1])
+        end
       end
+
+      @pattern, *@files = args.reject { |arg| arg.start_with? '-' }
+
       @opt.parse! args
 
-      @files = [*@files]
-      @files.reject! { |arg| arg.start_with?('-') }
+      @files = [*@files].reject { |arg| arg.start_with?('-') }
     end
-
     # rubocop:enable Metrics/MethodLength
     # rubocop:enable Metrics/AbcSize
 
+    # Run a new command line interface digesting the arguments
     def self.run!(argv)
       argv = argv.dup
       new(argv).run!
     end
 
+    # Show help or search for node patterns
     def run!
       if @help || @files.empty? && @pattern.nil?
         puts @opt.help
@@ -105,16 +127,21 @@ module Fast
       end
     end
 
+    # Create fast expression from node pattern using the command line
     def expression
       Fast.expression(@pattern)
     end
 
+    # Search for each file independent.
+    # If -d (debug option) is enabled, it will output details of each search.
+    # If capture option is enabled it will only print the captures, otherwise it
+    # prints all the results.
     def search_file(file)
       if debug_mode?
         Fast.debug { Fast.search_file(expression, file) }
       else
         begin
-          Fast.search_file(expression, file)
+          Fast.public_send(@captures ? :capture_file : :search_file, expression, file)
         rescue StandardError
           debug "Ops! An error occurred trying to search in #{expression.inspect} in #{file}", $ERROR_INFO, $ERROR_POSITION
           []
@@ -122,10 +149,14 @@ module Fast
       end
     end
 
+    # Search for the {#expression} on all the {#files}.
+    # It {#report} results if no options are passed.
+    # It binds pry if option "--pry" is passed.
     def search
       files.each do |file|
-        results = search_file(file)
-        next if results.nil? || results.empty?
+        results = [*search_file(file)]
+
+        next if results.empty?
 
         results.each do |result|
           if @pry
@@ -138,20 +169,46 @@ module Fast
       end
     end
 
+    # @return [Array<String>] with files from command line expression.
+    # @see Fast.ruby_files_from
     def files
       Fast.ruby_files_from(*@files)
     end
 
+    # @return [Boolean] true when "-d" or "--debug" option is passed
     def debug_mode?
       @debug == true
     end
 
+    # Output information if #debug_mode? is true.
     def debug(*info)
       puts(info) if debug_mode?
     end
 
+    # Report results using the actual options binded from command line.
+    # @see Fast.report
     def report(result, file)
-      Fast.report(result, file: file, show_sexp: @show_sexp)
+      Fast.report(result, file: file, show_sexp: @show_sexp, headless: @headless)
+    end
+
+    # Find shortcut by name. Preloads all `Fastfiles` before start.
+    # @param name [String]
+    # @return [Fast::Shortcut]
+    def find_shortcut(name)
+      require 'fast/shortcut'
+      Fast.load_fast_files!
+
+      shortcut = Fast.shortcuts[name] || Fast.shortcuts[name.to_sym]
+
+      shortcut || exit_shortcut_not_found(name)
+    end
+
+    # Exit process with warning message bolding the shortcut that was not found.
+    # Prints available shortcuts as extra help and exit with code 1.
+    def exit_shortcut_not_found(name)
+      puts "Shortcut \033[1m#{name}\033[0m not found :("
+      puts "Available shortcuts are: #{Fast.shortcuts.keys.join(', ')}." if Fast.shortcuts.any?
+      exit 1
     end
   end
 end

data/lib/fast/shortcut.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Allow user to define shortcuts and reuse them in the command line.
+module Fast
+  class << self
+    # Where to search for `Fastfile` archives?
+    # 1. Current directory that the command is being runned
+    # 2. Home folder
+    # 3. Using the `FAST_FILE_DIR` variable to set an extra folder
+    LOOKUP_FAST_FILES_DIRECTORIES = [Dir.pwd, ENV['HOME'], ENV['FAST_FILE_DIR']].freeze
+
+    # Store predefined searches with default paths through shortcuts.
+    # define your Fastfile in you root folder or
+    # @example Shortcut for finding validations in rails models
+    #   Fast.shortcut(:validations, "(send nil {validate validates})", "app/models")
+    def shortcut(identifier, *args, &block)
+      puts "identifier #{identifier.inspect} will be override" if shortcuts.key?(identifier)
+      shortcuts[identifier] = Shortcut.new(*args, &block)
+    end
+
+    # Stores shortcuts in a simple hash where the key is the identifier
+    # and the value is the object itself.
+    # @return [Hash<String,Shortcut>] as a dictionary.
+    def shortcuts
+      @shortcuts ||= {}
+    end
+
+    # @return [Array<String>] with existent Fastfiles from {LOOKUP_FAST_FILES_DIRECTORIES}.
+    def fast_files
+      @fast_files ||= LOOKUP_FAST_FILES_DIRECTORIES.compact
+        .map { |dir| File.join(dir, 'Fastfile') }
+        .select(&File.method(:exists?))
+    end
+
+    # Loads `Fastfiles` from {.fast_files} list
+    def load_fast_files!
+      fast_files.each(&method(:load))
+    end
+  end
+
+  # Wraps shortcuts for repeated command line actions or build custom scripts
+  # with shorcut blocks
+  # This is an utility that can be used preloading several shortcuts
+  # The shortcut structure will be consumed by [Fast::Cli] and feed with the
+  # command line arguments in realtime.
+  class Shortcut
+    attr_reader :args
+    def initialize(*args, &block)
+      @args = args if args.any?
+      @block = block
+    end
+
+    def single_run_with_block?
+      @block && @args.nil?
+    end
+
+    def options
+      @args.select { |arg| arg.start_with? '-' }
+    end
+
+    def params
+      @args - options
+    end
+
+    # Merge extra arguments from input returning a new arguments array keeping
+    # the options from previous alias and replacing the files with the
+    # @param [Array] extra_args
+    def merge_args(extra_args)
+      [params[0], *options, *extra_args]
+    end
+
+    # If the shortcut was defined with a single block and no extra arguments, it
+    # only runs the block and return the result of the yielded block.
+    # The block is also executed in the [Fast] module level. Making it easy to
+    # implement smalls scripts using several Fast methods.
+    # Use ARGV to catch regular arguments from command line if the block is
+    # given.
+    #
+    # @return [Hash<String, Array<Astrolabe::Node>] with file => search results.
+    def run
+      Fast.instance_exec(&@block) if single_run_with_block?
+    end
+  end
+end

data/lib/fast/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fast
-  VERSION = '0.1.2'
+  VERSION = '0.1.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ffast
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Jônatas Davi Paganini
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-10 00:00:00.000000000 Z
+date: 2019-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: astrolabe
@@ -230,10 +230,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".projections.json"
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
 - CODE_OF_CONDUCT.md
+- Fastfile
 - Gemfile
 - Guardfile
 - LICENSE.txt
@@ -264,6 +266,7 @@ files:
 - lib/fast.rb
 - lib/fast/cli.rb
 - lib/fast/experiment.rb
+- lib/fast/shortcut.rb
 - lib/fast/version.rb
 - mkdocs.yml
 homepage: https://jonatas.github.io/fast/