ffast 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49dd19ccc728102aba01cf03b72c5a4ce194e036bb7a489abee40bf488bd9821
-  data.tar.gz: 390d27be9261ea3333fe91d8561965ee9127965bf9fd1080134e08fba1914410
+  metadata.gz: fd904f00cff76125f3b6b79455b1fda97040acbe1e631d4842a26d5e126defde
+  data.tar.gz: 426d0dfd4d17fe9e491921ae431f75d28c683da1bf6f37e27d64d9808ff86f0a
 SHA512:
-  metadata.gz: 4b73de237734f1799832f4f724b8a2ebf4dfcf116ade615469af205cb61204d777a4e9f05b8483e7647251f20daeef28edf61e72cec2172319b3b1261beee4b0
-  data.tar.gz: 330f5f62da86cfa18508f53c13231bcf55993e44d0bea4a9e4fd59427fae1d1aabd22a27b352adac78d6fe24a8abe1ebaf21ea33ef0c63dbafb7a4fdf3883e12
+  metadata.gz: 773ec583e5c2dc7edf71d519ed0a09ace7f3714b85483f78a4ace150a85479a6cfcef20cf3724f5105204b3f26a4fb4f2a8e4040aebf366f049a3d11a7e84fcf
+  data.tar.gz: 2da3d58ad7036f74e245de58e654d736cc0f97f30bf116934166b1393132f3820e4b55f40039b99ea1589369dd650b694d874763fc36fd995bd521498b5e8257

data/Fastfile

@@ -18,7 +18,7 @@ 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|
+  rewrite_file('(casgn nil VERSION (str _)', 'lib/fast/version.rb') do |node|
     target = node.children.last.loc.expression
     pieces = target.source.split('.').map(&:to_i)
     pieces.reverse.each_with_index do |fragment, i|
@@ -32,8 +32,3 @@ Fast.shortcut :bump_version do
     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

@@ -79,14 +79,14 @@ It's corresponding s-expression would be:
 If we wanted to find this particular assignment somewhere in our AST, we can use
 Fast to look for a local variable named `value` with a value `42`:
 
-    Fast.match?(ast, '(lvasgn value (int 42))') # => true
+    Fast.match? '(lvasgn value (int 42))', ast # => true
 
 ### Wildcard Token
 
 If we wanted to find a variable named `value` that was assigned any integer value
 we could replace `42` in our query with an underscore ( `_` ) as a shortcut:
 
-    Fast.match?(ast, '(lvasgn value (int _))') # => true
+    Fast.match? '(lvasgn value (int _))', ast # => true
 
 ### Set Inclusion Token
 
@@ -94,7 +94,7 @@ If we weren't sure the type of the value we're assigning, we can use our set
 inclusion token (`{}`) from earlier to tell Fast that we expect either a `Float`
 or an `Integer`:
 
-    Fast.match?(ast, '(lvasgn value ({float int} _))') # => true
+    Fast.match? '(lvasgn value ({float int} _))', ast # => true
 
 ### All Matching Token
 
@@ -103,28 +103,28 @@ all matching token (`[]`) to express multiple conditions that need to be true.
 In this case we don't want the value to be a `String`, `Hash`, or an `Array` by
 prefixing all of the types with `!`:
 
-    Fast.match?(ast, '(lvasgn value ([!str !hash !array] _))') # => true
+    Fast.match? '(lvasgn value ([!str !hash !array] _))', ast # => true
 
 ### Node Child Token
 
 We can match any node with children by using the child token ( `...` ):
 
-    Fast.match?(ast, '(lvasgn value ...)') # => true
+    Fast.match? '(lvasgn value ...)', ast # => true
 
 We could even match any local variable assignment combining both `_` and `...`:
 
-    Fast.match?(ast, '(lvasgn _ ...)') # => true
+    Fast.match? '(lvasgn _ ...)', ast # => true
 
 ### Capturing the Value of an Expression
 
 You can use `$` to capture the contents of an expression for later use:
 
-    Fast.match?(ast, '(lvasgn value $...)') # => [s(:int, 42)]
+    Fast.match?('(lvasgn value $...)', ast) # => [s(:int, 42)]
 
 Captures can be used in any position as many times as you want to capture whatever
 information you might need:
 
-    Fast.match?(ast, '(lvasgn $_ $...)') # => [:value, s(:int, 42)]
+    Fast.match?('(lvasgn $_ $...)', ast) # => [:value, s(:int, 42)]
 
 > Keep in mind that `_` means something not nil and `...` means a node with
 > children.
@@ -142,7 +142,7 @@ method names and guarantee they are unique.
       already_exists
     end
 
-    puts Fast.search_file( '(def #duplicated)', 'example.rb')
+    puts Fast.search_file('(def #duplicated)', 'example.rb')
 
 The same principle can be used in the node level or for debugging purposes.
 
@@ -195,35 +195,31 @@ a single `Object`, like `a.b.c.d`. Its corresponding s-expression would be:
 You can also search using nested arrays with **pure values**, or **shortcuts** or
 **procs**:
 
