Skip to content

Add Psych.parse, Psych.parse_file, Psych.parse_stream and Psych::Nodes - #3304

Open
hasannadeem wants to merge 1 commit into
ruby:masterfrom
hasannadeem:psych-nodes
Open

hasannadeem wants to merge 1 commit into
ruby:masterfrom
hasannadeem:psych-nodes

Conversation

@hasannadeem

Copy link
Copy Markdown
Contributor

Psych.parse, Psych.parse_file and Psych.parse_stream had no signatures, because they return the YAML AST in Psych::Nodes, which had none either. (I left them out of #3288 for that reason.)

Parse methods (psych.rbs):

Method Signature
Psych.parse (String yaml, ?filename: ...) -> (Nodes::Document | false): false for an empty document
Psych.parse_file (path filename) -> (Nodes::Document | false) and [T] (path filename, fallback: T) -> (Nodes::Document | T)
Psych.parse_stream (String yaml, ?filename: ...) -> Nodes::Stream, and with a block that receives each Nodes::Document

The filename: type is the same as on the existing Psych.load/load_stream.

AST (new nodes.rbs):

  • Psych::Nodes::Node includes Enumerable[Node] (each walks the tree depth first) and has:
    • children, tag;
    • start_line/start_column/end_line/end_column: Integer?, because they are nil on a node built by hand rather than parsed;
    • to_ruby/transform;
    • yaml/to_yaml: a String, or the given IO, like Psych.dump;
    • the six alias? … stream? predicates.
  • The subclasses Alias, Document, Mapping, Scalar, Sequence and Stream add their initialize and attributes, the style constants (Scalar::LITERAL, Mapping::FLOW, …) and the encoding constants (Stream::UTF8, …). Each overrides its own predicate to return true.

to_ruby takes the same symbolize_names:, freeze: and strict_integer: keywords as Psych.load here. parse_symbols: exists only in psych 5, and the load signatures don't have it either. The API is otherwise the same in psych 4.0.6 and 5.3.1. module Psych in nodes.rbs has %a{annotate:rdoc:skip}, as in dbm.rbs, so the module's overview isn't copied there. The parse methods use %a{annotate:rdoc:copy:...}, like load_stream.

The tests parse a document with a %YAML and a %TAG directive, a tag, an anchor and an alias, so every node class and attribute is exercised on parsed nodes. The nil locations and root are checked on nodes built by hand, and every constant is checked too. They pass with psych 4.0.6 (the bundle), 5.2.6 (Ruby 3.4) and 5.3.1 (Ruby 4.0.7). Without the signatures the test file fails to load, and the parse tests fail.

The AST-building example from the Psych::Nodes docs type-checks with Steep:

stream = Psych::Nodes::Stream.new
doc    = Psych::Nodes::Document.new
seq    = Psych::Nodes::Sequence.new
scalar = Psych::Nodes::Scalar.new('foo')
stream.children << doc
doc.children    << seq
seq.children    << scalar
stream.to_yaml.upcase

So do tree.select(&:mapping?).map(&:start_line) and Psych.parse_file(path, fallback: nil)&.root, while scalar.value = 1 is still an error. Annotating core and stdlib from the full Ruby v4.0.7 source leaves both files unchanged, and rake validate and rake typecheck_test pass.

The parse methods return the YAML AST in Psych::Nodes, which had no
signatures. nodes.rbs adds Node and its Alias, Document, Mapping, Scalar,
Sequence and Stream subclasses, with their attributes, style and encoding
constants, to_ruby and yaml.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant