Alchemists: Projects

Metapath Project

2026-10-08T22:31:01+00:00

Metapath

Dynamically parses and enriches paths metadata so you can obtain information from directories and files with minimal effort. Having metadata for each directory and/or file — no matter how nested your directory structure is — allows you to perform additional processing on your file structure for analysis, transformation, import, and so much more.

Table of Contents

Features

Dynamically obtains metadata about a directory or a file.
Supports an optional, per directory, configuration.
Supports nested directory structures.
Answers an array of paths with associated metadata.

Requirements

Ruby.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install metapath --trust-policy HighSecurity

To install without security, run:

gem install metapath

You can also add the gem directly to your project:

bundle add metapath

Once the gem is installed, you only need to require it:

require "metapath"

Usage

Getting started is as quick as creating an instance and then pointing it at a directory structure:

metapath = Metapath.new
metapath.call Pathname.pwd

Success(
  [
    #<data Metapath::Model:0x00002710
      attributes = {},
      errors = {},
      label = "Crested Butte",
      name = "crested_butte",
      path = #<Pathname:/Users/demo/Scratch/photos/Crested_Butte.jpeg>,
      position = 0,
      tags = []
    >,
    #<data Metapath::Model:0x00002780
      attributes = {},
      errors = {},
      label = "Flaming Gorge",
      name = "flaming_gorge",
      path = #<Pathname:/Users/demo/Scratch/photos/Flaming_Gorge.jpeg>,
      position = 0,
      tags = []
    >,
    #<data Metapath::Model:0x000027f0
      attributes = {},
      errors = {},
      label = "Grand Canyon",
      name = "grand_canyon",
      path = #<Pathname:/Users/demo/Scratch/photos/Grand_Canyon.jpeg>,
      position = 0,
      tags = []
    >
  ]
)

Roots

When calling a metapath, you must always supply a root path for processing. In the earlier example, this was Pathname.pwd (current path):

metapath.call Pathname.pwd

Strings, if supplied, will be automatically converted into pathnames and auto-expanding into absolute paths. Examples:

metapath.call "~/photos"
# Expands to: #<Pathname:/Users/<your user>/photos>

metapath.call "photos"
# Expands to: #<Pathname:<current working directory>/photos>

metapath.call "/Users/demo/photos"
# Identical: "#<Pathname:/Users/demo/photos>"

All directories and files will be processed within the root path supplied (no matter how deeply nested).

Directories and Files

Each directory and file can have it’s own metadata using any of the following characters:

0-9: Any number is valid.
a-z: Any lowercase letter is valid. This includes Unicode.
A-Z: Any uppercase letter is valid. This includes Unicode.
- (hyphen): Translates to " - " when building the label. Example:
- Before: A-Demo.
- After: A - Demo.
_ (underscore): Translates to " " when building the label. Example:
- Before: A_Demo.
- After: A Demo.
+ (plus): Marks the start of tag or attribute information. See examples below for details.
, (comma): Specifies an array of tag or attribute metdata. See examples below for details.
= (equals): Delimits the key and value of an attribute. For example kind=demo, where kind is the key and demo is the value.
% (percent): Reserved for token replacement as commonly found in Rubysmith for processing of templates where you want to dynamically replace each placeholder (example: %demo%) with a dynamic value that matches the demo key (in this example). Currently meant for post-processing.
. (dot): Reserved for file extensions or multiple formats. Example: demo.html, demo.html.erb, etc.
~ (tilde): Reserved but currently not used.
@ (at): Reserved but currently not used.
^ (carrot): Reserved but currently not used.

All of the characters shown above allow you to have files and directories that don’t require special quoting which works well across multiple operating systems.

Positions

Prefix your directories or files with a number immediately followed by a dash to keep them organized but also for sequential processing order.

Format: <position>-<name>
Example 01-demo

The position is always 0 when none is given.

Attributes

Use attributes to provide additional metadata about your directories and files (use a comma to separate multiple values).

Format (single): <name>+<key>=<value>
Example (single): demo+album=panoramas
Format (multiple): <name>+<key>=<value>,<key>=<value>,<key>=<value>
Example (multiple): demo+album=panoramas,kind=landscapes,location=snow_peak

💡 Use a directory configuration (meta.yml) to extract common metadata if your metadata gets too long and unwieldy.

Configurations

You can configure common metadata per directory by placing a meta.yml in the root of any directory. The following is an example of what this file might contain:

tags:
  - demo
  - photos
attributes:
  album: panoramas
  kind: landscapes

With the above, you can supply as many tags and attributes as necessary which will then be inherited as common metadata when processing files within the directory. This includes inheriting configurations from parent directories. Keep in mind that any file with it’s own metdata will take precedence.

Only the tag and attributes keys are honored, all other top level keys are ignored.

Priority

Metadata is resolved by merging each of the following in order listed (lowest to highest):

Directory
meta.yml
File

Resolution of the above happens by merging metadata from the lowest level into the next level until all levels are merged as one. This means you can set defaults at the lowest level which will be inherited, or overwritten, at the highest level. In pseudo code, it looks like this:

directory.deep_merge(meta).deep_merge file

Monads

Every time you call your metapath instance, you’ll get either a Success or Failure as provided by Dry Monads. This allows you to use the Railway Pattern pattern to build fault tolerant functional pipelines for robust error processing.

When results are a success, you’ll get an array of models. Example:

Success(
  [
    #<data Metapath::Model:0x00002710
      attributes = {},
      label = "Crested Butte",
      name = "crested_butte",
      path = #<Pathname:/Users/demo/Scratch/photos/Crested_Butte.jpeg>,
      position = 0,
      tags = []
    >
  ]
)

You can get a success when errors are detected with metadata associated with your directories or files. For example, let’s say your meta.yml has the following content:

attributes:

Success(
  [
    #<data Metapath::Model:0x00002710
      attributes = {},
      errors = {attributes: ["must be filled"]},
      label = "Crested Butte",
      name = "crested_butte",
      path = #<Pathname:/Users/demo/Scratch/photos/Crested_Butte.jpeg>,
      position = 0,
      tags = []
    >
  ]
)

If a failure does occur, this usually means errors with your configuration. For example, let’s say your meta.yml has the following content:

Danger!

This means you’ll get the following result:

Failure "Invalid content: Danger."

Models

Each model is a Data object. Additionally, the following methods are also provided for you:

model = Metapath::Model[
  name: "demo",
  label: "Demo",
  tags: %w[demo photos],
  attributes: {
    "album" => "panoramas",
    "kind" => "landscapes"
  }
]

model.fetch "album"                  # "panoramas"
model.fetch "bogus", "fallback"      # "fallback"
model.fetch("bogus") { "fallback" }  # "fallback"
model.fetch "bogus"                  # KeyError

model.key? "album"                   # true
model.key? "bogus"                   # false

model.tag? "photos"                  # true
model.tag? "bogus"                   # false

other = Metapath::Model[name: "other", path: Pathname("_demo.html")]

other.partial?                       # true
model.partial?                       # false

other = Metapath::Model[name: "other", path: Pathname("demo.html"), errors: {message: "Danger!"}]

other.errors?                       # true
model.errors?                       # false

Development

To contribute, run:

git clone https://github.com/bkuhlmann/metapath
cd metapath
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.

Superfluid Project

2026-08-30T20:54:20+00:00

Superfluid

Enhances Liquid by smoothing out the rough edges with a strong focus on object composition and functional design. This includes a fully functional filter and tag registry so you can reuse lower level filters and tags within all aspects of your view layer.

Table of Contents

Features

Uses a customizable default environment with a cleaner Object API.
Uses Containable for filter and tag registries.
Registers filters via a Module, Functionable, commands (see Command Pattern for details), or containers (see Containable for details).
Registers tags via classes or containers (see Containable for details).
Provides a default renderer for quick rendering of templates and associated data.

Requirements

Ruby.
Liquid.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install superfluid --trust-policy HighSecurity

To install without security, run:

gem install superfluid

You can also add the gem directly to your project:

bundle add superfluid

Once the gem is installed, you only need to require it:

require "superfluid"

Usage

The quickest way to get started is to create a new instance:

renderer = Superfluid.new

Then you can render your template and associated data:

renderer.call "Hi, this is a {{ value }}.", "value" => "demo"

The above will yield the following output:

"Hi, this is a demo."

The following sections detail how you can configure your environment, register filters, and register tags.

Configuration

The configuration is used by the environment. This is created for you automatically but if you want an instance of the default configuration, use:

configuration = Superfluid::Configuration.new

#<Struct:Superfluid::Configuration:0x00001780
  default_resource_limits = {},
  error_mode = :strict,
  exception_renderer = #<Proc:0x0000000131200ee0 (lambda)>,
  file_system = #<data Superfluid::Systems::Memory:0x000017b0 templates = {}>,
  filter_registry = #<Superfluid::Registries::Filter:0x000000012f5a1290 @container=Superfluid::Filters::Container, @mode=:strict>,
  tag_registry = #<Superfluid::Registries::Tag:0x000000012f5860d0 @container=Superfluid::Tags::Container>
>

As you can see, the configuration is a Struct which means you can customize using any of these attributes:

default_resource_limits: Limits the resources that a template can consume. Default: {}.
error_mode: The error mode (details). Default: :strict.
exception_renderer: The function used to render error messages. Default: Core::Identity (see Core).
file_system: The file system. Default: Superfluid::Systems::Memory.new.
filter_registry: The filter registry. Default: Superfluid::Registries::Filter.new.
tag_registry: The tag registry. Default: Superfluid::Registries::Tag.new.

Environments

To build the default environment, use:

environment = Superfluid.build

To build the default environment directly (which is what the above does), use:

environment = Superfluid::Environment.new

If you’d like to build a custom environment, you can do this several ways. For demonstration purposes, only the error_mode is used below but all configuration attributes are accepted:

environment = Superfluid.build error_mode: :lax
environment = Superfluid::Environment.for error_mode: :lax
environment = Superfluid::Environment.new Superfluid::Configuration[error_mode: :lax]

You can also freeze the environment — which also freezes the filter and tag registries — once you’ve registered any/all filters and tags as follows:

environment.freeze

Systems

These are the file systems used to obtain templates for use within your custom tags. By default, an in memory system is provided for you: Superfluid::Systems::Memory. Liquid also provides it’s own systems as well. Each are described below.

Memory

Provided by this gem. Use to access templates via an in memory file system. This is enabled for you be default when using Superfluid.new and works in conjunction with the template tag which is also provided by this gem (see below for details). Again, this system is provided for you but you can be explicit if desired:

environment = Superfluid.build file_system: Superfluid::Systems::Memory.new
renderer = Superfluid.new(environment:)

template = <<~CONTENT
  {% template demo %}
    Hi, this is a {{ subject }}.
  {% endtemplate %}

  {% render "demo", subject: "demo" %}
CONTENT

renderer.call template
# "Hi, this is a demo."

Local

Provided by Liquid. Use to access templates via your local file system within a specific root folder. Usage:

Pathname("templates").tap(&:mkdir).join("_demo.liquid").tap { it.write "{{ salutation }}" }

environment = Superfluid.build file_system: Liquid::LocalFileSystem.new(Pathname("templates"))
renderer = Superfluid.new(environment:)

renderer.call(%({% include "demo" %}, this is a demo), {"salutation" => "Hi"})
# "Hi, this is a demo"

