ffast 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8e1cdbb944bd8939745c07350aaa66e4ff3e9e3313802ca23aaa7fbd33b742d
-  data.tar.gz: fcd59e90fedc893492aa791e129d18a8b2e2e72e72b8ca61be6be8fd3e4ad6b7
+  metadata.gz: e6f6f652de04a7f59c26a9556d136e8992f6cc5631b12a3b4a28d9e6f5784d1a
+  data.tar.gz: 62ae2e2bf65a375c78b2d81ac52247b2b5a60a38557540b9e0b0179cc6010e10
 SHA512:
-  metadata.gz: f33ebcf4e4275e783d75a761b78fc54a70f789f89ea735011a5a5628c7d2f8630271e29436aa1d3a15418f4186fc42764fad3ca5d72ef69bf2ccc860424299a3
-  data.tar.gz: ab1c3275a3415aba183ac6e558284d4f30bb5e462454758808df430059f077eb141f18a8ec725ad7738e1e9e3fd350688d674f6691a4d6165e17f039db34c653
+  metadata.gz: 72e1918179ab1b17a292975da6d6a2a673937032c6b924db8994edfb607c98cc80d6542a38a25597d506e23ff0c43f18d4b6a01178623c2c3cd0be982dbc4bb0
+  data.tar.gz: 5f3f02826dcdc0c13f906dfc5480f693c0cd6c5f6bae135a4f5cb99f7ac583a518a68333d562ad1fe61cec55f0dca8627978b81710d4d04507c89d28e9028131

data/README.md

