Find in AST - Search for code directly in Abstract Syntax Tree with a flexible pattern
Ruby Shell
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build Status

Fast is a "Find AST" tool to help you search in the code abstract syntax tree.

Ruby allow us to do the same thing in a few ways then it's hard to check how the code is written.

Syntax for find in AST

The current version cover the following 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
  • "" surround the value with double quotes to match literal strings

The syntax is inspired on RuboCop Node Pattern.


Add this line to your application's Gemfile:

gem 'ffast'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ffast

How it works

The idea is search in abstract tree using a simple expression build with an array:

A simple integer in ruby:


Is represented by:

s(:int, 1)

Basically s represents Parser::AST::Node and the node has a #type and #children.

def s(type, *children), children)

A local variable assignment:

value = 42

Can be represented with:

ast = s(:lvasgn, :value, s(:int, 42))

Now, lets find local variable named value with an value 42:

Fast.match?(ast, '(lvasgn value (int 42))') # true

Lets abstract a bit and allow some integer value using _ as a shortcut:

Fast.match?(ast, '(lvasgn value (int _))') # true

Lets abstract more and allow float or integer:

Fast.match?(ast, '(lvasgn value ({float int} _))') # true

Or combine multiple assertions using [] to join conditions:

Fast.match?(ast, '(lvasgn value ([!str !hash !array] _))') # true

Matches all local variables not string and not hash and not array.

We can match "a node with children" using ...:

Fast.match?(ast, '(lvasgn value ...)') # true

You can use $ to capture a node:

Fast.match?(ast, '(lvasgn value $...)') # => [s(:int, 42)]

Or match whatever local variable assignment combining both _ and ...:

Fast.match?(ast, '(lvasgn _ ...)') # true

You can also use captures in any levels you want:

Fast.match?(ast, '(lvasgn $_ $...)') # [:value, s(:int, 42)]

Keep in mind that _ means something not nil and ... means a node with children.

Then, if do you get a method declared:

def my_method

It will be represented with the following structure:

ast =
  s(:def, :my_method,
    s(:send, nil, :call_other_method))

Keep an eye on the node (args).

Then you know you can't use ... but you can match with (_) to match with such case.

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:

ast =
        s(:send, nil, :a),

You can search using sub-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

Shortcuts like ... and _ are just literals for procs. Then you can use procs directly too:

Fast.match?(ast, [:send, [ -> (node) { node.type == :send }, [:send, '...'], :c], :d]) # => true

And also work with expressions:

  '(send (send (send (send nil $_) $_) $_) $_)'
) # => [:a, :b, :c, :d]

If something does not work you can debug with a block:

Fast.debug { Fast.match?(s(:int, 1), [:int, 1]) }

It will output each comparison to stdout:

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:

def name

This can be represented as the following AST:

(def :name
    (send nil :person) :name))

Then, let's build a search for methods that calls an attribute with the same name:

Fast.match?(ast,'(def $_ ... (send (send nil _) \1))') # => [:name]

Search allows you to go deeply in the AST, collecting nodes that matches with the expression. It also returns captures if they exist.'a = 1'), '(int _)') # => s(:int, 1)

If you use captures, it returns the node and the captures respectively:'a = 1'), '(int $_)') # => [s(:int, 1), 1]


To pick just the captures and ignore the nodes, use Fast.capture:

Fast.capture(code('a = 1'), '(int $_)') # => 1


And if I want to refactor a code and use delegate <attribute>, to: <object>, try with replace:

Fast.replace ast,
  '(def $_ ... (send (send nil $_) \1))',
  -> (node, captures) {
    attribute, object = captures
      "delegate :#{attribute}, to: :#{object}"

Replacing file

Now let's imagine we have real files like sample.rb with the following code:

def good_bye
  message = ["good", "bye"]
  puts message.join(' ')

And we decide to remove the message variable and put it inline with the 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.

assignment = nil
Fast.replace_file('sample.rb', '({ lvasgn lvar } message )',
  -> (node, _) {
    if node.type == :lvasgn
      assignment = node.children.last
    elsif node.type == :lvar
      replace(node.location.expression, assignment.location.expression.source)

Other useful functions

To manipulate ruby files, some times you'll need some extra tasks.


This method parses the code and load into a AST representation.



You can use search_file and pass the path for search for expressions inside files.

Fast.search_file('file.rb', expression)

It's simple combination of Fast.ast_from_file with


You'll be probably looking for multiple ruby files, then this method fetches all internal .rb files

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 '(def match?)' lib/fast.rb
  • Use -d or --debug for enable debug mode.
  • Use --ast to output the AST instead of the original code


You can define experiments and build experimental research to improve some code in an automated way.

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.

Fast.experiment("RSpec/RemoveUselessBeforeAfterHook") do
  lookup 'spec'
  search "(block (send nil {before after}))"
  edit {|node| remove(node.loc.expression) }
  policy {|new_file| system("bin/spring rspec --fail-fast #{new_file}") }
  • 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

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.

See more examples in experiments folder.

To run multiple experiments, use fast-experiment runner:

fast-experiment <experiment-names> <files-or-folders>

You can limit experiments or file escope:

fast-experiment RSpec/RemoveUselessBeforeAfterHook spec/models/**/*_spec.rb


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

On the console we have a few functions like s and code to make it easy ;)

$ bin/console

code("a = 1") # => s(:lvasgn, s(:int, 1))

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


The gem is available as open source under the terms of the MIT License.