The above configures the local system to look for partials (templates) within the templates folder. You then reference them via the include tag.

By default, this system uses Kernel#format syntax to find your partials (i.e. "_%s.liquid"). If you don’t like this pattern, you can configure differently when creating a new instance. Example:

Liquid::LocalFileSystem.new "/a/path", "%s.html"

Blank

Provided by Liquid. This is an abstract class — meant for subclassing — because it will fail with a FileSystemError when read_template_file isn’t implemented. Usage:

environment = Superfluid.build file_system: Liquid::BlankFileSystem.new(Pathname("templates"))
renderer = Superfluid.new(environment:)

The above does nothing and is benign.

Filters

By default, Liquid only allows registration of filters as instance methods on a namespace (Module). Unfortunately, this leads to terrible design, bad practices, and unnecessarily hard to test objects. You can still register namespaces but this gem encourages the use of commands (see Command Pattern for further details) and containers via Containable which allows you tap into Functional Programming by using procs, lambdas, and any object that responds to #call. This allows you to build — and reuse — more powerful filters. The following details the different kinds of filters you can use, each broken down by category.

Defaults

Default filters are provided for you automatically and can be viewed via your environment. Example:

environment = Superfluid.build
environment.filter_registry.names

The above will produce a list of all registered filters. These including all filters provided by Liquid and those unique to this gem which are:

`jsonify`

Renders objects as JSON. Example:

renderer.call(%({{ data | jsonify }}), {"data" => {"a" => 1}})
# "{\"a\":1}"

`parse_json`

Parses JSON as a primitive. Example:

renderer.call(
  "{% assign data = payload | parse_json %}{{ data.one }}",
  {"payload" => %({"one": 1, "two": 2})}
)

# "1"

`pluralize`

Renders a plural string. Example:

renderer.call(%({{ text | pluralize: 0 }}), {"text" => "apple"})
# "0 apples"

renderer.call(%({{ text | pluralize: 1 }}), {"text" => "apple"})
# "1 apple"

renderer.call(%({{ text | pluralize: 2 }}), {"text" => "apple"})
# "2 apples"

renderer.call(%({{ text | pluralize: 3, "i", "us" }}), {"text" => "octopus"})
# "3 octopi"

`singularize`

Renders a singular string. Example:

renderer.call(%({{ text | singularize: 0 }}), {"text" => "apples"})
# "0 apples"

renderer.call(%({{ text | singularize: 1 }}), {"text" => "apples"})
# "1 apple"

renderer.call(%({{ text | singularize: 2 }}), {"text" => "apples"})
# "2 apples"

renderer.call(%({{ text | singularize: 1, "i", "us" }}), {"text" => "octopi"})
# "1 octopus"

`trim_end`

Renders string with trimmed end. Example:

renderer.call(%({{ text | trim_end: 10 }}), {"text" => "A demo."})
# "A demo."

renderer.call(%({{ text | trim_end: 10 }}), {"text" => "This is a demo."})
# "This is..."

renderer.call(%({{ text | trim_end: 10, "", "---" }}), {"text" => "This is a demo."})
# "This is---"

renderer.call(%({{ text | trim_end: 10, "", "" }}), {"text" => "This is a demo."})
# "This is a"

`trim_middle`

Renders string with trimmed middle. Example:

renderer.call(%({{ text | trim_middle: 20 }}), {"text" => "This is a demo."})
# "A demo."

renderer.call(%({{ text | trim_middle: 13 }}), {"text" => "This is a demo."})
# "This...demo."

renderer.call(%({{ text | trim_middle: 13, "--" }}), {"text" => "This is a demo."})
# "This--demo."

Modules

Module instance methods are what Liquid supports by default. You only need to define instance methods within a module and then register your module. Example:

# Namespaces
module Primary
  def echo(text) = text
end

module Secondary
  def capitalize(text) = text.capitalize

  def suffix(text, count = 1) = "#{text}-#{count}"
end

# Renderer
renderer = Superfluid.new { it.register_filters Primary, Secondary }

# Results
renderer.call %({{ "demo" | echo }})        # "demo"
renderer.call %({{ "demo" | capitalize }})  # "Demo"
renderer.call %({{ "demo" | suffix }})      # "demo-1"
renderer.call %({{ "demo" | suffix: 2 }})   # "demo-2"

As you can see, all three methods via the two namespaces are properly registered and immediately available for use. You’ll also notice multiple namespaces were registered at once but you can register them individually and/or chain them. Examples:

Superfluid.new do |environment|
  # Single.
  environment.register_filter Primary

  # Multiple.
  environment.register_filters Primary, Secondary

  # Chained.
  environment.register_filter(Primary)
             .register_filter(Secondary)
             .register_filters(Primary, Secondary)
end

Functionables

Functionable modules are identical to the module examples, as shown above, except you require and extend instead. Example:

require "functionable"

# Namespaces
module Primary
  extend Functionable

  def echo(text) = text
end

module Secondary
  extend Functionable

  def capitalize(text) = text.capitalize

  def suffix(text, count = 1) = "#{text}-#{count}"
end

This allows you to use purely functionable methods (see Functionable documentation for details). At this point, you can register your functionable namespaces as follows:

# Renderer
renderer = Superfluid.new { it.register_filters Primary, Secondary }

# Results
renderer.call %({{ "demo" | echo }})        # "demo"
renderer.call %({{ "demo" | capitalize }})  # "Demo"
renderer.call %({{ "demo" | suffix }})      # "demo-1"
renderer.call %({{ "demo" | suffix: 2 }})   # "demo-2"

Registration is identical to modules:

Superfluid.new do |environment|
  # Single.
  environment.register_filter Primary

  # Multiple.
  environment.register_filters Primary, Secondary

  # Chained.
  environment.register_filter(Primary)
             .register_filter(Secondary)
             .register_filters(Primary, Secondary)
end

Procs and Lambdas

Procs and lambdas are not supported by Liquid but are via this gem. Example:

# Setup

echo = proc { it }
capitalize = -> text { text.capitalize }
suffix = -> text, count = 1 { "#{text}-#{count}" }

# Renderer
renderer = Superfluid.new { it.register_filters echo:, capitalize:, suffix: }

# Results

renderer.call %({{ "demo" | echo }})        # "demo"
renderer.call %({{ "demo" | capitalize }})  # "Demo"
renderer.call %({{ "demo" | suffix }})      # "demo-1"
renderer.call %({{ "demo" | suffix: 2 }})   # "demo-2"

Registration can be singular, plural, or chained:

renderer = Superfluid.new do |environment|
  # Single.
  environment.register_filter(echo:)

  # Multiple.
  environment.register_filters(echo:, capitalize:, suffix:)

  # Chained.
  environment.register_filter(echo:)
             .register_filter(capitalize:)
             .register_filters(echo:, capitalize:, suffix:)
end

Classes

Classes, especially composable classes, are not supported by Liquid but are via this gem. You only need to ensure you include Core::Composable and implement the #call method. Example:

require "core"

class Suffixer
  include Core::Composable

  def initialize default: 1
    @default = default
  end

  def call(text, suffix = default) = "#{text}-#{suffix}"

  private

  attr_reader :default
end

Now you can register and render with the above class as follows:

# Renderer
renderer = Superfluid.new { it.register_filters suffix: Suffixer.new }

# Results

renderer.call %({{ "demo" | suffix }})      # "demo-1"
renderer.call %({{ "demo" | suffix: 2 }})   # "demo-2"

Registration can be singular, plural, or chained:

suffix = Suffixer.new

renderer = Superfluid.new do |environment|
  # Single.
  environment.register_filter(suffix:)

  # Multiple.
  environment.register_filters(suffix:)

  # Chained.
  environment.register_filter(suffix:)
             .register_filters(suffix:)
end

Containers

Containers are not supported by Liquid but are via this gem using Containable. To use, create a container and then register your dependencies:

require "containable"

module Container
  extend Containable

  register(:echo) { |text| text }
  register(:suffix) { |text, count = 1| "#{text}-#{count}"  }
end

Now you can merge the container as follows:

renderer = Superfluid.new { it.merge_filters Container }

You can also selectively merge by supplying only the filters you care about from the container:

renderer = Superfluid.new { it.merge_filters Container, :suffix }

Once registered, then you can use as follows:

renderer.call %({{ "demo" | echo }})       # "demo"
renderer.call %({{ "demo" | suffix }})     # "demo-1"
renderer.call %({{ "demo" | suffix: 2 }})  # "demo-2"

With containers, you have the full capabilities of the Containable. The above only scratches the surface of what’s possible.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/superfluid
cd superfluid
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.

RFC API Problem Project

2026-08-22T20:29:24+00:00

RFC API Problem

RFC API Problem implements RFC 9457: Problem Details for HTTP APIs. This allows you to produce HTTP error responses that are structured, machine readable, and consistent.

Table of Contents

Features

Provides JSON and XML serialization and deserialization.
Provides HTTP header and media type support.

Requirements

Ruby.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install rfc-api-problem --trust-policy HighSecurity

To install without security, run:

gem install rfc-api-problem

You can also add the gem directly to your project:

bundle add rfc-api-problem

Once the gem is installed, you only need to require it:

require "rfc/api/problem"

Usage

The quickest way to get started is to create a new instance and then cast as JSON or XML:

payload = RFC::API::Problem[
  type: "https://demo.io/problem_details/timeout",
  status: 413,
  detail: "You've exceeded the 5MB upload limit.",
  instance: "/profile/3a1bfd54-ae6c-4a61-8d0d-90c132428dc3"
]

payload.to_json

# {
#   "type" => "https://demo.io/problem_details/timeout",
#   "title" => "Content Too Large",
#   "status" => 413,
#   "detail" => "You've exceeded the 5MB upload limit.",
#   "instance" => "/profile/3a1bfd54-ae6c-4a61-8d0d-90c132428dc3"
# }

payload.to_xml

# <?xml version='1.0' encoding='UTF-8'?>
# <problem xmlns='urn:ietf:rfc:7807'>
#   <type>https://demo.io/problem_details/timeout</type>
#   <title>Content Too Large</title>
#   <status>413</status>
#   <detail>You&apos;ve exceeded the 5MB upload limit.</detail>
#   <instance>/profile/3a1bfd54-ae6c-4a61-8d0d-90c132428dc3</instance>
# </problem>

💡 You can also use RFC::API::Problem.new to create instances if you don’t like RFC::API::Problem.[], as shown above, but .[] is preferred.

Members

As briefly shown above, the minimum members (attributes) that make up problem details are:

type (optional): The full (or relative) URI that links to additional documentation. Default: "about:blank".
status (optional): The HTTP status code (or symbol) that must match your HTTP status code. Default: nil.
title (optional): The HTTP status label that must match your HTTP status code label. Default: HTTP status label (dynamically computed based on code unless overwritten).
detail (optional): The human readable reason for the error (should not include debugging information). Default: nil.
instance (optional): The full (or relative) URI that represents the cause of the error. Default: nil.
extensions (optional): A free form hash of additional details. Default: {}.

Media Types

For convenience, you can obtain the necessary media types for your HTTP headers as follows:

RFC::API::Problem::MEDIA_TYPE_JSON  # "application/problem+json"
RFC::API::Problem::MEDIA_TYPE_XML   # "application/problem+xml"

RFC::API::Problem.media_type_for :json  # "application/problem+json"
RFC::API::Problem.media_type_for :xml   # "application/problem+xml"

