Module: Fast

Defined in:
lib/fast.rb,
lib/fast/cli.rb,
lib/fast/version.rb,
lib/fast/shortcut.rb,
lib/fast/experiment.rb

Overview

Allow to replace code managing multiple replacements and combining replacements. Useful for large codebase refactor and multiple replacements in the same file.

Defined Under Namespace

Classes: All, Any, Capture, Cli, Experiment, ExperimentCombinations, ExperimentFile, ExpressionParser, Find, FindFromArgument, FindString, FindWithCapture, InstanceMethodCall, Matcher, Maybe, MethodCall, Not, Parent, Rewriter, Shortcut

Constant Summary collapse

LITERAL =

Literals are shortcuts allowed inside ExpressionParser

{
  '...' => ->(node) { node&.children&.any? },
  '_' => ->(node) { !node.nil? },
  'nil' => nil
}.freeze
TOKENIZER =

Allowed tokens in the node pattern domain

%r/
  [\+\-\/\*\\!]         # operators or negation
  |
  ===?                  # == or ===
  |
  \d+\.\d*              # decimals and floats
  |
  "[^"]+"               # strings
  |
  _                     # something not nil: match
  |
  \.{3}                 # a node with children: ...
  |
  \[|\]                 # square brackets `[` and `]` for all
  |
  \^                    # node has children with
  |
  \?                    # maybe expression
  |
  [\d\w_]+[\\!\?]?      # method names or numbers
  |
  \(|\)                 # parens `(` and `)` for tuples
  |
  \{|\}                 # curly brackets `{` and `}` for any
  |
  \$                    # capture
  |
  \#\w[\d\w_]+[\\!\?]?  # custom method call
  |
  \.\w[\d\w_]+\?       # instance method call
  |
  \\\d                  # find using captured expression
  |
  %\d                   # bind extra arguments to the expression
/x.freeze
VERSION = 
'0.1.4'
LOOKUP_FAST_FILES_DIRECTORIES =

Where to search for ‘Fastfile` archives?

  1. Current directory that the command is being runned

  2. Home folder

  3. Using the ‘FAST_FILE_DIR` variable to set an extra folder

[Dir.pwd, ENV['HOME'], ENV['FAST_FILE_DIR']].freeze

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.debugging ⇒ Object

Returns the value of attribute debugging.



209
210
211
 
# File 'lib/fast.rb', line 209

def debugging
  @debugging
end

.experiments ⇒ Object (readonly)

Returns the value of attribute experiments.



30
31
32
 
# File 'lib/fast/experiment.rb', line 30

def experiments
  @experiments
end

Class Method Details

.ast(content, buffer_name: '(string)') ⇒ Astrolabe::Node

Returns from the parsed content.

Examples:

Fast.ast("1") # => s(:int, 1)
Fast.ast("a.b") # => s(:send, s(:send, nil, :a), :b)

Returns:

  • (Astrolabe::Node) —

    from the parsed content



74
75
76
77
78
 
# File 'lib/fast.rb', line 74

def ast(content, buffer_name: '(string)')
  buffer = Parser::Source::Buffer.new(buffer_name)
  buffer.source = content
  Parser::CurrentRuby.new(Astrolabe::Builder.new).parse(buffer)
end

.ast_from_file(file) ⇒ Astrolabe::Node

caches the content based on the filename.

Examples:

Fast.ast_from_file("example.rb") # => s(...)

Returns:

  • (Astrolabe::Node) —

    parsed from file content



84
85
86
87
 
# File 'lib/fast.rb', line 84

def ast_from_file(file)
  @cache ||= {}
  @cache[file] ||= ast(IO.read(file), buffer_name: file)
end

.capture(pattern, node) ⇒ Array<Object>, Object

Return only captures from a search

Returns:

  • (Array<Object>) —

    with all captured elements.

  • (Object) —

    with single element when single capture.



193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/fast.rb', line 193

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

.capture_all(pattern, locations = ['.']) ⇒ Hash<String,Object>

Capture with pattern on a directory or multiple files

Parameters:

  • pattern (String)
  • locations (Array<String>) (defaults to: ['.']) —

    where to search. Default is ‘.’

Returns:

  • (Hash<String,Object>) —

    with files and captures



141
142
143
144
 
# File 'lib/fast.rb', line 141

def capture_all(pattern, locations = ['.'])
  capture_pattern = method(:capture_file).curry.call(pattern)
  group_results(capture_pattern, locations)
end

.capture_file(pattern, file) ⇒ Array<Object>

