The Ruby file (.rb)

The basics

What is an RB file?

Anatomy

What's inside a Ruby file

A Ruby file is a list of expressions that run from top to bottom. Classes, modules and methods are defined as the file runs, and every block ends with end. Here is a small but complete script, part by part.

#!/usr/bin/env ruby
# frozen_string_literal: true

require "json"
require_relative "lib/formatter"

# Greets people by name.
module Greeter
  DEFAULT_NAME = "world"

  class Person
    attr_reader :name

    def initialize(name = DEFAULT_NAME)
      @name = name
    end

    def greeting
      "Hello, #{name}!"
    end
  end

  def self.run(names)
    names.map { |name| Person.new(name).greeting }
  end
end

if __FILE__ == $PROGRAM_NAME
  puts JSON.generate(Greeter.run(ARGV))
end

1. 1#!/usr/bin/env ruby

   The shebang

   Used when the file is run as a program on macOS or Linux (./greeter.rb): it runs the file with the first ruby on the PATH, which respects version managers like rbenv. Ruby treats it as a comment.

2. 2# frozen_string_literal: true

   A magic comment

   A comment that changes how Ruby reads this file only. This one makes every string literal read-only. It must be in the first comment section of the file; an # encoding: comment must be on line 1, or line 2 after a shebang.

3. 3require "json"

   Loading a library

   require searches Ruby's load path: the standard library and installed gems. Each file is loaded once, however many times it's required.

4. 4require_relative "lib/formatter"

   Loading another file of yours

   Resolves the path from this file's folder, not from the folder you happen to run Ruby in. The .rb extension is left off.

5. 5module Greeter

   A module

   A namespace that keeps names like Person from clashing with other code. Module and class names are constants, so they start with a capital letter.

6. 6attr_reader :name

   An attribute reader

   Writes a name method that returns @name. :name is a symbol, an immutable identifier.

7. 7def initialize(name = DEFAULT_NAME)

   The constructor

   Runs when you call Person.new. @name is an instance variable, private to each object. The argument has a default value.

8. 8"Hello, #{name}!"

   An implicit return

   A method returns its last expression, so no return is needed. #{…} inserts a value into a double-quoted string; single quotes don't interpolate.

9. 9names.map { |name| … }

   A block

   Code passed to a method, here run once for each name. Braces are used for one-line blocks, do … end for longer ones.

10. 10if __FILE__ == $PROGRAM_NAME

    The entry-point check

    True only when this file is the one being run, not when another file requires it. That lets one file work both as a script and as a library.

Under the hood

What happens when you run a Ruby file

How to

How to run, edit and check a Ruby file

The rules

Magic comments, file names and project layout

my_gem/
  Gemfile               gems the project needs
  Gemfile.lock          exact versions Bundler chose: commit it
  my_gem.gemspec        the gem's name, version and dependencies
  Rakefile              tasks such as rake test (Ruby code, no extension)
  lib/
    my_gem.rb           what require "my_gem" loads
    my_gem/
      version.rb        defines MyGem::VERSION
  exe/
    my_gem              a command-line entry point with a shebang
  test/
    test_my_gem.rb

Dependencies

Gemfile, Gemfile.lock and Bundler

# Gemfile: Ruby code that Bundler reads
source "https://rubygems.org"

ruby ">= 3.3"

gem "sinatra", "~> 4.0"   # 4.x, but not 5.0
gem "csv"                 # a bundled gem since Ruby 3.4

group :test do
  gem "minitest"
end

History

Ruby versions that matter for files

Related formats

Ruby files and their neighbours

Troubleshooting

Errors when opening or running a Ruby file

Security

Is it safe to open or run a Ruby file?

Free downloads

Sample Ruby files to download

Free sample Ruby files for testing editors, syntax highlighters, linters, upload filters and size limits. All run with Ruby 3.2 or later, except sample-syntax-error.rb, which fails on purpose.

Loading…

What's inside sample-script.rb

The file is commented: open it in a text editor and each numbered comment marks one of these parts. Run it with ruby sample-script.rb, or add --json for JSON output.

