argh! more undocumented mysteries: to_yaml

[Tom Cloyd]

Beginner woes, here, no doubt, but woes nevertheless.

I'm exploring the wonders of the Object class, and I see Object#to_yaml.
Seems pretty obvious what to expect here, which would seem to account
for the total lack of documentation in each of the gazillion instances
of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
from (irb):10
from :0

Can someone explain what just happened?

Thanks!

t.

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[Mateusz Tybura]

[Note: parts of this message were removed to make it a legal post.]

I'm beginner to but I understand it. You cannot use to_yaml for Array,
because there's no method to_yaml for Array. Try to read about
Object#to_yaml in Ruby Documentation.

 

[Stefano Crocco]

Beginner woes, here, no doubt, but woes nevertheless.

I'm exploring the wonders of the Object class, and I see Object#to_yaml.
Seems pretty obvious what to expect here, which would seem to account
for the total lack of documentation in each of the gazillion instances
of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
from (irb):10
from :0

Can someone explain what just happened?

Thanks!

t.

Yes. to_yaml is defined in the yaml.rb file, so you need to require it before
using to_yaml:

irb(main):001:0> require 'yaml'
=> true
irb(main):002:0> [2,3,4,5, 'abc'].to_yaml
=> "--- \n- 2\n- 3\n- 4\n- 5\n- abc\n"

How are you supposed to know that to_yaml is not in ruby core but in the
standard library? I don't really know. When I started using ruby some years
ago, I downloaded a version of the rdoc documentation from
www.ruby-doc.org which only included documentation for the core classes (that
is, those you can use without need to require some files), while documentation
for the standard library was in a separate package. Unfortunately, the
documentation you can find nowadays includes both core and standard library.
This has the very unpleasant side effect of displaying together methods which
come from the core classes and methods which come from files in the standard
library (which should be required before using such methods). At any rate, at
the top of the page, just below the name of the class, there's a list of the
files which have been used to generate the documentation for the class. If a
method listed in the documentation doesn't seem to exist, try requiring those
files. In the specific case of Object#to_yaml, this doesn't work, though,
since the file where the method is defined, lib/yaml/rubytypes.rb, can't be
required directly, but only requiring 'yaml'. It can give you a hint.

Stefano

 

[Phillip Gawlowski]

Beginner woes, here, no doubt, but woes nevertheless.

I'm exploring the wonders of the Object class, and I see Object#to_yaml.
Seems pretty obvious what to expect here, which would seem to account
for the total lack of documentation in each of the gazillion instances
of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
from (irb):10
from :0

Can someone explain what just happened?

Thanks!

t.

irb(main):005:0> [2,3,4].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 3, 4]:Array
from (irb):5
from :0
irb(main):006:0> require "yaml"
=> true
irb(main):008:0> [2,3,4].to_yaml
=> "--- \n- 2\n- 3\n- 4\n"

See also:
http://ruby-doc.org/core/classes/YAML.html

--Phillip Gawlowski

 

[Tom Cloyd]

Documentation? WHAT documentation? Please read my email.

Also, replicate my example in irb - with any object you wish. (I tried
Array, Fixnum, Float - all raise the same error)

Finally, consider this statement from the general documentation for the
Class Object at http://www.ruby-doc.org/core/:
"Object <http://www.ruby-doc.org/core/classes/Object.html> is the parent
class <http://www.ruby-doc.org/core/classes/Object.html#M000348> of all
classes in Ruby. Its methods
<http://www.ruby-doc.org/core/classes/Object.html#M000359> are therefore
available to all objects unless explicitly overridden."

My problem remains as I stated it.

Thanks for your response, in any case. I will hold out for the
possibility that with a little more examination you'll see what I have
so far missed - the reason for this problem.

Thanks!

t.

I'm beginner to but I understand it. You cannot use to_yaml for Array,
because there's no method to_yaml for Array. Try to read about
Object#to_yaml in Ruby Documentation.

Beginner woes, here, no doubt, but woes nevertheless.