@@ -2,31 +2,34 @@
 
 [![Build Status](https://travis-ci.org/jonatas/fast.svg?branch=master)](https://travis-ci.org/jonatas/fast)
 
-Fast is a "Find AST" tool to help you search in the code abstract syntax tree.
+Fast, short for "Find AST", is a tool to search, prune, and edit Ruby ASTs.
 
-Ruby allow us to do the same thing in a few ways then it's hard to check
-how the code is written.
+Ruby is a flexible language that allows us to write code in multiple different ways
+to achieve the same end result, and because of this it's hard to verify how
+the code was written without an AST.
 
-Check the official documentation: https://jonatas.github.io/fast.
+Check out the official documentation: https://jonatas.github.io/fast.
 
-## Syntax for find in AST
+## Token Syntax for `find` in AST
 
-The current version cover the following elements:
+The current version of Fast covers the following token elements:
 
-- `()` to represent a **node** search
-- `{}` is for **any** matches like **union** conditions with **or** operator
-- `[]` is for **all** matches like **intersect** conditions with **and** operator
-- `$` is for **capture** current expression
-- `_` is **something** not nil
-- `nil` matches exactly **nil**
-- `...` is a **node** with children
-- `^` is to get the **parent node** of an expression
-- `?` is for **maybe**
-- `\1` to use the first **previous captured** element
-- `%1` to bind the first extra argument
-- `""` surround the value with double quotes to match literal strings
+- `()` - represents a **node** search
+- `{}` - looks for **any** element to match, like a **Set** inclusion or `any?` in Ruby
+- `[]` - looks for **all** elements to match, like `all?` in Ruby.
+- `$` - will **capture** the contents of the current expression like a `Regex` group
+- `#<method-name>` - will call `<method-name>` with `node` as param allowing you
+    to build custom rules.
+- `_` - represents any non-nil value, or **something** being present
+- `nil` -  matches exactly **nil**
+- `...` - matches a **node** with children
+- `^` - references the **parent node** of an expression
+- `?` - represents an element which **maybe** present
+- `\1` - represents a substitution for any of the **previously captured** elements
+- `%1` - to bind the first extra argument in an expression
+- `""` - will match a literal string with double quotes
 
-The syntax is inspired on [RuboCop Node Pattern](https://github.com/bbatsov/rubocop/blob/master/lib/rubocop/node_pattern.rb).
+The syntax is inspired by the [RuboCop Node Pattern](https://github.com/bbatsov/rubocop/blob/master/lib/rubocop/node_pattern.rb).
 
 ## Installation
 
@@ -34,21 +37,31 @@ The syntax is inspired on [RuboCop Node Pattern](https://github.com/bbatsov/rubo
 
 ## How it works
 
-The idea is search in abstract tree using a simple expression build with an array:
+### S-Expressions
 
-A simple integer in ruby:
+Fast works by searching the abstract syntax tree using a series of expressions
+to represent code called `s-expressions`.
+
+> `s-expressions`, or symbolic expressions, are a way to represent nested data.
+> They originate from the LISP programming language, and are frequetly used in
+> other languages to represent ASTs.
+
+### Integer Literals
+
+For example, let's take an `Integer` in Ruby:
 
 ```ruby
 1
 ```
 
-Is represented by:
+It's corresponding s-expression would be:
 
 ```ruby
 s(:int, 1)
 ```
 
-Basically `s` represents `Parser::AST::Node` and the node has a `#type` and `#children`.
+`s` in `Fast` and `Parser` are a shorthand for creating an `Parser::AST::Node`.
+Each of these nodes has a `#type` and `#children` contained in it:
 
 ```ruby
 def s(type, *children)
@@ -56,79 +69,138 @@ def s(type, *children)
 end
 ```
 
-A local variable assignment:
+### Variable Assignments
+
+Now let's take a look at a local variable assignment:
 
 ```ruby
 value = 42
 ```
 
-Can be represented with:
+It's corresponding s-expression would be:
 
 ```ruby
 ast = s(:lvasgn, :value, s(:int, 42))
 ```
 
-Now, lets find local variable named `value` with an value `42`:
+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`:
 
 ```ruby
-Fast.match?(ast, '(lvasgn value (int 42))') # true
+Fast.match?(ast, '(lvasgn value (int 42))')
+# => true
 ```
 
-Lets abstract a bit and allow some integer value using `_` as a shortcut:
+### 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:
 
 ```ruby
-Fast.match?(ast, '(lvasgn value (int _))') # true
+Fast.match?(ast, '(lvasgn value (int _))')
+# => true
 ```
 
-Lets abstract more and allow float or integer:
+### Set Inclusion Token
+
+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`:
 
 ```ruby
-Fast.match?(ast, '(lvasgn value ({float int} _))') # true
+Fast.match?(ast, '(lvasgn value ({float int} _))')
+# => true
 ```
 
-Or combine multiple assertions using `[]` to join conditions:
+### All Matching Token
+
+Say we wanted to say what we expect the value's type to _not_ be, we can use the
+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 `!`:
 
 ```ruby
 Fast.match?(ast, '(lvasgn value ([!str !hash !array] _))') # true
 ```
 
-Matches all local variables not string **and** not hash **and** not array.
+### Node Child Token
+
+We can match any node with children by using the child token ( `...` ):
+
+```ruby
+Fast.match?(ast, '(lvasgn value ...)')
+# => true
+```
+
+We could even match any local variable assignment combining both `_` and `...`:
+
+```ruby
+Fast.match?(ast, '(lvasgn _ ...)')
+# => true
+```
+
+### Capturing the Value of an Expression
 
-We can match "a node with children" using `...`:
+You can use `$` to capture the contents of an expression for later use:
 
 ```ruby
-Fast.match?(ast, '(lvasgn value ...)') # true
+Fast.match?(ast, '(lvasgn value $...)')
+# => [s(:int, 42)]
 ```
 
-You can use `$` to capture a node:
+Captures can be used in any position as many times as you want to capture whatever
+information you might need:
 
 ```ruby
-Fast.match?(ast, '(lvasgn value $...)') # => [s(:int, 42)]
+Fast.match?(ast, '(lvasgn $_ $...)')
+# => [:value, s(:int, 42)]
 ```
 
-Or match whatever local variable assignment combining both `_` and `...`:
+> Keep in mind that `_` means something not nil and `...` means a node with
+> children.
+
+### Calling Custom Methods
+
+You can also define custom methods to set more complicated rules. Let's say
+we're looking for duplicated methods in the same class. We need to collect
+method names and guarantee they are unique.
 
 ```ruby
-Fast.match?(ast, '(lvasgn _ ...)') # true
+def duplicated(method_name)
+  @methods ||= []
+  already_exists = @methods.include?(method_name)
+  @methods << method_name
+  already_exists
+end
+
+puts Fast.search_file( '(def #duplicated)', 'example.rb')
 ```
+The same principle can be used in the node level or for debugging purposes.
 
-You can also use captures in any levels you want:
+```ruby
+require 'pry'
+def debug(node)
+  binding.pry
+end
 
+puts Fast.search_file('#debug', 'example.rb')
+```
+If you want to get only `def` nodes you can also intersect expressions with `[]`:
 ```ruby
-Fast.match?(ast, '(lvasgn $_ $...)') # [:value, s(:int, 42)]
+puts Fast.search_file('[ def #debug ]', 'example.rb')
 ```
 
-Keep in mind that `_` means something not nil and `...` means a node with
-children.
+### Methods
 
-Then, if do you get a method declared:
+Let's take a look at a method declaration:
 
 ```ruby
 def my_method
   call_other_method
 end
 ```
-It will be represented with the following structure:
+
+It's corresponding s-expression would be:
 
 ```ruby
 ast =
@@ -137,13 +209,14 @@ ast =
     s(:send, nil, :call_other_method))
 ```
 
-Keep an eye on the node `(args)`.
+Pay close attention to the node `(args)`. We can't use `...` to match it, as it
+has no children (or arguments in this case), but we _can_ match it with a wildcard
+`_` as it's not `nil`.
 
-Then you know you can't use `...` but you can match with `(_)` to match with
-such case.
+### Call Chains
 
-Let's test a few other examples. You can go deeply with the arrays. Let's suppose we have a hardcore call to
-`a.b.c.d` and the following AST represents it:
+Let's take a look at a few other examples. Sometimes you have a chain of calls on
+a single `Object`, like `a.b.c.d`. Its corresponding s-expression would be:
 
 ```ruby
 ast =
@@ -156,59 +229,79 @@ ast =
     :d)
 ```
 
-You can search using sub-arrays with **pure values**, or **shortcuts** or
+### Alternate Syntax
+
+You can also search using nested 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?(ast, [:send, [:send, '...'], :d])
+# => true
+
+Fast.match?(ast, [:send, [:send, '...'], :c])
+# => false
+
+Fast.match?(ast, [:send, [:send, [:send, '...'], :c], :d])
+# => true
 ```
 
-Shortcuts like `...` and `_` are just literals for procs. Then you can use
-procs directly too:
+Shortcut tokens like child nodes `...` and wildcards `_` are just placeholders
+for procs. If you want, you can even use procs directly like so:
 
 ```ruby
-Fast.match?(ast, [:send, [ -> (node) { node.type == :send }, [:send, '...'], :c], :d]) # => true
+Fast.match?(ast, [
+  :send, [
+    -> (node) { node.type == :send },
+    [:send, '...'],
+    :c
+  ],
+  :d
+])
+# => true
 ```
 
-And also work with expressions:
+This also works with expressions:
 
 ```ruby
 Fast.match?(
   ast,
   '(send (send (send (send nil $_) $_) $_) $_)'
-) # => [:a, :b, :c, :d]
+)
+# => [:a, :b, :c, :d]
 ```
 
-If something does not work you can debug with a block:
+### Debugging
+
+If you find that a particular expression isn't working, you can use `debug` to
+take a look at what Fast is doing:
 
 ```ruby
 Fast.debug { Fast.match?(s(:int, 1), [:int, 1]) }
 ```
 
-It will output each comparison to stdout:
+Each comparison made while searching will be logged to your console (STDOUT) as
+Fast goes through the AST:
 
 ```
 int == (int 1) # => true
 1 == 1 # => true
 ```
-## Bind arguments to expressions
 
-Sometimes we need to define useful functions and bind arguments that will be
-based on dynamic decisions or other external input.
-For such cases you can bind the arguments with `%` and the index start from `1`.
+## Bind arguments to expressions
 
-Example:
+We can also dynamically interpolate arguments into our queries using the
+interpolation token `%`. This works much like `sprintf` using indexes starting
+from `1`:
 
 ```ruby
-Fast.match?(code['a = 1'], '(lvasgn %1 (int _))', :a) # true
+Fast.match?(code('a = 1'), '(lvasgn %1 (int _))', :a)
+# => true
 ```
 
-## Use previous captures in search
+## Using previous captures in search
 
 Imagine you're looking for a method that is just delegating something to
-another method, like:
+another method, like this `name` method:
 
 ```ruby
 def name
@@ -225,54 +318,68 @@ This can be represented as the following AST:
     (send nil :person) :name))
 ```
 
-Then, let's build a search for methods that calls an attribute with the same
-name:
+We can create a query that searches for such a method:
 
 ```ruby
-Fast.match?(ast,'(def $_ ... (send (send nil _) \1))') # => [:name]
+Fast.match?(ast,'(def $_ ... (send (send nil _) \1))')
+# => [:name]
 ```
 
 ## Fast.search
 
-Search allows you to go deeply in the AST, collecting nodes that matches with
-the expression. It also returns captures if they exist.
+Search allows you to go search the entire AST, collecting nodes that matches given
+expression. Any matching node is then returned:
 
 ```ruby
-Fast.search(code('a = 1'), '(int _)') # => s(:int, 1)
+Fast.search(code('a = 1'), '(int _)')
+# => s(:int, 1)
 ```
 
-If you use captures, it returns the node and the captures respectively:
+If you use captures along with a search, both the matching nodes and the
+captures will be returned:
 
 ```ruby
-Fast.search(code('a = 1'), '(int $_)') # => [s(:int, 1), 1]
+Fast.search(code('a = 1'), '(int $_)')
+# => [s(:int, 1), 1]
 ```
 
 ## Fast.capture
 
-To pick just the captures and ignore the nodes, use `Fast.capture`:
+To only pick captures and ignore the nodes, use `Fast.capture`:
 
 ```ruby
-Fast.capture(code('a = 1'), '(int $_)') # => 1
+Fast.capture(code('a = 1'), '(int $_)')
+# => 1
 ```
 ## Fast.replace
 
-And if I want to refactor a code and use `delegate <attribute>, to: <object>`, try with replace:
+<!--
+  Not sure how this section works, could you explain it in more detail?
+
+  It looks to capture the name of a method, and then not sure from there. Can
+  you provide an example AST to use there?
+
+  Delegate might be too dense of an example to use.
+-->
+
+If we want to replace code, we can use a delegate expression:
 
 ```ruby
-Fast.replace ast,
-  '(def $_ ... (send (send nil $_) \1))',
-  -> (node, captures) {
-    attribute, object = captures
-    replace(
-      node.location.expression,
-      "delegate :#{attribute}, to: :#{object}"
-    )
-  }
+query = '(def $_ ... (send (send nil $_) \1))'
+
+Fast.replace ast, query, -> (node, captures) {
+  attribute, object = captures
+
+  replace(
+    node.location.expression,
+    "delegate :#{attribute}, to: :#{object}"
+  )
+}
 ```
 
 ### Replacing file
 
-Now let's imagine we have real files like `sample.rb` with the following code:
+Now let's imagine we have a file like `sample.rb` with the following code:
 
 ```ruby
 def good_bye
@@ -281,33 +388,45 @@ def good_bye
 end
 ```
 
-And we decide to remove the `message` variable and put it inline with the `puts`.
+...and we decide to inline the contents of the `message` variable right after
+`puts`.
+
 
-Basically, we need to find the local variable assignment, store the value in
-memory. Remove the assignment expression and use the value where the variable
-is being called.
+To do this we would need to:
+
+* Remove the local variable assignment
+* Store the now-removed variable's value
+* Substitute the value where the variable was used before
 
 ```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
-  }
-)
+query = '({ lvasgn lvar } message )'
+
+Fast.replace_file('sample.rb', query, -> (node, _) {
+  # Find a variable assignment
+  if node.type == :lvasgn
+    assignment = node.children.last
+
+    # Remove the node responsible for the assignment
+    remove(node.location.expression)
+  # Look for the variable being used
+  elsif node.type == :lvar
+    # Replace the variable with the contents of the variable
+    replace(
+      node.location.expression,
+      assignment.location.expression.source
+    )
+  end
+})
 ```
 
 ## Other useful functions
 
-To manipulate ruby files, some times you'll need some extra tasks.
+To manipulate ruby files, sometimes you'll need some extra tasks.
 
 ## Fast.ast_from_File(file)
 
-This method parses the code and load into a AST representation.
+This method parses code from a file and loads it into an AST representation.
 
 ```ruby
 Fast.ast_from_file('sample.rb')