Payload

You’ll always get a RFC::API::Problem::Payload object answered back when using RFC::API::Problem.[] or RFC::API::Problem.new for which you can cast to JSON, XML, and other types. There are few conveniences provided for you when constructing a new payload. For instance, you can also use status to set default title:

RFC::API::Problem[status: 413]

# #<data RFC::API::Problem::Payload:0x00002950
#   detail = nil,
#   extensions = {},
#   instance = nil,
#   status = 413,
#   title = "Content Too Large",
#   type = "about:blank"
# >

Notice that standard HTTP 413 title of "Content Too Large" is provided for you but only if you don’t supply a title. This works for symbols too. Example:

RFC::API::Problem[status: :bad_request]

# #<data RFC::API::Problem::Payload:0x00002970
#   detail = nil,
#   extensions = {},
#   instance = nil,
#   status = 400,
#   title = "Bad Request",
#   type = "about:blank"
# >

This is similar to the above, but notice the status is cast to an integer while the title is also populated for you. Using either an integer or symbol for the HTTP status is handy for situations where you don’t need a custom title and prefer the default HTTP title.

Due to the payload being a Data object, you have all of the standard methods available to you which are frozen by default. That said, you can still add or check for extensions after the fact. Example:

payload = RFC::API::Problem[status: :forbidden]

payload.add_extension(:account, "/accounts/1")
       .add_extension(:balance, 50)

# #<data RFC::API::Problem::Payload:0x000029a0
#   detail = nil,
#   extensions = {
#     account: "/accounts/1",
#     balance: 50
#   },
#   instance = nil,
#   status = 403,
#   title = "Forbidden",
#   type = "about:blank"
# >

Given the above, you can also check if an extension exists:

payload.extension? :account  # true
payload.extension? :bogus    # false

JSON

Both serialization and deserialization of JSON is supported. For example, given the following payload:

payload = RFC::API::Problem[
  type: "https://demo.io/problem_details/out_of_credit",
  title: "You do not have enough credit.",
  status: 403,
  detail: "Your current balance is 30, but that costs 50.",
  instance: "/accounts/1",
  extensions: {
    balance: 30,
    accounts: %w[/accounts/1 /accounts/10]
  }
]

This means you can serialize as follows:

payload.to_json

# "{\"type\":\"https://demo.io/problem_details/out_of_credit\",\"title\":\"You do not have enough credit.\",\"status\":403,\"detail\":\"Your current balance is 30, but that costs 50.\",\"instance\":\"/accounts/1\",\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}"

payload.to_json indent: "  ", space: " ", object_nl: "\n", array_nl: "\n"

# {
#   "type": "https://demo.io/problem_details/out_of_credit",
#   "title": "You do not have enough credit.",
#   "status": 403,
#   "detail": "Your current balance is 30, but that costs 50.",
#   "instance": "/accounts/1",
#   "balance": 30,
#   "accounts": [
#     "/accounts/1",
#     "/accounts/10"
#   ]
# }

💡 All of the JSON output options are available to you when casting to JSON.

You can also deserialize by taking the result of the above and turning the raw JSON back into a RFC::API::Problem::Payload:

RFC::API::Problem.from_json "{\"type\":\"https://demo.io/problem_details/out_of_credit\",\"title\":\"You do not have enough credit.\",\"status\":403,\"detail\":\"Your current balance is 30, but that costs 50.\",\"instance\":\"/accounts/1\",\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}"

# #<data RFC::API::Problem::Payload:0x00002d10
#   detail = "Your current balance is 30, but that costs 50.",
#   extensions = {
#      balance: 30,
#     accounts: [
#       "/accounts/1",
#       "/accounts/10"
#     ]
#   },
#   instance = "/accounts/1",
#   status = 403,
#   title = "You do not have enough credit.",
#   type = "https://demo.io/problem_details/out_of_credit"
# >

XML

XML is supported too but isn’t as robust as JSON support, at the moment. This is mostly due to the fact that extensions can be deeply nested so your mileage may vary. For example, given the following payload:

payload = RFC::API::Problem[
  type: "https://demo.io/problem_details/out_of_credit",
  title: "You do not have enough credit.",
  status: 403,
  detail: "Your current balance is 30, but that costs 50.",
  instance: "/accounts/1",
  extensions: {
    balance: 30,
    accounts: %w[/accounts/1 /accounts/10]
  }
]

This means you can serialize as follows:

payload.to_xml
# "<?xml version='1.0' encoding='UTF-8'?><problem xmlns='urn:ietf:rfc:7807'><type>https://demo.io/problem_details/out_of_credit</type><title>You do not have enough credit.</title><status>403</status><detail>Your current balance is 30, but that costs 50.</detail><instance>/accounts/1</instance><balance>30</balance><accounts><i>/accounts/1</i><i>/accounts/10</i></accounts></problem>"

payload.to_xml indent: 2
# <?xml version='1.0' encoding='UTF-8'?>
# <problem xmlns='urn:ietf:rfc:7807'>
#   <type>
#     https://demo.io/problem_details/out_of_credit
#   </type>
#   <title>
#     You do not have enough credit.
#   </title>
#   <status>
#     403
#   </status>
#   <detail>
#     Your current balance is 30, but that costs 50.
#   </detail>
#   <instance>
#     /accounts/1
#   </instance>
#   <balance>
#     30
#   </balance>
#   <accounts>
#     <i>
#       /accounts/1
#     </i>
#     <i>
#       /accounts/10
#     </i>
#   </accounts>
# </problem>

💡 All of the REXML::Document.write output options are available to you when casting to XML.

You can also deserialize by taking the result of the above and turning the raw JSON back into a RFC::API::Problem::Payload:

payload = RFC::API::Problem.from_xml <<~XML
  <?xml version='1.0' encoding='UTF-8'?>
  <problem xmlns='urn:ietf:rfc:7807'>
    <type>https://demo.io/problem_details/out_of_credit</type>
    <title>You do not have enough credit.</title>
    <status>403</status>
    <detail>Your current balance is 30, but that costs 50.</detail>
    <instance>/accounts/1</instance>
    <balance>30</balance>
    <accounts>
      <i>/accounts/1</i>
      <i>/accounts/10</i>
    </accounts>
  </problem>
XML

# #<data RFC::API::Problem::Payload:0x00000940
#   detail = "Your current balance is 30, but that costs 50.",
#   extensions = {
#      balance: "30",
#     accounts: [
#       "/accounts/1",
#       "/accounts/10"
#     ]
#   },
#   instance = "/accounts/1",
#   status = 403,
#   title = "You do not have enough credit.",
#   type = "https://demo.io/problem_details/out_of_credit"
# >

Examples

There is a lot of useful information you can provide in your problem details depending on the context you are working in. Some have been shown above but here’s a few more that might be of interest.

HATEOAS

With HATEOAS, you can provide additional information and links for which the client can understand what next actions are available. The below example shows how you can provide additional resources for clients to adjust accordingly:

RFC::API::Problem[
  type: "https://demo.io/problem_details/rate_limit",
  title: "Rate limit exceeded",
  status: 429,
  detail: "You have exceeded your rate limit of 150 requests per minute",
  instance: "/articles",
  extensions: {
    retry_after: 5,
    links: [
      {
        ref: "self",
        href: "/articles"
      },
      {
        rel: "retry",
        href: "/articles",
        title: "Retry after five minutes"
      },
      {
        rel: "status",
        href: "/statuses/rate_limit",
        title: "Check current rate limit usage"
      }
    ]
  }
]

Semantic Structure

In other situations, you might need a different structure in order to aid clients that might be AI driven which needs a semantically structured response in order to course correct. Example:

RFC::API::Problem[
  type: "https://demo.io/problem_details/invalid_field",
  title: "Invalid field value",
  status: 400,
  detail: "The category requested doesn't exist",
  instance: "/categories",
  extensions: {
    parameters: {
      category_id: 123
    },
    suggestions: [
      "ruby",
      "git",
      "htmx"
    ]
  }
]

With the above, the client now knows what parameters where invalid along with relevant suggestions for proceeding. Even better, the suggestions implicitly show the types of IDs that are required.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/rfc-api-problem
cd rfc-api-problem
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

Resources

You can find additional resources here:

IANA Hypertext Transfer Protocol (HTTP) Problem Types: A registered list of problem types you can use.
HTTP Problem Type Registration Requests: Where you can register new problem types.

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.

RFC Web Link Project

2026-08-22T17:22:35+00:00

RFC Web Link

RFC Web Link implements RFC 8288: Web Linking. This allows you to process links via the HTTP link header when processing HTTP responses. For example, the following demonstrates a HTTP link header which links to a previous and next article:

link: <https://demo.io/articles?page=1>; rel="previous"; title="Previous",
      <https://demo.io/articles?page=3>; rel="next"; title="Next"

The above parses each line, delimited by a comma (,), and then each pair (attribute) in the line as delimited by a semicolon (;). This is not something you want to reinvent for each application you maintain so this gem handles the parsing (and creation) of HTTP link headers so you can stay focused on your own business logic.

Table of Contents

Features

Implements RFC 8288.
Parses web link headers into whole value objects for processing and/or inspection.
Provides explicit or implicit casting of whole value objects into a web links.

Requirements

Ruby.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install rfc-web-link --trust-policy HighSecurity

To install without security, run:

gem install rfc-web-link

You can also add the gem directly to your project:

bundle add rfc-web-link

Once the gem is installed, you only need to require it:

require "rfc/web/link"

Usage

The fastest way to get started is to create a new instance of the parser that you can reuse upon each HTTP request. Example:

parser = RFC::Web::Link.new "https://demo.io"

Then you can use the parser instance to parse HTTP headers and build lists you can interact with:

parser.call({"link" => "</articles>; rel=index"})

The above will yield the following set of links (in this case, only with a single link):

#<data RFC::Web::Link::Models::List:0x00000900
  links = [
    #<data RFC::Web::Link::Models::Link:0x00000920
      pairs = [                                                                                                                                                                                  #<data RFC::Web::Link::Models::Pair:0x00000940
          delimiter = "=",
          encoding = nil,
          key = "rel",
          language = nil,
          value = "index"
        >
      ],
      uri = "https://demo.io/articles"
    >
  ]
>

As you can see, you get an immutable Data (whole value) object for which you can directly access all attributes.

Root URI

A root URI (root_uri) must be supplied in order to resolve all relative URIs as absolute URIs. Generally, the root_uri is your host (i.e. primary domain). There are a few ways you can supply the root URI:

Initialization

The following sets the root URI globally so you only have to define it once:

parser = RFC::Web::Link.new "https://demo.io"

Call

The following sets the root URI per call.

parser = RFC::Web::Link.new
parser.call({"link" => "</articles>; rel=index"}, root_uri: "https://demo.io")

Call (override)

The following sets the root URI globally but also allows you to override the global value with a custom value per call.

parser = RFC::Web::Link.new "https://demo.io"

parser.call({"link" => "</articles>; rel=index"}, root_uri: "https://alt.io")

Delimiters

Each delimiter provides the following behavior:

Semicolon (;): Delimits each pair associated with a line.
Comma (,): Delimits each line of a link.

They must be quoted when not used as delimiters.

Attributes

There are six RFC 8288 registered target attributes:

anchor
hreflang
media
rel
title
type

Each is described in detail below.

anchor

Optional but, when supplied, can be a single string, quoted with special characters, a relative URI, or an absolute URI. Here’s a few examples:

Fragment: #footer
Quoted (special characters): "#overview,body,footer"
Relative URI: /policies
Absolute URI: https://demo.io/about

Relative URIs will automatically be expanded into an absolute URIs when parsed. This means if the root_uri is https://demo.io and the anchor’s value is /policies (relative), then the resulting URI will be: https://demo.io/polices. Examples:

Fragment

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; anchor=#footer"})

# #<data RFC::Web::Link::Models::List:0x000016f0
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x00001710
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00001730
#           delimiter = "=",
#           encoding = nil,
#           key = "anchor",
#           language = nil,
#           value = "#footer"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
>

list.to_s

# "<https://demo.io/articles>; anchor=#footer"

Quoted

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => %(</articles>; anchor="#overview,body,footer")})

# #<data RFC::Web::Link::Models::List:0x00001660
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x00001680
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000016a0
#           delimiter = "=",
#           encoding = nil,
#           key = "anchor",
#           language = nil,
#           value = "\"#overview,body,footer\""
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; anchor=\"#overview,body,footer\""

Relative URI

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; anchor=/policies"})

# #<data RFC::Web::Link::Models::List:0x000017c0
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000017e0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00001800
#           delimiter = "=",
#           encoding = nil,
#           key = "anchor",
#           language = nil,
#           value = "https://demo.io/policies"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; anchor=https://demo.io/policies"

Absolute URI

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; anchor=https://demo.io/about"})

# #<data RFC::Web::Link::Models::List:0x00001890
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000018b0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000018d0
#           delimiter = "=",
#           encoding = nil,
#           key = "anchor",
#           language = nil,
#           value = "https://demo.io/about"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; anchor=https://demo.io/about"

hreflang

Optional but, when supplied, is a hint indicating the language of the associated link. This does not override the value of the content-language header. Example:

Single

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; hreflang=en"})

# #<data RFC::Web::Link::Models::List:0x00000890
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000008b0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000008d0
#           delimiter = "=",
#           encoding = nil,
#           key = "hreflang",
#           language = nil,
#           value = "en"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; hreflang=en"

Multiple

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; hreflang=en; hreflang=de"})

# #<data RFC::Web::Link::Models::List:0x000016c0
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000016e0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00001700
#           delimiter = "=",
#           encoding = nil,
#           key = "hreflang",
#           language = nil,
#           value = "en"
#         >,
#         #<data RFC::Web::Link::Models::Pair:0x00001740
#           delimiter = "=",
#           encoding = nil,
#           key = "hreflang",
#           language = nil,
#           value = "de"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; hreflang=en; hreflang=de"

media

Optional but, when supplied, is a hint indicating the kind of media associated with the link. Example:

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; media=print"})

# #<data RFC::Web::Link::Models::List:0x000017d0
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000017f0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00001810
#           delimiter = "=",
#           encoding = nil,
#           key = "media",
#           language = nil,
#           value = "print"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; media=print"

rel

Required and must be first defined. Example:

Single

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; rel=index"})

# #<data RFC::Web::Link::Models::List:0x00000890
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000008b0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000008d0
#           delimiter = "=",
#           encoding = nil,
#           key = "rel",
#           language = nil,
#           value = "index"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; rel=index"

Shorthand

Short hand, for multiple relations, is supported as well. To use, each relation must be delimited by a space within a single quoted string. Example:

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => %(</articles>; rel="one two three")})

# #<data RFC::Web::Link::Models::List:0x00000960
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x00000980
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000009a0
#           delimiter = "=",
#           encoding = nil,
#           key = "rel",
#           language = nil,
#           value = "one"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >,
#     #<data RFC::Web::Link::Models::Link:0x000009f0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00000a10
#           delimiter = "=",
#           encoding = nil,
#           key = "rel",
#           language = nil,
#           value = "two"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >,
#     #<data RFC::Web::Link::Models::Link:0x00000a60
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00000a80
#           delimiter = "=",
#           encoding = nil,
#           key = "rel",
#           language = nil,
#           value = "three"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; rel=one, <https://demo.io/articles>; rel=two, <https://demo.io/articles>; rel=three"

Notice that the original relation short hand of "one two three" produced three unique links for each relation which allows you to type less while still producing three distinct links.

title

Optional but, when supplied, allows you to provide a human readable label for the associated link. This includes being able to encode and decode the value based on the delimiter used. For example, notice the difference in delimiters used below:

Plain (=): title=Demo (example)
Encoded (*=): title*=UTF-8'en'd%C3%A9j%C3%A0%20vu (example)

The title must not appear more than once. If multiple occurrences are detected then only the first is honored. Also, if = and *= is used then *= takes precedence. Examples:

Without Encoding

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; title=Demo"})

# #<data RFC::Web::Link::Models::List:0x00000890
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000008b0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000008d0
#           delimiter = "=",
#           encoding = nil,
#           key = "title",
#           language = nil,
#           value = "Demo"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; title=Demo"

With Encoding

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; title*=UTF-8'en'd%C3%A9j%C3%A0%20vu"})

# #<data RFC::Web::Link::Models::List:0x00000890
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000008b0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000008d0
#           delimiter = "*=",
#           encoding = "UTF-8",
#           key = "title",
#           language = "en",
#           value = "déjà vu"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; title*=UTF-8'en'd%C3%A9j%C3%A0%20vu"

type

Optional but, when supplied, is a hint indicating the MIME Type of the associated link. This does not override the value of the content-type header. Example:

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; type=text/html"})

# #<data RFC::Web::Link::Models::List:0x00000890
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000008b0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000008d0
#           delimiter = "=",
#           encoding = nil,
#           key = "type",
#           language = nil,
#           value = "text/html"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; type=text/html"

Extensions

Extensions allow you to extend your implementation beyond the registered target attributes, described above, with your own custom attributes. For example, maybe you want to use the following attributes which are specific to your application: hint, errata, copyright. You can do this as follows:

parser = RFC::Web::Link.new "https://demo.io"

list = parser.call(
  {"link" => %(</articles>; hint="A demo."; errata="For demonstration only."; copyright=2025)}
)

# #<data RFC::Web::Link::Models::List:0x00000980
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000009a0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000009c0
#           delimiter = "=",
#           encoding = nil,
#           key = "hint",
#           language = nil,
#           value = "\"A demo.\""
#         >,
#         #<data RFC::Web::Link::Models::Pair:0x00000a00
#           delimiter = "=",
#           encoding = nil,
#           key = "errata",
#           language = nil,
#           value = "\"For demonstration only.\""
#         >,
#         #<data RFC::Web::Link::Models::Pair:0x00000a40
#           delimiter = "=",
#           encoding = nil,
#           key = "copyright",
#           language = nil,
#           value = "2025"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; hint=\"A demo.\"; errata=\"For demonstration only.\"; copyright=2025"

You can also encode your extensions by using the *= delimiter. Example:

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; demo*=UTF-8'en'd%C3%A9j%C3%A0%20vu"})

# #<data RFC::Web::Link::Models::List:0x00000ad0
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x00000af0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00000b10
#           delimiter = "*=",
#           encoding = "UTF-8",
#           key = "demo",
#           language = "en",
#           value = "déjà vu"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; demo*=UTF-8'en'd%C3%A9j%C3%A0%20vu"

Models

You’ve already seen all of the models (whole value objects) used in the examples above but this section details what you can do with each model individually.

List

This model has both Data and Enumerable behavior because it encapsulates the list of links parsed from an HTTP link header or created by you. A list can be created multiple ways:

All At Once

list = RFC::Web::Link::Models::List[
  links: Set[
    RFC::Web::Link::Models::Link[
      uri: "https://demo.io",
      pairs: Set[
        RFC::Web::Link::Models::Pair[key: :title, value: "Demo"]
      ]
    ]
  ]
]

💡 Ensure you use a Set when adding your links and pairs.

Separately

pair = RFC::Web::Link::Models::Pair[key: :title, value: "Demo"]
list = RFC::Web::Link::Models::Link[uri: "https://demo.io"].add(pair)
list = RFC::Web::Link::Models::List.new.add(link)

Once you have a list, you can send the following messages including Data and Enumerable messages:

list.add line
list.clear
list.empty?
list.size
list.to_s
list.to_str

You’ll notice you can explicitly and implicitly cast your list to a string. This makes the following quite handy:

"link: #{list}"
# link: <https://demo.io>; title=Demo

Link

This model encapsulates a single HTTP link header. A link can be created multiple ways:

All At Once

link = RFC::Web::Link::Models::Link[
  uri: "https://demo.io",
  pairs: Set[
    RFC::Web::Link::Models::Pair[key: :title, value: "Demo"]
  ]
]

💡 Ensure you use a Set when adding your pairs.

Separately

pair = RFC::Web::Link::Models::Pair[key: :title, value: "Demo"]
link = RFC::Web::Link::Models::Link[uri: "https://demo.io"].add(pair)

Once you have a link, you can then send the following messages (including Data messages):

link.empty?
link.include? pair
link.add pair
link.append :relation, "index"
link.append :title,
            "déjà vu",
            delimiter: "*=",
            encoding: "UTF-8",
            language: "en"
link.find_pair key: "title", value: "Demo"
link.find_pair key: "title", value: /dem/i
link.find_pair key: "title", delimiter: /\*=/, value: "Demo"
link.pair? key: "title"
link.pair? key: "title", value: "Demo"
list.to_s
list.to_str

You’ll notice you can explicitly and implicitly cast your link to a string. This makes the following quite handy:

"link: #{link}"
# link: <https://demo.io>; title=Demo"

Pair

This models encapsulates a single HTTP link header pair (i.e. key/value). A pair can be created as follows:

Basic

pair = RFC::Web::Link::Models::Pair[key: :title, value: "Demo"]

# #<data RFC::Web::Link::Models::Pair:0x00001e90
#   delimiter = "=",
#   encoding = nil,
#   key = "title",
#   language = nil,
#   value = "Demo"
# >

pair.encoded?  # false

Encoded

pair = RFC::Web::Link::Models::Pair[
  key: :title,
  delimiter: "*=",
  value: "Demo",
  encoding: "UTF-8",
  language: "en"
]

# #<data RFC::Web::Link::Models::Pair:0x00001ec0
#   delimiter = "*=",
#   encoding = "UTF-8",
#   key = "title",
#   language = "en",
#   value = "Demo"
# >

pair.encoded?  # true

The key can be either a symbol or a string but is always stored as a string, internally. When using = as your delimiter (default), #encoded? will be false but when using *= as your delimiter, #encoded? will be true.

As with List and Link, you have full access to all Data messages and can explicitly and implicitly cast to a string. Example:

"Pair: #{pair}"
# Pair: title=Demo

Error Handling

As per RFC 8288, this implementation is designed to safely ignore malformed web links. To illustrate, we’ll start with an initialized parser:

parser = RFC::Web::Link.new "https://demo.io"

The following examples show the result of parsing different malformed URIs:

With Nil Value

parser.call({"link" => nil})

# #<data RFC::Web::Link::Models::List:0x00000880
#   links = []
# >

With Empty Value

parser.call({"link" => ""})

# #<data RFC::Web::Link::Models::List:0x00000880
#   links = []
# >

With No Leading Less Than Sign For URI

parser.call({"link" => "/articles; rel=index"})