I'm exploring the wonders of the Object class, and I see Object#to_yaml.
Seems pretty obvious what to expect here, which would seem to account
for the total lack of documentation in each of the gazillion instances
of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
from (irb):10
from :0

Can someone explain what just happened?

Thanks!

t.

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[Phillip Gawlowski]

Documentation? WHAT documentation? Please read my email.

Also, replicate my example in irb - with any object you wish. (I tried
Array, Fixnum, Float - all raise the same error)

Finally, consider this statement from the general documentation for the
Class Object at http://www.ruby-doc.org/core/:
"Object <http://www.ruby-doc.org/core/classes/Object.html> is the parent
class <http://www.ruby-doc.org/core/classes/Object.html#M000348> of all
classes in Ruby. Its methods
<http://www.ruby-doc.org/core/classes/Object.html#M000359> are therefore
available to all objects unless explicitly overridden."

My problem remains as I stated it.

Thanks for your response, in any case. I will hold out for the
possibility that with a little more examination you'll see what I have
so far missed - the reason for this problem.

You don't use the tools Ruby/irb gives you:=> ["<", "<=", "<=>", "==", "===", "=~", ">", ">=", "__id__",
"__send__", "allocate", "ancestors", "autoload", "autoload?", "class",
"class_eval", "class_variable_defined?", "class_variables", "clone",
"const_defined?", "const_get", "const_missing", "const_set",
"constants", "display", "dup", "eql?", "equal?", "extend"
, "freeze", "frozen?", "hash", "id", "include?", "included_modules",
"inspect","instance_eval", "instance_method", "instance_methods",
"instance_of?", "instance_variable_defined?", "instance_variable_get",
"instance_variable_set", "instance_variables", "is_a?", "kind_of?",
"method", "method_defined?", "methods", "module_eval", "name", "new",
"nil?", "object_id", "private_class_method", "private_instance_methods",
"private_method_defined?", "private_methods",
"protected_instance_methods", "protected_method_defined?",
"protected_methods", "public_class_method", "public_instance_methods",
"public_method_defined?", "public_methods", "respond_to?", "send",
"singleton_methods", "superclass", "taint", "tainted?", "to_a", "to_s",
"type", "untaint"]

As you can see, the method is not, by default, defined You already know
that the documentation leaves some things desirable, so start using
Google, or Ruby's capabilities of inspection, to narrow down your
mistakes/errors and do some troubleshooting. You'll need these skills
when writing applications, anyway.

And as an MS/MA you certainly learned research skills at college. If
they've atrophied, now's a good chance to resurrect them, no?

-- Phillip Gawlowski

 

[Tim Hunter]

How are you supposed to know that to_yaml is not in ruby core but in the
standard library? I don't really know. When I started using ruby some years
ago, I downloaded a version of the rdoc documentation from
www.ruby-doc.org which only included documentation for the core classes (that
is, those you can use without need to require some files), while documentation
for the standard library was in a separate package. Unfortunately, the
documentation you can find nowadays includes both core and standard library.

The ri command shows the documentation for the merged core and standard
libraries. It's sad but it's true. However, it isn't hard to find out
what's the the core and what isn't.

This link http://www.ruby-lang.org/en/documentation/ has a link to the
top-level www.ruby-doc.org as well as individual links to the core and
standard API sections of ruby-doc.

When I go to www.ruby-doc.org right now, the documentation for the Core
API is clearly separated from the documentation for the Standard API.
The yaml library is documented in the Standard API documentation.

When I view the online (first edition) version of _Programming_Ruby_
(http://www.ruby-doc.org/docs/ProgrammingRuby/) the core API is
documented in the "Built in Classes and Methods" chapter. The Standard
library is documented in the "Standard Library" chapter. The yaml
library isn't documented in that book because it didn't exist when the
first edition was written. The 2nd edition (pay for) includes yaml in
the Standard Library chapter. There is also a short tutorial about yaml
in the marshalling chapter.

 

[Dave Thomas]

I'm exploring the wonders of the Object class, and I see
Object#to_yaml. Seems pretty obvious what to expect here, which
would seem to account for the total lack of documentation in each of
the gazillion instances of this method which appear in core library.
Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6,
"abc"]:Array
from (irb):10
from :0