@@ -315,20 +434,17 @@ Fast.ast_from_file('sample.rb')
 
 ## Fast.search_file
 
-You can use `search_file` and pass the path for search for expressions inside
-files.
+You can use `search_file` to for search for expressions inside files.
 
 ```ruby
 Fast.search_file(expression, 'file.rb')
 ```
 
-It's simple combination of `Fast.ast_from_file` with `Fast.search`.
-
+It's a combination of `Fast.ast_from_file` with `Fast.search`.
 
 ## Fast.capture_file
 
-You can also use `Fast.capture_file` that is similar but return only the
-captures:
+You can use `Fast.capture_file` to only return captures:
 
 ```ruby
  Fast.capture_file('(class (const nil $_))', 'lib/fast.rb')
@@ -337,36 +453,46 @@ captures:
 
 ## Fast.ruby_files_from(arguments)
 
-You'll be probably looking for multiple ruby files, then this method fetches
-all internal `.rb` files 
+`Fast.ruby_files_from(arguments)` can get all Ruby files in a location:
 
 ```ruby
-Fast.ruby_files_from('lib') # => ["lib/fast.rb"]
+Fast.ruby_files_from('lib')
+# => ["lib/fast.rb"]
 ```
 
 ## `fast` in the command line
 
-It will also inject a executable named `fast` and you can use it to search and
-find code using the concept:
+Fast also comes with a command line utility called `fast`. You can use it to
+search and find code much like the library version:
 
 ```
 $ fast '(def match?)' lib/fast.rb
 ```
 
+The CLI tool takes the following flags
+
 - 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
 - Use `-c` to search from code example
 - Use `-s` to search similar code
 
+### Fast with Pry
+
+You can use `--pry` to stop on a particular source node, and run Pry at that
+location:
+
 ```
 $ fast '(block (send nil it))' spec --pry
 ```
-And inside pry session,  you can use `result` as the first result or `results`
-to use all occurrences found.
+
+Inside the pry session you can access `result` for the first result that was
+located, or `results` to get all of the occurrences found.
+
+Let's take a look at `results`:
 
 ```ruby
-results.map{|e|e.children[0].children[2]}
+results.map { |e| e.children[0].children[2] }
 # => [s(:str, "parses ... as Find"),
 # s(:str, "parses $ as Capture"),
 # s(:str, "parses quoted values as strings"),
@@ -374,9 +500,16 @@ results.map{|e|e.children[0].children[2]}
 # s(:str, "parses [] as All"), ...]
 ```
 
-Getting all `it` blocks without description:
+### Fast with RSpec
+
+Let's say we wanted to get all the `it` blocks in our `RSpec` code that
+currently do not have descriptions:
 
-    $ fast '(block (send nil it (nil)) (args ) (!str)) ) )' spec
+```
+$ fast '(block (send nil it (nil)) (args) (!str)) ) )' spec
+```
+
+This will return the following:
 
 ```ruby
 # spec/fast_spec.rb:166
@@ -390,31 +523,44 @@ it { expect(described_class).to be_match(code['"string"'], '(str "string")') }
 
 ## Experiments
 
-You can define experiments and build experimental research to improve some code in
-an automated way.
+Experiments can be used to run experiments against your code in an automated
+fashion. These experiments can be used to test the effectiveness of things
+like performance enhancements, or if a replacement piece of code actually works
+or not.
+
+Let's create an experiment to try and remove all `before` and `after` blocks
+from our specs.
 
-Let's create an experiment to try to remove `before` or `after` blocks
-and run specs. If the spec pass without need the hook, the hook is useless.
+If the spec still pass we can confidently say that the hook is useless.
 
 ```ruby
 Fast.experiment("RSpec/RemoveUselessBeforeAfterHook") do
+  # Lookup our spec files
   lookup 'spec'
+
+  # Look for every block starting with before or after
   search "(block (send nil {before after}))"
-  edit {|node| remove(node.loc.expression) }
-  policy {|new_file| system("bin/spring rspec --fail-fast #{new_file}") }
+
+  # Remove those blocks
+  edit { |node| remove(node.loc.expression) }
+
+  # Create a new file, and run RSpec against that new file
+  policy { |new_file| system("bin/spring rspec --fail-fast #{new_file}") }
 end
 ```
 
-- In the `lookup` you can pass files or folders.
-- The `search` contains the expression you want to match
-- With `edit` block you can apply the code change
-- And the `policy` is executed to check if the current change is valuable
+- `lookup` can be used to pass in files or folders.
+- `search` contains the expression you want to match
+- `edit` is used to apply code change
+- `policy` is what we execute to verify the current change still passes
+
+Each removal of a `before` and `after` block will occur in isolation to verify
+each one of them independently of the others. Each successful removal will be
+kept in a secondary change until we run out of blocks to remove.
 
-If the file contains multiple `before` or `after` blocks, each removal will
-occur independently and the successfull removals will be combined as a
-secondary change. The process repeates until find all possible combinations.
+You can see more examples in the [experiments](experiments) folder.
 
-See more examples in [experiments](experiments) folder.
+### Running Multiple Experiments
 
 To run multiple experiments, use `fast-experiment` runner:
 
