Program Structure and Lexical Elements

A magic comment on the first line (or on the second line when the first is a shebang) changes the script encoding. The word coding is accepted in place of encoding, so the Emacs form # -*- coding: iso-8859-1 -*- also works.

Source: Encoding directive

The position rule is stricter than for other magic comments. A # encoding: comment is honored only on line 1, or on line 2 when line 1 is a #! shebang. Verified on 4.0.7: with the comment on line 2 after an ordinary comment, after a blank line or after code, __ENCODING__ stayed UTF-8 and no warning was printed. Since UTF-8 is already the default, # encoding: utf-8 is redundant in a modern file, and RuboCop’s Style/Encoding cop removes it.

If a UTF-8 file contains bytes that are not valid UTF-8 (for example a Latin-1 é, byte 0xE9, saved by an old editor), parsing fails before anything runs. A UTF-8 byte order mark (EF BB BF) at the start of the file is ignored, so files saved by Windows editors still work.

Source: Encoding directive

The fix is to re-save the file as UTF-8 or to declare the real encoding with # encoding:. Code passed with -e is decoded with the locale encoding rather than UTF-8, which is why a literal with accents may fail under LC_ALL=C with the same invalid multibyte character error.

Source: Ruby command-line options

By default a string literal creates a new mutable String every time it is evaluated. With # frozen_string_literal: true every literal without interpolation is created once, at parse time, and frozen.

Source: frozen_string_literal directive

The rules:

Almost every file in a modern gem begins with this line, and RuboCop’s Style/FrozenStringLiteralComment enforces it; the habit prevents accidental mutation of shared constants and lets Ruby avoid allocations.

A Ractor other than the main one can read a constant only if its value is shareable (deeply frozen or otherwise safe), so Ruby 3.0 added a directive that makes constants deeply frozen. The documentation marks the directive as experimental, and two of its four modes are still named experimental_.

Source: shareable_constant_value directive

The directive applies from where it appears to the end of the current scope, and it can be repeated, so a file can switch modes. Here it is scoped to one module:

Source: shareable_constant_value directive

An invalid mode is ignored with warning: invalid value for shareable_constant_value: bogus. The directive does not affect Module#const_set, and it is unrelated to Object#freeze on ordinary objects, which is covered in Object Lifecycle, Freezing and Copying. Ractors themselves are in Ractors, and the reasoning about constants in Variables, Constants and Scope.

warn_indent controls the warning mismatched indentations at 'end' with 'def' at 3, which is emitted when an end is not aligned with the keyword that it closes. The warning is on under ruby -w, and an explicit # warn_indent: false suppresses it for the rest of the file:

Only the first end is reported, because the second def follows # warn_indent: false. In my runs with Prism on 4.0.7, # warn_indent: true on its own did not make the warning appear without -w, so rely on -w (or RuboCop’s Layout/EndAlignment) to catch it and use the directive only to silence the warning.

Source: warn_indent directive

A typical library file therefore starts like this, in this order: shebang (scripts only), # encoding: (only when not UTF-8), # frozen_string_literal: true, and then everything else. RuboCop’s Style/MagicCommentFormat enforces the spelling and Layout/EmptyLineAfterMagicComment the blank line after the last directive.

Ruby continues an expression onto the next line when the current line is unambiguously incomplete. The documented cases:

Source: NEWS for Ruby 4.0.0 (language changes) and Feature #20925

The leading-&& rule is new in Ruby 4.0. In Ruby 3.4 and earlier the same code is a syntax error (verified on 3.4.11: unexpected '&&', ignoring it), so people wrote the operator at the end of the line instead. Code written for 4.0 with leading operators will not parse on older Rubies; a gem that still supports 3.x should keep the trailing-operator style until it drops them.

A line that is already a complete expression ends there, whatever follows:

Source: Code layout

