### Install Addressable Gem in Ruby

Source: https://github.com/sporkmonger/addressable/blob/main/README.md

Provides the command to install the Addressable gem using RubyGems. It also includes optional steps for enabling native IDN support by installing libidn and the idn-ruby gem.

```bash
$ gem install addressable
```

```bash
# Debian/Ubuntu
$ sudo apt-get install libidn11-dev

# OS X
$ brew install libidn

$ gem install idn-ruby
```

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

### Specify Addressable Dependency in Ruby Gemspec

Source: https://github.com/sporkmonger/addressable/blob/main/README.md

Demonstrates how to declare the Addressable gem as a dependency in a Ruby gemspec file using semantic versioning constraints. It shows examples for general versioning and for specifying bug fix releases.

```ruby
spec.add_dependency 'addressable', '~> 2.7'
```

```ruby
spec.add_dependency 'addressable', '~> 2.3', '>= 2.3.7'
```

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

### Origin Extraction from URI in Ruby

Source: https://context7.com/sporkmonger/addressable/llms.txt

Demonstrates how to extract the origin (scheme, host, and port) from a URI using Addressable::URI. It covers standard extraction, handling of non-default ports, omission of default ports, and behavior with relative URIs. Also shows how to set the origin.

```ruby
require "addressable/uri"

# Standard origin extraction
uri = Addressable::URI.parse("https://example.com/path/to/resource?query=value")
uri.origin  #=> "https://example.com"

# Include non-default port
uri = Addressable::URI.parse("http://example.com:8080/api/v1/users")
uri.origin  #=> "http://example.com:8080"

# Default ports are omitted
uri = Addressable::URI.parse("https://example.com:443/secure")
uri.origin  #=> "https://example.com"

# Relative URIs return "null"
uri = Addressable::URI.parse("/path/to/resource")
uri.origin  #=> "null"

# Set origin (resets userinfo)
uri = Addressable::URI.parse("http://user:pass@example.com/path")
uri.origin = "https://secure.example.com:8443"
uri.to_s  #=> "https://secure.example.com:8443/path"
```

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

### Partial Template Expansion in Ruby

Source: https://context7.com/sporkmonger/addressable/llms.txt

Demonstrates partial expansion of Addressable::Template, allowing for staged expansion of URI variables. This is useful when not all variables are known at once, enabling chaining of expansion steps.

```ruby
require "addressable/template"

# Partial expansion preserves unexpanded variables
template = Addressable::Template.new("http://example.com/{?one,two,three}")
partial = template.partial_expand({"one" => "1", "three" => 3})
partial.pattern
#=> "http://example.com/?one=1{&two}&three=3"

# Chain partial expansions
template = Addressable::Template.new("http://{host}/{version}/users/{id}{?filter,sort}")
partial1 = template.partial_expand({"host" => "api.example.com", "version" => "v1"})
partial1.pattern
#=> "http://api.example.com/v1/users/{id}{?filter,sort}"

partial2 = partial1.partial_expand({"id" => "123"})
partial2.pattern
#=> "http://api.example.com/v1/users/123{?filter,sort}"

final = partial2.expand({"filter" => "active", "sort" => "name"})
final.to_s
#=> "http://api.example.com/v1/users/123?filter=active&sort=name"
```

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

### File Path to URI Conversion in Ruby

Source: https://context7.com/sporkmonger/addressable/llms.txt

Shows how to convert various file system paths into file:// URIs using Addressable::URI.convert_path. It handles absolute, relative, and Windows paths, ensuring proper encoding and URI formatting.

```ruby
require "addressable/uri"

# Convert Unix absolute path
uri = Addressable::URI.convert_path("/absolute/path/to/file.txt")
uri.to_s  #=> "file:///absolute/path/to/file.txt"

# Convert relative path (stays relative)
uri = Addressable::URI.convert_path("relative/path/to/file.txt")
uri.to_s  #=> "relative/path/to/file.txt"

# Convert Windows path with backslashes
uri = Addressable::URI.convert_path("c:\\windows\\system32\\file.txt")
uri.to_s  #=> "file:///c:/windows/system32/file.txt"

# Join relative with absolute
base = Addressable::URI.convert_path("/home/user/")
relative = Addressable::URI.convert_path("documents/file.pdf")
result = base + relative
result.to_s  #=> "file:///home/user/documents/file.pdf"

# Handle already-valid URIs
uri = Addressable::URI.convert_path("http://example.com/")
uri.to_s  #=> "http://example.com/"
```

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