@@ -422,7 +568,7 @@ To run multiple experiments, use `fast-experiment` runner:
 fast-experiment <experiment-names> <files-or-folders>
 ```
 
-You can limit experiments or file escope:
+You can limit the scope of experiments:
 
 ```
 fast-experiment RSpec/RemoveUselessBeforeAfterHook spec/models/**/*_spec.rb
@@ -434,7 +580,9 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 On the console we have a few functions like `s` and `code` to make it easy ;)
 
-    $ bin/console
+```
+$ bin/console
+```
 
 ```ruby
 code("a = 1") # => s(:lvasgn, s(:int, 1))
@@ -446,10 +594,8 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/jonatas/fast. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
-
 See more on the [official documentation](https://jonatas.github.io/fast).

data/docs/pry-integration.md

@@ -21,7 +21,7 @@ end
 
 And use it in the console:
 
-`pry
-fast '(def match?)' lib/fast.rb`
+```pry
+fast '(def match?)' lib/fast.rb
 ```
 

data/docs/syntax.md

@@ -368,3 +368,38 @@ ANSWER = 42
 ANSWER
 ```
 
+## Calling 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
+method names and guarantee they are unique.
+
+```ruby
+def duplicated(method_name)
+  @methods ||= []
+  already_exists = @methods.include?(method_name)
+  @methods << method_name
+  already_exists
+end
+
+puts Fast.search_file( '(def #duplicated)', 'example.rb')
+```
+The same principle can be used in the node level or for debugging purposes.
+
+```ruby
+require 'pry'
+def debug(node)
+  binding.pry
+end
+
+puts Fast.search_file('#debug', 'example.rb')
+```
+If you want to get only `def` nodes you can also intersect expressions with `[]`:
+```ruby
+puts Fast.search_file('[ def #debug ]', 'example.rb')
+```
+Or if you want to debug a very specific expression you can use `()` to specify
+more details of the node
+```ruby
+puts Fast.search_file('[ (def a) #debug ]', 'example.rb')
+```

data/examples/search_duplicated.rb

@@ -0,0 +1,15 @@
+require 'fast'
+
+# Search for duplicated methods interpolating the method and collecting previous
+# method names. Returns true if the name already exists in the same class level.
+# Note that this example will work only in a single file because it does not
+# cover any detail on class level.
+def duplicated(method_name)
+  @methods ||= []
+  already_exists = @methods.include?(method_name)
+  @methods << method_name
+  already_exists
+end
+
+puts Fast.search_file( '(def #duplicated)', 'example.rb')
+

data/lib/fast/version.rb

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

data/lib/fast.rb

@@ -54,6 +54,8 @@ module Fast
     |
     \$                    # capture
     |
+    \#\w[\d\w_]+[\\!\?]?  # custom method call
+    |
     \\\d                  # find using captured expression
     |
     %\d                   # find using binded argument
@@ -258,6 +260,7 @@ module Fast
       when '{' then Any.new(parse_until_peek('}'))
       when '[' then All.new(parse_until_peek(']'))
       when /^"/ then FindString.new(token[1..-2])
+      when /^#\w/ then MethodCall.new(token[1..-1])
       when '$' then Capture.new(parse)
       when '!' then (@tokens.any? ? Not.new(parse) : Find.new(token))
       when '?' then Maybe.new(parse)
@@ -375,6 +378,17 @@ module Fast
     end
   end
 
+  # Find using custom methods
+  class MethodCall < Find
+    def initialize(method_name)
+      @method_name = method_name
+    end
+
+    def match?(node)
+      Kernel.send(@method_name, node)
+    end
+  end
+
   # Allow use previous captures while searching in the AST.
   # Use `\\1` to point the match to the first captured element
   class FindWithCapture < Find

data/mkdocs.yml

@@ -17,6 +17,6 @@ nav:
   - Introduction: index.md
   - Syntax: syntax.md
   - Command Line: command_line.md
-  - Pry Integration: pry-integration.md
   - Experiments: experiments.md
   - Code Similarity: similarity_tutorial.md
+  - Pry Integration: pry-integration.md

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ffast
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Jônatas Davi Paganini
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-05 00:00:00.000000000 Z
+date: 2019-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: coderay
@@ -213,6 +213,7 @@ files:
 - examples/find_usage.rb
 - examples/let_it_be_experiment.rb
 - examples/method_complexity.rb
+- examples/search_duplicated.rb
 - examples/similarity_research.rb
 - experiments/let_it_be_experiment.rb
 - experiments/remove_useless_hook.rb