Can someone explain what just happened?

Tom:

Could you tell us just where you found the description of
Object#to_yaml.

As others have explained, to_yaml is not a built-in method. It is
added when you require the yaml library. So, if a piece of
documentation is out there that fails to make it clear that this
library must be loaded before to_yaml is called, then that
documentation needs to be fixed.

As others have also pointed out, once the library is loaded, you can
indeed invoke to_yaml on arrays, hashes, and so on.


Regards


Dave Thomas

 

[Dave Thomas]

I will hold out for the possibility that with a little more
examination you'll see what I have so far missed - the reason for
this problem.

Just to follow up on my previous email...

It's also possible you saw Object#to_yaml if you're using the 'ri'
utility and you have the yaml library installed on your local machine.
ri lists all the methods that can possibly appear in a class, and
(somewhat stupidly) fails to differential between those that are built
in and those that can be added. (I say somewhat stupidly because it
was my fault .

Regards


Dave Thomas

 

[Tom Cloyd]

Documentation? WHAT documentation? Please read my email.

Also, replicate my example in irb - with any object you wish. (I
tried Array, Fixnum, Float - all raise the same error)

Finally, consider this statement from the general documentation for
the Class Object at http://www.ruby-doc.org/core/:
"Object <http://www.ruby-doc.org/core/classes/Object.html> is the
parent class
<http://www.ruby-doc.org/core/classes/Object.html#M000348> of all
classes in Ruby. Its methods
<http://www.ruby-doc.org/core/classes/Object.html#M000359> are
therefore available to all objects unless explicitly overridden."

My problem remains as I stated it.

Thanks for your response, in any case. I will hold out for the
possibility that with a little more examination you'll see what I
have so far missed - the reason for this problem.

You don't use the tools Ruby/irb gives you:=> ["<", "<=", "<=>", "==", "===", "=~", ">", ">=", "__id__",
"__send__", "allocate", "ancestors", "autoload", "autoload?", "class",
"class_eval", "class_variable_defined?", "class_variables", "clone",
"const_defined?", "const_get", "const_missing", "const_set",
"constants", "display", "dup", "eql?", "equal?", "extend"
, "freeze", "frozen?", "hash", "id", "include?", "included_modules",
"inspect","instance_eval", "instance_method", "instance_methods",
"instance_of?", "instance_variable_defined?", "instance_variable_get",
"instance_variable_set", "instance_variables", "is_a?", "kind_of?",
"method", "method_defined?", "methods", "module_eval", "name", "new",
"nil?", "object_id", "private_class_method",
"private_instance_methods", "private_method_defined?",
"private_methods", "protected_instance_methods",
"protected_method_defined?", "protected_methods",
"public_class_method", "public_instance_methods",
"public_method_defined?", "public_methods", "respond_to?", "send",
"singleton_methods", "superclass", "taint", "tainted?", "to_a",
"to_s", "type", "untaint"]

As you can see, the method is not, by default, defined You already
know that the documentation leaves some things desirable, so start
using Google, or Ruby's capabilities of inspection, to narrow down
your mistakes/errors and do some troubleshooting. You'll need these
skills when writing applications, anyway.

And as an MS/MA you certainly learned research skills at college. If
they've atrophied, now's a good chance to resurrect them, no?

-- Phillip Gawlowski

Phillip, good research begins with careful observation - in this case,
of the materials at hand. In my immediately previous email I pointed out
that the ruby core documentation, for which I gave a reference, so you
could check my accuracy (basic scholarly method), tells me that
Object#to_yaml should be available to all object unless "explicitly
overridden". I then present some cases where it isn't available. That
contradiction is what I could not explain. I do not expect such a
blatant error/omission/contradiction - or whatever - in the ruby core
documentation. If I can't trust what it says about the root object of
all objects, then what can I trust? That, to me, looks like a problem -
and not exactly one I'd expect Google or some blog entry to solve.