### Parse and Normalize URIs with Addressable in Ruby

Source: https://github.com/sporkmonger/addressable/blob/main/README.md

Demonstrates how to parse a URI string into an Addressable::URI object, access its components like scheme, host, and path, and normalize internationalized domain names (IDNs). Requires the 'addressable/uri' library.

```ruby
require "addressable/uri"

uri = Addressable::URI.parse("http://example.com/path/to/resource/")
puts uri.scheme
#=> "http"
puts uri.host
#=> "example.com"
puts uri.path
#=> "/path/to/resource/"

uri_idn = Addressable::URI.parse("http://www.詹姆斯.com/")
puts uri_idn.normalize
#=> #<Addressable::URI:0xc9a4c8 URI:http://www.xn--8ws00zhy3a.com/>
```

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

### Public Suffix and Domain Extraction in Ruby

Source: https://context7.com/sporkmonger/addressable/llms.txt

Illustrates how to extract the top-level domain (TLD) and public suffix domain from a URI using Addressable::URI. It also shows how to set the TLD and demonstrates functionality with internationalized domain names.

```ruby
require "addressable/uri"

# Extract top-level domain
uri = Addressable::URI.parse("http://www.example.co.uk/path")
uri.tld  #=> "co.uk"

# Extract domain (public suffix + one level)
uri = Addressable::URI.parse("http://subdomain.example.co.uk/path")
uri.domain  #=> "example.co.uk"

# Set TLD
uri = Addressable::URI.parse("http://example.com/")
uri.tld = "org"
uri.host  #=> "example.org"

# Works with internationalized domains
uri = Addressable::URI.parse("http://subdomain.example.jp/")
uri.domain  #=> "example.jp"
```

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

### Match and Access URI via Template Variables

Source: https://context7.com/sporkmonger/addressable/llms.txt

This snippet demonstrates how to use Addressable::Template to match a URI and access its captured variables and named parameters. It shows how to extract specific data points like host, version, and resource from a matched URI.

```ruby
require "addressable/template"

template = Addressable::Template.new("http://{host}/api/{version}/{resource}")
uri = Addressable::URI.parse("http://api.example.com/api/v2/users")
match = template.match(uri)
match.variables  #=> ["host", "version", "resource"]
match.captures   #=> ["api.example.com", "v2", "users"]
match["host"]    #=> "api.example.com"
```

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

### Expand and Partially Expand URI Templates in Ruby

Source: https://github.com/sporkmonger/addressable/blob/main/README.md

Illustrates the use of Addressable::Template for expanding variables within a URI template and performing partial expansions. This functionality is useful for dynamically constructing URIs based on provided parameters. Requires the 'addressable/template' library.

```ruby
require "addressable/template"

template = Addressable::Template.new("http://example.com/{?query*}")
expanded_uri = template.expand({
  "query" => {
    'foo' => 'bar',
    'color' => 'red'
  }
})
puts expanded_uri
#=> #<Addressable::URI:0xc9a4c8 URI:http://example.com/?foo=bar&color=red>

template_partial = Addressable::Template.new("http://example.com/{?one,two,three}")
partial_expansion = template_partial.partial_expand({"one" => "1", "three" => 3}).pattern
puts partial_expansion
#=> "http://example.com/?one=1{&two}&three=3"
```

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

### Heuristic URI Parsing with Addressable

Source: https://context7.com/sporkmonger/addressable/llms.txt

Intelligently parses user-friendly URI strings that may not be strictly valid. It can automatically add missing schemes, fix malformed protocols, parse IP addresses, and detect email addresses. Dependencies: 'addressable/uri'.

```ruby
require "addressable/uri"

# Add missing scheme automatically
uri = Addressable::URI.heuristic_parse("example.com/path")
uri.to_s  #=> "http://example.com/path"

# Fix malformed protocol specifications
uri = Addressable::URI.heuristic_parse("http:/example.com")
uri.to_s  #=> "http://example.com"

# Parse IP addresses
uri = Addressable::URI.heuristic_parse("192.168.1.1/admin")
uri.to_s  #=> "http://192.168.1.1/admin"

# Custom scheme hints
uri = Addressable::URI.heuristic_parse("ftp.example.com/files", {:scheme => "ftp"})
uri.to_s  #=> "ftp://ftp.example.com/files"

# Email detection
uri = Addressable::URI.heuristic_parse("user@example.com")
uri.scheme  #=> "mailto"
uri.to_s    #=> "mailto:user@example.com"
```

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

