Ruby Document

ruby-talk
1

Hi All,

I feel a little frustrated with Ruby’s documentation. I like the
companion book “The Pragmatic Programmer”. However, it is apparently not
good enough to be a online manual. May be because I’m completely new to
Ruby. I just feel lost. The following is some of my questions. They are
all related to Ruby’s syntax. Please note that I am not currently
interested in the logic of the following example, just simply what the
syntax mean.

  1. In httpmail-0.3/ruby/dav.rb:

  • class Unlock < ::Net::NetPrivate::HTTPRequest
    Q: what is the :: before Net mean?

  • define_http_method_interface :PropFind, true, true
    Q: what is the : before PropFind mean? From the menu I know that I can
    use attr_reader. It seems to me that attr_reader is a special directive.
    But from this example, define_http_method_interface seems a method. So I
    guess attr_reader is defined as a method in Object? Anyway, what is the
    colon before a variable mean?

  1. In \ruby\lib\ruby\1.6\net\http.rb:

  • class << self
    Q: difference between << and < in class definition?

  • def HTTP.get( addr, path, port = nil )
    Q: difference between HTTP.get and HTTP#get? I vaguely know there are a
    notation of class method and instance method, but which is which? and
    in a class, can I just say def get(…) without HTTP. ?

I have a lot more similar questions. When I read the html help file, I
can not use search to find any information!

Could anyone please tell me how can I effectively find information about
the GRAMMA of ruby? And please, if you know, explain the above syntax to
me. Thanks a lot!!!

Shannon

2

- class Unlock < ::Net::NetPrivate::HTTPRequest
Q: what is the :: before Net mean?

This mean that Net is a top level constant

- define_http_method_interface :PropFind, true, true
Q: what is the : before PropFind mean?

To say that it's a symbol

- class << self
Q: difference between << and < in class definition?

<< to make reference to the singleton class associated with this object

< to specify an inheritence

- def HTTP.get( addr, path, port = nil )
Q: difference between HTTP.get and HTTP#get? I vaguely know there are a
notation of class method and instance method, but which is which? and

HTTP::get is a class method

in a class, can I just say def get(...) without HTTP. ?

Yes, for example

   class HTTP
      class << self
         def get(addr, path, port = nil)
         end
      end
   end

Guy Decoux

3

Shannon Fang xrfang@hotmail.com writes:

I feel a little frustrated with Ruby’s documentation. I like the
companion book “The Pragmatic Programmer”. However, it is apparently not
good enough to be a online manual. May be because I’m completely new to
Ruby. I just feel lost. The following is some of my questions. They are
all related to Ruby’s syntax. Please note that I am not currently
interested in the logic of the following example, just simply what the
syntax mean.

You might want to look at the Window’s help-file version of the book:
I believe that it is searchable. In the meantime, all these questions
(except the last) are answered in the chapter "The Ruby Language).

  1. In httpmail-0.3/ruby/dav.rb:
  • class Unlock < ::Net::NetPrivate::HTTPRequest
    Q: what is the :: before Net mean?

Page 214 “Scope of constants and variables”

  • define_http_method_interface :PropFind, true, true
    Q: what is the : before PropFind mean? From the menu I know that I can
    use attr_reader. It seems to me that attr_reader is a special directive.
    But from this example, define_http_method_interface seems a method. So I
    guess attr_reader is defined as a method in Object? Anyway, what is the
    colon before a variable mean?

It represents a literal of type symbol (page 207)

  1. In \ruby\lib\ruby\1.6\net\http.rb:
  • class << self
    Q: difference between << and < in class definition?

It defines a class based on the object ‘self’, which in a class
definition is the class itself (page 233, 243)

  • def HTTP.get( addr, path, port = nil )
    Q: difference between HTTP.get and HTTP#get? I vaguely know there are a
    notation of class method and instance method, but which is which? and
    in a class, can I just say def get(…) without HTTP. ?

Its in the notation convention section of the preface: A#b denotes an
instance method ‘b’ of class ‘A’.

I have a lot more similar questions. When I read the html help file,
I can not use search to find any information!

Could anyone please tell me how can I effectively find information about
the GRAMMA of ruby? And please, if you know, explain the above syntax to
me. Thanks a lot!!!

