File: C:/Ruby27-x64/share/doc/ruby/html/Psych/Parser.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>class Psych::Parser - RDoc Documentation</title>
<script type="text/javascript">
var rdoc_rel_prefix = "../";
var index_rel_prefix = "../";
</script>
<script src="../js/navigation.js" defer></script>
<script src="../js/search.js" defer></script>
<script src="../js/search_index.js" defer></script>
<script src="../js/searcher.js" defer></script>
<script src="../js/darkfish.js" defer></script>
<link href="../css/fonts.css" rel="stylesheet">
<link href="../css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="class">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="../index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="../table_of_contents.html#pages">Pages</a>
<a href="../table_of_contents.html#classes">Classes</a>
<a href="../table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div id="class-metadata">
<div id="parent-class-section" class="nav-section">
<h3>Parent</h3>
<p class="link"><a href="../Object.html">Object</a>
</div>
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
<h3>Methods</h3>
<ul class="link-list" role="directory">
<li ><a href="#method-c-new">::new</a>
<li ><a href="#method-i-mark">#mark</a>
<li ><a href="#method-i-parse">#parse</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="class-Psych::Parser">
<h1 id="class-Psych::Parser" class="class">
class Psych::Parser
</h1>
<section class="description">
<p>YAML event parser class. This class parses a YAML document and calls events on the handler that is passed to the constructor. The events can be used for things such as constructing a YAML AST or deserializing YAML documents. It can even be fed back to <a href="Emitter.html"><code>Psych::Emitter</code></a> to emit the same document that was parsed.</p>
<p>See <a href="Handler.html"><code>Psych::Handler</code></a> for documentation on the events that <a href="Parser.html"><code>Psych::Parser</code></a> emits.</p>
<p>Here is an example that prints out ever scalar found in a YAML document:</p>
<pre class="ruby"><span class="ruby-comment"># Handler for detecting scalar values</span>
<span class="ruby-keyword">class</span> <span class="ruby-constant">ScalarHandler</span> <span class="ruby-operator"><</span> <span class="ruby-constant">Psych</span><span class="ruby-operator">::</span><span class="ruby-constant">Handler</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">scalar</span> <span class="ruby-identifier">value</span>, <span class="ruby-identifier">anchor</span>, <span class="ruby-identifier">tag</span>, <span class="ruby-identifier">plain</span>, <span class="ruby-identifier">quoted</span>, <span class="ruby-identifier">style</span>
<span class="ruby-identifier">puts</span> <span class="ruby-identifier">value</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">Psych</span><span class="ruby-operator">::</span><span class="ruby-constant">Parser</span>.<span class="ruby-identifier">new</span>(<span class="ruby-constant">ScalarHandler</span>.<span class="ruby-identifier">new</span>)
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse</span>(<span class="ruby-identifier">yaml_document</span>)
</pre>
<p>Here is an example that feeds the parser back in to <a href="Emitter.html"><code>Psych::Emitter</code></a>. The YAML document is read from STDIN and written back out to STDERR:</p>
<pre class="ruby"><span class="ruby-identifier">parser</span> = <span class="ruby-constant">Psych</span><span class="ruby-operator">::</span><span class="ruby-constant">Parser</span>.<span class="ruby-identifier">new</span>(<span class="ruby-constant">Psych</span><span class="ruby-operator">::</span><span class="ruby-constant">Emitter</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">$stderr</span>))
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse</span>(<span class="ruby-identifier">$stdin</span>)
</pre>
<p><a href="../Psych.html"><code>Psych</code></a> uses <a href="Parser.html"><code>Psych::Parser</code></a> in combination with <a href="TreeBuilder.html"><code>Psych::TreeBuilder</code></a> to construct an AST of the parsed YAML document.</p>
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section class="constants-list">
<header>
<h3>Constants</h3>
</header>
<dl>
<dt id="ANY">ANY
<dd><p>Let the parser choose the encoding</p>
<dt id="UTF16BE">UTF16BE
<dd><p>UTF-16-BE <a href="../Encoding.html"><code>Encoding</code></a> with BOM</p>
<dt id="UTF16LE">UTF16LE
<dd><p>UTF-16-LE <a href="../Encoding.html"><code>Encoding</code></a> with BOM</p>
<dt id="UTF8">UTF8
<dd><p>UTF-8 <a href="../Encoding.html"><code>Encoding</code></a></p>
</dl>
</section>
<section class="attribute-method-details" class="method-section">
<header>
<h3>Attributes</h3>
</header>
<div id="attribute-i-external_encoding" class="method-detail">
<div class="method-heading attribute-method-heading">
<span class="method-name">external_encoding</span><span
class="attribute-access-type">[W]</span>
</div>
<div class="method-description">
<p><a href="Set.html"><code>Set</code></a> the encoding for this parser to <code>encoding</code></p>
</div>
</div>
<div id="attribute-i-handler" class="method-detail">
<div class="method-heading attribute-method-heading">
<span class="method-name">handler</span><span
class="attribute-access-type">[RW]</span>
</div>
<div class="method-description">
<p>The handler on which events will be called</p>
</div>
</div>
</section>
<section id="public-class-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Class Methods</h3>
</header>
<div id="method-c-new" class="method-detail ">
<div class="method-heading">
<span class="method-name">new</span><span
class="method-args">(handler = Handler.new)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Creates a new <a href="Parser.html"><code>Psych::Parser</code></a> instance with <code>handler</code>. YAML events will be called on <code>handler</code>. See <a href="Parser.html"><code>Psych::Parser</code></a> for more details.</p>
<div class="method-source-code" id="new-source">
<pre><span class="ruby-comment"># File ext/psych/lib/psych/parser.rb, line 47</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">initialize</span> <span class="ruby-identifier">handler</span> = <span class="ruby-constant">Handler</span>.<span class="ruby-identifier">new</span>
<span class="ruby-ivar">@handler</span> = <span class="ruby-identifier">handler</span>
<span class="ruby-ivar">@external_encoding</span> = <span class="ruby-constant">ANY</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
</section>
<section id="public-instance-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Instance Methods</h3>
</header>
<div id="method-i-mark" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
mark # → #<Psych::Parser::Mark>
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns a <a href="Parser/Mark.html"><code>Psych::Parser::Mark</code></a> object that contains line, column, and index information.</p>
<div class="method-source-code" id="mark-source">
<pre>static VALUE mark(VALUE self)
{
VALUE mark_klass;
VALUE args[3];
yaml_parser_t * parser;
TypedData_Get_Struct(self, yaml_parser_t, &psych_parser_type, parser);
mark_klass = rb_const_get_at(cPsychParser, rb_intern("Mark"));
args[0] = INT2NUM(parser->mark.index);
args[1] = INT2NUM(parser->mark.line);
args[2] = INT2NUM(parser->mark.column);
return rb_class_new_instance(3, args, mark_klass);
}</pre>
</div>
</div>
</div>
<div id="method-i-parse" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
parse(yaml)
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Parse the YAML document contained in <code>yaml</code>. Events will be called on the handler set on the parser instance.</p>
<p>See <a href="Parser.html"><code>Psych::Parser</code></a> and <a href="Parser.html#attribute-i-handler"><code>Psych::Parser#handler</code></a></p>
<div class="method-source-code" id="parse-source">
<pre>static VALUE parse(int argc, VALUE *argv, VALUE self)
{
VALUE yaml, path;
yaml_parser_t * parser;
yaml_event_t event;
int done = 0;
int state = 0;
int parser_encoding = YAML_ANY_ENCODING;
int encoding = rb_utf8_encindex();
rb_encoding * internal_enc = rb_default_internal_encoding();
VALUE handler = rb_iv_get(self, "@handler");
if (rb_scan_args(argc, argv, "11", &yaml, &path) == 1) {
if(rb_respond_to(yaml, id_path))
path = rb_funcall(yaml, id_path, 0);
else
path = rb_str_new2("<unknown>");
}
TypedData_Get_Struct(self, yaml_parser_t, &psych_parser_type, parser);
yaml_parser_delete(parser);
yaml_parser_initialize(parser);
if (rb_respond_to(yaml, id_read)) {
yaml = transcode_io(yaml, &parser_encoding);
yaml_parser_set_encoding(parser, parser_encoding);
yaml_parser_set_input(parser, io_reader, (void *)yaml);
} else {
StringValue(yaml);
yaml = transcode_string(yaml, &parser_encoding);
yaml_parser_set_encoding(parser, parser_encoding);
yaml_parser_set_input_string(
parser,
(const unsigned char *)RSTRING_PTR(yaml),
(size_t)RSTRING_LEN(yaml)
);
}
while(!done) {
VALUE event_args[5];
VALUE start_line, start_column, end_line, end_column;
if(!yaml_parser_parse(parser, &event)) {
VALUE exception;
exception = make_exception(parser, path);
yaml_parser_delete(parser);
yaml_parser_initialize(parser);
rb_exc_raise(exception);
}
start_line = INT2NUM((long)event.start_mark.line);
start_column = INT2NUM((long)event.start_mark.column);
end_line = INT2NUM((long)event.end_mark.line);
end_column = INT2NUM((long)event.end_mark.column);
event_args[0] = handler;
event_args[1] = start_line;
event_args[2] = start_column;
event_args[3] = end_line;
event_args[4] = end_column;
rb_protect(protected_event_location, (VALUE)event_args, &state);
switch(event.type) {
case YAML_STREAM_START_EVENT:
{
VALUE args[2];
args[0] = handler;
args[1] = INT2NUM((long)event.data.stream_start.encoding);
rb_protect(protected_start_stream, (VALUE)args, &state);
}
break;
case YAML_DOCUMENT_START_EVENT:
{
VALUE args[4];
/* Get a list of tag directives (if any) */
VALUE tag_directives = rb_ary_new();
/* Grab the document version */
VALUE version = event.data.document_start.version_directive ?
rb_ary_new3(
(long)2,
INT2NUM((long)event.data.document_start.version_directive->major),
INT2NUM((long)event.data.document_start.version_directive->minor)
) : rb_ary_new();
if(event.data.document_start.tag_directives.start) {
yaml_tag_directive_t *start =
event.data.document_start.tag_directives.start;
yaml_tag_directive_t *end =
event.data.document_start.tag_directives.end;
for(; start != end; start++) {
VALUE handle = Qnil;
VALUE prefix = Qnil;
if(start->handle) {
handle = rb_str_new2((const char *)start->handle);
PSYCH_TRANSCODE(handle, encoding, internal_enc);
}
if(start->prefix) {
prefix = rb_str_new2((const char *)start->prefix);
PSYCH_TRANSCODE(prefix, encoding, internal_enc);
}
rb_ary_push(tag_directives, rb_ary_new3((long)2, handle, prefix));
}
}
args[0] = handler;
args[1] = version;
args[2] = tag_directives;
args[3] = event.data.document_start.implicit == 1 ? Qtrue : Qfalse;
rb_protect(protected_start_document, (VALUE)args, &state);
}
break;
case YAML_DOCUMENT_END_EVENT:
{
VALUE args[2];
args[0] = handler;
args[1] = event.data.document_end.implicit == 1 ? Qtrue : Qfalse;
rb_protect(protected_end_document, (VALUE)args, &state);
}
break;
case YAML_ALIAS_EVENT:
{
VALUE args[2];
VALUE alias = Qnil;
if(event.data.alias.anchor) {
alias = rb_str_new2((const char *)event.data.alias.anchor);
PSYCH_TRANSCODE(alias, encoding, internal_enc);
}
args[0] = handler;
args[1] = alias;
rb_protect(protected_alias, (VALUE)args, &state);
}
break;
case YAML_SCALAR_EVENT:
{
VALUE args[7];
VALUE anchor = Qnil;
VALUE tag = Qnil;
VALUE plain_implicit, quoted_implicit, style;
VALUE val = rb_str_new(
(const char *)event.data.scalar.value,
(long)event.data.scalar.length
);
PSYCH_TRANSCODE(val, encoding, internal_enc);
if(event.data.scalar.anchor) {
anchor = rb_str_new2((const char *)event.data.scalar.anchor);
PSYCH_TRANSCODE(anchor, encoding, internal_enc);
}
if(event.data.scalar.tag) {
tag = rb_str_new2((const char *)event.data.scalar.tag);
PSYCH_TRANSCODE(tag, encoding, internal_enc);
}
plain_implicit =
event.data.scalar.plain_implicit == 0 ? Qfalse : Qtrue;
quoted_implicit =
event.data.scalar.quoted_implicit == 0 ? Qfalse : Qtrue;
style = INT2NUM((long)event.data.scalar.style);
args[0] = handler;
args[1] = val;
args[2] = anchor;
args[3] = tag;
args[4] = plain_implicit;
args[5] = quoted_implicit;
args[6] = style;
rb_protect(protected_scalar, (VALUE)args, &state);
}
break;
case YAML_SEQUENCE_START_EVENT:
{
VALUE args[5];
VALUE anchor = Qnil;
VALUE tag = Qnil;
VALUE implicit, style;
if(event.data.sequence_start.anchor) {
anchor = rb_str_new2((const char *)event.data.sequence_start.anchor);
PSYCH_TRANSCODE(anchor, encoding, internal_enc);
}
tag = Qnil;
if(event.data.sequence_start.tag) {
tag = rb_str_new2((const char *)event.data.sequence_start.tag);
PSYCH_TRANSCODE(tag, encoding, internal_enc);
}
implicit =
event.data.sequence_start.implicit == 0 ? Qfalse : Qtrue;
style = INT2NUM((long)event.data.sequence_start.style);
args[0] = handler;
args[1] = anchor;
args[2] = tag;
args[3] = implicit;
args[4] = style;
rb_protect(protected_start_sequence, (VALUE)args, &state);
}
break;
case YAML_SEQUENCE_END_EVENT:
rb_protect(protected_end_sequence, handler, &state);
break;
case YAML_MAPPING_START_EVENT:
{
VALUE args[5];
VALUE anchor = Qnil;
VALUE tag = Qnil;
VALUE implicit, style;
if(event.data.mapping_start.anchor) {
anchor = rb_str_new2((const char *)event.data.mapping_start.anchor);
PSYCH_TRANSCODE(anchor, encoding, internal_enc);
}
if(event.data.mapping_start.tag) {
tag = rb_str_new2((const char *)event.data.mapping_start.tag);
PSYCH_TRANSCODE(tag, encoding, internal_enc);
}
implicit =
event.data.mapping_start.implicit == 0 ? Qfalse : Qtrue;
style = INT2NUM((long)event.data.mapping_start.style);
args[0] = handler;
args[1] = anchor;
args[2] = tag;
args[3] = implicit;
args[4] = style;
rb_protect(protected_start_mapping, (VALUE)args, &state);
}
break;
case YAML_MAPPING_END_EVENT:
rb_protect(protected_end_mapping, handler, &state);
break;
case YAML_NO_EVENT:
rb_protect(protected_empty, handler, &state);
break;
case YAML_STREAM_END_EVENT:
rb_protect(protected_end_stream, handler, &state);
done = 1;
break;
}
yaml_event_delete(&event);
if (state) rb_jump_tag(state);
}
return self;
}</pre>
</div>
</div>
</div>
</section>
</section>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.2.1.1.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>