### Join and Resolve URIs using Addressable

Source: https://context7.com/sporkmonger/addressable/llms.txt

Joins relative URIs with base URIs according to RFC 3986 resolution rules. Supports joining with instance or class methods, and the '+' operator. Absolute URIs replace the base URI. Dependencies: 'addressable/uri'.

```ruby
require "addressable/uri"

# Join with instance method
base = Addressable::URI.parse("http://example.com/path/to/")
relative = Addressable::URI.parse("../resource?q=search")
result = base.join(relative)
result.to_s  #=> "http://example.com/path/resource?q=search"

# Join with class method
Addressable::URI.join("http://example.com/", "path", "to", "resource")
#=> #<Addressable::URI:0xcab390 URI:http://example.com/path/to/resource>

# Using + operator
base = Addressable::URI.parse("http://example.com/a/b/")
result = base + "../c/d"
result.to_s  #=> "http://example.com/a/c/d"

# Absolute URIs replace base completely
base = Addressable::URI.parse("http://example.com/path/")
absolute = Addressable::URI.parse("https://other.com/new")
result = base.join(absolute)
result.to_s  #=> "https://other.com/new"
```

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

### Percent Encoding and Decoding with Addressable

Source: https://context7.com/sporkmonger/addressable/llms.txt

Encodes and decodes URI components, offering control over character classes for encoding. Supports encoding full URIs and selective decoding. Dependencies: 'addressable/uri'.

```ruby
require "addressable/uri"

# Encode component with default character class
encoded = Addressable::URI.encode_component("hello world & goodbye")
#=> "hello%20world%20%26%20goodbye"

# Custom character class (preserve spaces and encode others)
encoded = Addressable::URI.encode_component(
  "simple/example",
  Addressable::URI::CharacterClasses::UNRESERVED
)
#=> "simple%2Fexample"

# Decode component
decoded = Addressable::URI.unencode_component("hello%20world%20%26%20goodbye")
#=> "hello world & goodbye"

# Encode full URI
uri = "http://example.com/path with spaces?query=value&special=ü"
encoded_uri = Addressable::URI.encode(uri)
#=> "http://example.com/path%20with%20spaces?query=value&special=%C3%BC"

# Decode with selective preservation
decoded = Addressable::URI.unencode_component("a%2Fb%2Fc", String, "/")
#=> "a%2Fb%2Fc"  (forward slash stays encoded)
```

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

### Extract Components from URI using Addressable Template in Ruby

Source: https://github.com/sporkmonger/addressable/blob/main/README.md

Shows how to extract components from a given URI object based on a defined URI template. This is useful for parsing structured data embedded within a URI. Requires 'addressable/template' and 'addressable/uri'.

```ruby
require "addressable/template"
require "addressable/uri"

template = Addressable::Template.new(
  "http://{host}{/segments*}/{?one,two,bogus}{#fragment}"
)
uri = Addressable::URI.parse(
  "http://example.com/a/b/c/?one=1&two=2#foo"
)

extracted_data = template.extract(uri)
puts extracted_data
#=>
# {
#   "host" => "example.com",
#   "segments" => ["a", "b", "c"],
#   "one" => "1",
#   "two" => "2",
#   "fragment" => "foo"
# }
```

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

### Parse URI from String using Addressable

Source: https://context7.com/sporkmonger/addressable/llms.txt

Parses a URI string into an Addressable::URI object, allowing access to individual components. It supports internationalized domain names and returns nil for nil input. Dependencies: 'addressable/uri'.

```ruby
require "addressable/uri"

# Parse a standard HTTP URI
uri = Addressable::URI.parse("http://user:pass@example.com:8080/path/to/resource?query=value&foo=bar#section")

# Access individual components
uri.scheme       #=> "http"
uri.user         #=> "user"
uri.password     #=> "pass"
uri.host         #=> "example.com"
uri.port         #=> 8080
uri.path         #=> "/path/to/resource"
uri.query        #=> "query=value&foo=bar"
uri.fragment     #=> "section"
uri.authority    #=> "user:pass@example.com:8080"

# Parse internationalized domain name
uri = Addressable::URI.parse("http://www.詹姆斯.com/")
uri.normalize
#=> #<Addressable::URI:0xc9a4c8 URI:http://www.xn--8ws00zhy3a.com/>

# Handle nil and return nil
Addressable::URI.parse(nil)  #=> nil
```

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