Add 'ensure' keyword

Author: mikeygough

lib/ruby_lsp/listeners/hover.rb

@@ -17,6 +17,7 @@ class Hover
         Prism::DefNode,
         Prism::DefinedNode,
         Prism::ElseNode,
+        Prism::EnsureNode,
         Prism::GlobalVariableAndWriteNode,
         Prism::GlobalVariableOperatorWriteNode,
         Prism::GlobalVariableOrWriteNode,
@@ -70,6 +71,7 @@ def initialize(response_builder, global_state, uri, node_context, dispatcher, so
           :on_def_node_enter,
           :on_defined_node_enter,
           :on_else_node_enter,
+          :on_ensure_node_enter,
           :on_global_variable_and_write_node_enter,
           :on_global_variable_operator_write_node_enter,
           :on_global_variable_or_write_node_enter,
@@ -139,6 +141,11 @@ def on_else_node_enter(node)
         handle_keyword_documentation(node.else_keyword)
       end
 
+      #: (Prism::EnsureNode node) -> void
+      def on_ensure_node_enter(node)
+        handle_keyword_documentation(node.ensure_keyword)
+      end
+
       #: (Prism::InterpolatedStringNode node) -> void
       def on_interpolated_string_node_enter(node)
         generate_heredoc_hover(node)

lib/ruby_lsp/static_docs.rb

@@ -20,6 +20,7 @@ module RubyLsp
     "def" => "Defines a method",
     "defined" => "Checks if a constant 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",
     "yield" => "Invokes the passed block with the given arguments",
   }.freeze #: Hash[String, String]
 end

static_docs/ensure.md

@@ -0,0 +1,83 @@
+# Ensure
+
+In Ruby, the `ensure` keyword is used to define a block of code that will always execute, regardless of whether an exception was raised or not. It's commonly used for cleanup operations like closing files or network connections.
+
+```ruby
+# Basic ensure usage
+file = File.open("example.txt")
+begin
+  content = file.read
+rescue StandardError => e
+  puts "Error reading file: #{e.message}"
+ensure
+  file.close # Always executes
+end
+```
+
+The `ensure` clause can be used with or without `rescue` blocks, and it will execute even if there's a return statement in the main block.
+
+```ruby
+def process_data
+  connection = Database.connect
+  begin
+    return connection.query("SELECT * FROM users")
+  ensure
+    connection.close # Executes even with the return statement
+  end
+end
+
+# Without rescue clause
+def write_log(message)
+  file = File.open("log.txt", "a")
+  begin
+    file.puts(message)
+  ensure
+    file.close
+  end
+end
+```
+
+## Multiple Rescue Clauses
+
+When using multiple `rescue` clauses, the `ensure` block always comes last and executes regardless of which `rescue` clause is triggered.
+
+```ruby
+def perform_operation
+  begin
+    # Main operation
+    result = dangerous_operation
+  rescue ArgumentError => e
+    puts "Invalid arguments: #{e.message}"
+  rescue StandardError => e
+    puts "Other error: #{e.message}"
+  ensure
+    # Cleanup code always runs
+    cleanup_resources
+  end
+end
+```
+
+## Implicit Begin Blocks
+
+In methods and class definitions, you can use `ensure` without an explicit `begin` block.
+
+```ruby
+def process_file(path)
+  file = File.open(path)
+  file.read # If this raises an error, ensure still executes
+ensure
+  file&.close # Using safe navigation operator in case file is nil
+end
+
+class DataProcessor
+  def initialize
+    @connection = Database.connect
+  rescue StandardError => e
+    puts "Failed to connect: #{e.message}"
+  ensure
+    puts "Initialization complete"
+  end
+end
+```
+
+The `ensure` keyword is essential for writing robust Ruby code that properly manages resources and handles cleanup operations, regardless of whether exceptions occur. 

test/requests/hover_expectations_test.rb

@@ -962,6 +962,16 @@ def my_method
         RUBY
         position: { line: 2, character: 2 },
       },
+      "ensure" => {
+        source: <<~RUBY,
+          begin
+            true
+          ensure
+            false
+          end
+        RUBY
+        position: { line: 2, character: 2 },
+      },
     }
 
     test_cases.each do |keyword, config|