-    Fast.match?(ast, [:send, [:send, '...'], :d]) # => true
-    Fast.match?(ast, [:send, [:send, '...'], :c]) # => false
-    Fast.match?(ast, [:send, [:send, [:send, '...'], :c], :d]) # => true
+    Fast.match? [:send, [:send, '...'], :d], ast  # => true
+    Fast.match? [:send, [:send, '...'], :c], ast  # => false
 
 Shortcut tokens like child nodes `...` and wildcards `_` are just placeholders
 for procs. If you want, you can even use procs directly like so:
 
-    Fast.match?(ast, [
+    Fast.match?([
       :send, [
         -> (node) { node.type == :send },
         [:send, '...'],
         :c
       ],
       :d
-    ]) # => true
+    ], ast) # => true
 
 This also works with expressions:
 
-    Fast.match?(
-      ast,
-      '(send (send (send (send nil $_) $_) $_) $_)'
-    ) # => [:a, :b, :c, :d]
+    Fast.match?('(send (send (send (send nil $_) $_) $_) $_)', ast) # => [:a, :b, :c, :d]
 
 ### Debugging
 
 If you find that a particular expression isn't working, you can use `debug` to
 take a look at what Fast is doing:
 
-    Fast.debug { Fast.match?(s(:int, 1), [:int, 1]) }
+    Fast.debug { Fast.match?([:int, 1], s(:int, 1)) }
 
 Each comparison made while searching will be logged to your console (STDOUT) as
 Fast goes through the AST:
@@ -237,7 +233,7 @@ We can also dynamically interpolate arguments into our queries using the
 interpolation token `%`. This works much like `sprintf` using indexes starting
 from `1`:
 
-    Fast.match?(code('a = 1'), '(lvasgn %1 (int _))', :a) # => true
+    Fast.match? '(lvasgn %1 (int _))', ('a = 1'), :a  # => true
 
 ## Using previous captures in search
 
@@ -264,18 +260,18 @@ We can create a query that searches for such a method:
 Search allows you to go search the entire AST, collecting nodes that matches given
 expression. Any matching node is then returned:
 
-    Fast.search(code('a = 1'), '(int _)') # => s(:int, 1)
+    Fast.search(Fast.ast('a = 1'), '(int _)') # => s(:int, 1)
 
 If you use captures along with a search, both the matching nodes and the
 captures will be returned:
 
-    Fast.search(code('a = 1'), '(int $_)') # => [s(:int, 1), 1]
+    Fast.search(Fast.ast('a = 1'), '(int $_)') # => [s(:int, 1), 1]
 
 ## Fast.capture
 
 To only pick captures and ignore the nodes, use `Fast.capture`:
 
-  Fast.capture(code('a = 1'), '(int $_)') # => 1
+  Fast.capture(Fast.ast('a = 1'), '(int $_)') # => 1
 
 ## Fast.replace
 
@@ -325,7 +321,7 @@ Or only the method name:
 In the context of the rewriter, the objective is removing the method and inserting the new
 delegate content. Then, the scope is `node.location.expression`:
 