Ruby warns (possibly useless use of +@ in void context), prints 1, and + 2 has been evaluated and thrown away. (This example is deliberately wrong; RuboCop reports it as Lint/Void.) The fix is the trailing operator: total = 1 + then 2.

A leading comma has no such rescue:

Source: Code layout

A blank line breaks a leading-dot chain; Ruby reports unexpected '.' at the first dot after the blank line. And a backslash continuation must be the very last character on the line (a trailing space after it makes it a syntax error), and it prevents comments between the joined lines:

Source: Code layout

Output: line 1. The backslash joins "line 1" to the comment line, the comment swallows the rest, and the line with "line 2" becomes a separate, useless expression (warning: possibly useless use of a literal in void context).

Finally, and/or have lower precedence than assignment, which turns a continued line into a trap:

This is (ok = title.empty?) or (title.size == 4): ok is assigned false and the second operand is evaluated and discarded. Use || for boolean logic and keep and/or for control flow (save or raise "cannot save"); see Operators and Precedence.

Source: Operator precedence

In some control structures a keyword can replace a newline, which is what makes one-line if and while possible.

Whether the then and do forms are good style is a matter for Control Expressions.

Ruby does not require indentation, and the community standard is two spaces with no tabs. The only language-level support is the mismatched indentations warning shown above. Layout is enforced by RuboCop’s Layout/* cops (see Style, Linting and Static Analysis).

Spaces change meaning in a few places. With def foo(x = 5) = x, puts -1 prints -1 but warns ambiguous first argument; put parentheses or a space even after '-' operator; foo [1] passes an array to foo (result [1]), while foo[1] indexes the result of foo (5[1] is 0); and p (1 + 2) * 3 is parsed as p((1 + 2) * 3) and prints 9. A space before the parenthesis of a method call is why RuboCop’s Lint/ParenthesesAsGroupedExpression and Lint/AmbiguousOperator exist. The grammar behind this lives with the operators: see Calling Methods and Argument Forwarding.

The first character (the sigil) tells Ruby what kind of name it is, before any declaration:

Source: Pre-defined global variables

The constant rule is why class loan is a syntax error: a class name must be a constant. Real messages from 4.0.7:

Source: Modules and Classes and Assignment: Local Variable Names

The last case is dangerous: my-title = "Dune" parses as my - (title = "Dune"), passes -c, and fails only at run time with undefined local variable or method 'my'.

Reassigning a constant is allowed but warned about, and a lower-case name is not a valid constant name:

Source: Module#const_get

(This example is deliberately wrong; RuboCop reports Lint/ConstantReassignment.)

A method name may end in one of three characters. They are part of the name, not operators, and Ruby assigns no meaning to them; the meaning is a convention that the whole standard library follows.

Source: Method names

A setter call is syntax sugar, which makes one pitfall worth knowing: inside a method, clerk_name = "Ana" creates a local variable; only self.clerk_name = "Ana" calls the setter. (A private setter can be called with self. as an exception, see Visibility and Encapsulation.)

Operators are methods, and a class defines them with def and the operator as the name. The unary forms add @ to distinguish them from the binary ones (-@ and +@; ! and ~ are already unary).

Source: Method names (operators are valid method names)

The overridable operators are + - * / % ** == != < > <= >= <=> === =~ !~ << >> & | ^ ~ ! [] []= +@ -@, plus the call operator .() (method call) and the backtick method. &&, ||, and, or, defined? and assignment itself cannot be redefined (a += 1 calls + and then assigns). The full list with precedence is in Operators and Precedence.

These are conventions, not rules; the compiler accepts other spellings, but the community style guide and RuboCop’s Naming/* cops treat them as the standard, and every library follows them.

Source: Ruby Style Guide: naming conventions

Naming guidance for design (a class name is a noun, a method name a verb phrase, a predicate reads as a question) is developed in Idioms, Style and Clean Code; how attr_reader, attr_writer and attr_accessor generate getters and setters is in Classes and Objects.

A reserved word is fine as a method name when it follows a . or &., as a hash key with the key: syntax, and as a symbol. You only cannot use it as a bare local variable, constant or def without a receiver.

Source: Method names

A bare keyword as a variable name is the classic beginner error. class = 2 does not say "unexpected keyword"; Prism reports it as a malformed class definition (the same "class/module name must be CONSTANT" message as in the previous section, repeated with several follow-up errors). Use klass, kind or class_name instead; klass is the long-standing Ruby spelling for a variable that holds a class.

it (Ruby 3.4) and _1 to _9 (Ruby 2.7, for example [[1, 2], [3, 4]].map { _1 + _2 } gives [3, 7]) name block parameters without declaring them. Neither is a reserved word: it is a contextual name, which refers to the implicit parameter only when the block has no explicit parameters and no local variable called it is in scope.

(The last line is a deliberate failure: once it = 5 has been assigned, it is that local variable, not the block parameter.) The details, the Ruby 4.0 Binding#implicit_parameters and the interaction with nested blocks are in Blocks, Procs and Lambdas.

Source: Ruby 3.4.0 release notes (the it block parameter)

Four names describe where the current code is. The first three are keywords, evaluated by the parser; __method__, __callee__ and __dir__ are Kernel methods.

Source: Kernel#__method__, Kernel#__callee__ and Kernel#__dir__

The idiom if __FILE__ == $PROGRAM_NAME (or $0) is true only when the file is the program that was started, and false when the same file is loaded by require; it lets a file be both a library and a script, and is the standard way to put a quick demonstration at the bottom of a library file. require_relative "shelf/version" is equivalent to require File.expand_path("shelf/version", __dir__).

BEGIN { ... } runs before any other code in the file; END { ... } runs when the program is about to exit. They are rare outside one-liners (ruby -ne 'BEGIN { count = 0 }; END { puts count }; count += gets.to_i'), and RuboCop’s Style/BeginBlock and Style/EndBlock flag them.

Source: BEGIN and END

The rules:

Source: Kernel#at_exit

A line that contains only __END__ ends the program text. Ruby stops parsing there, and the rest of the file is data. If the file is the program’s main script (the file given to ruby), the constant DATA is defined as a File object positioned just after the __END__ line.

Source: Object::DATA

Facts that matter in practice:

alias new_name old_name makes a second name for an existing method. It is a keyword, so the names are written without a comma and without a colon (symbols also work), and it works in any scope. Module#alias_method is the method form: it takes strings or symbols with commas, can be used with send or in a loop, and returns the new name as a symbol since Ruby 3.0.

Source: alias and Module#alias_method

undef name (or undef :name, or several names separated by commas) prevents the class from responding to a method and its ancestors' versions: a call raises NoMethodError even when a superclass defines the method. Module#remove_method only removes the definition from the current class, so lookup continues to the ancestors.

Source: undef, Module#undef_method and Module#remove_method

Module#undef_method is the method form of undef. Prefer making a method private, or not inheriting it, over undef in application code; the keyword mostly appears in BasicObject subclasses and in library code. See Method Lookup and super for the lookup order that makes the distinction matter.

defined?(expression) does not evaluate the expression (in the sense of running its side effects); it returns a string that describes it, or nil if the expression would not be valid. It is a keyword, and it is handled by the parser, which is why defined?(puts "x") prints nothing.

Source: defined?

The low precedence is the pitfall in the example above: without parentheses, defined? @count && @count.zero? is defined?(@count && @count.zero?), and it returns "expression" whether or not @count is set. Write defined?(@count) && @count.zero?. Even then, prefer a reflection method that says what you mean: instance_variable_defined?(:@count), Module#const_defined?, respond_to? or Binding#local_variable_defined?, which are less error-prone and work with names built at run time.

The regexp special variables are handled specially: defined?($1) is nil unless the last match had a first group, and defined?($&) is nil when there is no active match.