module Psych

Übersicht

Psych ist ein YAML Parser und Emittent. Psych nutzt libyaml [Homepage: pyyaml.org/wiki/LibYAML] oder [git repo: github.com/yaml/libyaml] für seine YAML Parsing- und Emittierungsfähigkeiten. Zusätzlich zur Umschließung von libyaml weiß Psych auch, wie die meisten Ruby-Objekte in und aus dem YAML-Format serialisiert und deserialisiert werden.

ICH MUSS JETZT SOFORT YAML PARSEN ODER EMITTEN!

# Parse some YAML
Psych.load("--- foo") # => "foo"

# Emit some YAML
Psych.dump("foo")     # => "--- foo\n...\n"
{ :a => 'b'}.to_yaml  # => "---\n:a: b\n"

Haben Sie mehr Zeit? Lesen Sie weiter!

YAML Parsing

Psych bietet eine Reihe von Schnittstellen zum Parsen eines YAML-Dokuments, die von niedrig bis hoch reichen, je nach Ihren Parsing-Anforderungen. Auf der niedrigsten Ebene gibt es einen ereignisbasierten Parser. Die mittlere Ebene bietet Zugriff auf den rohen YAML AST, und auf der höchsten Ebene besteht die Möglichkeit, YAML in Ruby-Objekte zu entpacken.

YAML Emittierung

Psych bietet eine Reihe von Schnittstellen, die von niedrig bis hoch reichen, zur Erzeugung von YAML-Dokumenten. Ganz ähnlich wie die YAML-Parsing-Schnittstellen bietet Psych auf der niedrigsten Ebene ein ereignisbasiertes System, auf der mittleren Ebene den Aufbau eines YAML AST und auf der höchsten Ebene die Konvertierung eines Ruby-Objekts direkt in ein YAML-Dokument.

High-Level API

Parsing

Der von Psych bereitgestellte High-Level YAML-Parser nimmt einfach YAML als Eingabe und gibt eine Ruby-Datenstruktur zurück. Informationen zur Verwendung des High-Level-Parsers finden Sie unter Psych.load

Lesen aus einem String

Psych.safe_load("--- a")             # => 'a'
Psych.safe_load("---\n - a\n - b")   # => ['a', 'b']
# From a trusted string:
Psych.load("--- !ruby/range\nbegin: 0\nend: 42\nexcl: false\n") # => 0..42

Lesen aus einer Datei

Psych.safe_load_file("data.yml", permitted_classes: [Date])
Psych.load_file("trusted_database.yml")

Fehlerbehandlung

begin
  # The second argument changes only the exception contents
  Psych.parse("--- `", "file.txt")
rescue Psych::SyntaxError => ex
  ex.file    # => 'file.txt'
  ex.message # => "(file.txt): found character that cannot start any token"
end

Emittierung

Der High-Level-Emitter hat die einfachste Schnittstelle. Psych nimmt einfach eine Ruby-Datenstruktur und konvertiert sie in ein YAML-Dokument. Sehen Sie Psych.dump für weitere Informationen zum Dumpen einer Ruby-Datenstruktur.

Schreiben in einen String

# Dump an array, get back a YAML string
Psych.dump(['a', 'b'])  # => "---\n- a\n- b\n"

# Dump an array to an IO object
Psych.dump(['a', 'b'], StringIO.new)  # => #<StringIO:0x000001009d0890>

# Dump an array with indentation set
Psych.dump(['a', ['b']], :indentation => 3) # => "---\n- a\n-  - b\n"

# Dump an array to an IO with indentation set
Psych.dump(['a', ['b']], StringIO.new, :indentation => 3)

Schreiben in eine Datei

Derzeit gibt es keine direkte API zum Dumpen von Ruby-Strukturen in Dateien

File.open('database.yml', 'w') do |file|
  file.write(Psych.dump(['a', 'b']))
end

Mid-Level API

Parsing

