ffast 0.2.0 → 0.2.3

data/README.md

@@ -12,6 +12,20 @@ the code was written without an AST.
 
 Check out the official documentation: https://jonatas.github.io/fast.
 
+## Documentation locally
+
+The documentation site is built with MkDocs Material and a few Markdown
+extensions. To run it locally:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -r requirements-docs.txt
+mkdocs serve
+```
+
+Then open `http://127.0.0.1:8000`.
+
 ## Token Syntax for `find` in AST
 
 The current version of Fast covers the following token elements:
@@ -53,48 +67,64 @@ to represent code called `s-expressions`.
 
 For example, let's take an `Integer` in Ruby:
 
-    1
+```ruby
+1
+```
 
-It's corresponding s-expression would be:
+Its corresponding s-expression would be:
 
-    s(:int, 1)
+```ruby
+s(:int, 1)
+```
 
-`s` in `Fast` and `Parser` are a shorthand for creating an `Parser::AST::Node`.
+`s` in `Fast` is a shorthand for creating a `Fast::Node`.
 Each of these nodes has a `#type` and `#children` contained in it:
 
-    def s(type, *children)
-      Parser::AST::Node.new(type, children)
-    end
+```ruby
+def s(type, *children)
+  Fast::Node.new(type, children: children)
+end
+```
 
 ### Variable Assignments
 
 Now let's take a look at a local variable assignment:
 
-    value = 42
+```ruby
+value = 42
+```
 
 It's corresponding s-expression would be:
 
-    ast = s(:lvasgn, :value, s(:int, 42))
+```ruby
+ast = s(:lvasgn, :value, s(:int, 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`:
 
-    Fast.match? '(lvasgn value (int 42))', ast # => true
+```ruby
+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? '(lvasgn value (int _))', ast # => true
+```ruby
+Fast.match?('(lvasgn value (int _))', ast) # => true
+``` 
 
 ### 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`:
-
-    Fast.match? '(lvasgn value ({float int} _))', ast # => true
+ 
+```ruby
+Fast.match?('(lvasgn value ({float int} _))', ast) # => true
+```
 
 ### All Matching Token
 
@@ -103,28 +133,38 @@ 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? '(lvasgn value ([!str !hash !array] _))', ast # => true
+```ruby
+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? '(lvasgn value ...)', ast # => true
+```ruby
+Fast.match?('(lvasgn value ...)', ast) # => true
+```
 
 We could even match any local variable assignment combining both `_` and `...`:
 
-    Fast.match? '(lvasgn _ ...)', ast # => true
+```ruby
+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?('(lvasgn value $...)', ast) # => [s(:int, 42)]
+```ruby
+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?('(lvasgn $_ $...)', ast) # => [:value, s(:int, 42)]
+```ruby
+Fast.match?('(lvasgn $_ $...)', ast) # => [:value, s(:int, 42)]
+```
 
 > Keep in mind that `_` means something not nil and `...` means a node with
 > children.
@@ -135,44 +175,53 @@ 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.
 
-    def duplicated(method_name)
-      @methods ||= []
-      already_exists = @methods.include?(method_name)
-      @methods << method_name
-      already_exists
-    end
+```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')
+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 `[]`:
 
-    puts Fast.search_file('[ def #debug ]', 'example.rb')
+```ruby
+puts Fast.search_file('[ def #debug ]', 'example.rb')
+```
 
 ### Methods
 
 Let's take a look at a method declaration:
 
-  def my_method
-    call_other_method
-  end
+```ruby
+def my_method
+  call_other_method
+end
+```
 
-It's corresponding s-expression would be:
+Its corresponding s-expression would be:
 
-    ast =
-      s(:def, :my_method,
-        s(:args),
-        s(:send, nil, :call_other_method))
+```ruby
+ast =
+  s(:def, :my_method,
+    s(:args),
+    s(:send, nil, :call_other_method))
+```
 