Your ">> Object.methods.sort " tip is useful, as is the suggestion that
I learn more of Ruby's self-inspection tools. I will pursue this. It
didn't occur to me that irb would deny use of this method. That was
clearly an erroneous assumption, howsoever reasonable it may have seemed
at the time.

t.

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[Stefano Crocco]

The ri command shows the documentation for the merged core and standard
libraries. It's sad but it's true. However, it isn't hard to find out
what's the the core and what isn't.

This link http://www.ruby-lang.org/en/documentation/ has a link to the
top-level www.ruby-doc.org as well as individual links to the core and
standard API sections of ruby-doc.

When I go to www.ruby-doc.org right now, the documentation for the Core
API is clearly separated from the documentation for the Standard API.
The yaml library is documented in the Standard API documentation.

As far as I can see, the links to the 'Core documentation' on both www.ruby-
doc.org and http://www.ruby-lang.org/en/documentation/ point to the same
documentation, which sadly contains both the core and the standard library. As
you say, the standard library is also documented in its own section, which is
much more organized, and easy to use.

Stefano

 

[Tom Cloyd]

Beginner woes, here, no doubt, but woes nevertheless.

I'm exploring the wonders of the Object class, and I see Object#to_yaml.
Seems pretty obvious what to expect here, which would seem to account
for the total lack of documentation in each of the gazillion instances
of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
from (irb):10
from :0

Can someone explain what just happened?

Thanks!

t.

Yes. to_yaml is defined in the yaml.rb file, so you need to require it before
using to_yaml:

irb(main):001:0> require 'yaml'
=> true
irb(main):002:0> [2,3,4,5, 'abc'].to_yaml
=> "--- \n- 2\n- 3\n- 4\n- 5\n- abc\n"

How are you supposed to know that to_yaml is not in ruby core but in the
standard library? I don't really know. When I started using ruby some years
ago, I downloaded a version of the rdoc documentation from
www.ruby-doc.org which only included documentation for the core classes (that
is, those you can use without need to require some files), while documentation
for the standard library was in a separate package. Unfortunately, the
documentation you can find nowadays includes both core and standard library.
This has the very unpleasant side effect of displaying together methods which
come from the core classes and methods which come from files in the standard
library (which should be required before using such methods). At any rate, at
the top of the page, just below the name of the class, there's a list of the
files which have been used to generate the documentation for the class. If a
method listed in the documentation doesn't seem to exist, try requiring those
files. In the specific case of Object#to_yaml, this doesn't work, though,
since the file where the method is defined, lib/yaml/rubytypes.rb, can't be
required directly, but only requiring 'yaml'. It can give you a hint.

Stefano

Interesting. I have NO idea how I might have found this out, but I will
make a note to try requiring something if it doesn't seem to be
available. I fault myself for not thinking of that!

t.

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[Tom Cloyd]

Just to follow up on my previous email...