1. Comments 1 and 2: shebang and magic comment

   #!/usr/bin/env ruby on line 1 and # frozen_string_literal: true on line 2, the two lines most Ruby scripts start with.

2. Comments 3 and 4: require and a module

   require "json" loads a library that ships with Ruby, and a module keeps the script's names in one namespace.

3. Comments 5 and 6: Data and a heredoc

   Data.define creates an immutable value class, and a squiggly heredoc (<<~TEXT) holds the sample data, including one deliberately bad line.

4. Comment 7: parsing with a rescue

   each_line.with_index and filter_map, with a rescue inside the block: the bad line produces a warning on stderr and is skipped.

5. Comment 8: Enumerable

   group_by, transform_values, sum and sort_by chained together to total each category.

6. Comment 9: frozen strings in practice

   Because literals are frozen, the report is built in a mutable copy made with +"". format() pads the columns.

7. Comments 10 and 11: the entry point

   if __FILE__ == $PROGRAM_NAME runs the script part only when the file is executed; abort reports a missing file and exits with status 1; --json prints the items with JSON.pretty_generate.

All sample Ruby files

• Commented sample script

  sample-script.rb · 3.1 KB (3,181 bytes)

  Totals a small expense list by category, with numbered comments explaining each part: magic comment, module, Data, heredoc, blocks, error handling and the entry-point check. Runs without warnings under ruby -w.

  • Checking editors, highlighters and linters on modern Ruby
  • Teaching the parts of a Ruby file
  DownloadOpen

• UTF-8 encoding test

  sample-utf8.rb · 1.7 KB (1,698 bytes)

  Greetings in 12 languages plus symbols and emoji, with each string's length in characters and bytes, Unicode case mapping and normalisation, and a method with a non-ASCII name.

  • Spotting encoding bugs in editors and pipelines
  • Testing right-to-left and CJK text in code viewers
  DownloadOpen

• frozen_string_literal demo

  sample-frozen-string.rb · 1.1 KB (1,095 bytes)

  Shows what the magic comment changes: a FrozenError caught and reported, mutable copies with +"", unfrozen interpolated strings, and identical literals sharing one object.

  • Seeing the magic comment's effect, with and without it
  • Testing Ruby upgrades for chilled-string warnings
  DownloadOpen

• Windows (CRLF) line endings

  sample-crlf.rb · 894 bytes

  A script with a shebang, saved with CRLF line endings. ruby sample-crlf.rb works (with a warning under -w); ./sample-crlf.rb on macOS or Linux fails with the ruby\r error.

  • Testing line-ending conversion in Git, editors and upload pipelines
  • Reproducing the CRLF shebang error
  DownloadOpen

• Missing end (deliberate syntax error)

  sample-syntax-error.rb · 573 bytes

  A method whose def has no matching end. Clearly labelled; ruby -c reports a syntax error at the end of the file and exits with status 1.

  • Testing how editors, linters and CI report syntax errors
  • Comparing error messages between Ruby versions
  DownloadOpen

• 100 KB Ruby file

  sample-100kb.rb · 100 KB (102,400 bytes)

  A table of the 14,390 happy numbers up to 100,112 and a check that it's complete, padded with a comment to exactly 102,400 bytes.

  • Upload and size-limit tests
  • Parser, highlighter and editor performance
  DownloadOpen

Ways to test with them

• Syntax checks: ruby -c should print Syntax OK for every sample except sample-syntax-error.rb; use that one to check how your CI or editor reports errors.
• Ruby upgrades: delete line 1 of sample-frozen-string.rb and run it with ruby -W:deprecated on Ruby 3.4 or later to see the chilled-string warning.
• Line endings: pass sample-crlf.rb through Git or your pipeline and check whether the CRLFs survive; if they became LFs, ./sample-crlf.rb starts working.
• Upload limits: sample-100kb.rb is exactly 102,400 bytes, for testing a limit at the boundary.

Free to use for testing, teaching and demos, commercially or not, with no attribution needed. A link back to this page is always appreciated.

Questions

Ruby files, frequently asked