I don’t think the grammar alone will help you too much. I recommend
reading at least chapter 18 (The Ruby Language) all the way through:
it should answer most of your questions.

Regards

Dave

4

I feel a little frustrated with Ruby’s documentation. I like the
companion book “The Pragmatic Programmer”. However, it is apparently not
good enough to be a online manual. May be because I’m completely new to
Ruby.

I am completely new to Ruby, and I echo your frustration. There should be
a book intended to introduce Ruby to newbies.

I’d also like to see a book for people who don’t know OO. I’ve programmed
for several years, but I don’t know OO. Ruby is my first OO language. I
find that the current book jumps into classes before it’s covered the
basics like flow-control, functions and variables. I still figured it
out, but it was harder than it could have been. It also starts on
iterators before explaining more basic syntas. The ‘Class#method’ syntax
and a couple other things are not explained either.

There could be a chapter or two for people who simply have never
programmed before. There’s nothing wrong with starting classes sooner
than you would in another language, but it still should come after more
basic things.

Just a thought.

Daniel.

5

[questions]

Hi Shannon,

I haven’t studied all the answers, but I know that some/most/all (not sure
which) of the questions are answered in the FAQ. Check it out; you’ll learn a
lot from it. And I’d really appreciate feedback on it so it can answer your
questions better.

Cheers,
Gavin

···

From: “Shannon Fang” xrfang@hotmail.com

6

Hi –

I feel a little frustrated with Ruby’s documentation. I like the
companion book “The Pragmatic Programmer”. However, it is apparently not
good enough to be a online manual. May be because I’m completely new to
Ruby.

I am completely new to Ruby, and I echo your frustration. There should be
a book intended to introduce Ruby to newbies.

Have you looked at “Teach Yourself Ruby in 21 Days” (from Sams)?

I’d also like to see a book for people who don’t know OO. I’ve programmed
for several years, but I don’t know OO. Ruby is my first OO language. I
find that the current book jumps into classes before it’s covered the
basics like flow-control, functions and variables. I still figured it
out, but it was harder than it could have been. It also starts on
iterators before explaining more basic syntas. The ‘Class#method’ syntax
and a couple other things are not explained either.

There could be a chapter or two for people who simply have never
programmed before. There’s nothing wrong with starting classes sooner
than you would in another language, but it still should come after more
basic things.

To go from never having programmed, to a full understanding of
everything in the Pickaxe book, would require more than you could get
from a couple of introductory chapters added to the book. However…
the idea of having first-time programmer books that use Ruby is a good
one. I believe there’s at least one such book among the 23 Japanese
books on Ruby, and I know there’s been discussion of doing such a
thing in English (as well as related things, like a book along those
lines specifically targeted at children), but I’m not sure who’s
working on what right now.

David

···

On Sun, 1 Dec 2002, Daniel Carrera wrote:

–
David Alan Black
home: dblack@candle.superlink.net
work: blackdav@shu.edu
Web: http://pirate.shu.edu/~blackdav

7

Daniel Carrera dcarrera@math.umd.edu writes:

I am completely new to Ruby, and I echo your frustration. There should be
a book intended to introduce Ruby to newbies.

I agree (and I believe there might be one in the works)

I’d also like to see a book for people who don’t know OO. I’ve programmed
for several years, but I don’t know OO. Ruby is my first OO language. I
find that the current book jumps into classes before it’s covered the
basics like flow-control, functions and variables. I still figured it
out, but it was harder than it could have been. It also starts on
iterators before explaining more basic syntas.

Agreed - it assumes that you’ve programmed in some other language. I
certainly wouldn’t recommend the PickAxe if you’ve never coded before.

The ‘Class#method’ syntax and a couple other things are not
explained either.

To be fair, it’s there in the section on notation conventions.

There could be a chapter or two for people who simply have never
programmed before. There’s nothing wrong with starting classes
sooner than you would in another language, but it still should come
after more basic things.

Ah, but in Ruby, classes and objects are the most basic thing :slight_smile:

It was an interesting challenge trying to come up with a flow for that
book. We really wanted to cover the OO stuff in the very first
chapter, because we really dislike books that teach an OO language but
ignore classes and objects until chapter 20. In the end, we couldn’t
quite do it, and had to add the quick intro chapter.

However, if I was writing as Ruby for Folks Who Have Never Programmed
Before book, I’d still start with the OO stuff. I just might not do it
using code examples. We’re surrounded in our daily lives with objects
and classes, and it seems to be a very natural to teach computing by
drawing on that knowledge.

However, as you’re said, the PickAxe is not that book.

Cheers

Dave

8

In my experience, starting to learn programming from (almost) zero
using Ruby, it has worked so far to start with the pickaxe book and
read and work through it from beginning to end. Then I read and worked
through Teach Yourself Ruby in 21 Days. Then I went back to the
pickaxe book and re-read and worked through the parts that are most
relevant to me now. I found that my understanding of the pickaxe book
was much much deeper the second time through. I still have work to do
in using both books to teach myself more.

For “big-picture” object-oriented concepts, I have started with UML
Explained and UML Distilled. I don’t know if these two were the right
way to go, but I know I will understand them better over time. If
someone can recommend additional “big-picture” books, that would be
great. So far, my possible candidates are the Larman book and Design
Patterns Explained, but I’m sure there are others. The problem with
all of these books, however, is that when they give concrete
programming examples they use Java (or the like) and not Ruby!

I think the two possible upcoming books on Ruby for the absolute
beginner and Ruby for children are extraordinarily good ideas and I
hope to see them soon.

By the way, I love Ruby!

···

On Saturday, November 30, 2002, at 01:40 PM, dblack@candle.superlink.net wrote:

Hi –

On Sun, 1 Dec 2002, Daniel Carrera wrote:

I feel a little frustrated with Ruby’s documentation. I like the
companion book “The Pragmatic Programmer”. However, it is apparently
not
good enough to be a online manual. May be because I’m completely new
to
Ruby.

I am completely new to Ruby, and I echo your frustration. There
should be
a book intended to introduce Ruby to newbies.

Have you looked at “Teach Yourself Ruby in 21 Days” (from Sams)?

I’d also like to see a book for people who don’t know OO. I’ve
programmed
for several years, but I don’t know OO. Ruby is my first OO
language. I
find that the current book jumps into classes before it’s covered the
basics like flow-control, functions and variables. I still figured it
out, but it was harder than it could have been. It also starts on
iterators before explaining more basic syntas. The ‘Class#method’
syntax
and a couple other things are not explained either.

There could be a chapter or two for people who simply have never
programmed before. There’s nothing wrong with starting classes sooner
than you would in another language, but it still should come after
more
basic things.

To go from never having programmed, to a full understanding of
everything in the Pickaxe book, would require more than you could get
from a couple of introductory chapters added to the book. However…
the idea of having first-time programmer books that use Ruby is a good
one. I believe there’s at least one such book among the 23 Japanese
books on Ruby, and I know there’s been discussion of doing such a
thing in English (as well as related things, like a book along those
lines specifically targeted at children), but I’m not sure who’s
working on what right now.

David

–
David Alan Black
home: dblack@candle.superlink.net
work: blackdav@shu.edu
Web: http://pirate.shu.edu/~blackdav

9

To go from never having programmed, to a full understanding of
everything in the Pickaxe book, would require more than you could get
from a couple of introductory chapters added to the book. However…
the idea of having first-time programmer books that use Ruby is a good
one. I believe there’s at least one such book among the 23 Japanese
books on Ruby, and I know there’s been discussion of doing such a
thing in English (as well as related things, like a book along those
lines specifically targeted at children), but I’m not sure who’s
working on what right now.

I’ve been working on a beginning Ruby book that tries not to make too many
assumptions other than at least a working knowledge of basic programming
concepts (i.e., the reader should know what a loop is, or what an array is).
There is a fair amount of space devoted to explaining OO programming and
design concepts.

Unfortunately, the market for Ruby books appears rather poor, or at least
poor enough to put the future of my book in jeopardy.

James Britt

···

David

–
David Alan Black
home: dblack@candle.superlink.net
work: blackdav@shu.edu
Web: http://pirate.shu.edu/~blackdav