From 95343e1cf02e97470dc70cd6dde896472be6869f Mon Sep 17 00:00:00 2001 From: Aaron Patterson Date: Sun, 3 Jan 2010 18:41:14 -0800 Subject: adding more documentation --- ext/psych/parser.c | 13 ++++++++++ lib/psych/handler.rb | 70 +++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 77 insertions(+), 6 deletions(-) diff --git a/ext/psych/parser.c b/ext/psych/parser.c index c51f45c..7755c80 100644 --- a/ext/psych/parser.c +++ b/ext/psych/parser.c @@ -194,6 +194,19 @@ static VALUE parse(VALUE self, VALUE yaml) void Init_psych_parser() { cPsychParser = rb_define_class_under(mPsych, "Parser", rb_cObject); + + /* Any encoding: Let the parser choose the encoding */ + rb_define_const(cPsychParser, "ANY", INT2NUM(YAML_ANY_ENCODING)); + + /* UTF-8 Encoding */ + rb_define_const(cPsychParser, "UTF8", INT2NUM(YAML_UTF8_ENCODING)); + + /* UTF-16-LE Encoding with BOM */ + rb_define_const(cPsychParser, "UTF16LE", INT2NUM(YAML_UTF16LE_ENCODING)); + + /* UTF-16-BE Encoding with BOM */ + rb_define_const(cPsychParser, "UTF16BE", INT2NUM(YAML_UTF16BE_ENCODING)); + ePsychSyntaxError = rb_define_class_under(mPsych, "SyntaxError", rb_eSyntaxError); rb_define_method(cPsychParser, "parse", parse, 1); diff --git a/lib/psych/handler.rb b/lib/psych/handler.rb index f67a554..2364782 100644 --- a/lib/psych/handler.rb +++ b/lib/psych/handler.rb @@ -1,25 +1,83 @@ module Psych ### - # Default event handlers used in conjunction with Psych::Parser + # Psych::Handler is an abstract base class that defines the events used + # when dealing with Psych::Parser. Clients who want to use Psych::Parser + # should implement a class that inherits from Psych::Handler and define + # events that they can handle. + # + # Psych::Handler defines all events that Psych::Parser can possibly send to + # event handlers. + # + # See Psych::Parser for more details class Handler ### - # Called with +encoding+ when the YAML stream starts. + # Called with +encoding+ when the YAML stream starts. This method is + # called once per stream. A stream may contain multiple documents. + # + # See the constants in Psych::Parser for the possible values of +encoding+. def start_stream encoding end ### # Called when the document starts with the declared +version+, - # +tag_directives+, if the document is +implicit+ + # +tag_directives+, if the document is +implicit+. + # + # +version+ will be an array of integers indicating the YAML version being + # dealt with, +tag_directives+ is a list of tuples indicating the prefix + # and suffix of each tag, and +implicit+ is a boolean indicating whether + # the document is started implicitly. + # + # === Example + # + # Given the following YAML: + # + # %YAML 1.1 + # %TAG ! tag:tenderlovemaking.com,2009: + # --- !squee + # + # The parameters for start_document must be this: + # + # version # => [1, 1] + # tag_directives # => [["!", "tag:tenderlovemaking.com,2009:"]] + # implicit # => false def start_document version, tag_directives, implicit end ### - # Called with the document ends. - def end_document implicit = true + # Called with the document ends. +implicit+ is a boolean value indicating + # whether or not the document has an implicit ending. + # + # === Example + # + # Given the following YAML: + # + # --- + # hello world + # + # +implicit+ will be true. Given this YAML: + # + # --- + # hello world + # ... + # + # +implicit+ will be false. + def end_document implicit end ### - # Called when an alias is found to +anchor+ + # Called when an alias is found to +anchor+. +anchor+ will be the name + # of the anchor found. + # + # === Example + # + # Here we have an example of an array that references itself in YAML: + # + # --- &ponies + # - first element + # - *ponies + # + # &ponies is the achor, *ponies is the alias. In this case, alias is + # called with "ponies". def alias anchor end -- cgit v1.2.3