{ "content": [ { "type": "text", "text": "# Psych (ri)\n\n## Section Outline\n\n- **Psych** (7 lines)\n- **Overview** (7 lines)\n- **I NEED TO PARSE OR EMIT YAML RIGHT NOW!** (9 lines) — 5 subsections\n - YAML Parsing (6 lines)\n - YAML Emitting (6 lines)\n - High-level API (56 lines)\n - Mid-level API (58 lines)\n - Low-level API (81 lines)\n- **Constants:** (10 lines)\n- **Class methods:** (18 lines)\n\n## Full Content\n\n### Psych\n\n(from gem psych-5.4.0)\n------------------------------------------------------------------------\n\n### Overview\n\nPsych is a YAML parser and emitter. Psych leverages libyaml [Home page:\nhttps://pyyaml.org/wiki/LibYAML] or [git repo:\nhttps://github.com/yaml/libyaml] for its YAML parsing and emitting\ncapabilities. In addition to wrapping libyaml, Psych also knows how to\nserialize and de-serialize most Ruby objects to and from the YAML\nformat.\n\n### I NEED TO PARSE OR EMIT YAML RIGHT NOW!\n\n# Parse some YAML\nPsych.load(\"--- foo\") # => \"foo\"\n\n# Emit some YAML\nPsych.dump(\"foo\") # => \"--- foo\\n...\\n\"\n{ :a => 'b'}.toyaml # => \"---\\n:a: b\\n\"\n\nGot more time on your hands? Keep on reading!\n\n#### YAML Parsing\n\nPsych provides a range of interfaces for parsing a YAML document ranging\nfrom low level to high level, depending on your parsing needs. At the\nlowest level, is an event based parser. Mid level is access to the raw\nYAML AST, and at the highest level is the ability to unmarshal YAML to\nRuby objects.\n\n#### YAML Emitting\n\nPsych provides a range of interfaces ranging from low to high level for\nproducing YAML documents. Very similar to the YAML parsing interfaces,\nPsych provides at the lowest level, an event based system, mid-level is\nbuilding a YAML AST, and the highest level is converting a Ruby object\nstraight to a YAML document.\n\n#### High-level API\n\n=== Parsing\n\nThe high level YAML parser provided by Psych simply takes YAML as input\nand returns a Ruby data structure. For information on using the high\nlevel parser see Psych.load\n\n==== Reading from a string\n\nPsych.safeload(\"--- a\") # => 'a'\nPsych.safeload(\"---\\n - a\\n - b\") # => ['a', 'b']\n# From a trusted string:\nPsych.load(\"--- !ruby/range\\nbegin: 0\\nend: 42\\nexcl: false\\n\") # => 0..42\n\n==== Reading from a file\n\nPsych.safeloadfile(\"data.yml\", permittedclasses: [Date])\nPsych.loadfile(\"trusteddatabase.yml\")\n\n==== Exception handling\n\nbegin\n# The second argument changes only the exception contents\nPsych.parse(\"--- `\", \"file.txt\")\nrescue Psych::SyntaxError => ex\nex.file # => 'file.txt'\nex.message # => \"(file.txt): found character that cannot start any token\"\nend\n\n=== Emitting\n\nThe high level emitter has the easiest interface. Psych simply takes a\nRuby data structure and converts it to a YAML document. See Psych.dump\nfor more information on dumping a Ruby data structure.\n\n==== Writing to a string\n\n# Dump an array, get back a YAML string\nPsych.dump(['a', 'b']) # => \"---\\n- a\\n- b\\n\"\n\n# Dump an array to an IO object\nPsych.dump(['a', 'b'], StringIO.new) # => #\n\n# Dump an array with indentation set\nPsych.dump(['a', ['b']], :indentation => 3) # => \"---\\n- a\\n- - b\\n\"\n\n# Dump an array to an IO with indentation set\nPsych.dump(['a', ['b']], StringIO.new, :indentation => 3)\n\n==== Writing to a file\n\nCurrently there is no direct API for dumping Ruby structure to file:\n\nFile.open('database.yml', 'w') do |file|\nfile.write(Psych.dump(['a', 'b']))\nend\n\n#### Mid-level API\n\n=== Parsing\n\nPsych provides access to an AST produced from parsing a YAML document.\nThis tree is built using the Psych::Parser and Psych::TreeBuilder. The\nAST can be examined and manipulated freely. Please see\nPsych::parsestream, Psych::Nodes, and Psych::Nodes::Node for more\ninformation on dealing with YAML syntax trees.\n\n==== Reading from a string\n\n# Returns Psych::Nodes::Stream\nPsych.parsestream(\"---\\n - a\\n - b\")\n\n# Returns Psych::Nodes::Document\nPsych.parse(\"---\\n - a\\n - b\")\n\n==== Reading from a file\n\n# Returns Psych::Nodes::Stream\nPsych.parsestream(File.read('database.yml'))\n\n# Returns Psych::Nodes::Document\nPsych.parsefile('database.yml')\n\n==== Exception handling\n\nbegin\n# The second argument changes only the exception contents\nPsych.parse(\"--- `\", \"file.txt\")\nrescue Psych::SyntaxError => ex\nex.file # => 'file.txt'\nex.message # => \"(file.txt): found character that cannot start any token\"\nend\n\n=== Emitting\n\nAt the mid level is building an AST. This AST is exactly the same as\nthe AST used when parsing a YAML document. Users can build an AST by\nhand and the AST knows how to emit itself as a YAML document. See\nPsych::Nodes, Psych::Nodes::Node, and Psych::TreeBuilder for more\ninformation on building a YAML AST.\n\n==== Writing to a string\n\n# We need Psych::Nodes::Stream (not Psych::Nodes::Document)\nstream = Psych.parsestream(\"---\\n - a\\n - b\")\n\nstream.toyaml # => \"---\\n- a\\n- b\\n\"\n\n==== Writing to a file\n\n# We need Psych::Nodes::Stream (not Psych::Nodes::Document)\nstream = Psych.parsestream(File.read('database.yml'))\n\nFile.open('database.yml', 'w') do |file|\nfile.write(stream.toyaml)\nend\n\n#### Low-level API\n\n=== Parsing\n\nThe lowest level parser should be used when the YAML input is already\nknown, and the developer does not want to pay the price of building an\nAST or automatic detection and conversion to Ruby objects. See\nPsych::Parser for more information on using the event based parser.\n\n==== Reading to Psych::Nodes::Stream structure\n\nparser = Psych::Parser.new(TreeBuilder.new) # => #\nparser = Psych.parser # it's an alias for the above\n\nparser.parse(\"---\\n - a\\n - b\") # => #\nparser.handler # => #\nparser.handler.root # => #\n\n==== Receiving an events stream\n\nrecorder = Psych::Handlers::Recorder.new\nparser = Psych::Parser.new(recorder)\n\nparser.parse(\"---\\n - a\\n - b\")\nrecorder.events # => [list of [event, args] lists]\n# event is one of: Psych::Handler::EVENTS\n# args are the arguments passed to the event\n\n=== Emitting\n\nThe lowest level emitter is an event based system. Events are sent to a\nPsych::Emitter object. That object knows how to convert the events to a\nYAML document. This interface should be used when document format is\nknown in advance or speed is a concern. See Psych::Emitter for more\ninformation.\n\n==== Writing to a Ruby structure\n\nPsych.parser.parse(\"--- a\") # => #\n\nparser.handler.first # => #\nparser.handler.first.toruby # => [\"a\"]\n\nparser.handler.root.first # => #\nparser.handler.root.first.toruby # => \"a\"\n\n# You can instantiate an Emitter manually\nPsych::Visitors::ToRuby.new.accept(parser.handler.root.first)\n# => \"a\"\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n------------------------------------------------------------------------\n\n### Constants:\n\nDEFAULTSNAKEYAMLVERSION:\n[not documented]\n\nLIBYAMLVERSION:\nThe version of libyaml Psych is using\n\nVERSION:\nThe version of Psych you are using\n\n### Class methods:\n\ndump\ndumpstream\nlibyamlversion\nload\nloadfile\nloadstream\nparse\nparsefile\nparsestream\nparser\nsafedump\nsafeload\nsafeloadfile\nsafeloadstream\ntojson\nunsafeload\nunsafeloadfile\n\n" } ], "structuredContent": { "command": "Psych", "section": "", "mode": "ri", "summary": null, "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "Psych", "lines": 7, "subsections": [] }, { "name": "Overview", "lines": 7, "subsections": [] }, { "name": "I NEED TO PARSE OR EMIT YAML RIGHT NOW!", "lines": 9, "subsections": [ { "name": "YAML Parsing", "lines": 6 }, { "name": "YAML Emitting", "lines": 6 }, { "name": "High-level API", "lines": 56 }, { "name": "Mid-level API", "lines": 58 }, { "name": "Low-level API", "lines": 81 } ] }, { "name": "Constants:", "lines": 10, "subsections": [] }, { "name": "Class methods:", "lines": 18, "subsections": [] } ] } }