Capture elements from searches in files. Keep in mind you need to use ‘$` in the pattern to make it work.

Returns:

  • (Array<Object>) —

    captured from the pattern matched in the file



171
172
173
 
# File 'lib/fast.rb', line 171

def capture_file(pattern, file)
  capture pattern, ast_from_file(file)
end

.debug ⇒ Object

Utility function to inspect search details using debug block.

It prints output of all matching cases.

int == (int 1) # => true
1 == 1 # => true

Examples:

Fast.debug do
   Fast.match?([:int, 1], s(:int, 1))
end


221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/fast.rb', line 221

def debug
  return yield if debugging

  self.debugging = true
  result = nil
  Find.class_eval do
    alias_method :original_match_recursive, :match_recursive
    alias_method :match_recursive, :debug_match_recursive
    result = yield
    alias_method :match_recursive, :original_match_recursive # rubocop:disable Lint/DuplicateMethods
  end
  self.debugging = false
  result
end

.experiment(name, &block) ⇒ Object

Fast.experiment is a shortcut to define new experiments and allow them to work together in experiment combinations.

The following experiment look into ‘spec` folder and try to remove `before` and `after` blocks on testing code. Sometimes they’re not effective and we can avoid the hard work of do it manually.

If the spec does not fail, it keeps the change.

Examples:

Remove useless before and after block

Fast.experiment("RSpec/RemoveUselessBeforeAfterHook") do
  lookup 'spec'
  search "(block (send nil {before after}))"
  edit { |node| remove(node.loc.expression) }
  policy { |new_file| system("rspec --fail-fast #{new_file}") }
end


25
26
27
28
 
# File 'lib/fast/experiment.rb', line 25

def experiment(name, &block)
  @experiments ||= {}
  @experiments[name] = Experiment.new(name, &block)
end

.expression(string) ⇒ Object 



205
206
207
 
# File 'lib/fast.rb', line 205

def expression(string)
  ExpressionParser.new(string).parse
end

.expression_from(node) ⇒ String

Extracts a node pattern expression from a given node supressing identifiers and primitive types. Useful to index abstract patterns or similar code structure.

Examples:

Fast.expression_from(Fast.ast('1')) # => '(int _)'
Fast.expression_from(Fast.ast('a = 1')) # => '(lvasgn _ (int _))'
Fast.expression_from(Fast.ast('def name; person.name end')) # => '(def _ (args) (send (send nil _) _))'

Parameters:

  • node (Astrolabe::Node)

Returns:

  • (String) —

    with an pattern to search from it.

See Also:



259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/fast.rb', line 259

def expression_from(node)
  case node
  when Parser::AST::Node
    children_expression = node.children.map(&method(:expression_from)).join(' ')
    "(#{node.type}#{' ' + children_expression if node.children.any?})"
  when nil, 'nil'
    'nil'
  when Symbol, String, Numeric
    '_'
  end
end

.fast_files ⇒ Array<String>

Returns with existent Fastfiles from LOOKUP_FAST_FILES_DIRECTORIES.

Returns:



29
30
31
32
33
 
# File 'lib/fast/shortcut.rb', line 29

def fast_files
  @fast_files ||= LOOKUP_FAST_FILES_DIRECTORIES.compact
    .map { |dir| File.join(dir, 'Fastfile') }
    .select(&File.method(:exists?))
end

.group_results(search_pattern, locations) ⇒ Object 



146
147
148
149
150
151
 
# File 'lib/fast.rb', line 146

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

.highlight(node, show_sexp: false) ⇒ Object

Highligh some source code based on the node. Useful for printing code with syntax highlight.



17
18
19
20
21
22
23
24
25
 
# File 'lib/fast/cli.rb', line 17

def highlight(node, show_sexp: false)
  output =
    if node.respond_to?(:loc) && !show_sexp
      node.loc.expression.source
    else
      node
    end
  CodeRay.scan(output, :ruby).term
end

.load_fast_files! ⇒ Object