It's also possible you saw Object#to_yaml if you're using the 'ri'
utility and you have the yaml library installed on your local machine.
ri lists all the methods that can possibly appear in a class, and
(somewhat stupidly) fails to differential between those that are built
in and those that can be added. (I say somewhat stupidly because it
was my fault .

Regards


Dave Thomas

Well, Dave, looks like we've found our culprit (heh heh). However, I
simply cannot fault someone who's been such an asset to us all. I will
try simply to remember that Ruby and its documentation is a work in
progress, and that as my own cleverness grows, my expectations of Ruby's
can gracefully diminish. Every weekend I spend with Ruby is increasingly
informative, and this one is no exception. And...the good folks on this
list are a major reason for my continuing education. Thanks to you all.

t.

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[Phillip Gawlowski]

Phillip, good research begins with careful observation - in this case,
of the materials at hand. In my immediately previous email I pointed out
that the ruby core documentation, for which I gave a reference, so you
could check my accuracy (basic scholarly method), tells me that
Object#to_yaml should be available to all object unless "explicitly
overridden". I then present some cases where it isn't available. That
contradiction is what I could not explain. I do not expect such a
blatant error/omission/contradiction - or whatever - in the ruby core
documentation. If I can't trust what it says about the root object of
all objects, then what can I trust? That, to me, looks like a problem -
and not exactly one I'd expect Google or some blog entry to solve.

You do know, however, that the state of Ruby's documentation on the web
is rather bad. Which creates faulty assumptions, as you've noticed.

And yes, something like this is something a blog entry (or, more
generally speaking, a blog entry) can solve, since you more likely than
not aren't the first person to have this problem.

Unfortunately, the only way to get a reasonably up-to-date documentation
for Ruby is via Programming Ruby (and maybe The Ruby Programming
Language), which also provides usage examples. The free edition of the
Pickaxe is slightly out of date (as has been mentioned elsewhere).

The trick is, that you are standing on the shoulder of giants. Tapping
into that, can make Ruby much more hassle free (and I've ran against a
wall when using Ruby's documentation myself, hence my fondness for the
Pickaxe).

-- Phillip Gawlowski

 

[Tom Cloyd]

I'm exploring the wonders of the Object class, and I see
Object#to_yaml. Seems pretty obvious what to expect here, which would
seem to account for the total lack of documentation in each of the
gazillion instances of this method which appear in core library.
Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
from (irb):10
from :0

Can someone explain what just happened?

Tom:

Could you tell us just where you found the description of Object#to_yaml.

As others have explained, to_yaml is not a built-in method. It is
added when you require the yaml library. So, if a piece of
documentation is out there that fails to make it clear that this
library must be loaded before to_yaml is called, then that
documentation needs to be fixed.

As others have also pointed out, once the library is loaded, you can
indeed invoke to_yaml on arrays, hashes, and so on.


Regards


Dave Thomas

OK...now THIS is the reaction I was really looking for, which is why I
provided the documentation I did in my first two emails. From my point
of view, and as your response here would seem to support, beginners like
me can, in exploring the interface to Ruby (part of which is its
available documentation) find glitches which those of you with expert
knowledge all too easily miss. We are, in fact, a uniquely valuable
resource, I would hope. I'm trying to be, in any case.

So...here's the path to the documentation (can't give an specific URL,
due to use of frames):
1. go to http://www.ruby-doc.org/core/
2. in the middle panel, select the Object class.
3. scroll down to Methods, and find the to_yaml method
4. clicking on that, you'll see there's no documentation. So, go back to
the top of the Object's page, and see the sentence I noted in my second
email: " Object is the parent class of all classes in Ruby. Its methods
are therefore available to all objects unless explicitly overridden."

To my mind, there is nothing here that suggests that I must "require"
anything to get access to this method. Hence my (enduring) bewilderment.
Were I more knowledgeable about object inspection, I'd have seen why I
got the irb error I did, but still would not have know why irb blocks
this method.

I hope this helps the cause, and thanks for your interest.

t.

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[Tom Cloyd]

You do know, however, that the state of Ruby's documentation on the
web is rather bad. Which creates faulty assumptions, as you've
noticed.

And yes, something like this is something a blog entry (or, more
generally speaking, a blog entry) can solve, since you more likely
than not aren't the first person to have this problem.

Unfortunately, the only way to get a reasonably up-to-date
documentation for Ruby is via Programming Ruby (and maybe The Ruby
Programming Language), which also provides usage examples. The free
edition of the Pickaxe is slightly out of date (as has been mentioned
elsewhere).

The trick is, that you are standing on the shoulder of giants. Tapping
into that, can make Ruby much more hassle free (and I've ran against a
wall when using Ruby's documentation myself, hence my fondness for the
Pickaxe).

-- Phillip Gawlowski