-    Fast.replace ast, '(def $_ ... (send (send nil $_) \1))' do |node, captures|
+    Fast.replace '(def $_ ... (send (send nil $_) \1))', ast do |node, captures|
       attribute, object = captures
 
       replace(
@@ -360,7 +356,7 @@ To refactor and reach the proposed example, follow a few steps:
 #### Entire example
 
     assignment = nil
-    Fast.replace_file 'sample.rb', '({ lvasgn lvar } message )', -> (node, _) {
+    Fast.replace_file '({ lvasgn lvar } message )', 'sample.rb' do |node, _|
       # Find a variable assignment
       if node.type == :lvasgn
         assignment = node.children.last
@@ -466,7 +462,7 @@ 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|
+  rewrite_file('(casgn nil VERSION (str _)', 'lib/fast/version.rb') do |node|
     target = node.children.last.loc.expression
     pieces = target.source.split(".").map(&:to_i)
     pieces.reverse.each_with_index do |fragment,i|

data/docs/command_line.md

@@ -6,7 +6,6 @@ and you can use it to search and find code using the concept:
 ```
 $ fast '(def match?)' lib/fast.rb
 ```
-
 - Use `-d` or `--debug` for enable debug mode.
 - Use `--ast` to output the AST instead of the original code
 - Use `--pry` to jump debugging the first result with pry
@@ -35,12 +34,8 @@ Getting all `it` blocks without description:
 
 ```ruby
 # spec/fast_spec.rb:166
-it { expect(described_class).to be_match(s(:int, 1), '(...)') }
-# spec/fast_spec.rb:167
-it { expect(described_class).to be_match(s(:int, 1), '(_ _)') }
-# spec/fast_spec.rb:168
-it { expect(described_class).to be_match(code['"string"'], '(str "string")') }
-# ... more results
+it { expect(described_class).to be_match('(...)', s(:int, 1)) }
+...
 ```
 
 ## `--debug`
@@ -122,12 +117,12 @@ You can define a `Fastfile` in any project with your custom shortcuts and easy
 check some code or run some task.
 
 
-## Shortcuts
+## Shortcut examples
 
 Create shortcuts with blocks enables introduce custom coding in
 the scope of the `Fast` module.
 
-## Example: Print library version.
+### 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:
@@ -152,7 +147,7 @@ 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
+### 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
@@ -210,5 +205,33 @@ Fast.shortcut :shortcuts do
 end
 ```
 
-You can find these examples in the [Fastfile](https://github.com/jonatas/fast/tree/master/Fastfile).
+Or we can make it a bit more friendly and also use Fast to process the shortcut
+positions and pick the comment that each shortcut have in the previous line: 
+
+```ruby
+# List all shortcut with comments
+Fast.shortcut :shortcuts do
+  fast_files.each do |file|
+    lines = File.readlines(file).map{|line|line.chomp.gsub(/\s*#/,'').strip}
+    result = capture_file('(send ... shortcut $(sym _))', file)
+    result = [result] unless result.is_a?Array
+    result.each do |capture|
+      target = capture.loc.expression
+      puts "fast .#{target.source[1..-1].ljust(30)} # #{lines[target.line-2]}"
+    end
+  end
+end
+```
+
+And it will be printing all loaded shortcuts with comments:
+
+```
+$ fast .shortcuts
+fast .version                        # Let's say you'd like to show the version that is over the version file
+fast .parser                         # Simple shortcut that I used often to show how the expression parser works
+fast .bump_version                   # Use `fast .bump_version` to rewrite the version file
+fast .shortcuts                      # List all shortcut with comments
+```
+
+You can find more examples in the [Fastfile](https://github.com/jonatas/fast/tree/master/Fastfile).
 

data/docs/index.md

@@ -64,9 +64,36 @@ The current version cover the following elements:
 
 Jump to [Syntax](syntax.md).
 
-## Fast.match?
+## ast
 
-`match?` is the most granular function that tries to compare a node with an
+Use `Fast.ast` to convert simple code to AST objects. You can use it as
+`ruby-parse` but directly from the console.
+
+```ruby
+Fast.ast("1")       # => s(:int, 1)
+Fast.ast("method")  # => s(:send, nil, :method)
+Fast.ast("a.b")     # => s(:send, s(:send, nil, :a), :b)
+Fast.ast("1 + 1")   # => s(:send, s(:int, 1), :+, s(:int, 1))
+Fast.ast("a = 2")   # => s(:lvasgn, :a, s(:int, 2))
+Fast.ast("b += 2")  # => s(:op_asgn, s(:lvasgn, :b), :+, s(:int, 2))
+```
+
+It uses [astrolable](https://github.com/yujinakayama/astrolabe) gem behind the scenes:
+
+```ruby
+Fast.ast(Fast.ast("1")).class
+=> Astrolabe::Node
+Fast.ast(Fast.ast("1")).type
+=> :int
+Fast.ast(Fast.ast("1")).children
+=> [1]
+```
+
+See also [ast_from_file](#ast_from_file).
+
+## match?
+
+`Fast.match?` is the most granular function that tries to compare a node with an
 expression. It returns true or false and some node captures case it find
 something.
 
@@ -107,25 +134,25 @@ ast = s(:lvasgn, :value, s(:int, 42))
 Now, lets find local variable named `value` with an value `42`:
 
 ```ruby
-Fast.match?(ast, '(lvasgn value (int 42))') # true
+Fast.match?('(lvasgn value (int 42))', ast) # true
 ```
 
 Lets abstract a bit and allow some integer value using `_` as a shortcut:
 
 ```ruby
-Fast.match?(ast, '(lvasgn value (int _))') # true
+Fast.match?('(lvasgn value (int _))', ast) # true
 ```
 
 Lets abstract more and allow float or integer:
 
 ```ruby
-Fast.match?(ast, '(lvasgn value ({float int} _))') # true
+Fast.match?('(lvasgn value ({float int} _))', ast) # true
 ```
 
 Or combine multiple assertions using `[]` to join conditions:
 
 ```ruby
-Fast.match?(ast, '(lvasgn value ([!str !hash !array] _))') # true
+Fast.match?('(lvasgn value ([!str !hash !array] _))', ast) # true
 ```
 
 Matches all local variables not string **and** not hash **and** not array.
@@ -133,25 +160,25 @@ Matches all local variables not string **and** not hash **and** not array.
 We can match "a node with children" using `...`:
 
 ```ruby
-Fast.match?(ast, '(lvasgn value ...)') # true
+Fast.match?('(lvasgn value ...)', ast) # true
 ```
 
 You can use `$` to capture a node:
 
 ```ruby
-Fast.match?(ast, '(lvasgn value $...)') # => [s(:int, 42)]
+Fast.match?('(lvasgn value $...)', ast) # => [s(:int), 42]
 ```
 
 Or match whatever local variable assignment combining both `_` and `...`:
 
 ```ruby
-Fast.match?(ast, '(lvasgn _ ...)') # true
+Fast.match?('(lvasgn _ ...)', ast) # true
 ```
 
 You can also use captures in any levels you want:
 
 ```ruby
-Fast.match?(ast, '(lvasgn $_ $...)') # [:value, s(:int, 42)]
+Fast.match?('(lvasgn $_ $...)', ast) # [:value, s(:int), 42]
 ```
 
 Keep in mind that `_` means something not nil and `...` means a node with
@@ -196,31 +223,28 @@ You can search using sub-arrays with **pure values**, or **shortcuts** or
 **procs**:
 
 ```ruby
-Fast.match?(ast, [:send, [:send, '...'], :d]) # => true
-Fast.match?(ast, [:send, [:send, '...'], :c]) # => false
-Fast.match?(ast, [:send, [:send, [:send, '...'], :c], :d]) # => true
+Fast.match?([:send, [:send, '...'], :d], ast) # => true
+Fast.match?([:send, [:send, '...'], :c], ast) # => false
+Fast.match?([:send, [:send, [:send, '...'], :c], :d], ast) # => true
 ```
 
 Shortcuts like `...` and `_` are just literals for procs. Then you can use
 procs directly too:
 
 ```ruby
-Fast.match?(ast, [:send, [ -> (node) { node.type == :send }, [:send, '...'], :c], :d]) # => true
+Fast.match?([:send, [ -> (node) { node.type == :send }, [:send, '...'], :c], :d], ast) # => true
 ```
 
 And also work with expressions:
 
 ```ruby
-Fast.match?(
-  ast,
-  '(send (send (send (send nil $_) $_) $_) $_)'
-) # => [:a, :b, :c, :d]
+Fast.match?('(send (send (send (send nil $_) $_) $_) $_)', ast) # => [:a, :b, :c, :d]
 ```
 
 If something does not work you can debug with a block:
 
 ```ruby
-Fast.debug { Fast.match?(s(:int, 1), [:int, 1]) }
+Fast.debug { Fast.match?([:int, 1], s(:int, 1)) }
 ```
 
 It will output each comparison to stdout:
@@ -230,70 +254,40 @@ int == (int 1) # => true
 1 == 1 # => true
 ```
 
-## Use previous captures in search
-
-Imagine you're looking for a method that is just delegating something to
-another method, like:
-
-```ruby
-def name
-  person.name
-end
-```
-
-This can be represented as the following AST:
-
-```
-(def :name
-  (args)
-  (send
-    (send nil :person) :name))
-```
-
-Then, let's build a search for methods that calls an attribute with the same
-name:
-
-```ruby
-Fast.match?(ast,'(def $_ ... (send (send nil _) \1))') # => [:name]
-```
-
-## Fast.search
+## search
 
 Search allows you to go deeply in the AST, collecting nodes that matches with
 the expression. It also returns captures if they exist.
 
 ```ruby
-Fast.search(code('a = 1'), '(int _)') # => s(:int, 1)
+Fast.search('(int _)', Fast.ast('a = 1')) # => s(:int, 1)
 ```
 
 If you use captures, it returns the node and the captures respectively:
 
 ```ruby
-Fast.search(code('a = 1'), '(int $_)') # => [s(:int, 1), 1]
+Fast.search('(int $_)', Fast.ast('a = 1')) # => [s(:int, 1), 1]
 ```
 
-## Fast.capture
+## capture
 
 To pick just the captures and ignore the nodes, use `Fast.capture`:
 
 ```ruby
-Fast.capture(code('a = 1'), '(int $_)') # => 1
+Fast.capture('(int $_)', Fast.ast('a = 1')) # => 1
 ```
-## Fast.replace
+## replace
 
 And if I want to refactor a code and use `delegate <attribute>, to: <object>`, try with replace:
 
 ```ruby
-Fast.replace ast, '(def $_ ... (send (send nil $_) \1))' do |node, captures|
-    attribute, object = captures
-    replace(
-      node.location.expression,
-      "delegate :#{attribute}, to: :#{object}"
-    )
-  end
+Fast.replace '(def $_ ... (send (send nil $_) \1))', ast do |node, captures|
+  attribute, object = captures
+  replace(node.location.expression, "delegate :#{attribute}, to: :#{object}")
+end
 ```
 
-## Fast.replace_file
+## replace_file
 
 Now let's imagine we have real files like `sample.rb` with the following code:
 
@@ -312,19 +306,49 @@ is being called.
 
 ```ruby
 assignment = nil
-Fast.replace_file('sample.rb', '({ lvasgn lvar } message )',
-  -> (node, _) {
-    if node.type == :lvasgn
-      assignment = node.children.last
-      remove(node.location.expression)
-    elsif node.type == :lvar
-      replace(node.location.expression, assignment.location.expression.source)
-    end
-  }
-)
+Fast.replace_file('({ lvasgn lvar } message )','sample.rb')  do |node, _|
+  if node.type == :lvasgn
+    assignment = node.children.last
+    remove(node.location.expression)
+  elsif node.type == :lvar
+    replace(node.location.expression, assignment.location.expression.source)
+  end
+end
 ```
 
-## Fast.ast_from_File(file)
+It will return an output of the new source code with the changes but not save
+the file. You can use ()[#rewrite_file] if you're confident about the changes.
+
+## capture_file
+
+`Fast.capture_file` can be used to combine [capture](#capture) and file system.
+
+```ruby
+Fast.capture_file("$(casgn)", "lib/fast/version.rb") # => s(:casgn, nil, :VERSION, s(:str, "0.1.3"))
+Fast.capture_file("(casgn nil _ (str $_))", "lib/fast/version.rb") # => "0.1.3"
+```
+
+## capture_all
+
+`Fast.capture_all` can be used to combine [capture_file](#capture_file) from multiple sources:
+
+```ruby
+Fast.capture_all("(casgn nil $_)") # => { "./lib/fast/version.rb"=>:VERSION, "./lib/fast.rb"=>[:LITERAL, :TOKENIZER], ...}
+```
+
+The second parameter can also be passed with to filter specific folders:
+
+```ruby
+Fast.capture_all("(casgn nil $_)", "lib/fast") # => {"lib/fast/shortcut.rb"=>:LOOKUP_FAST_FILES_DIRECTORIES, "lib/fast/version.rb"=>:VERSION}
+```
+
+
+## rewrite_file
+
+`Fast.rewrite_file` works exactly as the `replace` but it will override the file
+from the input.
+
+## ast_from_file
 
 This method parses the code and load into a AST representation.
 
@@ -332,7 +356,7 @@ This method parses the code and load into a AST representation.
 Fast.ast_from_file('sample.rb')
 ```
 
-## Fast.search_file
+## search_file
 
 You can use `search_file` and pass the path for search for expressions inside
 files.
@@ -343,7 +367,7 @@ Fast.search_file(expression, 'file.rb')
 
 It's simple combination of `Fast.ast_from_file` with `Fast.search`.
 
-## Fast.ruby_files_from(arguments)
+## ruby_files_from
 
 You'll be probably looking for multiple ruby files, then this method fetches
 all internal `.rb` files 
@@ -352,3 +376,22 @@ all internal `.rb` files
 Fast.ruby_files_from(['lib']) # => ["lib/fast.rb"]
 ```
 
+## search_all
+
+Combines the [search_file](#search_file) with [ruby_files_from](#ruby_files_from)
+multiple locations and returns tuples with files and results.
+
+```ruby
+Fast.search_all("(def ast_from_file)")
+=> {"./lib/fast.rb"=>[s(:def, :ast_from_file,
+  s(:args,
+    s(:arg, :file)),
+  s(:begin,
+```
+
+You can also override the second param and pass target files or folders:
+
+```ruby
+Fast.search_all("(def _)", '../other-folder')
+```
+

data/docs/similarity_tutorial.md

@@ -53,7 +53,7 @@ observe some specific node types and try to group the similarities
 using the pattern generated.
 
 ```ruby
-Fast.search_file('lib/fast.rb', 'class')
+Fast.search_file('class', 'lib/fast.rb')
 ```
 Capturing the constant name and filtering only for symbols is easy and we can
 see that we have a few classes defined in the the same file.

data/docs/syntax.md

@@ -251,56 +251,8 @@ def duplicate(value)
 # example.rb:
 duplicate
 ```
-One extra method name was printed because of `$` is capturing the element.
-
-Let's use the `--pry` for inspecting the results.
-
-    $ fast '(def $_)' example.rb --pry
-
-It will open pry with access to `result` as the first result and
-`results` with all matching results.
-
-```
-From: /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/ffast-0.0.2/bin/fast @ line 60 :
-
-    55:
-    56:   results.each do |result|
-    57:     next if result.nil? || result == []
-    58:     if pry
-    59:       require 'pry'
- => 60:       binding.pry # rubocop:disable Lint/Debugger
-    61:     else
-    62:       Fast.report(result, file: file, show_sexp: show_sexp)
-    63:     end
-    64:   end
-    65: end
-```
 
-Inspecting the results you can see that they are mixing AST nodes and the
-captures.
-
-```ruby
-[1] pry(main)> results
-=> [s(:def, :magic,
-  s(:args),
-  s(:send, nil, :rand,
-    s(:const, nil, :ANSWER))),
- :magic,
- s(:def, :duplicate,
-  s(:args,
-    s(:arg, :value)),
-  s(:send,
-    s(:lvar, :value), :*,
-    s(:int, 2))),
- :duplicate]
-```
-
-We can filter the captures to make it easy to analyze.
-
-```ruby
-[2] pry(main)> results.grep(Symbol)
-=> [:magic, :duplicate]
-```
+One extra method name was printed because of `$` is capturing the element.
 
 ## `nil` matches exactly **nil**
 
@@ -368,7 +320,7 @@ ANSWER = 42
 ANSWER
 ```
 
-## Calling Custom Methods
+## `#` for custom methods
 
 Custom methods can let you into ruby doman for more complicated rules. Let's say
 we're looking for duplicated methods in the same class. We need to collect
@@ -403,10 +355,41 @@ more details of the node
 ```ruby
 puts Fast.search_file('[ (def a) #debug ]', 'example.rb')
 ```
-## Calling Instance Methods
+
+## `.` for instance methods
 
 You can also call instance methods using `.<method-name>`.
 
 Example `nil` is the same of calling `nil?` and you can also use `(int .odd?)`
 to pick only odd integers. The `int` fragment can also be `int_type?`.
 
+## `\1` for first previous capture
+
+Imagine you're looking for a method that is just delegating something to
+another method, like:
+
+```ruby
+def name
+  person.name
+end
+```
+
+This can be represented as the following AST:
+
+```
+(def :name
+  (args)
+  (send
+    (send nil :person) :name))
+```
+
+Then, let's build a search for methods that calls an attribute with the same
+name:
+
+```ruby
+Fast.match?('(def $_ ... (send (send nil _) \1))', ast) # => [:name]
+```
+
+With the method name being captured with `$_` it can be later referenced in the
+expression with `\1`. If the search contains multiple captures, the `\2`,`\3`
+can be used as the sequence of captures.

data/lib/fast.rb

@@ -89,9 +89,9 @@ module Fast
     # Verify if a given AST matches with a specific pattern
     # @return [Boolean] case matches ast with the current expression
     # @example
-    #   Fast.match?(Fast.ast("1"),"int") # => true
-    def match?(ast, pattern, *args)
-      Matcher.new(ast, pattern, *args).match?
+    #   Fast.match?("int", Fast.ast("1")) # => true
+    def match?(pattern, ast, *args)
+      Matcher.new(pattern, ast, *args).match?
     end
 
     # Replaces content based on a pattern.
@@ -104,10 +104,10 @@ module Fast
     #   end # => variable_renamed = 1
     # @return [String] with the new source code after apply the replacement
     # @see Fast::Rewriter
-    def replace(ast, pattern, source = nil, &replacement)
+    def replace(pattern, ast, source = nil, &replacement)
       buffer = Parser::Source::Buffer.new('replacement')
       buffer.source = source || ast.loc.expression.source
-      to_replace = search(ast, pattern)
+      to_replace = search(pattern, ast)
       types = to_replace.grep(Parser::AST::Node).map(&:type).uniq
 
       rewriter = Rewriter.new
@@ -122,21 +122,46 @@ module Fast
     # @return [Array<Astrolabe::Node>] that matches the pattern
     def search_file(pattern, file)
       node = ast_from_file(file)
-      search node, pattern
+      search pattern, node
+    end
+
+    # Search with pattern on a directory or multiple files
+    # @param [String] pattern
+    # @param [Array<String>] *locations where to search. Default is '.'
+    # @return [Hash<String,Array<Astrolabe::Node>>] with files and results
+    def search_all(pattern, locations = ['.'])
+      search_pattern = method(:search_file).curry.call(pattern)
+      group_results(search_pattern, locations)
+    end
+
+    # Capture with pattern on a directory or multiple files
+    # @param [String] pattern
+    # @param [Array<String>] locations where to search. Default is '.'
+    # @return [Hash<String,Object>] with files and captures
+    def capture_all(pattern, locations = ['.'])
+      capture_pattern = method(:capture_file).curry.call(pattern)
+      group_results(capture_pattern, locations)
+    end
+
+    def group_results(search_pattern, locations)
+      ruby_files_from(*locations)
+        .map { |f| { f => search_pattern.call(f) } }
+        .reject { |results| results.values.all?(&:empty?) }
+        .inject(&:merge!)
     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)
+    def replace_file(pattern, file, &replacement)
       ast = ast_from_file(file)
-      replace(ast, pattern, IO.read(file), &replacement)
+      replace(pattern, ast, IO.read(file), &replacement)
     end
 
     # Combines #replace_file output overriding the file if the output is different
     # from the original file content.
-    def rewrite_file(file, pattern, &replacement)
+    def rewrite_file(pattern, file, &replacement)
       previous_content = IO.read(file)
-      content = replace_file(file, pattern, &replacement)
+      content = replace_file(pattern, file, &replacement)
       File.open(file, 'w+') { |f| f.puts content } if content != previous_content
     end
 
@@ -144,21 +169,20 @@ module Fast
     # in the pattern to make it work.
     # @return [Array<Object>] captured from the pattern matched in the file
     def capture_file(pattern, file)
-      node = ast_from_file(file)
-      capture node, pattern
+      capture pattern, ast_from_file(file)
     end
 
     # Search recursively into a node and its children.
     # If the node matches with the pattern it returns the node,
     # otherwise it recursively collect possible children nodes
     # @yield node and capture if block given
-    def search(node, pattern)
-      if (match = match?(node, pattern))
+    def search(pattern, node)
+      if (match = match?(pattern, node))
         yield node, match if block_given?
         match != true ? [node, match] : [node]
       else
         node.each_child_node
-          .flat_map { |e| search(e, pattern) }
+          .flat_map { |child| search(pattern, child) }
           .compact.flatten
       end
     end
@@ -166,16 +190,16 @@ module Fast
     # Return only captures from a search
     # @return [Array<Object>] with all captured elements.
     # @return [Object] with single element when single capture.
-    def capture(node, pattern)
-      res =
-        if (match = match?(node, pattern))
-          match == true ? node : match
-        else
-          node.each_child_node
-            .flat_map { |child| capture(child, pattern) }
-            .compact.flatten
-        end
-      res&.size == 1 ? res[0] : res
+    def capture(pattern, node)
+      res = if (match = match?(pattern, node))
+              match == true ? node : match
+            else
+              node.each_child_node
+                .flat_map { |child| capture(pattern, child) }
+                .compact.flatten
+            end
+      res = [res] unless res.is_a?(Array)
+      res.one? ? res.first : res
     end
 
     def expression(string)
@@ -190,7 +214,7 @@ module Fast
     #
     # @example
     #   Fast.debug do
-    #      Fast.match?(s(:int, 1), [:int, 1])
+    #      Fast.match?([:int, 1], s(:int, 1))
     #   end
     #  int == (int 1) # => true
     #  1 == 1 # => true
@@ -268,7 +292,7 @@ module Fast
     end
 
     def match?(node)
-      Fast.match?(node, search)
+      Fast.match?(search, node)
     end
 
     # Generate methods for all affected types.
@@ -382,24 +406,24 @@ module Fast
     end
 
     def match?(node)
-      match_recursive(node, valuate(token))
+      match_recursive(valuate(token), node)
     end
 
-    def match_recursive(node, expression)
+    def match_recursive(expression, node)
       case expression
       when Proc then expression.call(node)
       when Find then expression.match?(node)
-      when Symbol then compare_symbol_or_head(node, expression)
+      when Symbol then compare_symbol_or_head(expression, node)
       when Enumerable
         expression.each_with_index.all? do |exp, i|
-          match_recursive(i.zero? ? node : node.children[i - 1], exp)
+          match_recursive(exp, i.zero? ? node : node.children[i - 1])
         end
       else
         node == expression
       end
     end
 
-    def compare_symbol_or_head(node, expression)
+    def compare_symbol_or_head(expression, node)
       case node
       when Parser::AST::Node
         node.type == expression.to_sym
@@ -410,13 +434,13 @@ module Fast
       end
     end
 
-    def debug_match_recursive(node, expression)
-      match = original_match_recursive(node, expression)
-      debug(node, expression, match)
+    def debug_match_recursive(expression, node)
+      match = original_match_recursive(expression, node)
+      debug(expression, node, match)
       match
     end
 
-    def debug(node, expression, match)
+    def debug(expression, node, match)
       puts "#{expression} == #{node} # => #{match}"
     end
 
@@ -490,7 +514,7 @@ module Fast
   #
   # @example check comparision of integers that will always return true
   #   ast = Fast.ast("1 == 1") => s(:send, s(:int, 1), :==, s(:int, 1))
-  #   Fast.match?(ast, "(send $(int _) == \1)") # => [s(:int, 1)]
+  #   Fast.match?("(send $(int _) == \1)", ast) # => [s(:int, 1)]
   class FindWithCapture < Find
     attr_writer :previous_captures
 
@@ -514,10 +538,10 @@ module Fast
   # Use `%1` in the expression and the Matcher#prepare_arguments will
   # interpolate the argument in the expression.
   # @example interpolate the node value 1
-  #   Fast.match?(Fast.ast("1"), "(int %1)", 1) # => true
-  #   Fast.match?(Fast.ast("1"), "(int %1)", 2) # => false
+  #   Fast.match?("(int %1)", Fast.ast("1"), 1) # => true
+  #   Fast.match?("(int %1)", Fast.ast("1"), 2) # => false
   # @example interpolate multiple arguments
-  #   Fast.match?(Fast.ast("1"), "(%1 %2)", :int, 1) # => true
+  #   Fast.match?("(%1 %2)", Fast.ast("1"), :int, 1) # => true
   class FindFromArgument < Find
     attr_writer :arguments
 
@@ -532,7 +556,7 @@ module Fast
     def match?(node)
       raise 'You must define arguments to match' unless @arguments
 
-      compare_symbol_or_head node, @arguments[@capture_argument]
+      compare_symbol_or_head @arguments[@capture_argument], node
     end
 
     def to_s
@@ -605,7 +629,7 @@ module Fast
   #   Fast.expression("{int float}")
   class Any < Find
     def match?(node)
-      token.any? { |expression| Fast.match?(node, expression) }
+      token.any? { |expression| Fast.match?(expression, node) }
     end
 
     def to_s
@@ -651,51 +675,51 @@ module Fast
   # @example simple match
   #   ast = Fast.ast("a = 1")
   #   expression = Fast.expression("(lvasgn _ (int _))")
-  #   Matcher.new(ast,expression).match? # true
+  #   Matcher.new(expression, ast).match? # true
   #
   # @example simple capture
   #   ast = Fast.ast("a = 1")
   #   expression = Fast.expression("(lvasgn _ (int $_))")
-  #   Matcher.new(ast,expression).match? # => [1]
+  #   Matcher.new(expression, ast).match? # => [1]
   #
   class Matcher
-    def initialize(ast, fast, *args)
+    def initialize(pattern, ast, *args)
       @ast = ast
-      @fast = if fast.is_a?(String)
-                Fast.expression(fast)
-              else
-                [*fast].map(&Find.method(:new))
-              end
+      @expression = if pattern.is_a?(String)
+                      Fast.expression(pattern)
+                    else
+                      [*pattern].map(&Find.method(:new))
+                    end
       @captures = []
-      prepare_arguments(@fast, args) if args.any?
+      prepare_arguments(@expression, args) if args.any?
     end
 
     # @return [true] if the @param ast recursively matches with expression.
     # @return #find_captures case matches
-    def match?(ast = @ast, fast = @fast)
-      head, *tail = fast
+    def match?(expression = @expression, ast = @ast)
+      head, *tail_expression = expression
       return false unless head.match?(ast)
-      return find_captures if tail.empty?
+      return find_captures if tail_expression.empty?
 
-      match_tail?(ast.children, tail)
+      match_tail?(tail_expression, ast.children)
     end
 
     # @return [true] if all children matches with tail
-    def match_tail?(child, tail)
+    def match_tail?(tail, child)
       tail.each_with_index.all? do |token, i|
         prepare_token(token)
-        token.is_a?(Array) ? match?(child[i], token) : token.match?(child[i])
+        token.is_a?(Array) ? match?(token, child[i]) : token.match?(child[i])
       end && find_captures
     end
 
-    # Look recursively into @param fast to check if the expression is have
+    # Look recursively into @param expression to check if the expression is have
     # captures.
     # @return [true] if any sub expression have captures.
-    def captures?(fast = @fast)
-      case fast
+    def captures?(expression = @expression)
+      case expression
       when Capture then true
-      when Array then fast.any?(&method(:captures?))
-      when Find then captures?(fast.token)
+      when Array then expression.any?(&method(:captures?))
+      when Find then captures?(expression.token)
       end
     end
 
@@ -705,13 +729,13 @@ module Fast
     # @return [true] in case of no captures in the expression
     # @see Fast::Capture
     # @see Fast::FindFromArgument
-    def find_captures(fast = @fast)
-      return true if fast == @fast && !captures?(fast)
+    def find_captures(expression = @expression)
+      return true if expression == @expression && !captures?(expression)
 
-      case fast
-      when Capture then fast.captures
-      when Array then fast.flat_map(&method(:find_captures)).compact
-      when Find then find_captures(fast.token)
+      case expression
+      when Capture then expression.captures
+      when Array then expression.flat_map(&method(:find_captures)).compact
+      when Find then find_captures(expression.token)
       end
     end
 

data/lib/fast/cli.rb

@@ -35,19 +35,26 @@ module Fast
   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}")) unless headless
+      puts(highlight("# #{file}:#{line}")) unless headless
     end
-    puts Fast.highlight(result, show_sexp: show_sexp)
+    puts highlight(result, show_sexp: show_sexp)
   end
 
   # Command Line Interface for Fast
   class Cli # rubocop:disable Metrics/ClassLength
     attr_reader :pattern, :show_sexp, :pry, :from_code, :similar, :help
-
-    # rubocop:disable Metrics/MethodLength
-    # rubocop:disable Metrics/AbcSize
     def initialize(args)
-      @opt = OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
+      args = replace_args_with_shortcut(args) if args.first&.start_with?('.')
+
+      @pattern, *@files = args.reject { |arg| arg.start_with? '-' }
+
+      option_parser.parse! args
+
+      @files = [*@files].reject { |arg| arg.start_with?('-') }
+    end
+
+    def option_parser # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      @option_parser ||= OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
         opts.banner = 'Usage: fast expression <files> [options]'
         opts.on('-d', '--debug', 'Debug fast engine') do
           @debug = true
@@ -67,6 +74,7 @@ module Fast
 
         opts.on('--pry', 'Jump into a pry session with results') do
           @pry = true
+          require 'pry'
         end
 
         opts.on('-c', '--code', 'Create a pattern from code example') do
@@ -92,25 +100,17 @@ module Fast
           @help = true
         end
       end
+    end
 
-      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
+    def replace_args_with_shortcut(args)
+      shortcut = find_shortcut args.first[1..-1]
+      if shortcut.single_run_with_block?
+        shortcut.run
+        exit
+      else
+        args.one? ? shortcut.args : shortcut.merge_args(args[1..-1])
       end
-
-      @pattern, *@files = args.reject { |arg| arg.start_with? '-' }
-
-      @opt.parse! args
-
-      @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)
@@ -121,7 +121,7 @@ module Fast
     # Show help or search for node patterns
     def run!
       if @help || @files.empty? && @pattern.nil?
-        puts @opt.help
+        puts option_parser.help
       else
         search
       end
@@ -136,43 +136,25 @@ module Fast
     # 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)
+    def search
       if debug_mode?
-        Fast.debug { Fast.search_file(expression, file) }
+        Fast.debug { execute_search }
       else
-        begin
-          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
-          []
-        end
-      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.empty?
-
-        results.each do |result|
-          if @pry
-            require 'pry'
-            binding.pry # rubocop:disable Lint/Debugger
-          else
+        execute_search do |file, results|
+          results.each do |result|
+            binding.pry if @pry # rubocop:disable Lint/Debugger
             report(result, file)
           end
         end
       end
     end
 
-    # @return [Array<String>] with files from command line expression.
-    # @see Fast.ruby_files_from
-    def files
-      Fast.ruby_files_from(*@files)
+    def execute_search
+      method_name = @captures ? :capture_all : :search_all
+      (Fast.public_send(method_name, expression, @files) || []).each do |file, results|
+        results = [results] unless results.is_a?(Array)
+        yield file, results
+      end
     end
 
     # @return [Boolean] true when "-d" or "--debug" option is passed

data/lib/fast/experiment.rb

@@ -287,7 +287,7 @@ module Fast
 
     # @return [Array<Astrolabe::Node>]
     def search_cases
-      Fast.search(@ast, experiment.expression) || []
+      Fast.search(experiment.expression, @ast) || []
     end
 
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
@@ -297,7 +297,7 @@ module Fast
     # @return [void]
     def partial_replace(*indices)
       replacement = experiment.replacement
-      new_content = Fast.replace_file @file, experiment.expression do |node, *captures|
+      new_content = Fast.replace_file experiment.expression, @file do |node, *captures|
         if indices.nil? || indices.empty? || indices.include?(match_index)
           if replacement.parameters.length == 1
             instance_exec node, &replacement

data/lib/fast/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ffast
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Jônatas Davi Paganini
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-26 00:00:00.000000000 Z
+date: 2019-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: astrolabe