ffast 0.2.2 → 0.2.3

data/docs/sql-support.md

@@ -1,253 +0,0 @@
-# SQL Support
-
-Fast is partially supporting SQL syntax. Behind the scenes it parses SQL using
-[pg_query](https://github.com/pganalyze/pg_query) and simplifies it to AST Nodes
-using the same interface. It's using Postgresql parser behind the scenes,
-but probably could be useful for other SQL similar diallects.
-
-
-!!! info "fast auto detects SQL files in the command line"
-
-    By default, this module is not included into the main library.
-    Fast can auto-detect file extensions and choose the sql path in case the
-    file relates to sql.
-
-    Use `fast --sql` in case you want to force the usage of the SQL parser.
-
-    ```
-
-    ```
-
-
-# Parsing a sql content
-
-```ruby
-require 'fast/sql'
-ast = Fast.parse_sql('select 1')
-# => s(:select_stmt,
-#     s(:target_list,
-#       s(:res_target,
-#         s(:val,
-#           s(:a_const,
-#             s(:val,
-#               s(:integer,
-#                 s(:ival, 1))))))))
-```
-
-## Why it's interesting to use AST for SQL?
-
-Both SQL are available and do the same thing:
-```sql
-select * from customers
-```
-or
-```sql
-table customers
-```
-
-they have exactly the same objective but written down in very different syntax.
-
-Give a try:
-
-```ruby
-Fast.parse_sql("select * from customers") == Fast.parse_sql("table customers") # => true
-```
-
-## Match
-
-Use `match?` with your node pattern to traverse the abstract syntax tree.
-
-```ruby
- Fast.match?("(select_stmt ...)", ast) # => true
-```
-
-Use `$` to capture elements from the AST:
-
-```ruby
- Fast.match?("(select_stmt $...)", ast)
-=> [s(:target_list,
-  s(:res_target,
-    s(:val,
-      s(:a_const,
-        s(:val,
-          s(:integer,
-            s(:ival, 1)))))))]
-
-```
-
-You can dig deeper into the AST specifying nodes:
-
-```ruby
-Fast.match?("(select_stmt (target_list (res_target (val ($...)))))", ast)
-# => [s(:a_const,
-#     s(:val,
-#       s(:integer,
-#         s(:ival, 1))))]
-```
-
-And ignoring node types or values using `_`. Check all [syntax](/syntax) options.
-
-```ruby
-Fast.match?("(select_stmt (_ (_ (val ($...)))))", ast)
-# => [s(:a_const,
-#     s(:val,
-#       s(:integer,
-#         s(:ival, 1))))]
-```
-
-## Search directly from the AST
-
-You can also search directly from nodes and keep digging:
-
-```ruby
-ast = Fast.parse_sql('select 1');
-ast.search('ival') # => [s(:ival, s(:ival, 1))]
-```
-
-Use first to return the node directly:
-
-```ruby
-ast.first('(ival (ival _))')  #=> s(:ival, s(:ival, 1))
-```
-
-Combine the `capture` method with `$`:
-
-```ruby
-ast.capture('(ival (ival $_))') # => [1]
-```
-
-
-# Examples
-
-Let's dive into a more complex example capturing fields and from clause of a
-condition. Let's start parsing the sql:
-
-## Capturing fields and where clause
-
-
-```ruby
-ast = Fast.parse_sql('select name from customer')
-#   => s(:select_stmt,
-#     s(:target_list,
-#       s(:res_target,
-#         s(:val,
-#           s(:column_ref,
-#             s(:fields,
-#               s(:string,
-#                 s(:str, "name"))))))),
-#     s(:from_clause,
-#       s(:range_var,
-#         s(:relname, "customer"),
-#         s(:inh, true),
-#         s(:relpersistence, "p"))))
-```
-
-Now, let's build the expression to get the fields and from_clause.
-
-```ruby
- cols_and_from = "
-   (select_stmt
-     (target_list (res_target (val (column_ref (fields $...)))))
-     (from_clause (range_var $(relname _))))
-"
-```
-
-Now, we can use `Fast.capture` or `Fast.match?` to extract the values from the
-AST.
-
-```ruby
-Fast.capture(cols_and_from, ast)
-# => [s(:string,
-#     s(:str, "name")), s(:relname, "customer")]
-```
-
-## Search inside
-
-```ruby
-relname = Fast.parse_sql('select name from customer').search('relname').first
-# => s(:relname, "customer")
-```
-
-Find the location of a node.
-
-```ruby
-relname.location # => #<Parser::Source::Map:0x00007fd3bcb0b7f0
-#  @expression=#<Parser::Source::Range (sql) 17...25>,
-#  @node=s(:relname, "customer")>
-```
-
-The location can be useful to allow you to do refactorings and find specific
-delimitations of objects in the string.
-
-The attribute `expression` gives access to the source range.
-
-```ruby
-relname.location.expression
-# => #<Parser::Source::Range (sql) 17...25>
-```
-
-The `source_buffer` is shared and can be accessed through the expression.
-
-```ruby
-relname.location.expression.source_buffer
-# => #<Fast::SQL::SourceBuffer:0x00007fd3bc2a6420
-#    @name="(sql)",
-#    @source="select name from customer",
-#    @tokens=
-#     [<PgQuery::ScanToken: start: 0, end: 6, token: :SELECT, keyword_kind: :RESERVED_KEYWORD>,
-#      <PgQuery::ScanToken: start: 7, end: 11, token: :NAME_P, keyword_kind: :UNRESERVED_KEYWORD>,
-#      <PgQuery::ScanToken: start: 12, end: 16, token: :FROM, keyword_kind: :RESERVED_KEYWORD>,
-#      <PgQuery::ScanToken: start: 17, end: 25, token: :IDENT, keyword_kind: :NO_KEYWORD>]>
-```
-
-The tokens are useful to find the proper node location during the build but
-they're not available for all the nodes, so, it can be very handy as an extra
-reference.
-
-## Replace
-
-Replace fragments of your SQL based on AST can also be done with all the work
-inherited from Parser::TreeRewriter components.
-
-```ruby
-Fast.parse_sql('select 1').replace('ival', '2') # => "select 2"
-```
-
-The previous example is a syntax sugar for the following code:
-
-```ruby
-Fast.replace_sql('ival',
-  Fast.parse_sql('select 1'),
-  &->(node){ replace(node.location.expression, '2') }
-) # => "select 2"
-```
-
-The last argument is a proc that runs on the [parser tree rewriter](https://www.rubydoc.info/gems/parser/Parser/TreeRewriter
-) scope.
-
-Let's break down the previous code:
-
-```ruby
-ast = Fast.parse_sql("select 1")
-#  => s(:select_stmt,
-#    s(:target_list,
-#      s(:res_target,
-#        s(:val,
-#          s(:a_const,
-#            s(:ival,
-#              s(:ival, 1)))))))
-```
-
-The pattern is simply matching node type that is `ival` but it could be a complex expression
-like `(val (a_const (val (ival (ival _)))))`.
-
-Completing the example:
-
-```ruby
- Fast.replace_sql("ival", ast, &-> (n) { replace(n.loc.expression, "3") })
- # => "select 3"
-```
-
-`loc` is a shortcut for `location` attribute.
-
-

data/docs/syntax.md

@@ -1,395 +0,0 @@
-# Syntax
-
-The syntax is inspired on [RuboCop Node Pattern](https://github.com/bbatsov/rubocop/blob/master/lib/rubocop/node_pattern.rb).
-
-You can find a great tutorial about RuboCop node pattern in the
-[official documentation](https://rubocop.readthedocs.io/en/latest/node_pattern/).
-
-## Code example
-
-Let's consider the following `example.rb` code example:
-
-```ruby
-class Example
-  ANSWER = 42
-  def magic
-    rand(ANSWER)
-  end
-  def duplicate(value)
-    value * 2
-  end
-end
-```
-
-Looking the AST representation we have:
-
-    $ ruby-parse example.rb
-
-```
-(class
-  (const nil :Example) nil
-  (begin
-    (casgn nil :ANSWER
-      (int 42))
-    (def :magic
-      (args)
-      (send nil :rand
-        (const nil :ANSWER)))
-    (def :duplicate
-      (args
-        (arg :value))
-      (send
-        (lvar :value) :*
-        (int 2)))))
-```  
-
-Now, let's explore all details of the current AST, combining with the syntax
-operators.
-
-Fast works with a single word that will be the node type.
-
-A simple search of `def` nodes can be done and will also print the code.
-
-    $ fast def example.rb
-
-```ruby
-# example.rb:3
-  def magic
-    rand(ANSWER)
-  end
-```
-
-or check the `casgn` that will show constant assignments:
-
-    $ fast casgn example.rb
-
-```ruby
-# example.rb:2
-ANSWER = 42
-```
-
-## `()` to represent a **node** search
-
-To specify details about a node, the `(` means navigate deeply into a node and
-go deep into the expression.
-
-    $ fast '(casgn' example.rb
-
-```ruby
-# example.rb:2
-ANSWER = 42
-```
-
-Fast matcher never checks the end of the expression and close parens are not
-necessary. We keep them for the sake of specify more node details but the
-expression works with incomplete parens.
-
-    $ fast '(casgn)' example.rb
-
-```ruby
-# example.rb:2
-ANSWER = 42
-```
-
-Closing extra params also don't have a side effect.
-
-    $ fast '(casgn))' example.rb
-
-```ruby
-# example.rb:2
-ANSWER = 42
-```
-
-It also automatically flat parens case you put more levels in the beginning.
-
-    $ fast '((casgn))' example.rb
-
-```ruby
-# example.rb:2
-ANSWER = 42
-```
-
-For checking AST details while doing some search, you can use `--ast` in the
-command line for printing the AST instead of the code:
-
-    $ fast '((casgn ' example.rb --ast
-
-```ruby
-# example.rb:2
-(casgn nil :ANSWER
-  (int 42))
-```
-
-## `_` is **something** not nil
-
-Let's enhance our current expression and specify that we're looking for constant
-assignments of integers ignoring values and constant names replacing with `_`.
-
-    $ fast '(casgn nil _ (int _))' example.rb
-
-```ruby
-# example.rb:2
-ANSWER = 42
-```
-
-Keep in mind that `_` means not nil and  `(casgn _ _ (int  _))` would not
-match.
-
-Let's search for integer nodes:
-
-    $ fast int example.rb
-```ruby
-# example.rb:2
-42
-# example.rb:7
-2
-```
-
-The current search show the nodes but they are not so useful without understand
-the expression in their context. We need to check their `parent`.
-
-## `^` is to get the **parent node** of an expression
-
-By default, Parser::AST::Node  does not have access to parent and for accessing
-it you can say `^` for reaching the parent.
-
-    $ fast '^int' example.rb
-
-```ruby
-# example.rb:2
-ANSWER = 42
-# example.rb:7
-value * 2
-```
-
-And using it multiple times will make the node match from levels up:
-
-    $ fast '^^int' example.rb
-
-```ruby
-# example.rb:2
-ANSWER = 42
-  def magic
-    rand(ANSWER)
-  end
-  def duplicate(value)
-    value * 2
-  end
-```
-
-## `[]` join conditions
-
-Let's hunt for integer nodes that the parent is also a method:
-
-    $ fast '[ ^^int def ]' example.rb
-
-The match will filter only nodes that matches all internal expressions.
-
-```ruby
-# example.rb:6
-def duplicate(value)
-    value * 2
-  end
-```
-
-The expression is matching nodes that have a integer granchild and also with
-type `def`.
-
-## `...` is a **node** with children
-
-Looking the method representation we have:
-
-    $ fast def example.rb --ast
-
-```ruby
-# example.rb:3
-(def :magic
-  (args)
-  (send nil :rand
-    (const nil :ANSWER)))
-# example.rb:6
-(def :duplicate
-  (args
-    (arg :value))
-  (send
-    (lvar :value) :*
-    (int 2)))
-```
-
-And if we want to delimit only methods with arguments:
-
-    $ fast '(def _ ...)' example.rb
-
-```ruby
-# example.rb:6
-def duplicate(value)
-    value * 2
-  end
-```
-
-If we use `(def _ _)` instead it will match both methods because `(args)` 
-does not have children but is not nil.
-
-## `$` is for **capture** current expression
-
-Now, let's say we want to extract some method name from current classes.
-
-In such case we don't want to have the node definition but only return the node
-name.
-
-```ruby
-# example.rb:2
-def magic
-    rand(ANSWER)
-  end
-# example.rb:
-magic
-# example.rb:9
-def duplicate(value)
-    value * 2
-  end
-# example.rb:
-duplicate
-```
-
-One extra method name was printed because of `$` is capturing the element.
-
-## `nil` matches exactly **nil**
-
-Nil is used in the code as a node type but parser gem also represents empty
-spaces in expressions with nil.
-
-Example, a method call from Kernel is a `send` from `nil` calling the method
-while I can also send a method call from a class.
-
-```
-$ ruby-parse -e 'method'
-(send nil :method)
-```
-
-And a method from a object will have the nested target not nil.
-
-```
-$ ruby-parse -e 'object.method'
-(send
-  (send nil :object) :method)
-```
-
-Let's build a serch for any calls from `nil`:
-
-    $ fast '(_ nil _)' example.rb
-
-```ruby
-# example.rb:3
-Example
-# example.rb:4
-ANSWER = 42
-# example.rb:6
-rand(ANSWER)
-```
-
-Double check the expressions that have matched printing the AST:
-
-    $ fast '(_ nil _)' example.rb --ast
-
-```ruby
-# example.rb:3
-(const nil :Example)
-# example.rb:4
-(casgn nil :ANSWER
-  (int 42))
-# example.rb:6
-(send nil :rand
-  (const nil :ANSWER))
-```
-
-## `{}` is for **any** matches like **union** conditions with **or** operator
-
-Let's say we to add check all occurrencies of the constant `ANSWER`.
-
-We'll need to get both `casgn` and `const` node types. For such cases we can
-surround the expressions with `{}` and it will return if the node matches with
-any of the internal expressions.
-
-    $ fast '({casgn const} nil ANSWER)' example.rb
-
-```
-# example.rb:4
-ANSWER = 42
-# example.rb:6
-ANSWER
-```
-
-## `#` 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
-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')
-```
-
-## `.` 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/docs/videos.md

@@ -1,16 +0,0 @@
-# Videos
-
-- [Ruby Kaigi TakeOut 2020: Grepping Ruby code like a boss](https://www.youtube.com/watch?v=YczrZQC9aP8&feature=youtu.be&amp)
-
-<iframe width="560" height="315" src="https://www.youtube.com/embed/YczrZQC9aP8?" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
-
-Also, similar livecoding session at [RubyConf Brazil 2019 (Portuguese)](https://www.eventials.com/locaweb/jonatas-paganini-live-coding-grepping-ruby-code-like-a-boss/#_=_).
-
-- Introduction to [inline code](https://www.youtube.com/watch?v=KQXglNLUv7o).
-<iframe width="560" height="315" src="https://www.youtube.com/embed/KQXglNLUv7o" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
-
-- [Making local variables inline](https://www.youtube.com/watch?v=JD44nhegCRs)
-<iframe width="560" height="315" src="https://www.youtube.com/embed/YN0s9kV1A2A" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
-
-- [Making methods inline](https://www.youtube.com/watch?v=JD44nhegCRs)
-<iframe width="560" height="315" src="https://www.youtube.com/embed/YN0s9kV1A2A" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>