### Install and Format Ruby File

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/README.md

Use Homebrew to install rubyfmt and then format a Ruby file in place or print to standard output.

```bash
brew install rubyfmt

rubyfmt -i myfile.rb

rubyfmt myfile.rb
```

--------------------------------

### Install ruby-lsp-rubyfmt-formatter Gem Globally

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/README.md

Install the ruby-lsp-rubyfmt-formatter gem globally using the gem command.

```bash
gem install ruby-lsp-rubyfmt-formatter
```

--------------------------------

### Install rubyfmt via Homebrew

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/README.md

Install the rubyfmt formatter using the Homebrew package manager.

```bash
brew install rubyfmt
```

--------------------------------

### Build rubyfmt from Source

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/README.md

Instructions for building the rubyfmt executable from source using Cargo. Ensure Cargo is installed and then build in release mode.

```bash
cargo build --release

cp target/release/rubyfmt-main /path/on/your/path/rubyfmt
```

--------------------------------

### Configure Neovim with null-ls for rubyfmt

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/README.md

Set up the null-ls Neovim plugin to use rubyfmt for formatting. This requires the null-ls plugin to be installed and configured.

```lua
null_ls.setup({
  sources = {
    null_ls.builtins.formatting.rubyfmt,
  },
})
```

--------------------------------

### Header Opt-In Formatting

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Format only files that start with the `# rubyfmt: true` magic comment using the `--header-opt-in` flag. Other files are ignored.

```ruby
# rubyfmt: true
# Only this file will be formatted when --header-opt-in is active
class MyClass
  def hello ; puts "hi" ; end
end
```

```bash
rubyfmt --header-opt-in -i app/
# Only formats files that carry the "# rubyfmt: true" header
```

--------------------------------

### Ruby Block Syntax Normalization Example

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Illustrates rubyfmt's transformation of various block syntaxes into a normalized form, removing empty blank lines within do/end blocks.

```ruby
# Input (actual)
a(1) do

end

a 1 do

end

a.b 1 do

end

# Output (expected) – empty blank lines inside do/end blocks removed,

```

--------------------------------

### Configure VS Code for Formatto extension

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/README.md

Configure VS Code to use the Formatto extension as the default formatter for Ruby files. This requires the Formatto extension to be installed.

```json
{
  "[ruby]": {
    "editor.defaultFormatter": "damolinx.formatto"
  }
}
```

--------------------------------

### Header Opt-Out Formatting

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Skip formatting files that start with the `# rubyfmt: false` magic comment using the `--header-opt-out` flag. All other files are formatted normally.

```ruby
# rubyfmt: false
# This file will never be touched by rubyfmt --header-opt-out
GENERATED_CODE = <<~RUBY
  ...
RUBY
```

```bash
rubyfmt --header-opt-out -i app/
# Skips any file carrying the "# rubyfmt: false" header
```

--------------------------------

### rubyfmt::init_logger

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Initialises the internal debug logger. In debug builds this enables `DEBUG`-level output to stderr; in release builds it is a no-op. Call once at program start.

```APIDOC
## `rubyfmt::init_logger`

### Description
Initialises the internal debug logger. In debug builds this enables `DEBUG`-level output to stderr; in release builds it is a no-op. Call once at program start.

### Usage
```rust
fn main() {
    rubyfmt::init_logger(); // enable debug logging in debug builds
    let result = rubyfmt::format_buffer(b"x=1\n");
    println!("{}", String::from_utf8_lossy(&result.unwrap()));
}
```
```

--------------------------------

### Initialize rubyfmt Debug Logger

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Call `init_logger` once at program start to initialize the internal debug logger. In debug builds, this enables `DEBUG`-level output to stderr; in release builds, it is a no-op.

```rust
fn main() {
    rubyfmt::init_logger(); // enable debug logging in debug builds
    let result = rubyfmt::format_buffer(b"x=1\n");
    println!("{}", String::from_utf8_lossy(&result.unwrap()));
}
```

--------------------------------

### Build and Run Docker Image

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Build a Docker image for Rubyfmt testing and run it to access a Linux build environment.

```bash
docker build -t rubyfmt_testing_container:local -f ./dockerfiles/build.Dockerfile ./
docker run -it rubyfmt_testing_container:local bash
```

--------------------------------

### Build Rubyfmt from Source

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Build the Rubyfmt release binary from source using Cargo. Requires a recent Rust toolchain.

```bash
# Requires a recent Rust / Cargo toolchain (tested with 1.95.0)
cargo build --release
# Copy the binary onto your PATH
cp target/release/rubyfmt-main /usr/local/bin/rubyfmt
```

--------------------------------

### Run All Benchmarks in Rust

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Execute all benchmarks, including stress tests and large real-world fixtures.

```bash
cargo bench
```

--------------------------------

### Add New Formatting Fixture

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Steps to add a new formatting fixture: create the unformatted input file, create the expected output file, and run fixture tests to confirm.

```bash
# 1. Create the unformatted input
cat > fixtures/small/my_feature_actual.rb <<'EOF'
def foo   ;  bar  ;  end
EOF

# 2. Create the expected output
cat > fixtures/small/my_feature_expected.rb <<'EOF'
def foo
  bar
end
EOF

# 3. Run fixtures tests to confirm the new case passes
cargo test --test fixtures_test
```

--------------------------------

### Format Rust Source Code

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Run `make fmt` to format the Rust source code using `cargo fmt`.

```bash
make fmt    # cargo fmt
```

--------------------------------

### Format Ruby AST with rubyfmt

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Use `toplevel_format_program_with_prism` for lower-level formatting when you already have a parsed `ruby_prism::Node` tree. Writes to any `std::io::Write` sink.

```rust
use rubyfmt;
use std::io::Cursor;

fn format_to_vec(source: &[u8]) -> Result<Vec<u8>, rubyfmt::RichFormatError> {
    let parse_result = ruby_prism::parse(source);

    // Surface parse errors before attempting formatting
    if let Some(err) = parse_result.errors().next() {
        eprintln!("Parse error: {:?}", err);
        return Err(rubyfmt::RichFormatError::SyntaxError);
    }

    let end_data = parse_result.data_loc();
    let mut output = Cursor::new(Vec::new());

    rubyfmt::toplevel_format_program_with_prism(
        &mut output,
        parse_result.node(),
        parse_result.comments(),
        source,
        end_data,
    )?;

    Ok(output.into_inner())
}
```

--------------------------------

### Configure VS Code for ruby-lsp

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/README.md

Configure VS Code settings to use Shopify.ruby-lsp as the default formatter for Ruby files and enable format on save.

```json
{
  "[ruby]": {
    "editor.defaultFormatter": "Shopify.ruby-lsp",
    "editor.formatOnSave": true
  },
  "rubyLsp.formatter": "rubyfmt"
}
```

--------------------------------

### Run All Tests

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/CONTRIBUTING.md

Execute all tests for the project. This is useful for ensuring code integrity.

```bash
cargo test
```

--------------------------------

### Configure Vim for rubyfmt

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/README.md

Set up Vim to use the rubyfmt executable. This involves sourcing the rubyfmt.vim script and setting the path to the executable in your vimrc.

```vim
source /path/to/rubyfmt.vim
let g:rubyfmt_path = /path/to/target/release/rubyfmt-main
```

--------------------------------

### Run Specific Fixture Tests

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/CONTRIBUTING.md

Run tests specifically for the fixtures. This command is recommended for ongoing development and testing new features.

```bash
cargo test --test fixtures_test
```

--------------------------------

### Configure VS Code for ruby-lsp and rubyfmt

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Configure VS Code settings to use Shopify.ruby-lsp as the default formatter and specify rubyfmt as the formatter.

```json
// .vscode/settings.json
{
  "[ruby]": {
    "editor.defaultFormatter": "Shopify.ruby-lsp",
    "editor.formatOnSave": true
  },
  "rubyLsp.formatter": "rubyfmt"
}
```

--------------------------------

### Run Release-Mode Tests in Rust

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Execute tests in release mode to match the Continuous Integration environment.

```bash
cargo test --release
```

--------------------------------

### Lint Rust Source Code

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Run `make lint` to perform linting using `cargo clippy` and other fixture/script linters.

```bash
make lint   # cargo clippy + fixture/script lints
```

--------------------------------

### Format a File In-Place

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Format a Ruby file and overwrite the original file with the changes. This command only writes if the content has changed.

```bash
rubyfmt -i app/models/user.rb
# file.rb is now reformatted; no output to stdout
```

--------------------------------

### Autoformat Code

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/CONTRIBUTING.md

Clean up code formatting to meet project standards, preparing it for CI.

```bash
make fmt
```

--------------------------------

### rubyfmt::format_buffer

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

The primary library entry point. Accepts raw Ruby source bytes and returns the formatted bytes, or a RichFormatError if the source has a syntax error or an IO problem occurs.

```APIDOC
## `rubyfmt::format_buffer`

### Description
Accepts raw Ruby source bytes and returns the formatted bytes, or a `RichFormatError` if the source has a syntax error or an IO problem occurs.

### Usage
```rust
use rubyfmt;

fn main() {
    let source = b"def foo  ;  bar  ;  end\n";

    match rubyfmt::format_buffer(source) {
        Ok(formatted) => {
            // formatted == b"def foo\n  bar\nend\n"
            println!("{}", String::from_utf8_lossy(&formatted));
        }
        Err(rubyfmt::RichFormatError::SyntaxError) => {
            eprintln!("Syntax error in input");
            std::process::exit(1);
        }
        Err(rubyfmt::RichFormatError::IOError(e)) => {
            eprintln!("IO error: {}", e);
            std::process::exit(3);
        }
    }
}
```
```

--------------------------------

### rubyfmt::toplevel_format_program_with_prism

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Lower-level API that accepts an already-parsed `ruby_prism::Node` tree, its comment list, the original source bytes, and an optional end-location. Writes formatted output to any `std::io::Write` sink.

```APIDOC
## `rubyfmt::toplevel_format_program_with_prism`

### Description
Lower-level API that accepts an already-parsed `ruby_prism::Node` tree, its comment list, the original source bytes, and an optional end-location. Writes formatted output to any `std::io::Write` sink. Use this when you need to share a single parse across multiple operations.

### Usage
```rust
use rubyfmt;
use std::io::Cursor;

fn format_to_vec(source: &[u8]) -> Result<Vec<u8>, rubyfmt::RichFormatError> {
    let parse_result = ruby_prism::parse(source);

    // Surface parse errors before attempting formatting
    if let Some(err) = parse_result.errors().next() {
        eprintln!("Parse error: {:?}", err);
        return Err(rubyfmt::RichFormatError::SyntaxError);
    }

    let end_data = parse_result.data_loc();
    let mut output = Cursor::new(Vec::new());

    rubyfmt::toplevel_format_program_with_prism(
        &mut output,
        parse_result.node(),
        parse_result.comments(),
        source,
        end_data,
    )?;

    Ok(output.into_inner())
}
```
```

--------------------------------

### Format Stdin with Filepath Context

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Apply `.gitignore` or `.rubyfmtignore` rules to stdin input by specifying the intended filepath for the input.

```bash
cat lib/generated_file.rb | rubyfmt --stdin-filepath lib/generated_file.rb
```

--------------------------------

### Format a Single File to Stdout

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Format a Ruby file and print the result to standard output without modifying the original file.

```bash
rubyfmt app/models/user.rb
# Output: formatted Ruby printed to stdout
```

--------------------------------

### Include Gitignored Files

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Use the `--include-gitignored` flag to format files that are normally excluded by `.gitignore` rules.

```bash
rubyfmt --include-gitignored -i vendor/
```

--------------------------------

### Add ruby-lsp-rubyfmt-formatter Gem

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/README.md

Add the ruby-lsp-rubyfmt-formatter gem to your project's development dependencies using Bundler.

```bash
bundle add ruby-lsp-rubyfmt-formatter --group development
```

--------------------------------

### Run Linting

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/CONTRIBUTING.md

Perform linting checks on the codebase to ensure code quality and style consistency.

```bash
make lint
```

--------------------------------

### Format Files from a List

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Format files specified in a text file, where each line contains a path to a file to be formatted. Useful for formatting only changed files.

```bash
# Create a file list
git diff --name-only HEAD | grep '\.rb$' > /tmp/changed.rb.txt

rubyfmt -i @/tmp/changed.rb.txt
# Only the listed files are formatted
```

--------------------------------

### Format Ruby Source from Stdin

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Pipe Ruby source code through rubyfmt for formatting when no file paths are provided.

```bash
cat app/models/user.rb | rubyfmt
# or
echo 'def foo  ; end' | rubyfmt
# def foo
# end
```

--------------------------------

### Check for Formatting Differences

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Check a Ruby file for formatting differences and output a unified diff. Exits with a non-zero status code if changes are detected, making it suitable for CI.

```bash
rubyfmt -c app/models/user.rb
# Example diff output:
# ---	app/models/user.rb
# +++	app/models/user.rb
# @@ -1,5 +1,4 @@
# -	a(1) do
# -
# -	end
# +	a(1) do
# +	end

# Exit codes:
#   0  → no formatting changes needed
#   1  → syntax error found
#   5  → formatting differences detected
```

--------------------------------

### Configure Sublime Text for rubyfmt

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/README.md

Configure Sublime Text settings for the rubyfmt plugin, specifying the Ruby executable, rubyfmt executable, and enabling format on save.

```json
{
  "ruby_executable": "ruby",
  "rubyfmt_executable": "rubyfmt",
  "format_on_save": true
}
```

--------------------------------

### Fail Fast on Errors

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Enable `--fail-fast` to make rubyfmt exit immediately upon encountering the first syntax or IO error, rather than continuing and reporting warnings.