Agreed - with all. And I own a copy of Pickaxe 2nd ed., in marvelous
searchable PDF format (highly recommended). However, the to_yaml method
is not documented in the discussion of the Object class - it's not
reasonable to expect EVERYTHING to be covered, I'm sure.

An exhaustive search of the book reveals only that to_yaml_properties is
discussed at one point, and in the context it appears to be related to
the YAML standard library, BECAUSE a require is used, and what I was
recently taught (on this list) is that core library doesn't have to be
required, AND the online documentation says that to_yaml is core. With
the information I have, at this point, I'm not clever enough to think my
way out of this confusion.

Just wanted to make it clear that I did do a fair amount of due
diligence before bringing the problem here.

t.


--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[James Britt]

How are you supposed to know that to_yaml is not in ruby core but in the
standard library? I don't really know.

Yes; it is a good question.

Sadly, the rdoc/ri tool is brain-dead about mix-ins.

When I started using ruby some years

ago, I downloaded a version of the rdoc documentation from
www.ruby-doc.org which only included documentation for the core classes (that
is, those you can use without need to require some files), while documentation
for the standard library was in a separate package. Unfortunately, the
documentation you can find nowadays includes both core and standard library.

It appears that the Ruby source code includes .document files that
direct which source files should be processed by rdoc

What has happened is that there is no clear separation in the rdoc
settings between core classes and standard lib.

The Yaml source files get pulled in by rdoc along with several other
std-lib files, as well as core files. Rdoc stores what it finds and
emits an aggregate result. Since yaml alters core classes, the
resulting rdoc falsely shows Array, String, etc as having to_yaml
methods as if they were built into the original code. There is no
indication that those methods only exist if YAML is included.

This has the very unpleasant side effect of displaying together methods which
come from the core classes and methods which come from files in the standard
library (which should be required before using such methods). At any rate, at
the top of the page, just below the name of the class, there's a list of the
files which have been used to generate the documentation for the class. If a
method listed in the documentation doesn't seem to exist, try requiring those
files.

A useful tip, but a sad indication of rdoc's failings with mix-ins.

 

[Tim Hunter]

As far as I can see, the links to the 'Core documentation' on both www.ruby-
doc.org and http://www.ruby-lang.org/en/documentation/ point to the same
documentation, which sadly contains both the core and the standard library. As
you say, the standard library is also documented in its own section, which is
much more organized, and easy to use.

So it does. Thanks for pointing this out. It would be nice if some
talented Rubyist were to upgrade rdoc so that this didn't happen. Until
then I'll have to refer to my paper documentation when my memory fails
me. (Which it frequently does.)

 

[Dave Thomas]

Agreed - with all. And I own a copy of Pickaxe 2nd ed., in marvelous
searchable PDF format (highly recommended). However, the to_yaml
method is not documented in the discussion of the Object class -
it's not reasonable to expect EVERYTHING to be covered, I'm sure.

Tom:

(page numbers below are for the printed copy)

Page 758 is the description of the YAML standard library.

Because it's a standard library, you know you need to use require
(page 653). And the examples on the YAML page all show the use of
require.

I hadn't realized you owned a copy of the book--if I had, I could have
saved you time by pointing you at these pages.

Just to reiterate: to_yaml is not a method of the built-in Object
class. That's why it doesn't appear in the documentation of object.
When you do <rewquire 'yaml'>, that library _adds_ the method to object.


Dave Thomas

 

[Dave Thomas]

It appears that the Ruby source code includes .document files that
direct which source files should be processed by rdoc

What has happened is that there is no clear separation in the rdoc
settings between core classes and standard lib.

The Yaml source files get pulled in by rdoc along with several other
std-lib files, as well as core files. Rdoc stores what it finds and
emits an aggregate result. Since yaml alters core classes, the
resulting rdoc falsely shows Array, String, etc as having to_yaml
methods as if they were built into the original code. There is no
indication that those methods only exist if YAML is included.

James:

When you use all this stuff to build ruby-doc, why not override the
defaults so you can present the information differently?


Regards


Dave Thomas