-Pay close attention to the node `(args)`. We can't use `...` to match it, as it
+Note 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`.
 
@@ -181,45 +230,55 @@ has no children (or arguments in this case), but we _can_ match it with a wildca
 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:
 
-    ast =
+```ruby
+ast =
+  s(:send,
+    s(:send,
       s(:send,
-        s(:send,
-          s(:send,
-            s(:send, nil, :a),
-            :b),
-          :c),
-        :d)
+        s(:send, nil, :a),
+        :b),
+      :c),
+    :d)
+```
 
 ### Alternate Syntax
 
 You can also search using nested arrays with **pure values**, or **shortcuts** or
 **procs**:
 
-    Fast.match? [:send, [:send, '...'], :d], ast  # => true
-    Fast.match? [:send, [:send, '...'], :c], ast  # => false
+```ruby
+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?([
-      :send, [
-        -> (node) { node.type == :send },
-        [:send, '...'],
-        :c
-      ],
-      :d
-    ], ast) # => true
+```ruby
+Fast.match?([
+  :send, [
+    -> (node) { node.type == :send },
+    [:send, '...'],
+    :c
+  ],
+  :d
+], ast) # => true
+```
 
 This also works with expressions:
 
-    Fast.match?('(send (send (send (send nil $_) $_) $_) $_)', ast) # => [:a, :b, :c, :d]
+```ruby
+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?([:int, 1], s(:int, 1)) }
+```ruby
+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:
@@ -233,61 +292,83 @@ 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? '(lvasgn %1 (int _))', ('a = 1'), :a  # => true
+```ruby
+Fast.match? '(lvasgn %1 (int _))', ('a = 1'), :a  # => true
+```
 
 ## Using previous captures in search
 
 Imagine you're looking for a method that is just delegating something to
 another method, like this `name` method:
 
-    def name
-      person.name
-    end
+```ruby
+def name
+  person.name
+end
+```
 
 This can be represented as the following AST:
 
-    (def :name
-      (args)
-      (send
-        (send nil :person) :name))
+```
+(def :name
+  (args)
+  (send
+    (send nil :person) :name))
+```
 
 We can create a query that searches for such a method:
 
-    Fast.match?('(def $_ ... (send (send nil _) \1))', ast) # => [:name]
+```ruby
+Fast.match?('(def $_ ... (send (send nil _) \1))', ast) # => [:name]
+```
+    
 
 ## Fast.search
 
 Search allows you to go search the entire AST, collecting nodes that matches given
 expression. Any matching node is then returned:
 
-    Fast.search('(int _)', Fast.ast('a = 1')) # => s(:int, 1)
+```ruby
+Fast.search('(int _)', Fast.ast('a = 1')) # => s(:int, 1)
+```
 
 If you use captures along with a search, both the matching nodes and the
 captures will be returned:
 
-    Fast.search('(int $_)', Fast.ast('a = 1')) # => [s(:int, 1), 1]
+```ruby
+Fast.search('(int $_)', Fast.ast('a = 1')) # => [s(:int, 1), 1]
+```
+    
 
 You can also bind external parameters from the search:
 
-    Fast.search('(int %1)', Fast.ast('a = 1'), 1) # => [s(:int, 1)]
+```ruby
+Fast.search('(int %1)', Fast.ast('a = 1'), 1) # => [s(:int, 1)]
+```
 
 ## Fast.capture
 
 To only pick captures and ignore the nodes, use `Fast.capture`:
 
-  Fast.capture('(int $_)', Fast.ast('a = 1')) # => 1
+```ruby
+Fast.capture('(int $_)', Fast.ast('a = 1')) # => 1
+```
 
 ## Fast.replace
 
 Let's consider the following example:
 
-    def name
-      person.name
-    end
+```ruby
+def name
+  person.name
+end
+```
 
 And, we want to replace code to use `delegate` in the expression:
 
