rbs

RBS

RBS ist eine Sprache zur Beschreibung der Struktur von Ruby-Programmen. Sie können die Definition einer Klasse oder eines Moduls aufschreiben: in der Klasse definierte Methoden, Instanzvariablen und ihre Typen sowie Vererbungs-/Mischungsbeziehungen. Es ermöglicht auch die Deklaration von Konstanten und globalen Variablen.

Das Folgende ist ein kleines Beispiel von RBS für eine Chat-App.

 module ChatApp
  VERSION: String

  class User
    attr_reader login: String
    attr_reader email: String

    def initialize : (login: String, email: String) -> void
  end

  class Bot
    attr_reader name: String
    attr_reader email: String
    attr_reader owner: User

    def initialize : (name: String, owner: User) -> void
  end

  class Message
    attr_reader id: String
    attr_reader string: String
    attr_reader from: User | Bot                     # `|` means union types: `#from` can be `User` or `Bot`
    attr_reader reply_to: Message?                   # `?` means optional type: `#reply_to` can be `nil`

    def initialize : (from: User | Bot, string: String) -> void

    def reply : (from: User | Bot, string: String) -> Message
  end

  class Channel
    attr_reader name: String
    attr_reader messages: Array[Message]
    attr_reader users: Array[User]
    attr_reader bots: Array[Bot]

    def initialize : (name: String) -> void

    def each_member : () { (User | Bot) -> void } -> void  # `{` and `}` means block.
                   | () -> Enumerator[User | Bot, void ]   # Method can be overloaded.
  end
end 

Die Zielversion

• Die Standardbibliothekssignaturen zielen auf die neueste Version von Ruby ab. ( 3.2 ab 2023.)
• Der Bibliothekscode zielt auf Nicht-EOL-Versionen von Ruby ab. ( >= 3.0 ab 2023.)

Installation

Installieren Sie das rbs Gem. $ gem install rbs über die Befehlszeile oder fügen Sie eine Zeile in Ihre Gemfile ein.

 gem "rbs" 

CLI

Das Gem wird mit dem rbs -Befehlszeilentool geliefert, um zu demonstrieren, was es kann, und um bei der Entwicklung von RBS zu helfen.

$ rbs version
$ rbs list
$ rbs ancestors ::Object
$ rbs methods ::Object
$ rbs method Object then

Für einen Endbenutzer von rbs wird rbs prototype wahrscheinlich am nützlichsten sein. Dieser Befehl generiert Boilerplate-Signaturdeklarationen für Ruby-Dateien. Angenommen, Sie haben das folgende Ruby-Skript geschrieben.

 # person.rb
class Person
  attr_reader :name
  attr_reader :contacts

  def initialize ( name : )
    @name = name
    @contacts = [ ]
  end

  def speak
    "I'm #{ @name } and I love Ruby!"
  end
end

Der oben genannte Prototyp wird automatisch generiert

$ rbs prototype rb person.rb
class Person
  @name: untyped

  @contacts: untyped

  attr_reader name: untyped

  attr_reader contacts: untyped

  def initialize: (name: untyped) -> void

  def speak: () -> ::String
end

Es druckt Signaturen für alle Methoden, Klassen, Instanzvariablen und Konstanten. Dies ist nur ein Ausgangspunkt und Sie sollten die Ausgabe so bearbeiten, dass sie genauer mit Ihrer Signatur übereinstimmt.

rbs prototype bietet drei Optionen.

• rb generiert nur aus dem verfügbaren Ruby-Code
• rbi generiert aus Sorbet RBI
• runtime wird von der Laufzeit-API generiert

Bibliothek

Es gibt zwei wichtige Konzepte: Umgebung und Definition .

Eine Umgebung ist ein Wörterbuch, das alle Deklarationen verfolgt. Welche Deklaration ist mit String Klasse verknüpft? Eine Umgebung wird Ihnen die Antwort geben.

Eine Definition gibt Ihnen die Details der Klasse. Was ist der Typ des Rückgabewerts der gsub -Methode der String -Klasse? Die Definition der String Klasse kennt die Liste der bereitgestellten Methoden und deren Typen.

Im Folgenden finden Sie einen kleinen Code zum Abrufen der Definition der String#gsub -Methode.

 require "rbs"

loader = RBS :: EnvironmentLoader . new ( )

# loader.add(path: Pathname("sig"))   # Load .rbs files from `sig` directory
# loader.add(library: "pathname")     # Load pathname library

environment = RBS :: Environment . from_loader ( loader ) . resolve_type_names

# ::String
string = RBS :: TypeName . new ( name : :String , namespace : RBS :: Namespace . root )

# Class declaration for ::String
decl = environment . class_decls [ string ]

# Builder provides the translation from `declaration` to `definition`
builder = RBS :: DefinitionBuilder . new ( env : environment )

# Definition of instance of String
instance = builder . build_instance ( string )

# Print the types of `gsub` method:
puts instance . methods [ :gsub ] . method_types . join ( " n " )
# Outputs =>
#  (::Regexp | ::string pattern, ::string replacement) -> ::String
#  (::Regexp | ::string pattern, ::Hash[::String, ::String] hash) -> ::String
#  (::Regexp | ::string pattern) { (::String match) -> ::_ToS } -> ::String
#  (::Regexp | ::string pattern) -> ::Enumerator[::String, self]

# Definition of singleton of String
singleton = builder . build_singleton ( string )
# No `gsub` method for String singleton
puts singleton . methods [ :gsub ] 

Führer

• Architektur
• Beitragsleitfaden für Kern- und Standardbibliothekssignaturen
• Anleitung zum Schreiben von Unterschriften
• Leitfaden für Stdlib-Signaturen
• Syntax
• RBS am Beispiel
• RBS-Sammlung
• Verwenden von Data und Struct
• Mit RBS ein Juwel veröffentlichen

Gemeinschaft

Hier ist eine Liste einiger Orte, an denen Sie mit aktiven Betreuern sprechen können.

• Ruby Discord Server (Einladungslink) – Wir haben rbs Kanal auf dem Ruby Discord Server.
• ruby-jp Slack Workspace (auf Japanisch) – Wir haben einen types im Ruby-jp Slack Workspace.
• gem_rbs_collection – Wir verfügen über ein Repository mit RBS-Typdefinitionen von Drittanbietern für den Fall, dass Ihre Abhängigkeit nicht mit RBS-Dateien geliefert wird.

Entwicklung

Führen Sie nach dem Auschecken des Repos bin/setup aus, um Abhängigkeiten zu installieren. Führen Sie dann bundle exec rake test aus, um die Tests auszuführen. Sie können auch bin/console ausführen, um eine interaktive Eingabeaufforderung zu erhalten, mit der Sie experimentieren können.

Um dieses Juwel auf Ihrem lokalen Computer zu installieren, führen Sie bundle exec rake install aus. Um eine neue Version zu veröffentlichen, aktualisieren Sie die Versionsnummer in version.rb und führen Sie dann bundle exec rake release aus. Dadurch wird ein Git-Tag für die Version erstellt, Git-Commits und -Tags gepusht und die .gem Datei an rubygems.org gepusht.

Mitwirken

Fehlerberichte und Pull-Requests sind auf GitHub unter https://github.com/ruby/rbs willkommen.