Psych bietet Zugriff auf einen AST, der aus dem Parsen eines YAML-Dokuments erzeugt wurde. Dieser Baum wird mithilfe von Psych::Parser und Psych::TreeBuilder erstellt. Der AST kann frei untersucht und manipuliert werden. Bitte sehen Sie Psych::parse_stream, Psych::Nodes und Psych::Nodes::Node für weitere Informationen zum Umgang mit YAML-Syntaxbäumen.

Lesen aus einem String

# Returns Psych::Nodes::Stream
Psych.parse_stream("---\n - a\n - b")

# Returns Psych::Nodes::Document
Psych.parse("---\n - a\n - b")

Lesen aus einer Datei

# Returns Psych::Nodes::Stream
Psych.parse_stream(File.read('database.yml'))

# Returns Psych::Nodes::Document
Psych.parse_file('database.yml')

Fehlerbehandlung

begin
  # The second argument changes only the exception contents
  Psych.parse("--- `", "file.txt")
rescue Psych::SyntaxError => ex
  ex.file    # => 'file.txt'
  ex.message # => "(file.txt): found character that cannot start any token"
end

Emittierung

Auf der mittleren Ebene wird ein AST erstellt. Dieser AST ist genau derselbe wie der AST, der beim Parsen eines YAML-Dokuments verwendet wird. Benutzer können einen AST manuell erstellen, und der AST weiß, wie er sich selbst als YAML-Dokument emittieren kann. Sehen Sie Psych::Nodes, Psych::Nodes::Node und Psych::TreeBuilder für weitere Informationen zum Erstellen eines YAML AST.

Schreiben in einen String

# We need Psych::Nodes::Stream (not Psych::Nodes::Document)
stream = Psych.parse_stream("---\n - a\n - b")

stream.to_yaml # => "---\n- a\n- b\n"

Schreiben in eine Datei

# We need Psych::Nodes::Stream (not Psych::Nodes::Document)
stream = Psych.parse_stream(File.read('database.yml'))

File.open('database.yml', 'w') do |file|
  file.write(stream.to_yaml)
end

Low-Level API

Parsing

Der Parser auf der niedrigsten Ebene sollte verwendet werden, wenn die YAML-Eingabe bereits bekannt ist und der Entwickler nicht den Aufwand für den Aufbau eines AST oder die automatische Erkennung und Konvertierung in Ruby-Objekte auf sich nehmen möchte. Sehen Sie Psych::Parser für weitere Informationen zur Verwendung des ereignisbasierten Parsers.

Lesen in die Struktur Psych::Nodes::Stream

parser = Psych::Parser.new(TreeBuilder.new) # => #<Psych::Parser>
parser = Psych.parser                       # it's an alias for the above

parser.parse("---\n - a\n - b")             # => #<Psych::Parser>
parser.handler                              # => #<Psych::TreeBuilder>
parser.handler.root                         # => #<Psych::Nodes::Stream>

Empfangen eines Ereignisstroms

recorder = Psych::Handlers::Recorder.new
parser = Psych::Parser.new(recorder)

parser.parse("---\n - a\n - b")
recorder.events # => [list of [event, args] lists]
                # event is one of: Psych::Handler::EVENTS
                # args are the arguments passed to the event

Emittierung

Der Emitter auf der niedrigsten Ebene ist ein ereignisbasiertes System. Ereignisse werden an ein Psych::Emitter-Objekt gesendet. Dieses Objekt weiß, wie die Ereignisse in ein YAML-Dokument konvertiert werden. Diese Schnittstelle sollte verwendet werden, wenn das Dokumentformat im Voraus bekannt ist oder die Geschwindigkeit eine Rolle spielt. Sehen Sie Psych::Emitter für weitere Informationen.

Schreiben in eine Ruby-Struktur

Psych.parser.parse("--- a")       # => #<Psych::Parser>

parser.handler.first              # => #<Psych::Nodes::Stream>
parser.handler.first.to_ruby      # => ["a"]

parser.handler.root.first         # => #<Psych::Nodes::Document>
parser.handler.root.first.to_ruby # => "a"

# You can instantiate an Emitter manually
Psych::Visitors::ToRuby.new.accept(parser.handler.root.first)
# => "a"