-    delegate :name, to: :person
+```ruby
+delegate :name, to: :person
+```
 
 We already target this example using `\1` on 
 [Search and refer to previous capture](#using-previous-captures-in-search) and
@@ -297,59 +378,73 @@ The [Fast.replace](Fast#replace-class_method) yields a #{Fast::Rewriter} context
 The internal replace method accepts a range and every `node` have
 a `location` with metadata about ranges of the node expression.
 
-    ast = Fast.ast("def name; person.name end")
-    # => s(:def, :name, s(:args), s(:send, s(:send, nil, :person), :name))
+```ruby
+ast = Fast.ast("def name; person.name end")
+# => s(:def, :name, s(:args), s(:send, s(:send, nil, :person), :name))
+```
 
 Generally, we  use the `location.expression`:
 
-    ast.location.expression # => #<Parser::Source::Range (string) 0...25>
+```ruby
+ast.location.expression # => #<Fast::Source::Range (string) 0...25>
+```
 
 But location also brings some metadata about specific fragments:
 
-    ast.location.instance_variables
-    # => [:@keyword, :@operator, :@name, :@end, :@expression, :@node]
+```ruby
+ast.location.instance_variables # => [:@keyword, :@operator, :@name, :@end, :@expression, :@node]
+```
 
 Range for the keyword that identifies the method definition:
-
-    ast.location.keyword # => #<Parser::Source::Range (string) 0...3>
+```ruby
+ast.location.keyword # => #<Fast::Source::Range (string) 0...3>
+```
 
 You can always pick the source of a source range:
 
-    ast.location.keyword.source # => "def"
+```ruby
+ast.location.keyword.source # => "def"
+```
 
 Or only the method name:
 
-    ast.location.name # => #<Parser::Source::Range (string) 4...8>
-    ast.location.name.source # => "name"
+```ruby
+ast.location.name # => #<Fast::Source::Range (string) 4...8>
+ast.location.name.source # => "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 '(def $_ ... (send (send nil $_) \1))', ast do |node, captures|
-      attribute, object = captures
-
-      replace(
-        node.location.expression,
-        "delegate :#{attribute}, to: :#{object}"
-      )
-    end
+```ruby
+Fast.replace '(def $_ ... (send (send nil $_) \1))', ast do |node, captures|
+  attribute, object = captures
 
+  replace(
+    node.location.expression,
+    "delegate :#{attribute}, to: :#{object}"
+  )
+end
+```
 
 ### Replacing file
 
 Now let's imagine we have a file like `sample.rb` with the following code:
 
-    def good_bye
-      message = ["good", "bye"]
-      puts message.join(' ')
-    end
+```ruby
+def good_bye
+  message = ["good", "bye"]
+  puts message.join(' ')
+end
+```
 
 and we decide to inline the contents of the `message` variable right after
 
-    def good_bye
-      puts ["good", "bye"].join(' ')
-    end
-
+```ruby
+def good_bye
+  puts ["good", "bye"].join(' ')
+end
+```
 
 To refactor and reach the proposed example, follow a few steps:
 
@@ -359,22 +454,24 @@ To refactor and reach the proposed example, follow a few steps:
 
 #### Entire example
 
-    assignment = nil
-    Fast.replace_file '({ lvasgn lvar } message )', 'sample.rb' do |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
-    end 
+```ruby
+assignment = nil
+Fast.replace_file '({ lvasgn lvar } message )', 'sample.rb' do |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
+end 
+```
 
 Keep in mind the current example returns a content output but do not rewrite the
 file.
@@ -386,14 +483,17 @@ To manipulate ruby files, sometimes you'll need some extra tasks.
 ## Fast.ast_from_file(file)
 
 This method parses code from a file and loads it into an AST representation.
-
-    Fast.ast_from_file('sample.rb')
+```ruby
+Fast.ast_from_file('sample.rb')
+```
 
 ## Fast.search_file
 
 You can use `search_file` to for search for expressions inside files.
 
-    Fast.search_file(expression, 'file.rb')
+```ruby
+Fast.search_file(expression, 'file.rb')
+```
 
 It's a combination of `Fast.ast_from_file` with `Fast.search`.
 
@@ -401,15 +501,22 @@ It's a combination of `Fast.ast_from_file` with `Fast.search`.
 
 You can use `Fast.capture_file` to only return captures:
 
-    Fast.capture_file('(class (const nil $_))', 'lib/fast.rb')
-    # => [:Rewriter, :ExpressionParser, :Find, :FindString, ...]
+```ruby
+Fast.capture_file('(class (const nil $_))', 'lib/fast.rb')
+# => [:Rewriter, :ExpressionParser, :Find, :FindString, ...]
+```
 
 ## Fast.ruby_files_from(arguments)
 
 The `Fast.ruby_files_from(arguments)` can get all ruby files from file list or folders:
 
-    Fast.ruby_files_from('lib') 
-    # => ["lib/fast/experiment.rb", "lib/fast/cli.rb", "lib/fast/version.rb", "lib/fast.rb"]
+```ruby
+Fast.ruby_files_from('lib') 
+# => ["lib/fast/experiment.rb", "lib/fast/cli.rb", "lib/fast/version.rb", "lib/fast.rb"]
+```
+
+> Note: it doesn't support glob special selectors like `*.rb` or `**/*` as it
+> recursively looks for ruby files in the givem params.
 
 ## `fast` in the command line
 
@@ -532,19 +639,21 @@ from our specs.
 
 If the spec still pass we can confidently say that the hook is useless.
 
-    Fast.experiment("RSpec/RemoveUselessBeforeAfterHook") do
-      # Lookup our spec files
-      lookup 'spec'
+```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}))"
+  # Look for every block starting with before or after
+  search "(block (send nil {before after}))"
 
-      # Remove those blocks
-      edit { |node| remove(node.loc.expression) }
+  # 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
+  # Create a new file, and run RSpec against that new file
+  policy { |new_file| system("bin/spring rspec --fail-fast #{new_file}") }
+end
+```
 
 - `lookup` can be used to pass in files or folders.
 - `search` contains the expression you want to match
@@ -578,7 +687,10 @@ 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
-    code("a = 1") # => s(:lvasgn, s(:int, 1))
+
+```ruby
+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 [rubygems.org](https://rubygems.org).
 

data/bin/console

@@ -3,15 +3,20 @@
 
 require 'bundler/setup'
 require 'fast'
+require 'fast/sql'
 
 def s(type, *children)
-  Parser::AST::Node.new(type, children)
+  Fast::Node.new(type, children: children)
 end
 
 def code(string)
   Fast.ast(string)
 end
 
+def sql(string)
+  Fast.parse_sql(string)
+end
+
 def reload!
   load 'lib/fast.rb'
 end

data/bin/fast-experiment

@@ -8,6 +8,7 @@ require 'fast/experiment'
 require 'coderay'
 
 arguments = ARGV
+autoclean = arguments.delete('--autoclean')
 
 experiment_files = Fast.ruby_files_from(File.expand_path('../experiments', __dir__))
 experiment_files.each(&method(:require))
@@ -23,6 +24,7 @@ end
 if arguments.any?
   ruby_files = arguments.all? { |e| File.exist?(e) && e.end_with?('.rb') }
   experiments.each do |experiment|
+    experiment.autoclean = autoclean
     if ruby_files
       experiment.files = arguments
     else
@@ -30,4 +32,5 @@ if arguments.any?
     end
   end
 end
+experiments.each { |experiment| experiment.autoclean = autoclean }
 experiments.each(&:run)

data/bin/fast-mcp

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../../lib', __FILE__))
+require 'fast/mcp_server'
+
+Fast::McpServer.run!