Ruby

https://docs.ruby-lang.org/en/3.4/
Admin
Ruby is an interpreted object-oriented programming language known for its simple syntax and often...
Tokens:4,522,049
Snippets:37,446
Trust Score:9.5
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Setup for Math examples

Source: https://docs.ruby-lang.org/en/3.4/Math.html

Assumed setup for the examples in this documentation: includes Math and defines INFINITY as Float::INFINITY.

```ruby
include Math
INFINITY = Float::INFINITY
```

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

### start Ruby examples

Source: https://docs.ruby-lang.org/en/3.4/Date.html

Ruby examples showing the start date for different calendar reform dates and the resulting Date.jd output.

```ruby
d = Date.new(2001, 2, 3, Date::ITALY)
s = d.start     # => 2299161.0
Date.jd(s).to_s # => "1582-10-15"

d = Date.new(2001, 2, 3, Date::ENGLAND)
s = d.start     # => 2361222.0
Date.jd(s).to_s # => "1752-09-14"

Date.new(2001, 2, 3, Date::GREGORIAN).start # => -Infinity
Date.new(2001, 2, 3, Date::JULIAN).start    # => Infinity
```

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

### Setup for StringScanner#[] examples

Source: https://docs.ruby-lang.org/en/3.4/StringScanner.html

Sets up a scanner with named captures for the subsequent [] examples.

```ruby
scanner = StringScanner.new('Fri Dec 12 1975 14:39')
scanner.scan(/(?<wday>\w+) (?<month>\w+) (?<day>\d+) /)

```

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

### Setup for week date examples

Source: https://docs.ruby-lang.org/en/3.4/strftime_formatting_rdoc.html

Creates two Time objects used in the following week date examples.

```ruby
t0 = Time.new(2023, 1, 1) # => 2023-01-01 00:00:00 -0600
t1 = Time.new(2024, 1, 1) # => 2024-01-01 00:00:00 -0600
```

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

### Create install directory

Source: https://docs.ruby-lang.org/en/3.4/contributing/building_ruby_md.html

Create the directory where the new Ruby will be installed. The example uses ~/.rubies/ruby-master as the install prefix.

```shell
mkdir ~/.rubies
```

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

### Array#[] start and length examples

Source: https://docs.ruby-lang.org/en/3.4/Array.html

Array#[] with start and length arguments returns a new array of the given length starting at the given offset.

```ruby
a = [:foo, 'bar', 2]
a[0, 2] # => [:foo, "bar"]
a[1, 2] # => ["bar", 2]

```

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

### Install dependencies with bundle install

Source: https://docs.ruby-lang.org/en/3.4/contributing/making_changes_to_stdlibs_md.html

Installs the dependencies for the standard library before building or testing.

```shell
bundle install

```

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

### Daily rotation setup

Source: https://docs.ruby-lang.org/en/3.4/Logger.html

Sets up a logger that rotates daily for the periodic rotation example.

```ruby
logger = Logger.new('t.log', 'daily')

```

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

### new_start Ruby example

Source: https://docs.ruby-lang.org/en/3.4/Date.html

Returns a copy of self with the given start value.

```ruby
d0 = Date.new(2000, 2, 3)
d0.julian? # => false
d1 = d0.new_start(Date::JULIAN)
d1.julian? # => true
```

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

### ENV.take(5) example

Source: https://docs.ruby-lang.org/en/3.4/globals_rdoc.html

Shows how to inspect the ENV hash, which contains current environment variables and their values. The example takes the first five entries.

```ruby
ENV.take(5)
# =>
[["COLORTERM", "truecolor"],
 ["DBUS_SESSION_BUS_ADDRESS", "unix:path=/run/user/1000/bus"],
 ["DESKTOP_SESSION", "ubuntu"],
 ["DISPLAY", ":0"],
 ["GDMSESSION", "ubuntu"]]
```

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

### FileUtils.install: copy array of sources into directory

Source: https://docs.ruby-lang.org/en/3.4/FileUtils.html

Shows that when src is an array and dest is a directory, install copies each path to dest/path. The example installs two files and verifies they exist.

```ruby
File.file?('src3.txt') # => true
File.file?('src3.dat') # => true
FileUtils.mkdir('dest3')
FileUtils.install(['src3.txt', 'src3.dat'], 'dest3')
File.file?('dest3/src3.txt') # => true
File.file?('dest3/src3.dat') # => true

```

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

### Fiber#backtrace example

Source: https://docs.ruby-lang.org/en/3.4/Fiber.html

Shows how to get the execution stack of a fiber using backtrace with optional start, count, and range arguments. The backtrace is empty before the fiber starts and nil after it finishes.

```ruby
def level3
  Fiber.yield
end

def level2
  level3
end

def level1
  level2
end

f = Fiber.new { level1 }

# It is empty before the fiber started
f.backtrace
#=> []

f.resume

f.backtrace
#=> ["test.rb:2:in `yield'", "test.rb:2:in `level3'", "test.rb:6:in `level2'", "test.rb:10:in `level1'", "test.rb:13:in `block in <main>'"]
p f.backtrace(1) # start from the item 1
#=> ["test.rb:2:in `level3'", "test.rb:6:in `level2'", "test.rb:10:in `level1'", "test.rb:13:in `block in <main>'"]
p f.backtrace(2, 2) # start from item 2, take 2
#=> ["test.rb:6:in `level2'", "test.rb:10:in `level1'"]
p f.backtrace(1..3) # take items from 1 to 3
#=> ["test.rb:2:in `level3'", "test.rb:6:in `level2'", "test.rb:10:in `level1'"]

