Ir al contenido principal

Ruby

Un cliente idiomático de Ruby para BibleQL.

Instalación​

Gemfile
gem "bibleql-ruby"
bundle install

O directamente:

gem install bibleql-ruby

Configuración​

require "bibleql"

BibleQL.configure do |config|
  config.api_key = ENV.fetch("BIBLEQL_API_KEY")
  config.default_translation = "spa-rv1909"
  config.api_url = "https://bibleql.org/graphql"
  config.timeout = 30
end

client = BibleQL.client

O por instancia, que es más fácil de testear:

client = BibleQL::Client.new(
  api_key: ENV.fetch("BIBLEQL_API_KEY"),
  default_translation: "spa-rv1909"
)
Configura api_url explícitamente

El valor por defecto de la gema apunta a una URL alojada en Render, no a https://bibleql.org/graphql. Fíjalo si quieres el endpoint canónico.

Para saber dónde va esto en una aplicación Rails, cómo usar las credenciales de Rails y cuándo elegir un cliente global o por instancia, consulta Configurar los SDKs.

Todos los ejemplos siguientes asumen un client creado como arriba.

Leer pasajes​

passage = client.passage("Juan 3:16")

passage.reference       # => "Juan 3:16"
passage.text            # => "Porque de tal manera amó Dios al mundo..."
passage.translation_id  # => "spa-rv1909"
passage.verses          # => [#<BibleQL::Verse ...>]

Cambia la traducción por llamada:

client.passage("John 3:16", translation: "eng-web")

Versículos y capítulos​

verse = client.verse("MAT", 5, 3)
verse.book_name  # => "Mateo"
verse.chapter    # => 5
verse.verse      # => 3
verse.text

verses = client.chapter("MAT", 5)

Búsqueda​

results = client.search("amor", limit: 5)

results.each do |verse|
  puts "#{verse.book_name} #{verse.chapter}:#{verse.verse}"
  puts verse.text
end

Recuerda que esto es coincidencia de subcadenas, no stemming — consulta Buscar en la Biblia.

Versículo aleatorio​

client.random_verse
client.random_verse(testament: "NT")
client.random_verse(books: "PSA")

testament acepta las cadenas "OT" y "NT". Pasar books hace que testament se ignore — consulta Comportamiento de la API.

Versículo del día​

client.verse_of_the_day
client.verse_of_the_day(date: "2026-01-01")

Devuelve un Passage, que puede contener más de un versículo.

Descubrimiento​

client.translations              # => [#<BibleQL::Translation ...>]
client.translation("spa-rv1909") # con .books
client.languages                 # .code, .translation_count, .translations
client.books                     # los 66 canónicos
client.bible_index               # .chapters => [#<BibleQL::Chapter number= verse_count=>]

Gestión de errores​

begin
  client.passage("Nonexistent 1:1")
rescue BibleQL::NotFoundError => e
  warn "No encontrado: #{e.message}"
rescue BibleQL::AuthenticationError
  warn "Revisa BIBLEQL_API_KEY"
rescue BibleQL::RateLimitError
  warn "Límite superado — espera antes de reintentar"
rescue BibleQL::TimeoutError, BibleQL::ConnectionError => e
  warn "Problema de red transitorio: #{e.message}"
rescue BibleQL::QueryError => e
  warn "Error de GraphQL: #{e.message}"
  warn e.errors.inspect # el arreglo de errores original
end

BibleQL::ServerError cubre las respuestas 5xx. Consulta Errores para ver a qué corresponde cada uno.

No cubierto por la gema​

semanticSearch, concordance y concordanceIndex no tienen métodos en la versión actual. Usa los documentos GraphQL de Búsqueda semántica y Concordancia con cualquier cliente HTTP.