Loads ‘Fastfiles` from fast_files list



36
37
38
 
# File 'lib/fast/shortcut.rb', line 36

def load_fast_files!
  fast_files.each(&method(:load))
end

.match?(pattern, ast, *args) ⇒ Boolean

Verify if a given AST matches with a specific pattern

Examples:

Fast.match?("int", Fast.ast("1")) # => true

Returns:

  • (Boolean) —

    case matches ast with the current expression



93
94
95
 
# File 'lib/fast.rb', line 93

def match?(pattern, ast, *args)
  Matcher.new(pattern, ast, *args).match?
end

.replace(pattern, ast, source = nil, &replacement) ⇒ String

Replaces content based on a pattern.

Examples:

Fast.replace?(Fast.ast("a = 1"),"lvasgn") do |node|
  replace(node.location.name, 'variable_renamed')
end # => variable_renamed = 1

Parameters:

  • ast (Astrolabe::Node) —

    with the current AST to search.

  • pattern (String) —

    with the expression to be targeting nodes.

  • replacement (Proc) —

    gives the [Rewriter] context in the block.

Returns:

  • (String) —

    with the new source code after apply the replacement

See Also:



107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/fast.rb', line 107

def replace(pattern, ast, source = nil, &replacement)
  buffer = Parser::Source::Buffer.new('replacement')
  buffer.source = source || ast.loc.expression.source
  to_replace = search(pattern, ast)
  types = to_replace.grep(Parser::AST::Node).map(&:type).uniq

  rewriter = Rewriter.new
  rewriter.buffer = buffer
  rewriter.search = pattern
  rewriter.replacement = replacement
  rewriter.replace_on(*types)
  rewriter.rewrite(buffer, ast)
end

.replace_file(pattern, file, &replacement) ⇒ Object

Replaces the source of an ast_from_file with and the same source if the pattern does not match.



155
156
157
158
 
# File 'lib/fast.rb', line 155

def replace_file(pattern, file, &replacement)
  ast = ast_from_file(file)
  replace(pattern, ast, IO.read(file), &replacement)
end

.report(result, show_sexp: false, file: nil, headless: false) ⇒ Object

Combines highlight with files printing file name in the head with the source line.

Examples:

Fast.highlight(Fast.search(...))

Parameters:

  • result (Astrolabe::Node)
  • show_sexp (Boolean) (defaults to: false) —

    Show string expression instead of source

  • file (String) (defaults to: nil) —

    Show the file name and result line before content

  • headless (Boolean) (defaults to: false) —

    Skip printing the file name and line before content



35
36
37
38
39
40
41
 
# File 'lib/fast/cli.rb', line 35

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(highlight("# #{file}:#{line}")) unless headless
  end
  puts highlight(result, show_sexp: show_sexp)
end

.rewrite_file(pattern, file, &replacement) ⇒ Object

Combines #replace_file output overriding the file if the output is different from the original file content.



162
163
164
165
166
 
# File 'lib/fast.rb', line 162

def rewrite_file(pattern, file, &replacement)
  previous_content = IO.read(file)
  content = replace_file(pattern, file, &replacement)
  File.open(file, 'w+') { |f| f.puts content } if content != previous_content
end

.ruby_files_from(*files) ⇒ Array<String>

When the argument is a folder, it recursively fetches all ‘.rb` files from it.

Parameters:

  • files —

    can be file paths or directories.

Returns:

  • (Array<String>) —

    with all ruby files from arguments.



239
240
241
242
243
244
245
246
247
248
 
# File 'lib/fast.rb', line 239

def ruby_files_from(*files)
  directories = files.select(&File.method(:directory?))

  if directories.any?
    files -= directories
    files |= directories.flat_map { |dir| Dir["#{dir}/**/*.rb"] }
    files.uniq!
  end
  files
end

.search(pattern, node) { ... } ⇒ Object

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

Yields:

  • node and capture if block given



179
180
181
182
183
184
185
186
187
188
 
# File 'lib/fast.rb', line 179

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 { |child| search(pattern, child) }
      .compact.flatten
  end
end

.search_all(pattern, locations = ['.']) ⇒ Hash<String,Array<Astrolabe::Node>>

Search with pattern on a directory or multiple files

Parameters:

  • pattern (String)
  • *locations (Array<String>) —

    where to search. Default is ‘.’

Returns:

  • (Hash<String,Array<Astrolabe::Node>>) —

    with files and results



132
133
134
135
 
# File 'lib/fast.rb', line 132

def search_all(pattern, locations = ['.'])
  search_pattern = method(:search_file).curry.call(pattern)
  group_results(search_pattern, locations)
end

.search_file(pattern, file) ⇒ Array<Astrolabe::Node>

Search with pattern directly on file

Returns:

  • (Array<Astrolabe::Node>) —

    that matches the pattern



123
124
125
126
 
# File 'lib/fast.rb', line 123

def search_file(pattern, file)
  node = ast_from_file(file)
  search pattern, node
end

.shortcut(identifier, *args, &block) ⇒ Object

Store predefined searches with default paths through shortcuts. define your Fastfile in you root folder or

Examples:

Shortcut for finding validations in rails models

Fast.shortcut(:validations, "(send nil {validate validates})", "app/models")


16
17
18
19
 
# File 'lib/fast/shortcut.rb', line 16

def shortcut(identifier, *args, &block)
  puts "identifier #{identifier.inspect} will be override" if shortcuts.key?(identifier)
  shortcuts[identifier] = Shortcut.new(*args, &block)
end

.shortcuts ⇒ Hash<String,Shortcut>

Stores shortcuts in a simple hash where the key is the identifier and the value is the object itself.

Returns:

  • (Hash<String,Shortcut>) —

    as a dictionary.



24
25
26
 
# File 'lib/fast/shortcut.rb', line 24

def shortcuts
  @shortcuts ||= {}
end