```bash
rubyfmt --fail-fast -i app/
# Exits with a non-zero code as soon as any error is encountered
```

--------------------------------

### Format Directory Recursively

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Format all `.rb` files within a directory recursively, respecting `.gitignore` and `.rubyfmtignore` rules.

```bash
rubyfmt -i app/
# Formats every .rb file under app/ in place
```

--------------------------------

### Format Ruby Source Bytes with rubyfmt

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Use `format_buffer` to format raw Ruby source bytes. It returns formatted bytes or a `RichFormatError` for syntax or IO issues.

```rust
use rubyfmt;

fn main() {
    let source = b"def foo  ;  bar  ;  end\n";

    match rubyfmt::format_buffer(source) {
        Ok(formatted) => {
            // formatted == b"def foo\n  bar\nend\n"
            println!("{}", String::from_utf8_lossy(&formatted));
        }
        Err(rubyfmt::RichFormatError::SyntaxError) => {
            eprintln!("Syntax error in input");
            std::process::exit(1);
        }
        Err(rubyfmt::RichFormatError::IOError(e)) => {
            eprintln!("IO error: {}", e);
            std::process::exit(3);
        }
    }
}
```

--------------------------------

### Ignore Files with .rubyfmtignore

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Use a `.rubyfmtignore` file with standard `.gitignore` syntax to exclude specific paths from formatting. Files matching these patterns are silently skipped.

```gitignore
# .rubyfmtignore
vendor/
db/schema.rb
app/assets/javascripts/
**/*_generated.rb
```

```bash
rubyfmt -i .
# Files matching .rubyfmtignore are silently skipped
```

--------------------------------

### Format Ruby Code via Stdin

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/README.md

Pipe Ruby code to the rubyfmt command to format it and output the result to standard output.

```bash
cat file.rb | rubyfmt
```

--------------------------------

### Configure VS Code for VSCode Ruby extension

Source: https://github.com/fables-tales/rubyfmt/blob/trunk/README.md

Configure VS Code settings to use rubyfmt with the deprecated VSCode Ruby extension. Ensure the language server is enabled and format on save is active.

```json
{
  "ruby.useLanguageServer": true,
  "ruby.format": "rubyfmt",
  "[ruby]": {
    "editor.formatOnSave": true
  }
}
```

--------------------------------

### Map rubyfmt Errors to Exit Codes

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

The `as_exit_code` method on `RichFormatError` maps formatting outcomes to integer process exit codes, mirroring CLI behavior.

```rust
use rubyfmt::FormatError;

fn exit_code_demo(err: &rubyfmt::RichFormatError) -> i32 {
    // FormatError variants and their integer exit codes:
    // FormatError::OK                = 0  (no error)
    // FormatError::SyntaxError       = 1
    // FormatError::RipperParseFailure= 2  (legacy)
    // FormatError::IOError           = 3
    // FormatError::OtherRubyError    = 4
    // FormatError::DiffDetected      = 5  (check mode only)
    err.as_exit_code()
}
```

--------------------------------

### rubyfmt::FormatError exit codes

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Maps formatting outcomes to process exit codes, mirroring the CLI behaviour.

```APIDOC
## `rubyfmt::FormatError` exit codes

### Description
Maps formatting outcomes to process exit codes, mirroring the CLI behaviour.

### Usage
```rust
use rubyfmt::FormatError;

fn exit_code_demo(err: &rubyfmt::RichFormatError) -> i32 {
    // FormatError variants and their integer exit codes:
    // FormatError::OK                = 0  (no error)
    // FormatError::SyntaxError       = 1
    // FormatError::RipperParseFailure= 2  (legacy)
    // FormatError::IOError           = 3
    // FormatError::OtherRubyError    = 4
    // FormatError::DiffDetected      = 5  (check mode only)
    err.as_exit_code()
}
```
```

--------------------------------

### Argument List Whitespace Cleanup in Rubyfmt

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Removes extraneous spaces around the forwarding ellipsis in argument lists. This ensures cleaner syntax for method definitions and calls.

```ruby
# Input
def a( ... )
  b(...)
end

# Output – extraneous spaces around forwarding ellipsis removed
def a(...)
  b(...)
end
```

--------------------------------

### Boolean Operator Indentation in Rubyfmt

Source: https://context7.com/fables-tales/rubyfmt/llms.txt

Ensures consistent single-level indentation under boolean operators like 'and' and 'or' for improved readability. This formatting is applied automatically by Rubyfmt.

```ruby
# Input
true and
  false or
    maybe? and
    some_other_things!

# Output – consistent single-level indentation under the operator
true and
  false or
  maybe? and
  some_other_things!
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.