Add 'for' keyword

Author: mikeygough

lib/ruby_lsp/listeners/hover.rb

@@ -18,6 +18,7 @@ class Hover
         Prism::DefinedNode,
         Prism::ElseNode,
         Prism::EnsureNode,
+        Prism::ForNode,
         Prism::GlobalVariableAndWriteNode,
         Prism::GlobalVariableOperatorWriteNode,
         Prism::GlobalVariableOrWriteNode,
@@ -72,6 +73,7 @@ def initialize(response_builder, global_state, uri, node_context, dispatcher, so
           :on_defined_node_enter,
           :on_else_node_enter,
           :on_ensure_node_enter,
+          :on_for_node_enter,
           :on_global_variable_and_write_node_enter,
           :on_global_variable_operator_write_node_enter,
           :on_global_variable_or_write_node_enter,
@@ -146,6 +148,11 @@ def on_ensure_node_enter(node)
         handle_keyword_documentation(node.ensure_keyword)
       end
 
+      #: (Prism::ForNode node) -> void
+      def on_for_node_enter(node)
+        handle_keyword_documentation(node.for_keyword)
+      end
+
       #: (Prism::InterpolatedStringNode node) -> void
       def on_interpolated_string_node_enter(node)
         generate_heredoc_hover(node)

lib/ruby_lsp/static_docs.rb

@@ -21,6 +21,7 @@ module RubyLsp
     "defined" => "Checks if a constant, variable or method is defined",
     "else" => "Executes the code in the else block if the condition is false",
     "ensure" => "Executes the code in the ensure block regardless of whether an exception is raised or not",
+    "for" => "Iterates over a collection of elements",
     "yield" => "Invokes the passed block with the given arguments",
   }.freeze #: Hash[String, String]
 end

static_docs/for.md

@@ -0,0 +1,97 @@
+# For
+
+In Ruby, the `for` keyword creates a loop that iterates over a collection. While functional, Rubyists typically prefer using iterators like `each` for better readability and block scoping.
+
+```ruby
+# Basic for loop with a range
+for i in 1..3
+  puts i
+end
+# Output:
+# 1
+# 2
+# 3
+```
+
+The `for` loop can iterate over any object that responds to `each`, including arrays and hashes.
+
+```ruby
+# Iterating over an array
+fruits = ["apple", "banana", "orange"]
+
+for fruit in fruits
+  puts "I like #{fruit}"
+end
+# Output:
+# I like apple
+# I like banana
+# I like orange
+
+# Iterating over a hash
+scores = { alice: 95, bob: 87 }
+
+for name, score in scores
+  puts "#{name} scored #{score}"
+end
+# Output:
+# alice scored 95
+# bob scored 87
+```
+
+## Variable Scope
+
+Unlike block-based iterators, variables defined in a `for` loop remain accessible after the loop ends.
+
+```ruby
+# Variable remains in scope
+for value in [1, 2, 3]
+  doubled = value * 2
+end
+
+puts doubled # Output: 6 (last value)
+
+# Comparison with each (creates new scope)
+[1, 2, 3].each do |value|
+  doubled = value * 2
+end
+
+# puts doubled # Would raise NameError
+```
+
+## Breaking and Next
+
+The `for` loop supports control flow keywords like `break` and `next`.
+
+```ruby
+# Using break to exit early
+for number in 1..5
+  break if number > 3
+  puts number
+end
+# Output:
+# 1
+# 2
+# 3
+
+# Using next to skip iterations
+for number in 1..5
+  next if number.even?
+  puts number
+end
+# Output:
+# 1
+# 3
+# 5
+```
+
+While Ruby provides the `for` loop for compatibility and familiarity, the preferred Ruby way is to use iterators with blocks:
+
+```ruby
+# Preferred Ruby style using each
+(1..3).each { |i| puts i }
+
+# For more complex iterations
+(1..3).each do |i|
+  puts i
+end
+``` 

test/requests/hover_expectations_test.rb

@@ -972,6 +972,13 @@ def my_method
         RUBY
         position: { line: 2, character: 2 },
       },
+      "for" => {
+        source: <<~RUBY,
+          for i in 1..10
+          end
+        RUBY
+        position: { line: 0, character: 2 },
+      },
     }
 
     test_cases.each do |keyword, config|