# #<data RFC::Web::Link::Models::List:0x00000880
#   links = []
# >

Without Attributes

parser.call({"link" => "</articles>"})

# #<data RFC::Web::Link::Models::List:0x00000880
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000008b0
#       pairs = [],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

With Missing Attribute Value

parser.call({"link" => "</articles>; rel"})

# #<data RFC::Web::Link::Models::List:0x000008a0
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x00000910
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00000930
#           delimiter = nil,
#           encoding = nil,
#           key = "rel",
#           language = nil,
#           value = nil
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

Development

To contribute, run:

git clone https://github.com/bkuhlmann/rfc-web-link
cd rfc-web-link
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.

Docker Debian Ruby Project

2026-06-14T23:06:10+00:00

Docker Debian Ruby

Provides a Ruby focused Debian Docker image with current tooling for development purposes. Great for local development and/or continuous integration builds using the most up-to-date tooling.

Table of Contents

Features
Requirements
Setup
Usage
Development
Tests
License
Security
Code of Conduct
Contributions
Developer Certificate of Origin
Versions
Community
Credits

Features

Installs jemalloc.
Installs Ruby with YJIT.
Updates RubyGems.

Requirements

Docker.

Setup

To set up the project, run:

git clone https://github.com/bkuhlmann/docker-debian-ruby.git
cd docker-debian-ruby
git checkout:0.3.0

Usage

All versions of this image can be found on Docker Hub. The image can be pulled as follows:

docker pull bkuhlmann/debian-ruby:latest  # <= Pull latest version.
docker pull bkuhlmann/debian-ruby:0.3.0   # <= Pull specific version.

You can also build on top of this image via your Dockerfile:

FROM bkuhlmann/debian-ruby:latest  # <= Latest version.
FROM bkuhlmann/debian-ruby:0.3.0   # <= Specific version.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/docker-debian-ruby.git
cd docker-debian-ruby

To build, run:

bin/build

To use the console, run:

bin/console

To deploy the latest version, run:

bin/deploy

To automatically calculate the next logical version and deploy it, run:

bin/deploy p

Versions are calculated and created via the Milestoner gem. Best practice is to deploy both the latest version and next version. Example:

bin/deploy
bin/deploy p

The above will ensure new images are created with the following tags:

latest: This is the most recent stable version which may or may not be ahead of the last version released.
<major>.<minor>.<patch>: This the next logical version as calculated and created by Milestoner.

Tests

To test, run:

bin/console
ruby --version

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Built with Rubysmith.
Engineered by Brooke Kuhlmann.

htmx Slide Project

2026-05-24T17:41:14+00:00

htmx Slide

This library is a htmx extension for rendering slides.

Table of Contents

Features

Renders slides with silky smooth CSS View Transitions.
Provides customizable slide transitions.
Provides full screen toggling of your presentation.
Provides keyboard shortcuts.
Works with seamlessly with dynamically or statically generated web sites.

Screencasts

Your browser does not support the video tag.

Requirements

htmx.
Node (optional, for development).
Ruby (optional, for development).
entr (optional, for development).

Setup

The following assumes you are already using htmx and have it configured in the same manner as documented in this setup section.

To load CSS and JavaScript, add the following to your page:

<link href="https://unpkg.com/htmx-slide@latest/build/style.css" rel="stylesheet">

<script src="https://unpkg.com/htmx-slide@latest"
        integrity="sha384-wqhWD7RgQ3amBmpZ0soDOU6KHATp+GRksh5Y47N/vP3YYyNgaQoipBLP/Qn511zP"
        crossorigin="anonymous"
        defer>
</script>

To use via Import Maps, add the following to your layout:

<link href="https://unpkg.com/htmx-slide@latest/build/style.css" rel="stylesheet">

<script type="importmap">
  {
    "imports": {
      "htmx-slide": "https://unpkg.com/htmx-slide@latest"
    }
  }
</script>

<script type="module">
  import "htmx-slide";
</script>

To install via NPM, run:

npm install htmx-slide

Once the library is installed, you only need to import it:

import "htmx-slide/build/style.css";
import "htmx-slide";

Usage

To use, add a top-level element (section in this case) where you enable the slide extension. Once the extension has been enabled, you can then add your view port, progress bar, and actions. Example:

<section class="htmx-slide">
  <div class="container">
    <div class="viewport">
      <img src="one.svg"
           alt="One"
           class="slide"
           width="960"
           height="540"
           data-transitions-forward="push"
           data-transitions-backward="wipe">
    </div>

    <progress class="progress" value="0" max="4"></progress>

    <div class="actions">
      <a href="_five.html"
         class="action"
         data-direction="backward"
         hx-get="_five.html"
         hx-trigger="click, keyup[key == 'ArrowLeft'] from:body"
         hx-push_url="true">
        Previous
      </a>

      <span class="status">1 of 5</span>

      <a href="_two.html"
         class="action"
         data-direction="forward"
         hx-get="_two.html"
         hx-trigger="click, keyup[key == 'ArrowRight'] from:body"
         hx-push_url="true">
        Next
      </a>

      <button data-fullscreen-trigger>[ ]</button>
    </div>
  </div>
</section>

The above is the minimum to load the extension, the initial slide, and navigate between slides. Here’s the breakdown:

section (required): The section element provides a semantic element to encapsulate all functionality and supply the minimum attributes. You’re not limited to the section element as any valid HTML element would work for your top level element.
- class (optional): Provides a default style for the extension. If you don’t want any styling then you can remove along with the associated style.css. The style.css is compiled from the style sheets located in the lib/stylesheets of this project. If you need a detailed breakdown on how CSS View Transitions and key frames work, check out the htmx View Transitions article to learn more.
.container (required): Ensures the view port, progress bar, and associated actions don’t expand the width of your slides.
.viewport (required): Ensures contents of this element can be toggled via the Fullscreen API.
.slide (required): Ensures your slide can be updated with a new slide based on the direction you are going.
.progress (optional): Provides real-time progress. Delete if not desired.
.actions (required): Ensures you can navigate to the previous, next, first, and last slide. You can add or remove actions as desired. The above shows what’s possible. When using action links, use the following attributes:
- .action (optional): Allows you to style the action if desired.
- data-direction (required): Ensures this extension knows which direction to transition the slide. Valid values are: forward or backward.
- hx-get (required): Requests the next slide.
- hx-trigger(required): Triggers the action. Feel free to customize keyboard short behavior as desired.
- hx-push_url (optional): Ensures your browser history is updated so back and forward navigation works.
data-fullscreen-trigger (optional): Triggers full screen mode. The value is meant to be empty and any value supplied is ignored. You can, optionally, add a data-fullscreen-target with any valid CSS selector in case you want to target a different element for full screen. The default is: .viewport.

When building your implementation, the above shows the initial page to render. All subsequent pages only need to be HTML partials which have the elements shown in the .container as those are the only elements that need to change upon each HTTP GET request.

Configuration

In addition to the above, you can configure the extension globally or per element. The following details each.

Defaults

This extensions is configured with the following defaults:

DEFAULTS = {
  slide: ".slide",
  transitions: {
    forward: "push",
    backward: "push"
  },
  fullscreen: {
    key: "f",
    trigger: "[data-fullscreen-trigger]",
    target: ".viewport"
  }
};

Each is key is described as follows:

slide: Defines the slide selector. This can be any valid CSS selector.
transitions: Defines the transitions.
- forward: Defines the forward transition.
- backward: Defines the backward transition.
fullscreen: Defines fullscreen behavior.
- key: Defines the keyboard shortcut to toggle full screen mode.
- trigger: Defines the trigger selector of the element that will toggle full screen mode. This can be any valid CSS selector.
- target: Defines the full screen target selector for which will enlarged in full screen mode.

Globals

You can override the defaults using HCON notation as follows:

<meta name="htmx-config"
      content="slide.slide:.slide
               slide.fullscreen.forward:push
               slide.fullscreen.backward:push
               slide.fullscreen.key:k
               slide.fullscreen.trigger:[data-fullscreen-trigger]
               slide.fullscreen.target:.viewport">

With the above, you’ll notice the global configuration is identical to the DEFAULTS. This is where you would customize as desired. At the moment, all keys must be represented even if you only customize a few of them.

Elements

You can also customize behavior by specific element using data attributes. For example, to change transitions, apply the following attributes to your slide (img) element:

data-transitions-forward="push"
data-transitions-backward="push"

The above gives you fine level control over the behavior of each slide instead of inheriting the default or global configuration and is a powerful way to keep your presentation interesting with different transitions.

You can also change full screen behavior by editing the element (button) that toggles full screen mode as follows:

data-fullscreen-target=".viewport"

Precedence

The configuration is dynamically computed based on global and per element customization with the first in the following list having the most specificity followed by least specificity:

Elements
Globals
Defaults

Keyframes

Keyframes provide the low level animation sequences for use in your view transitions (see below). The source for these can be found in the lib/stylesheets/keyframes.css file which is included when you import the htmx-slide/build/style.css as described Setup section above.

Each keyframe uses the htmx-slide-* prefix but feel free to add your own and link them to your own view transitions.

View Transitions

View transitions (i.e. ::view-transition-old, ::view-transition-new) are built atop the keyframes and are what make the slide transitions possible. The source for these can be found in the lib/stylesheets/view_transitions.css file which is included when you import the htmx-slide/build/style.css as described Setup section above.

Several view transitions are provided for you:

Curtain
Iris
Push (default)
Scale
Wipe

You can customize each slide’s transition, as mentioned in the Configuration section, by using the following data attributes on the extension element or the slide element. Example:

data-transitions-forward="iris": Uses the iris transition when moving forward to the next slide.
data-transitions-backward="scale": Uses the scale transition when moving backward to the next slide.

Each view transition name uses the htmx-slide-<name>-forward prefix. You can create and use your own transitions by using the same format as long as your name is unique and doesn’t conflict with the provided transitions. Once your custom view transition is ready, use the name of your transition via the data-transitions-* attributes to enable.

Partials

All of your partials needs to be wrapped within the hx-partial tag. You can always add more partials and standard HTML elements as you like but the following detail what is possible:

Slide

This is your most critical partial which informs htmx how to swap in and transition your new slide. Use of transition:true is important for enabling CSS View Transitions. Example:

<hx-partial hx-target=".slide" hx-swap="outerHTML transition:true">
  <img src="one.svg"
       alt="One"
       class="slide"
       width="960"
       height="540"
       data-transitions-forward="push"
       data-transitions-backward="wipe">
</hx-partial>

Progress

As mentioned earlier this is optional but handy for providing a clear visual indication of where you are in your presentation. Example:

<hx-partial hx-target=".progress" hx-swap="outerHTML">
  <progress class="progress" value="0" max="4"></progress>
</hx-partial>

Actions

You are not limited to previous and next actions as mentioned earlier because you can add as many as you deem necessary. For example, the following shows how to use previous, next, first, and last actions for navigation.

With First and Last Actions

