Argh! more undocumented mysteries: to_yaml

tbcox23 · March 16, 2008, 2:57pm

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 C., MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< [email protected] >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)

tbcox23 · March 16, 2008, 3:11pm

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.

2008/3/16, Tom C. [email protected]:

tbcox23 · March 16, 2008, 3:14pm

On Sunday 16 March 2008, Tom C. wrote:

    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

tbcox23 · March 16, 2008, 3:16pm

Tom C. wrote:

   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 G.

tbcox23 · March 16, 2008, 3:35pm

Tom C. wrote:

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:

Object.methods.sort
=> [“<”, “<=”, “<=>”, “==”, “===”, “=~”, “>”, “>=”, “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 G.

tbcox23 · March 16, 2008, 4:59pm

Stefano C. wrote:

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
(Programming Ruby: The Pragmatic Programmer's Guide) 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.

tbcox23 · March 16, 2008, 5:00pm

On Mar 16, 2008, at 8:56 AM, Tom C. wrote:

  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 T.

tbcox23 · March 16, 2008, 5:07pm

On Mar 16, 2008, at 9:18 AM, Tom C. wrote:

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 T.

tbcox23 · March 16, 2008, 3:19pm

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.

Mateusz T. wrote:

for the total lack of documentation in each of the gazillion instances

t.

–

–

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

tbcox23 · March 16, 2008, 5:09pm

Phillip G. wrote:

http://www.ruby-doc.org/core/classes/Object.html#M000348 of all
You don’t use the tools Ruby/irb gives you:
“method”, “method_defined?”, “methods”, “module_eval”, “name”, “new”,
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 G.

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 C., MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< [email protected] >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)

tbcox23 · March 16, 2008, 5:18pm

Dave T. wrote:

utility and you have the yaml library installed on your local machine.

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 C., MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< [email protected] >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)

tbcox23 · March 16, 2008, 5:12pm

Stefano C. wrote:

NoMethodError: undefined method `to_yaml’ for [2, 5, 3, 6, “abc”]:Array
Yes. to_yaml is defined in the yaml.rb file, so you need to require it before
www.ruby-doc.org which only included documentation for the core classes (that
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 C., MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< [email protected] >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)

tbcox23 · March 16, 2008, 5:28pm

Tom C. wrote:

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 P.ming
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 G.

tbcox23 · March 16, 2008, 5:31pm

Dave T. wrote:

NoMethodError: undefined method `to_yaml’ for [2, 5, 3, 6, “abc”]:Array
As others have explained, to_yaml is not a built-in method. It is

Dave T.

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):

go to RDoc Documentation
in the middle panel, select the Object class.
scroll down to Methods, and find the to_yaml method
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 C., MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< [email protected] >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)

tbcox23 · March 16, 2008, 5:42pm

Phillip G. wrote:

the ruby core documentation. If I can’t trust what it says about the
than not aren’t the first person to have this problem.
Pickaxe).

– Phillip G.

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 C., MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< [email protected] >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)

tbcox23 · March 16, 2008, 5:19pm

On Sunday 16 March 2008, Tim H. wrote:

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

tbcox23 · March 16, 2008, 5:50pm

Stefano C. wrote:

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.

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.)

tbcox23 · March 16, 2008, 5:49pm

Stefano C. wrote:

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.

–
James B.

“Inside every large system there’s a small system trying to get out”.
- Chet Hendrickson

tbcox23 · March 16, 2008, 5:54pm

On Mar 16, 2008, at 11:37 AM, Tom C. wrote:

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 T.

tbcox23 · March 16, 2008, 5:56pm

On Mar 16, 2008, at 11:47 AM, James B. wrote:

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 T.