f.resume

# It is nil after the fiber is finished
f.backtrace
#=> nil
```

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

### Bundler.setup example with Gemfile and behavior

Source: https://docs.ruby-lang.org/en/3.4/Bundler.html

Shows a Gemfile and demonstrates how Bundler.setup restricts require to Gemfile gems and standard library, with exact version loading.

```ruby
gem 'first_gem', '= 1.0'
group :test do
  gem 'second_gem', '= 1.0'
end
```

```ruby
require 'third_gem' # allowed, required from global gems
require 'first_gem' # allowed, loads the last installed version
Bundler.setup
require 'fourth_gem' # fails with LoadError
require 'second_gem' # loads exactly version 1.0
```

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

### setup → Qtrue # first time / setup → nil # thereafter

Source: https://docs.ruby-lang.org/en/3.4/OpenSSL/SSL/SSLContext.html

Sets up the SSLContext, returning Qtrue on first call and nil thereafter.

```APIDOC
## setup → Qtrue # first time
setup → nil # thereafter

### Description
Sets up the SSLContext. On the first call, it returns Qtrue; on subsequent calls, it returns nil. This method is called internally to configure the underlying SSL_CTX.
```

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

### Implementing example_store helper

Source: https://docs.ruby-lang.org/en/3.4/PStore.html

Implementation of the example_store helper used throughout the documentation. It creates a temporary file, instantiates a PStore, populates it with three entries (:foo, :bar, :baz), and yields the store to the caller.

```ruby
require 'pstore'
require 'tempfile'
# Yield a pristine store for use in examples.
def example_store
  # Create the store in a temporary file.
  Tempfile.create do |file|
    store = PStore.new(file)
    # Populate the store.
    store.transaction do
      store[:foo] = 0
      store[:bar] = 1
      store[:baz] = 2
    end
    yield store
  end
end

```

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

### Gem.install interactive IRB example

Source: https://docs.ruby-lang.org/en/3.4/Gem.html

Interactive example showing how to use `Gem.install` from IRB. The output shows the gem being fetched and the resulting Gem::Specification object.

```irb
% irb
>> Gem.install "minitest"
Fetching: minitest-5.14.0.gem (100%)
=> [#<Gem::Specification:0x1013b4528 @name="minitest", ...>]
```

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

### IO#gets with limit example

Source: https://docs.ruby-lang.org/en/3.4/IO.html

Ruby example of IO#gets with an integer limit. Limits the number of bytes in the returned line.

```ruby
# No more than one line.
File.open('t.txt') {|f| f.gets(10) } # => "First line"
File.open('t.txt') {|f| f.gets(11) } # => "First line\n"
File.open('t.txt') {|f| f.gets(12) } # => "First line\n"

```

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

### request_body_permitted? example

Source: https://docs.ruby-lang.org/en/3.4/Net/HTTPGenericRequest.html

Example of request_body_permitted? for Post and Get.

```ruby
Net::HTTP::Post.new(uri).request_body_permitted? # => true
Net::HTTP::Get.new(uri).request_body_permitted?  # => false

```

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

### Ruby example for output?

Source: https://docs.ruby-lang.org/en/3.4/WIN32OLE/Param.html

Ruby example that iterates over the parameters of the NewWindow method and prints each parameter's name and output? result.

```ruby
tobj = WIN32OLE::Type.new('Microsoft Internet Controls', 'DWebBrowserEvents')
method = WIN32OLE::Method.new(tobj, 'NewWindow')
method.params.each do |param|
  puts "#{param.name} #{param.output?}"
end

```

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

### IO#gets with no arguments example

Source: https://docs.ruby-lang.org/en/3.4/IO.html

Ruby example of IO#gets with no arguments. Returns the next line determined by $/ and assigns it to $_. Returns nil at EOF.

```ruby
f = File.open('t.txt')
f.gets # => "First line\n"
$_     # => "First line\n"
f.gets # => "\n"
f.gets # => "Fourth line\n"
f.gets # => "Fifth line\n"
f.gets # => nil
f.close

```

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

### Initialize SetupCommand with options

Source: https://docs.ruby-lang.org/en/3.4/Gem/Commands/SetupCommand.html

Initializes the setup command with default options and registers all command-line options. The super call sets defaults such as format_executable: false, document: %w[ri], force: true, and site_or_vendor: "sitelibdir". Each add_option block updates the options hash; note that --[no-]document with no value defaults to %w[rdoc ri], and --[no-]rdoc/--[no-]ri modify the document array in place.

```ruby
# File lib/rubygems/commands/setup_command.rb, line 15
def initialize
  super "setup", "Install RubyGems",
        format_executable: false, document: %w[ri],
        force: true,
        site_or_vendor: "sitelibdir",
        destdir: "", prefix: "", previous_version: "",
        regenerate_binstubs: true,
        regenerate_plugins: true

  add_option "--previous-version=VERSION",
             "Previous version of RubyGems",
             "Used for changelog processing" do |version, options|
    options[:previous_version] = version
  end

  add_option "--prefix=PREFIX",
             "Prefix path for installing RubyGems",
             "Will not affect gem repository location" do |prefix, options|
    options[:prefix] = File.expand_path prefix
  end

  add_option "--destdir=DESTDIR",
             "Root directory to install RubyGems into",
             "Mainly used for packaging RubyGems" do |destdir, options|
    options[:destdir] = File.expand_path destdir
  end

  add_option "--[no-]vendor",
             "Install into vendorlibdir not sitelibdir" do |vendor, options|
    options[:site_or_vendor] = vendor ? "vendorlibdir" : "sitelibdir"
  end

  add_option "--[no-]format-executable",
             "Makes `gem` match ruby",
             "If Ruby is ruby18, gem will be gem18" do |value, options|
    options[:format_executable] = value
  end

  add_option "--[no-]document [TYPES]", Array,
             "Generate documentation for RubyGems",
             "List the documentation types you wish to",
             "generate.  For example: rdoc,ri" do |value, options|
    options[:document] = case value
                         when nil   then %w[rdoc ri]
                         when false then []
                         else value
    end
  end

  add_option "--[no-]rdoc",
             "Generate RDoc documentation for RubyGems" do |value, options|
    if value
      options[:document] << "rdoc"
    else
      options[:document].delete "rdoc"
    end

    options[:document].uniq!
  end

  add_option "--[no-]ri",
             "Generate RI documentation for RubyGems" do |value, options|
    if value
      options[:document] << "ri"
    else
      options[:document].delete "ri"
    end

    options[:document].uniq!
  end

  add_option "--[no-]regenerate-binstubs",
             "Regenerate gem binstubs" do |value, options|
    options[:regenerate_binstubs] = value
  end

  add_option "--[no-]regenerate-plugins",
             "Regenerate gem plugins" do |value, options|
    options[:regenerate_plugins] = value
  end

  add_option "-f", "--[no-]force",
             "Forcefully overwrite binstubs" do |value, options|
    options[:force] = value
  end

  add_option("-E", "--[no-]env-shebang",
             "Rewrite executables with a shebang",
             "of /usr/bin/env") do |value, options|
    options[:env_shebang] = value
  end

  @verbose = nil
end
```

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

### Generate HTML documentation with make html

Source: https://docs.ruby-lang.org/en/3.4/contributing/documentation_guide_md.html

Run inside the build directory to generate HTML documentation in the {build folder}/.ext/html directory. Requires a build directory; if none exists, follow the quick start guide up to step 4.

```shell
make html

```

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

### Test Ruby installation

Source: https://docs.ruby-lang.org/en/3.4/contributing/building_ruby_md.html

Test the newly-installed Ruby by running a one-line script that prints 'Hello, World!'.

```shell
~/.rubies/ruby-master/bin/ruby -e "puts 'Hello, World!'"
```

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

### GET /todos/2

Source: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html

Example of using the `get` instance method within a session.

```APIDOC
## [GET] /todos/2

### Description
Sends a GET request to the specified path using the current session. This method is available within a session started with `Net::HTTP.start` or manually with `start`/`finish`.

### Method
GET

### Endpoint
/todos/2

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to request.

### Response
#### Success Response (200)
- **body** (string) - The response body.

### Response Example
{
  "body": "..."
}
```

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

### setup(*groups) - Set up Bundler environment

Source: https://docs.ruby-lang.org/en/3.4/Bundler.html

Validates runtime, prints major deprecations, and loads all groups if no groups specified, otherwise loads the specified groups. Returns @setup if already set.

```ruby
# File lib/bundler.rb, line 157
def setup(*groups)
  # Return if all groups are already loaded
  return @setup if defined?(@setup) && @setup

  definition.validate_runtime!

  SharedHelpers.print_major_deprecations!

  if groups.empty?
    # Load all groups, but only once
    @setup = load.setup
  else
    load.setup(*groups)
  end
end
```

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

### GET /todos/1

Source: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html

Example of using the `get` instance method within a session.

```APIDOC
## [GET] /todos/1

### Description
Sends a GET request to the specified path using the current session. This method is available within a session started with `Net::HTTP.start` or manually with `start`/`finish`.

### Method
GET

### Endpoint
/todos/1

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to request.

### Response
#### Success Response (200)
- **body** (string) - The response body.

### Response Example
{
  "body": "..."
}
```

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

### Install Ruby

Source: https://docs.ruby-lang.org/en/3.4/contributing/building_ruby_md.html

Install the newly-compiled Ruby into the prefix directory. Use `make SUDO=sudo install` if you need to run with sudo and avoid document generation with different permissions.

```shell
make install
```

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

### Connect with TCPSocket.new

Source: https://docs.ruby-lang.org/en/3.4/Socket.html

Simpler alternative to the low-level Socket example, using the TCPSocket convenience class to connect to example.com on port 80.

```ruby
s = TCPSocket.new 'example.com', 80

```

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

### Process.uid example

Source: https://docs.ruby-lang.org/en/3.4/Process/UID.html

Example of calling Process.uid to get the real user ID.

```ruby
Process.uid # => 1000

```

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

### Process.euid example

Source: https://docs.ruby-lang.org/en/3.4/Process/UID.html

Example of calling Process.euid to get the effective user ID.

```ruby
Process.euid # => 501

```

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

### Usage examples for SyntaxSuggest::Cli

Source: https://docs.ruby-lang.org/en/3.4/SyntaxSuggest/Cli.html

Shows typical ways to instantiate and call the CLI with different arguments: --help, a file path, --record=tmp, and --terminal.

```ruby
Cli.new(argv: ["--help"]).call
Cli.new(argv: ["<path/to/file>.rb"]).call
Cli.new(argv: ["<path/to/file>.rb", "--record=tmp"]).call
Cli.new(argv: ["<path/to/file>.rb", "--terminal"]).call
```

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

### FileUtils.install: verbose and noop example with output

Source: https://docs.ruby-lang.org/en/3.4/FileUtils.html

Shows the effect of verbose: true and noop: true. The commands are printed but no files are copied. The output shows the equivalent install -c commands.

```ruby
FileUtils.install('src0.txt', 'dest0.txt', noop: true, verbose: true)
FileUtils.install('src1.txt', 'dest1.txt', noop: true, verbose: true)
FileUtils.install('src2.txt', 'dest2', noop: true, verbose: true)

```

```text
install -c src0.txt dest0.txt
install -c src1.txt dest1.txt
install -c src2.txt dest2

```

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

### Example 1: listen with bind

Source: https://docs.ruby-lang.org/en/3.4/Socket.html

Example 1 for Socket#listen: creates a TCP socket, binds to localhost port 2200, and listens with a backlog of 5.

```ruby
require 'socket'
include Socket::Constants
socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
socket.bind( sockaddr )
socket.listen( 5 )
```

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

### Get AST from proc and method

Source: https://docs.ruby-lang.org/en/3.4/RubyVM/AbstractSyntaxTree.html

Examples of using of to get AST nodes from a proc and a method. The first example passes a proc literal, the second defines a method and passes it with method(:hello).

```ruby
RubyVM::AbstractSyntaxTree.of(proc {1 + 2})
# => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:35-1:42>

def hello
  puts "hello, world"
end

RubyVM::AbstractSyntaxTree.of(method(:hello))
# => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:0-3:3>
```

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

### Set up x86 YJIT environment with Rosetta

Source: https://docs.ruby-lang.org/en/3.4/yjit/yjit_md.html

Steps to set up an x86 environment on Apple Silicon using Rosetta: install Rosetta, start an x86 shell with arch -x86_64 zsh, verify the architecture, and set the rustc default target to x86-64. Note that you must install a separate Homebrew for each architecture and Cargo installs to $HOME/.cargo by default.

```shell
$ softwareupdate --install-rosetta
```

```shell
$ arch -x86_64 zsh
```

```shell
$ arch -x86_64 zsh
$ arch
i386
```

```shell
$ rustup default stable-x86_64-apple-darwin
```

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

### WIN32OLE::Type#guid implementation and usage

Source: https://docs.ruby-lang.org/en/3.4/WIN32OLE/Type.html

C implementation of the guid method and a Ruby example showing its usage. It returns the GUID of the type.

```c
static VALUE
foletype_guid(VALUE self)
{
    ITypeInfo *pTypeInfo = itypeinfo(self);
    return ole_type_guid(pTypeInfo);
}
```

```ruby
tobj = WIN32OLE::Type.new('Microsoft Excel 9.0 Object Library', 'Application')
puts tobj.guid  # => {00024500-0000-0000-C000-000000000046}
```

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

### Array#[] start+length overflow examples

Source: https://docs.ruby-lang.org/en/3.4/Array.html

Array#[] with start and length when start + length exceeds the array size returns all elements from start to the end.

```ruby
a = [:foo, 'bar', 2]
a[0, 4] # => [:foo, "bar", 2]
a[1, 3] # => ["bar", 2]
a[2, 2] # => [2]

```

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

### Simple file tree used in examples

Source: https://docs.ruby-lang.org/en/3.4/Dir.html

Shows the simple file tree used by examples on this page. The tree includes a directory 'example' with files 'config.h' and 'main.rb', and a 'lib' directory containing 'song.rb' and a 'song' subdirectory with 'karaoke.rb'.

```text
example/
├── config.h
├── lib/
│   ├── song/
│   │   └── karaoke.rb
│   └── song.rb
└── main.rb
```

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

### unix_rights: Get array of IO objects (Ruby example)

Source: https://docs.ruby-lang.org/en/3.4/Socket/AncillaryData.html

Ruby example showing how to use unix_rights with recvmsg. Requires :scm_rights=>true to get the array; otherwise returns nil. The example demonstrates sending a message with SCM_RIGHTS and receiving it, showing the array of IO objects.

```Ruby
# recvmsg needs :scm_rights=>true for unix_rights
s1, s2 = UNIXSocket.pair
p s1                                         #=> #<UNIXSocket:fd 3>
s1.sendmsg "stdin and a socket", 0, nil, Socket::AncillaryData.unix_rights(STDIN, s1)
_, _, _, ctl = s2.recvmsg(:scm_rights=>true)
p ctl                                        #=> #<Socket::AncillaryData: UNIX SOCKET RIGHTS 6 7>
p ctl.unix_rights                            #=> [#<IO:fd 6>, #<Socket:fd 7>]
p File.identical?(STDIN, ctl.unix_rights[0]) #=> true
p File.identical?(s1, ctl.unix_rights[1])    #=> true

# If :scm_rights=>true is not given, unix_rights returns nil
s1, s2 = UNIXSocket.pair
s1.sendmsg "stdin and a socket", 0, nil, Socket::AncillaryData.unix_rights(STDIN, s1)
_, _, _, ctl = s2.recvmsg
p ctl #=> #<Socket::AncillaryData: UNIX SOCKET RIGHTS 6 7>
p ctl.unix_rights #=> nil
```

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

### finish: Complete option setup

Source: https://docs.ruby-lang.org/en/3.4/RDoc/Options.html

Completes unfinished option setup: writes options and exits if requested, sets default output directory, adds root to include, builds exclude regexp, fixes page dir, checks files, sets default template, and loads locale.

```ruby
# File lib/rdoc/options.rb, line 619
def finish
  if @write_options then
    write_options
    exit
  end

  @op_dir ||= 'doc'

  root = @root.to_s
  if @rdoc_include.empty? || !@rdoc_include.include?(root)
    @rdoc_include << root
  end

  @exclude = self.exclude

  finish_page_dir

  check_files

  # If no template was specified, use the default template for the output
  # formatter

  unless @template then
    @template     = @generator_name
    @template_dir = template_dir_for @template
  end

  if @locale_name
    @locale = RDoc::I18n::Locale[@locale_name]
    @locale.load(@locale_dir)
  else
    @locale = nil
  end

  self
end
```

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

### Socket#recvfrom example with server and client

Source: https://docs.ruby-lang.org/en/3.4/Socket.html

Two-file example showing a server that listens and receives up to 20 bytes via recvfrom, and a client that connects and sends a message. Run the server first, then the client.

```ruby
# In one file, start this first
require 'socket'
include Socket::Constants
socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
socket.bind( sockaddr )
socket.listen( 5 )
client, client_addrinfo = socket.accept
data = client.recvfrom( 20 )[0].chomp
puts "I only received 20 bytes '#{data}'"
sleep 1
socket.close

# In another file, start this second
require 'socket'
include Socket::Constants
socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
socket.connect( sockaddr )
socket.puts "Watch this get cut short!"
socket.close

```

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

### Ruby example for WIN32OLE::TypeLib#guid

Source: https://docs.ruby-lang.org/en/3.4/WIN32OLE/TypeLib.html

Creates a TypeLib object and retrieves its GUID string.

```ruby
tlib = WIN32OLE::TypeLib.new('Microsoft Excel 9.0 Object Library')
guid = tlib.guid # -> '{00020813-0000-0000-C000-000000000046}'
```

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

### spec_file() - Get installed spec file path

Source: https://docs.ruby-lang.org/en/3.4/Gem/Installer.html

Returns the location of the spec file that will be installed.

```ruby
# File lib/rubygems/installer.rb, line 426
def spec_file
  File.join gem_home, "specifications", "#{spec.full_name}.gemspec"
end
```

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

### Output of Logger#add examples

Source: https://docs.ruby-lang.org/en/3.4/Logger.html

Output of the previous add method examples.

```text
I, [2022-05-12T16:25:31.469726 #36328]  INFO -- mung: mung
E, [2022-05-12T16:25:55.349414 #36328] ERROR -- mung: No good
E, [2022-05-12T16:26:35.841134 #36328] ERROR -- gnum: No good
```

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

### Set up example variables and files

Source: https://docs.ruby-lang.org/en/3.4/File.html

Defines sample text, Russian, and binary data variables, then writes them to files 't.txt', 't.rus', and 't.dat' (the last with UTF-16 encoding). Used as the basis for many examples in the File class documentation.

```ruby
# English text with newlines.
text = <<~EOT
  First line
  Second line

  Fourth line
  Fifth line
EOT

# Russian text.
russian = "\u{442 435 441 442}" # => "тест"

# Binary data.
data = "\u9990\u9991\u9992\u9993\u9994"

# Text file.
File.write('t.txt', text)

# File with Russian text.
File.write('t.rus', russian)

# File with binary data.
f = File.new('t.dat', 'wb:UTF-16')
f.write(data)
f.close

```

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

### IO#gets with nil and empty separator example

Source: https://docs.ruby-lang.org/en/3.4/IO.html

Ruby example of IO#gets with special separator values: nil reads the entire file, and '' reads a paragraph (up to two line separators).

```ruby
f = File.new('t.txt')
# Get all.
f.gets(nil) # => "First line\nSecond line\n\nFourth line\nFifth line\n"
f.rewind
# Get paragraph (up to two line separators).
f.gets('')  # => "First line\nSecond line\n\n"
f.close

```

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

### Run specific spec with --example

Source: https://docs.ruby-lang.org/en/3.4/contributing/testing_ruby_md.html

Runs a specific spec by matching the test name with the --example flag.

```shell
make test-spec SPECOPTS="../spec/ruby/core/string/to_s_spec.rb --example='returns self when self.class == String'"

```

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

### Install build dependencies with scoop

Source: https://docs.ruby-lang.org/en/3.4/windows_md.html

Installs git, sed, and ruby 3.0 or later using scoop, required when building from GIT source.

```shell
scoop install git sed ruby

```

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

### collect_method example with :preserve

Source: https://docs.ruby-lang.org/en/3.4/FileUtils.html

Example call showing that `:preserve` is accepted by `cp`, `copy`, `cp_r`, and `install`.

```ruby
FileUtils.collect_method(:preserve) # => ["cp", "copy", "cp_r", "install"]
```

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

### install()

Source: https://docs.ruby-lang.org/en/3.4/Gem/Installer.html

Installs the gem and returns a loaded Gem::Specification for the installed gem.

```APIDOC
## install()

### Description
Installs the gem and returns a loaded `Gem::Specification` for the installed gem.

### Method
Instance Method

### Signature
`install()`

### Returns
- **Gem::Specification** - The specification of the installed gem.

### Behavior
- Runs pre-install checks and hooks.
- Removes any previous gem files.
- Extracts files, builds extensions, and writes build info.
- Generates bin scripts and plugins.
- Writes the spec and cache file.
- Runs post-install hooks.
- Raises `Gem::FilePermissionError` if permission is denied.

### Installed Structure
```
@gem_home/
  cache/<gem-version>.gem #=> a cached copy of the installed gem
  gems/<gem-version>/... #=> extracted files
  specifications/<gem-version>.gemspec #=> the Gem::Specification
```
```

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

### Install required libraries with vcpkg

Source: https://docs.ruby-lang.org/en/3.4/windows_md.html

Installs required libraries using vcpkg on the directory of the ruby repository.

```shell
vcpkg --triplet x64-windows install

```

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

### Supervise: ring example with supervisor and re-start

Source: https://docs.ruby-lang.org/en/3.4/ractor_md.html

Ring example that restarts the last Ractor after a Ractor::RemoteError, using a helper method to create Ractors.

```ruby
# ring example with supervisor and re-start

def make_ractor r, i
  Ractor.new r, i do |r, i|
    loop do
      msg = Ractor.receive
      raise if /e/ =~ msg
      r.send msg + "r#{i}"
    end
  end
end

r = Ractor.current
rs = (1..10).map{|i|
  r = make_ractor(r, i)
}

msg = 'e0' # error causing message
begin
  r.send msg
  p Ractor.select(*rs, Ractor.current)
rescue Ractor::RemoteError
  r = rs[-1] = make_ractor(rs[-2], rs.size-1)
  msg = 'x0'
  retry
end

#=> [:receive, "x0r9r9r8r7r6r5r4r3r2r1"]

```

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

### Using example_store in examples

Source: https://docs.ruby-lang.org/en/3.4/PStore.html

Shows the expected usage pattern for examples on this page. The example_store method yields a fresh, populated PStore instance for use inside the block.

```ruby
example_store do |store|
  # Example code using store goes here.
end

```

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

### each_strongly_connected_component_from example

Source: https://docs.ruby-lang.org/en/3.4/TSort.html

Example usage of each_strongly_connected_component_from starting from node 2. Shows the output for two different graphs.

```ruby
class G
  include TSort
  def initialize(g)
    @g = g
  end
  def tsort_each_child(n, &b) @g[n].each(&b) end
  def tsort_each_node(&b) @g.each_key(&b) end
end

graph = G.new({1=>[2, 3], 2=>[4], 3=>[2, 4], 4=>[]})
graph.each_strongly_connected_component_from(2) {|scc| p scc }
#=> [4]
#   [2]

graph = G.new({1=>[2], 2=>[3, 4], 3=>[2], 4=>[]})
graph.each_strongly_connected_component_from(2) {|scc| p scc }
#=> [4]
#   [2, 3]
```

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

### to_mailtext - Example usage

Source: https://docs.ruby-lang.org/en/3.4/URI/MailTo.html

Example showing how to parse a mailto URI and call to_mailtext to get the email text.

```ruby
require 'uri'

uri = URI.parse("mailto:ruby-list@ruby-lang.org?Subject=subscribe&cc=myaddr")
uri.to_mailtext
# => "To: ruby-list@ruby-lang.org\nSubject: subscribe\nCc: myaddr\n\n\n"

```

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

### Size-based rotation setup with three files

Source: https://docs.ruby-lang.org/en/3.4/Logger.html

Sets up a logger with three 1-megabyte files for the size-based rotation example.

```ruby
logger = Logger.new('t.log', 3)

```

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

### Ractor network diagram for basic example

Source: https://docs.ruby-lang.org/en/3.4/ractor_md.html

ASCII diagram showing the network for the previous basic Ractor example: main sends to r, r returns to main.

```text
+------+        +---+
  * main |------> * r *---+
  +------+        +---+   |
      ^                   |
      +-------------------+
```

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

### setup C implementation

Source: https://docs.ruby-lang.org/en/3.4/OpenSSL/SSL/SSLContext.html

C implementation of the Ruby method SSLContext#setup. Configures the SSL_CTX with certificate, key, client CA, CA file/path, verify mode, timeout, and verify depth. Returns nil if the context is frozen, otherwise Qtrue on first call and nil thereafter.

```c
static VALUE
ossl_sslctx_setup(VALUE self)
{
    SSL_CTX *ctx;
    X509 *cert = NULL, *client_ca = NULL;
    EVP_PKEY *key = NULL;
    char *ca_path = NULL, *ca_file = NULL;
    int verify_mode;
    long i;
    VALUE val;

    if(OBJ_FROZEN(self)) return Qnil;
    GetSSLCTX(self, ctx);

#if !defined(OPENSSL_NO_DH)
    SSL_CTX_set_tmp_dh_callback(ctx, ossl_tmp_dh_callback);
#endif

#ifdef HAVE_SSL_CTX_SET_POST_HANDSHAKE_AUTH
    SSL_CTX_set_post_handshake_auth(ctx, 1);
#endif

    val = rb_attr_get(self, id_i_cert_store);
    if (!NIL_P(val)) {
        X509_STORE *store = GetX509StorePtr(val); /* NO NEED TO DUP */
        SSL_CTX_set_cert_store(ctx, store);
        X509_STORE_up_ref(store);
    }

    val = rb_attr_get(self, id_i_extra_chain_cert);
    if(!NIL_P(val)){
        rb_block_call(val, rb_intern("each"), 0, 0, ossl_sslctx_add_extra_chain_cert_i, self);
    }

    /* private key may be bundled in certificate file. */
    val = rb_attr_get(self, id_i_cert);
    cert = NIL_P(val) ? NULL : GetX509CertPtr(val); /* NO DUP NEEDED */
    val = rb_attr_get(self, id_i_key);
    key = NIL_P(val) ? NULL : GetPrivPKeyPtr(val); /* NO DUP NEEDED */
    if (cert && key) {
        if (!SSL_CTX_use_certificate(ctx, cert)) {
            /* Adds a ref => Safe to FREE */
            ossl_raise(eSSLError, "SSL_CTX_use_certificate");
        }
        if (!SSL_CTX_use_PrivateKey(ctx, key)) {
            /* Adds a ref => Safe to FREE */
            ossl_raise(eSSLError, "SSL_CTX_use_PrivateKey");
        }
        if (!SSL_CTX_check_private_key(ctx)) {
            ossl_raise(eSSLError, "SSL_CTX_check_private_key");
        }
    }

    val = rb_attr_get(self, id_i_client_ca);
    if(!NIL_P(val)){
        if (RB_TYPE_P(val, T_ARRAY)) {
            for(i = 0; i < RARRAY_LEN(val); i++){
                client_ca = GetX509CertPtr(RARRAY_AREF(val, i));
                if (!SSL_CTX_add_client_CA(ctx, client_ca)){
                    /* Copies X509_NAME => FREE it. */
                    ossl_raise(eSSLError, "SSL_CTX_add_client_CA");
                }
            }
        }
        else{
            client_ca = GetX509CertPtr(val); /* NO DUP NEEDED. */
            if (!SSL_CTX_add_client_CA(ctx, client_ca)){
                /* Copies X509_NAME => FREE it. */
                ossl_raise(eSSLError, "SSL_CTX_add_client_CA");
            }
        }
    }

    val = rb_attr_get(self, id_i_ca_file);
    ca_file = NIL_P(val) ? NULL : StringValueCStr(val);
    val = rb_attr_get(self, id_i_ca_path);
    ca_path = NIL_P(val) ? NULL : StringValueCStr(val);
#ifdef HAVE_SSL_CTX_LOAD_VERIFY_FILE
    if (ca_file && !SSL_CTX_load_verify_file(ctx, ca_file))
        ossl_raise(eSSLError, "SSL_CTX_load_verify_file");
    if (ca_path && !SSL_CTX_load_verify_dir(ctx, ca_path))
        ossl_raise(eSSLError, "SSL_CTX_load_verify_dir");
#else
    if (ca_file || ca_path) {
        if (!SSL_CTX_load_verify_locations(ctx, ca_file, ca_path))
            ossl_raise(eSSLError, "SSL_CTX_load_verify_locations");
    }
#endif

    val = rb_attr_get(self, id_i_verify_mode);
    verify_mode = NIL_P(val) ? SSL_VERIFY_NONE : NUM2INT(val);
    SSL_CTX_set_verify(ctx, verify_mode, ossl_ssl_verify_callback);
    if (RTEST(rb_attr_get(self, id_i_client_cert_cb)))
        SSL_CTX_set_client_cert_cb(ctx, ossl_client_cert_cb);

    val = rb_attr_get(self, id_i_timeout);
    if(!NIL_P(val)) SSL_CTX_set_timeout(ctx, NUM2LONG(val));

    val = rb_attr_get(self, id_i_verify_depth);
    if(!NIL_P(val)) SSL_CTX_set_verify_depth(ctx, NUM2INT(val));

```

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

### UU-encoding 'u' pack and unpack examples

Source: https://docs.ruby-lang.org/en/3.4/packed_data_rdoc.html

Shows how 'u' encodes and decodes UU-encoded strings. Includes examples for empty, single-character, and multi-character inputs.

```ruby
[""].pack("u")        # => ""
["a"].pack("u")       # => "!80``\n"
["aaa"].pack("u")     # => "#86%A\n"

"".unpack("u")        # => [""]
"#86)C\n".unpack("u") # => ["abc"]
```

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

### Initialize PushCommand with options

Source: https://docs.ruby-lang.org/en/3.4/Gem/Commands/PushCommand.html

Sets up the push command with proxy, key, and OTP options, plus --host and --attestation flags. Tracks whether the host was user-defined.

```ruby
# File lib/rubygems/commands/push_command.rb, line 32
def initialize
  super "push", "Push a gem up to the gem server", host: host, attestations: []

  @user_defined_host = false

  add_proxy_option
  add_key_option
  add_otp_option

  add_option("--host HOST",
             "Push to another gemcutter-compatible host",
             "  (e.g. https://rubygems.org)") do |value, options|
    options[:host] = value
    @user_defined_host = true
  end

  add_option("--attestation FILE",
              "Push with sigstore attestations") do |value, options|
    options[:attestations] << value
  end

  @host = nil
end

```

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

### started?: Check if session is started

Source: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html

Returns true if the HTTP session has been started. The example shows the state changes before, during, and after a session, including with the block form of Net::HTTP.start.

```ruby
# File lib/net/http.rb, line 1484
def started?
  @started
end
```

```ruby
http = Net::HTTP.new(hostname)
http.started? # => false
http.start
http.started? # => true
http.finish # => nil
http.started? # => false

Net::HTTP.start(hostname) do |http|
  http.started?
end # => true
http.started? # => false
```

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

### Array#[] negative range-start examples

Source: https://docs.ruby-lang.org/en/3.4/Array.html

Array#[] with a range whose start is negative calculates the start index from the end of the array.

```ruby
a = [:foo, 'bar', 2]
a[-1..2] # => [2]
a[-2..2] # => ["bar", 2]
a[-3..2] # => [:foo, "bar", 2]

```

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

### gets - Example and Output

Source: https://docs.ruby-lang.org/en/3.4/Kernel.html

Reads lines from a file named 'testfile' (added to ARGV) and prints each line. The output shows the file contents.

```ruby
ARGV << "testfile"
print while gets

```

```text
This is line one
This is line two
This is line three
And so on...

```

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

### Get effective group ID with Process.egid

Source: https://docs.ruby-lang.org/en/3.4/Process.html

Example of calling Process.egid to get the effective group ID. Not available on all platforms.

```ruby
Process.egid # => 500

```

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

### setup_signer(signer_options: {})

Source: https://docs.ruby-lang.org/en/3.4/Gem/Package.html

Prepares the gem for signing and checksum generation.

```APIDOC
## setup_signer(signer_options: {})

### Description
Prepares the gem for signing and checksum generation. If a signing certificate and key are not present, only checksum generation is set up. It uses the GEM_PRIVATE_KEY_PASSPHRASE environment variable for the passphrase.

### Parameters
- **signer_options** (Hash) - Optional - Additional options for the signer. Defaults to {}.

### Source
```ruby
# File lib/rubygems/package.rb, line 568
def setup_signer(signer_options: {})
  passphrase = ENV["GEM_PRIVATE_KEY_PASSPHRASE"]
  if @spec.signing_key
    @signer =
      Gem::Security::Signer.new(
        @spec.signing_key,
        @spec.cert_chain,
        passphrase,
        signer_options
      )

    @spec.signing_key = nil
    @spec.cert_chain = @signer.cert_chain.map(&:to_s)
  else
    @signer = Gem::Security::Signer.new nil, nil, passphrase
    @spec.cert_chain = @signer.cert_chain.map(&:to_pem) if
      @signer.cert_chain
  end
end
```
```

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

### Build Ruby with UCRT in Windows cmd

Source: https://docs.ruby-lang.org/en/3.4/windows_md.html

Build Ruby from source in Windows cmd after enabling the UCRT64 environment. Requires a RubyInstaller-Devkit installation and git-for-windows. Installs OpenSSL, libyaml, and libffi dependencies, then clones the Ruby repository and runs autogen, configure, and make.

```cmd
ridk enable ucrt64

pacman -S --needed %MINGW_PACKAGE_PREFIX%-openssl %MINGW_PACKAGE_PREFIX%-libyaml %MINGW_PACKAGE_PREFIX%-libffi

cd c:\
mkdir work
cd work
git clone https://github.com/ruby/ruby

cd c:\work\ruby
sh autogen.sh
sh configure  -C --disable-install-doc
make
```

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

### dir - Get target install directory

Source: https://docs.ruby-lang.org/en/3.4/Gem/Installer.html

Returns the target install directory (gem_dir) as a string; the directory is not guaranteed to be populated.

```ruby
# File lib/rubygems/installer.rb, line 882
def dir
  gem_dir.to_s
end
```

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

### IO::Buffer#set_string C implementation and Ruby example

Source: https://docs.ruby-lang.org/en/3.4/IO/Buffer.html

C implementation and Ruby usage example for IO::Buffer#set_string. Efficiently copies from a source String into the buffer at offset using memmove. The example sets the buffer starting from offset 1, taking 2 bytes starting from the string's second character.

```c
static VALUE
io_buffer_set_string(int argc, VALUE *argv, VALUE self)
{
    rb_check_arity(argc, 1, 4);

    struct rb_io_buffer *buffer = NULL;
    TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, buffer);

    VALUE string = rb_str_to_str(argv[0]);

    const void *source_base = RSTRING_PTR(string);
    size_t source_size = RSTRING_LEN(string);

    return io_buffer_copy_from(buffer, source_base, source_size, argc-1, argv+1);
}

```

```ruby
buf = IO::Buffer.new(8)
# =>
# #<IO::Buffer 0x0000557412714a20+8 INTERNAL>
# 0x00000000  00 00 00 00 00 00 00 00                         ........

# set buffer starting from offset 1, take 2 bytes starting from string's
# second
buf.set_string('test', 1, 2, 1)
# => 2
buf
# =>
# #<IO::Buffer 0x0000557412714a20+8 INTERNAL>
# 0x00000000  00 65 73 00 00 00 00 00                         .es.....

```
Tokens:
Raw