<hx-partial hx-target=".actions" hx-swap="outerHTML">
  <div class="actions">
    <a href="_five.html"
       class="action"
       data-direction="backward"
       hx-get="_five.html"
       hx-trigger="click, keyup[key == 'ArrowLeft'] from:body"
       hx-push_url="true">
      Previous
    </a>

    <span class="status">1 of 5</span>

    <a href="_two.html"
       class="action"
       data-direction="forward"
       hx-get="_two.html"
       hx-trigger="click, keyup[key == 'ArrowRight'] from:body"
       hx-push_url="true">
      Next
    </a>

    <a href="_one.html"
       class="action"
       data-direction="backward"
       hx-get="_one.html"
       hx-trigger="click, keyup[event.code == 'BracketLeft'] from:body"
       hx-push_url="true">
      First
    </a>

    <button data-fullscreen-trigger>[ ]</button>

    <a href="_five.html"
       class="action"
       data-direction="forward"
       hx-get="_five.html"
       hx-trigger="click, keyup[event.code == 'BracketRight'] from:body"
       hx-push_url="true">
      Last
    </a>
  </div>
</hx-partial>

As long as your actions are defined within the .actions element and wrapped within a hx-partial element, this extension will swap them in properly.

Examples

Should you need real-word examples of this extension in production use, check out the following:

Talks: A collection of talks given at past presentations.
Terminus: A web server for ePaper devices. Each playlist uses this extension for viewing screens rendered on your ePaper devices.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/htmx-slide
cd htmx-slide
bin/setup

To build, run:

bin/build

To view the interactive demonstration, run:

bin/demo
open http://localhost:3030

Any changes to source code will automatically rebuild and reload the demonstration.

Tests

To test, run:

bin/rake

Deployment

To deploy, follow these steps:

Ensure you are on the main branch.
Ensure you’ve updated the CITATION.cff and package.json with new version and committed the changes.
Run the following:

bin/build
bin/publish

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Built with Rubysmith.
Engineered by Brooke Kuhlmann.

Pi Project

2026-02-01T21:37:39+00:00

Pi

This project automates the setup of Raspberry Pi devices by flashing your microSSD card with a fully customized Raspberry Pi OS for immediate use. This allows you to spend more time putting your Raspberry Pis to good use.

Table of Contents

Features
Requirements
Setup
Configuration
- Raspberry Pi Imager
Usage
- SSH
- Scripts
- Example
Development
License
Security
Code of Conduct
Contributions
Developer Certificate of Origin
Versions
Community
Credits

Features

Allows you to setup and configure multiple Raspberry Pi devices.
Allows you to manage multiple device profiles.
Allows you to install and run multiple services on your devices.

Requirements

Setup

Ensure you have the Raspberry Pi Imager installed for your operating system because this project depends on the Raspberry Pi Imager to format the micro SSD for your Raspberry Pi. If on macOS, use Homebrew as follows:

brew install --cask raspberry-pi-imager

Next, clone this project:

git clone https://github.com/bkuhlmann/pi.git
cd pi
git checkout 0.3.0

Configuration

By default, this project assumes you want to use the Raspberry Pi Imager. You can override the defaults by setting the following environment variables (see settings/main.sh for details):

EDITOR: This has no default but assumes you have this configured to run your favorite text editor. For example, if using Sublime Text, the value would be: sublime.
PI_CLI: The path to where the Raspberry Pi Imager is installed. By default, this assumes a macOS installation.
PI_URI: The Raspberry Pi OS to be installed. By default, this assumes 64-bit, Lite OS.
PI_INTEGRITY: The integrity SHA used to verify the OS you are installing is valid. You can find the corresponding SHA for each OS on the Raspberry Pi OS page. You’ll want to update this each time you change the PI_URI.

This project comes preconfigured with several scripts to help you get up and running quickly. You can find them in the scripts folder:

services: A directory of executable scripts for managing multiple services. This is meant to be customized with your own logic for installing, configuring, and running your services. The docker service is provided for you, by default, so you can use Docker to run multiple projects at once.
setup: The primary script that first updates your system and then runs all services.
update: Ensures your Raspberry Pi OS is upgraded and up-to-date with latest software. You can also use this script to keep your OS updated on a scheduled basis.

If you’d like to customize any of the above scripts, you can do so by making a copy of them using identical script name in your XDG configuration folder. Example:

$XDG_CONFIG_HOME/pi/scripts/services
$XDG_CONFIG_HOME/pi/scripts/setup
$XDG_CONFIG_HOME/pi/scripts/update

This is also a good way to zero them out entirely if you want them to do nothing.

Raspberry Pi Imager

When first getting set up, you’ll want to use the Raspberry Pi Imager to walk through setting up your device for the first time. Afterwards, you can copy and customize the files created by the Raspberry Pi Imager. This is only necessary if you’ve never used this project before and don’t feel comfortable writing all of the configuration files by default.

Insert the micro SSD into your machine you want to format.
Launch Raspberry Pi Imager.
Select your Raspberry Pi hardware.
Click on Raspberry Pi OS (other) software.
Select Raspberry Pi OS Lite (64-bit).
Select your micro SSD card (example: "Generic- SD/MMC Media").
Enter your desired hostname.
Fill in your capital city, time zone, and keyboard layout.
Fill in your username and password for your desired Raspberry user account.
Fill in your SSID and password for your local network.
Enable SSH by supplying the path to your public key (i.e. $HOME/.ssh/*.pub).
Choose whether to enable/disable Raspberry Pi Connect.
Write image to disk.

When the above is complete, you’ll be able to inspect the files created for you by running the following:

cd /Volumes/bootfs
cat network-config
cat user-data

You’ll want to make a copy of each of the above files so you can customize them for different networks and hosts as follows:

cp /Volumes/bootfs/network-config $XDG_CONFIG_HOME/pi/networks/demo.yml
cp /Volumes/bootfs/user-data $XDG_CONFIG_HOME/pi/hosts/demo.yml

This allows you to have multiple profiles, so-to-speak, for different networks and hosts. Due to these being YAML configurations, you can quickly adjust your host name, SSH public key, time zone, WiFi SSID, etc. You can learn more about the structure and configuration of each of these files via the Raspberry Pi Documentation.

Usage

To run, use:

bin/run

You’ll then be greeted with the following options:

Usage: run OPTION

Script Options:
  s: Setup
  e: Edit configuration
  o: Open configuration
  E: Eject Card
  q: Quit/Exit

Enter selection:

The above breaks down as follows:

Setup: Formats, configures, and sets up your micro SSD card so you can boot your Raspberry Pi with desired operating system and custom configuration. A wizard will prompt you for further information.
Edit configuration: Allows you to select and edit an individual XDG configuration in your default editor.
Open configuration: Allows you to open and view your entire XDG configuration in your default editor.
Eject Card: Allows you to eject (unmount) the micro SSD card created during setup.
Quit/Exit: Allows you to quit the CLI.

If you know which option you want to run, like setup, you can skip the interactive options shown above. Example:

bin/run s

SSH

Once you’ve configured your Raspberry Pi settings, you can insert your micro SSD card into your Raspberry Pi, and connect power. Then you can look for your device to show up on your local network with whatever host name you gave it. To make SSH’ing into your device more convenient, edit your SSH configuration (i.e. $HOME/.ssh/config) to add your new host. Example:

Host demo.local
  HostName 192.168.0.123
  User admin
  IdentityFile ~/.ssh/demo

With SSH configured, you can SSH into your Raspberry Pi. Example:

ssh admin@demo.local

Scripts

After SSH’ing into your Raspberry Pi, run the setup script from your home directory to complete the setup of your device. Example:

/boot/firmware/setup

This’ll run all of the scripts/services (default or custom) based on the configuration you used when setting up your micro SSD card.

Example

The following is an example of what the output can look like when running setup (i.e. bin/run s) where I walk through all options to configure my Raspberry Pi 5 (a.k.a. five) using my demo network complete with default services and my custom Terminus service:

Setup Output Example

Have you inserted your micro SSD card for formatting (y/n)? y

Please select your host configuration:

1) /Users/demo/.config/pi/hosts/five.yml
2) /Users/demo/.config/pi/hosts/zero.yml
#? 1

Please select your network configuration:

1) /Users/demo/.config/pi/networks/demo.yml
#? 1

Using host configuration: /Users/demo/.config/pi/hosts/five.yml.
Using network configuration: /Users/demo/.config/pi/networks/demo.yml.
Using setup script: /Users/demo/Engineering/OSS/pi/scripts/setup.
Using update script: /Users/demo/Engineering/OSS/pi/scripts/update.

The following external disks are detected for your micro SSD:

/dev/disk4 (disk image):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:     Apple_partition_scheme                        +5.4 GB     disk4
   1:        Apple_partition_map                         32.3 KB    disk4s1
   2:                  Apple_HFS projects                5.4 GB     disk4s2

/dev/disk5 (external, physical):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:     FDisk_partition_scheme                        *31.7 GB    disk5
   1:             Windows_FAT_32 bootfs                  536.9 MB   disk5s1
   2:                      Linux                         31.2 GB    disk5s2

Please enter your disk number (i.e. 1, 2, 3) for /dev/disk to format: 5
CacheManager initialized with background thread
Detected total system memory: 24576 MB on "macOS"
Optimal async queue depth: 256 (available: 9093 MB, budget: 1363 MB, block size: 1024 KB, baseline: 256 )
FileOperations log callback installed
Starting background cache operations
Found cached file info, starting background verification: "/Users/demo/Library/Caches/Raspberry Pi/Raspberry Pi Imager/lastdownload.cache"
Starting background drive list polling
Opening macOS device: /dev/rdisk5
Device path detected, using macOS authorization...
Successfully opened device with authorization, fd=13 (direct I/O enabled)
Block device size: 31719424000 bytes (blocks=61952000, block_size=512)
PrepareForSequentialRead: fd=13 path=/dev/rdisk5
  F_RDAHEAD result: 0 (OK)
  F_NOCACHE result: 0 (OK)
Write successful.

Copied: /Users/demo/Engineering/OSS/pi/scripts/setup to /Volumes/bootfs/setup.
Copied: /Users/demo/Engineering/OSS/pi/scripts/update to /Volumes/bootfs/update.
Copied: /Users/demo/Engineering/OSS/pi/scripts/services/docker to /Volumes/bootfs/services/docker.
Copied: /Users/demo/.config/pi/scripts/services/terminus to /Volumes/bootfs/services/terminus.

Raspberry Pi SSD card is ready!
Please eject card before using.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/pi.git
cd pi

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Build with Bashsmith.
Engineered by Brooke Kuhlmann.

Functionable Project

2025-11-02T15:44:12+00:00

Functionable

Enhances modules to be functional by disabling the ability to extend, include, or prepend while also ensuring all methods are class methods. This allows you to use a module as a functional collection of related methods for reuse throughout your application via composition instead of inheritance. In other words, this is an enhanced version of module_function by preventing inheritance and reducing the memory overhead due to making copies of the original methods.

Features

Allows modules to be a collection of functional methods.
Allows your modules and/or methods to be composable instead of inherited.
Provides faster performance and a reduced memory than any object within your application. See the Benchmarks section for details.

Requirements

Ruby.
A solid understanding Ruby Modules.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install functionable --trust-policy HighSecurity

To install without security, run:

gem install functionable

You can also add the gem directly to your project:

bundle add functionable

Once the gem is installed, you only need to require it:

require "functionable"

Usage

Enhancing your module to be functional is as simple as extending your module:

module Math
  extend Functionable

  def add(first, second) = first + second

  def subtract(first, second) = first - second

  def multiply(first, second) = first * second

  def divide(first, second) = first / second
end

Math.add 6, 3       # 9
Math.subtract 6, 3  # 3
Math.multiply 6, 3  # 18
Math.divide 6, 3    # 2

That’s it! Now you can add related methods, as desired, which are specific to your namespace.

Function Methods

You can acquire the array of function method names that were implemented and created by you. By default, you’ll get an empty array when no methods are defined:

module Demo
  extend Functionable
end

Demo.function_methods  # []

Once methods are defined, you’ll then get an array of names:

module Demo
  extend Functionable

  def one = 1

  def two = 2
end

Demo.function_methods  # [:one, :two]

This behavior is similar to what a Module already provides you when it comes to categorizing method names:

Module#instance_methods
Module#private_instance_methods
Module#protected_instance_methods
Module#public_instance_methods
Module#undefined_instance_methods

Conceal

Should you need to make any of your methods private, use the conceal method as follows:

module Demo
  extend Functionable

  def welcome(*) = print(*)

  def print(message = "The default message.") = puts message

  conceal :print
end

Demo.welcome  # "The default message."
Demo.print    # private method 'print' called for module Demo (NoMethodError)

The conceal method takes the same parameters as the private_class_method which means you can use a string, symbol, a single argument, multiple arguments, or an array.

Avoidances

Functional modules are only meant to be a collection of related methods which allows you to namespace your behavior, compose multiple methods together, and use composition to inject your module as a dependency within objects that need this functionality.

This means the following behavior is disabled (each uses an anonymous module and/or class for demonstration purposes and reduced syntax).

Extend

Use composition instead of inheritance:

functions = Module.new.extend Functionable
Class.new.extend functions

# Module extend is disabled. (NoMethodError)

Include

Use composition instead of inheritance:

functions = Module.new.extend Functionable
Class.new.include functions

# Module include is disabled. (NoMethodError)

You also can’t include Funtionable, only extend:

Module.new.include Functionable
# Module include is disabled, use extend instead. (NoMethodError)

Prepend

Use composition instead of inheritance:

functions = Module.new.extend Functionable
Class.new.prepend functions

# Module prepend is disabled. (NoMethodError)

You also can’t prepend, only extend:

Module.new.prepend Functionable
# Module prepend is disabled, use extend instead. (NoMethodError)

Module Function

The following is not allowed because you have this behavior when extending Functionable:

Module.new do
  extend Functionable

  module_function
end

# Module function behavior is disabled. (NoMethodError)

Public

Avoid the following since all methods are public by default:

Module.new do
  extend Functionable

  public

  def demo = :demo
end

# Public visibility is disabled. (NoMethodError)

Protected

Avoid the following since a functionable module isn’t mean to be inherited:

Module.new do
  extend Functionable

  protected

  def demo = :demo
end

# Protected visibility is disabled. (NoMethodError)

Private

Avoid the following by using conceal instead:

Module.new do
  extend Functionable

  private

  def demo = :demo
end

# Private visibility is disabled, use conceal instead. (NoMethodError)

Aliasing

Avoid aliasing as you are not meant to inherit methods within a functional module:

Module.new do
  extend Functionable

  def demo = :demo
  alias_method :demo, :alt
end

# Aliasing :alt as :demo is disabled. (NoMethodError)

Class Variables

Avoid using class variables since they are a code smell and introduce unwanted state:

demo = Module.new do
  extend Functionable

  def get = class_variable_get :@@bogus

  def set = class_variable_set :@@bogus, :bogus
end

demo.get  # Getting class variable :@@bogus is disabled. (NoMethodError)
demo.set  # Setting class variable :@@bogus is disabled. (NoMethodError)

Class Methods

Avoid class methods, use instance methods instead:

Module.new do
  extend Functionable

  def self.bogus = :bogus
end

# Avoid defining :bogus as a class method because the method will be automatically converted to a class method for you. (NoMethodError)

Constants

Avoid dynamically setting constants since you can add constants directly to the top of the module:

demo = Module.new do
  extend Functionable

  def bogus = const_set :BOGUS, :bogus
end

demo.bogus  # Setting constant :BOGUS is disabled. (NoMethodError)

Define Method

Avoid dynamically defining a method since you can explicitly define your method instead:

Module.new do
  extend Functionable

  define_method :bogus, :bogus
end

# Defining method :bogus is disabled. (NoMethodError)

Remove Method

Avoid dynamically removing a method since you can explicitly delete the method instead.

Module.new do
  extend Functionable

  remove_method :bogus
end

# Removing method :bogus is disabled. (NoMethodError)

Undef Method

Avoid dynamically undefining a method since you can explicitly delete the method instead.

Module.new do
  extend Functionable

  undef_method :bogus
end

# Undefining method :bogus is disabled. (NoMethodError)

Benchmarks

When you lean into the power of functional programming in Ruby, you gain performance and lower your memory footprint since you are creating the minimal amount of objects necessary. In terms of CPU performance, here’s a benchmark script (see bin/benchmark included in this project):

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

require "bundler/inline"

gemfile true do
  source "https://rubygems.org"

  gem "benchmark-ips"
  gem "functionable", path: ".."
end

module ModuleSelf
  extend self

  def call(message = "benchmark") = message
end

module ModuleFunction
  module_function

  def call(message = "benchmark") = message
end

module ModuleFunctionable
  extend Functionable

  def call(message = "benchmark") = message
end

class ClassFunction
  def initialize message = "benchmark"
    @message = message
  end

  def call = message

  private

  attr_reader :message
end

proc_function = proc { |message = "message"| message }
lambda_function = -> message = "benchmark" { message }
memoized_instance = ClassFunction.new
memoized_method = memoized_instance.method :call

Benchmark.ips do |benchmark|
  benchmark.config time: 5, warmup: 2

  benchmark.report("Proc") { proc_function.call }
  benchmark.report("Lambda") { lambda_function.call }
  benchmark.report("Module (function)") { ModuleFunction.call }
  benchmark.report("Module (functionable)") { ModuleFunctionable.call }
  benchmark.report("Module (self)") { ModuleSelf.call }
  benchmark.report("Class (new)") { ClassFunction.new.call }
  benchmark.report("Class (memoized)") { memoized_instance.call }
  benchmark.report("Method (new)") { memoized_instance.method(:call).call }
  benchmark.report("Method (memoized)") { memoized_method.call }

  benchmark.compare!
end

When you run the above benchmark, you should see the following results:

ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [arm64-darwin25.2.0]
Warming up --------------------------------------
                Proc     2.275M i/100ms
              Lambda     2.212M i/100ms
   Module (function)     4.654M i/100ms
Module (functionable)
                         4.682M i/100ms
       Module (self)     4.567M i/100ms
         Class (new)     2.359M i/100ms
    Class (memoized)     4.536M i/100ms
        Method (new)     1.176M i/100ms
   Method (memoized)     2.173M i/100ms
Calculating -------------------------------------
                Proc     23.976M (± 0.1%) i/s   (41.71 ns/i) -    120.575M in   5.029071s
              Lambda     24.414M (± 0.2%) i/s   (40.96 ns/i) -    123.885M in   5.074316s
   Module (function)     61.028M (± 0.7%) i/s   (16.39 ns/i) -    307.154M in   5.033292s
Module (functionable)
                         60.864M (± 0.5%) i/s   (16.43 ns/i) -    304.327M in   5.000243s
       Module (self)     60.261M (± 0.6%) i/s   (16.59 ns/i) -    301.446M in   5.002511s
         Class (new)     28.202M (± 8.2%) i/s   (35.46 ns/i) -    141.526M in   5.048420s
    Class (memoized)     57.157M (± 1.0%) i/s   (17.50 ns/i) -    285.794M in   5.000639s
        Method (new)     13.265M (± 9.7%) i/s   (75.39 ns/i) -     65.847M in   5.012654s
   Method (memoized)     24.390M (± 0.2%) i/s   (41.00 ns/i) -    123.861M in   5.078408s

Comparison:
   Module (function): 61027866.3 i/s
Module (functionable): 60864191.4 i/s - same-ish: difference falls within error
       Module (self): 60261194.0 i/s - same-ish: difference falls within error
    Class (memoized): 57156588.3 i/s - 1.07x  slower
         Class (new): 28201872.3 i/s - 2.16x  slower
              Lambda: 24414262.5 i/s - 2.50x  slower
   Method (memoized): 24389728.5 i/s - 2.50x  slower
                Proc: 23975703.7 i/s - 2.55x  slower
        Method (new): 13264797.8 i/s - 4.60x  slower

As you can see, a functional module is one of the fastest while everything else is much slower.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/functionable
cd functionable
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.

Inspectable Project

2025-05-10T22:07:05+00:00

Inspectable

Inspectable is a customizable object inspector which enhances Ruby Object Inspection behavior beyond what is provided by default. You can always implement your own #inspect method but this becomes tedious when you need to exclude or transform the same instance variables across multiple objects.

Table of Contents

Features

Allows you to customize and configure Object#inspect with minimal effort.
Allows you to exclude instance variables that are too verbose or undesired.
Allows you to register reusable transformers for more advanced behavior.

Requirements

Ruby.
A good understanding of default Ruby Object Inspection behavior.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install inspectable --trust-policy HighSecurity

To install without security, run:

gem install inspectable

You can also add the gem directly to your project:

bundle add inspectable

Once the gem is installed, you only need to require it:

require "inspectable"

Usage

By default, Object#inspect includes all instance variables so this gem is designed to exclude what you don’t need or transform variables before being inspected. Otherwise, you don’t need this gem at all. Take the following, for example:

class Demo
  include Inspectable[:token]

  def initialize token: "secret", uri: "https://demo.io"
    @token = token
    @uri = uri
  end
end

Demo.new.inspect
#<Demo:0x00000000000005d0 @uri="https://demo.io">

Notice, when inspecting the instance of Demo, the token instance variable was excluded. This is important when you want to hide sensitive information, information that is too verbose, or you don’t need at all.

You can also use the built-in transformers to transform sensitive information as well. Example:

class Demo
  include Inspectable[token: :redact]

  def initialize token: "secret", uri: "https://demo.io"
    @token = token
    @uri = uri
  end
end

Demo.new.inspect
"#<Demo:0x0000000000000ea0 @token=\"[REDACTED]\", @uri=\"https://demo.io\">"

The above is nearly identical to the first example except we’ve used the built-in :redact transformer which replaced "secret" with "[REDACTED]". This is why this transformer is provided for you because leaking sensitive information is a fairly common occurrence that this gem has made this simple for you to manage. To learn more, see the Transformers section below.

Registry

At the moment, this gem’s registry only allows the registration of custom transformers. Example:

Inspectable.add_transformer(:upcase, -> value { value.upcase if value })
           .add_transformer "cleaner", -> value { value.sub(/\h{10}/, "") if value }

Notice you can register transformers using strings or symbols. The latter is preferred because all transformers are identified by symbol when referenced. The value must be a lambda where the value is the value of your instance variable which will be transformed at time of object inspection.

Here’s an example using the above registered transformers:

class Demo
  include Inspectable[name: :suffix, label: :upcase]

  def initialize name: "demo-ab12ef", label: "Demo"
    @name = name
    @label = label
  end
end

Demo.new.inspect
"#<Demo:0x00000000000012f0 @name=\"demo\", @label=\"DEMO\">"

Transformers

This gem includes a few built-in transformers that can help you hide sensitive information or reduce verbosity. To view them, use:

Inspectable.transformers

# {
#   redact: Inspectable::Transformers::Redactor,
#     type: Inspectable::Transformers::Typer
# }

Each is explained below.

Redactor

This transformer’s sole purpose is to hide sensitive information and is most helpful for obscuring credentials, passwords, and secrets in general. When your instance variable’s value is not nil, you’ll see "[REDACTED]" as the value. Otherwise, if your instance variable’s value is nil, you’ll see nil instead.

To use, supply the instance variable you want to transform as the key and the transformer’s key (symbol) as the value. Example:

include Inspectable[demo: :redact]

Typer

This transformer always computes the instance variable’s type.

This transformer is most helpful for objects, like Dry Schema, that are extremely verbose. With this transformer, you can see the type of schema without all of the additional details. This transformer is also handy when you only want type information in general.

To use, supply the instance variable you want to transform as the key and the transformer’s key (symbol) as the value. Example:

include Inspectable[demo: :type]

Overrides

Should you not like default transformer behavior, you can override an existing transformer with your own. For example, maybe you’d like the Redactor transformer to use "[FILTERED]" instead of "[REDACTED]". Here’s how you do that:

Inspectable.add_transformer :redact, -> value { "[FILTERED]" if value }

The above will override default behavior with your own functionality.

Custom

You can add as many transformers as you like by using the .add_transformer method. Here are the guidelines for customization:

Use only a string or symbol for the first argument (a symbol is preferred). This allows you to quickly identify and use your transformer when applying custom inspection behavior to your objects.
Use a lambda for the second argument. The lambda must accept a value as the first positional parameter. How you transform the value is up to you but you’ll want to adhere to default Ruby Object Inspection behavior.

Let’s say you need to remove hex values from showing up when inspecting a variable value, you could register a custom transformer for this:

Inspectable.add_transformer :dehexer, -> value { value.sub(/\h+/, "").inspect if value }

The above would strip hexes from the output. Notice the guard to check if the value exists before performing the transformation. This is good to have when your value might be nil so you don’t have exceptions.

ℹ️ In most cases, you must send the #inspect message to the transformed value. In situations, where you are dealing with a constant, you’ll want to avoid sending the #inspect message because constants shouldn’t be quoted. All of this is important when adhering to default Ruby Object Inspection behavior.

Native

As of Ruby 4.0.0, limited native support is provided via the private instance_variables_to_inspect instance method. This method is not compatible with this gem because this gem makes instance_variables_to_inspect redundant and will fail with a NoMethodError exception. Example:

Class.new do
  include Inspectable(:name)

  def initialize name = "test"
    @name = name
  end

  private

  def instance_variables_to_inspect = [:@name]
end

# undefined method 'Inspectable' for class (NoMethodError)

To resolve the above exception, remove instance_variables_to_inspect and let this gem handle everything for you.

RSpec

To aid in your testing, you can use the match_inspection RSpec matcher by requiring it in your spec helper:

# spec_helper.rb

require "inspectable/rspec/matchers/match_inspection"

Once required, you can use the matcher by supplying the expected attributes as follows:

RSpec.describe Demo do
  subject(:demo) { described_class.new }

  describe "#inspect" do
    it "has inspected attributes" do
      expect(demo.inspect).to match_inspection(label: "Demo", name: :demo)
    end
  end
end

You can also customize the matcher by providing a by hash before any expected attributes consisting of the following attributes:

prefix: The prefix of your attribute names. Default: "@".
delimiter: The delimiter between each attribute name and value. Default: "=".
separator: The separator between each attribute. Default: ", ".

For example, the following is an explicit demonstration of what the matcher implicitly provides for you by default:

RSpec.describe Demo do
  subject(:demo) { described_class.new }

  describe "#inspect" do
    it "has inspected attributes" do
      expect(demo.inspect).to match_inspection(
        by: {prefix: "@", delimiter: "=", separator: ", "},
        label: "Demo",
        name: :demo
      )
    end
  end
end

In situations where the spec fails, you’ll get a formatted error to help you quickly resolve and fix the issue:

expected (using prefix: "@", delimiter: "=", and separator: ", "):

"#<Demo:0x00000000000014d0
@label="Demo",
@name=:demo
@email="demo@demo.io"

to match:

@label="Demo",
@name=:demo

Development

To contribute, run:

git clone https://github.com/bkuhlmann/inspectable
cd inspectable
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.

Kagi API Project

2025-05-04T21:10:43+00:00

Kagi API

A monadic API client for Kagi privacy focused information. This allows you to access the full Kagi API using a fault tolerant pipeline to yield whole value objects (i.e. Data) for immediate interaction within your own applications.

⚠️ Roughly ~2% of funds go to Yandex search results. Unfortunately, Yandex is a Russian company that helps fund corrupt propaganda, the killing of Ukrainians, and other despicable acts. I was not aware of this when I wrote this API client. More can be found here so you can make an informed decision.

Table of Contents

Features

Provides a Kagi API client.
Provides full access to the Kagi APIs.
Provides a fault tolerant pipeline for API requests and responses.

Requirements

Ruby.
A Kagi account with an API key.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install kagi-api --trust-policy HighSecurity

To install without security, run:

gem install kagi-api

You can also add the gem directly to your project:

bundle add kagi-api

Once the gem is installed, you only need to require it:

require "kagi/api"

Usage

This client provides access to multiple endpoints. Each endpoint will answer either answer a Success or Failure (as provided by Dry Monads) based on result of the API call. This allows you pattern match in your own code when using each endpoint. Example:

client = Kagi::API.new

case client.fast query: "Ruby"
  in Success(payload) then puts payload
  in Failure(response) then puts response
  else puts "Unknown HTTP response."
end

See Endpoints for further details.

Configuration

You can configure the client using a block and adjusting the content_type, token, and/or uri settings as desired. For example, you’d only need to supply your Kagi API token (as found via your account settings) to start using the client:

client = Kagi::API.new do |settings| settings.token = "secret" }
client.fast query: "Ruby"

If you don’t configure the client, then the following defaults will be used:

client = Kagi::API.new do |settings|
  settings.content_type = "application/json"
  settings.token = nil
  settings.uri = "https://kagi.com/api/v0"
end

Environment

You can configure the client via the following environment variables. This is handy when you don’t want to use block syntax or want fallbacks when no configuration is provided.

KAGI_API_CONTENT_TYPE: Defines the HTTP Content-Type header. You shouldn’t need to change this. Default: "application/json".
KAGI_API_TOKEN: Defines your personal key for API access. Default: nil.
KAGI_API_URI: Defines the API URI. Default: "https://kagi.com/api/v0".

Endpoints

All endpoints are accessible via the client instance. Each will answer a Success or Failure result you can pattern match against. Even better, within each result, you’ll get a Data object you can immediately interact with. See below to learn more about each endpoint.

Enrich News

Message #enrich_news to make API requests. Example:

client = Kagi::API.new

client.enrich_news q: "Ruby programming language"

# Success(#<data Kagi::API::Models::Search meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=577, balance=2.259763>, data=[#<data Kagi::API::Models::Content::Search type=0, rank=nil, title="The Ruby Programming Language (Ruby)", url="https://github.com/ruby/ruby", snippet="For a complete list of ways to install Ruby...", published_at=2025-05-04 09:17:12 UTC, thumbnail=nil>]>)

client.enrich_news

# Failure(#<data Kagi::API::Models::Error meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=87, balance=2.366512>, error=[#<data Kagi::API::Models::Content::Error code=1, message="Missing q parameter", reference=nil>]>)

See Kagi API Documentation for further details.

Enrich Web

Message #enrich_web to make API requests. Example:

client = Kagi::API.new

client.enrich_web q: "Ruby programming language"

# Success(#<data Kagi::API::Models::Search meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=451, balance=2.257763>, data=[#<data Kagi::API::Models::Content::Search type=0, rank=nil, title="Ruby Programming Language", url="https://www.ruby-lang.org/en/", snippet="There is a vulnerability about Command Injection in RDoc which is bundled in Ruby. There is an XML round-trip vulnerability in REXML gem bundled with Ruby. And there is also an unintentional file creation vulnerability in tempfile library bundled with Ruby on Windows, because it uses tmpdir internally.", published_at=nil, thumbnail=nil>]>)

client.enrich_web

# Failure(#<data Kagi::API::Models::Error meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=27, balance=2.362512>, error=[#<data Kagi::API::Models::Content::Error code=1, message="Missing q parameter", reference=nil>]>)

See Kagi API Documentation for further details.

Fast

Message #fast to make API requests. Example:

client = Kagi::API.new

client.fast query: "Ruby"

# Success(#<data Kagi::API::Models::Fast meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=2915, balance=2.362512>, data=#<data Kagi::API::Models::Content::Fast output="Ruby is a dynamic, open-source programming language that focuses on simplicity and productivity. It has an elegant syntax that is natural to read and easy to write. Ruby supports multiple programming paradigms, including functional, object-oriented, and imperative. It is also known for its flexible nature, allowing developers to easily modify its parts. ", tokens=1172, references=[]>>)

client.fast

# Failure(#<data Kagi::API::Models::Error meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=26, balance=2.347512>, error=[#<data Kagi::API::Models::Content::Error code=1, message="Parameter \"query\" is required and must not be empty", reference=nil>]>)

See Kagi API Documentation for further details.

Search

Message #search to make API requests. Example:

client = Kagi::API.new

client.search q: "Ruby"

# Success(#<data Kagi::API::Models::Search meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=1225, balance=2.322512>, data=[#<data Kagi::API::Models::Content::Search type=0, rank=nil, title="Ruby Programming Language", url="https://www.ruby-lang.org/en/", snippet="A dynamic, open source programming language with a focus on simplicity and productivity. It has an elegant syntax that is natural to read and easy to write.", published_at=nil, thumbnail=nil>]>)

client.search

# Failure(#<data Kagi::API::Models::Error meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=27, balance=2.322512>, error=[#<data Kagi::API::Models::Content::Error code=1, message="Missing q parameter", reference=nil>]>)

See Kagi API Documentation for further details.

Summarize

Message #summarize to make API requests. Example:

client = Kagi::API.new

client.summarize url: "https://www.ruby-lang.org/en", summary_type: "summary"

# Success(#<data Kagi::API::Models::Summary meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=3828, balance=2.261763>, data=#<data Kagi::API::Models::Content::Summary output="The Ruby Programming Language is a dynamic, open-source language designed for simplicity and productivity, featuring an elegant syntax that is easy to read and write. It is well-known for its straightforward \"Hello World!\" program, which requires minimal syntax. The Ruby community actively shares updates, including recent releases such as Ruby 3.5.0-preview1, Ruby 3.4.3, and Ruby 3.3.8, along with security advisories highlighting vulnerabilities like CVE-2025-43857 related to the net-imap gem. \n\nUsers can easily get started with Ruby through resources like \"Try Ruby!\" and \"Ruby in Twenty Minutes.\" The website offers extensive documentation, libraries, and success stories, encouraging participation in a vibrant community through mailing lists, user groups, and issue tracking. Ruby's commitment to user engagement is evident through various community platforms where developers can collaborate and share knowledge. The site also provides multilingual support, making Ruby accessible to a global audience.", tokens=2025>>)

client.summarize

# Failure(#<data Kagi::API::Models::Error meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=114, balance=2.322512>, error=[#<data Kagi::API::Models::Content::Error code=200, message="We are sorry, this input is not supported. (Invalid Input)", reference=nil>]>)

See Kagi API Documentation for further details.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/kagi-api
cd kagi-api
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.