Standard library documentation

ruby-talk
1

An example of a puzzle I've run into many times before -

I'm wanting to use the readline module. I go to http://www.gotapi.com/rubystdlib, and look it up, and get a page that tells me essentially nothing that I can use. THIS is documentation? I don't see the point.

I don't see where else to go to find out how to use this module. I seem to be missing some essential resource.

Can anyone help?

t.

···

--

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

2

Tom Cloyd wrote:

An example of a puzzle I've run into many times before -

I'm wanting to use the readline module. I go to
Homepage - Got API - All about APIs, and look it up, and get a page that
tells me essentially nothing that I can use. THIS is documentation? I
don't see the point.

I don't see where else to go to find out how to use this module. I seem
to be missing some essential resource.

Can anyone help?

I'm with you. Totally pathetic.

···

--
Posted via http://www.ruby-forum.com/\.

3

Tom Cloyd wrote:

An example of a puzzle I've run into many times before -

I'm wanting to use the readline module. I go to Homepage - Got API - All about APIs, and look it up, and get a page that tells me essentially nothing that I can use. THIS is documentation? I don't see the point.

I don't see where else to go to find out how to use this module. I seem to be missing some essential resource.

Can anyone help?

t.

OK, looking here -
http://adam.blog.heroku.com/past/2008/1/22/using_rubys_readline_library/
I read "There appears to be no documentation <http://ruby-doc.org/stdlib/libdoc/readline/rdoc/index.html&gt; for Ruby's readline support. What's worse, it's written in C, so you can't (easily) read the source to find out its interface." Well, that sure leave ME out in the cold. Adam's explanation there is, well, obscure.

I'm playing with various ways of using readline, like

require 'readline'
puts 'test under way'
opt = readline( "=--> \n")
puts( opt)

Nothing works, so far. The code above seems to stop at line 2. Or maybe it's 3, but there's no prompt output. We surely never get to line 4.

So...tell me please, what exactly is the point of making undocumented software available? I'm never understood this. Seems irresponsible, or lazy, or thoughtless. In my case, I'd use this, but...I can't, so...done for now. Not exactly a triumph for anyone, I'd say.

What do other people do in this situation? I'm cruising Google, and it's a wasteland on this issue, so far. All I'm doing is wasting time here. Sad.

t.

···

--

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

4

# I don't see where else to go to find out how to use this
# module. I seem to be missing some essential resource.

1 in gotapi, i found it under core classes (i just type readline under search, and it gave me the hints)

2 also in noobkit (http://www.noobkit.com/show/ruby/ruby/ruby-core/kernel/readline.html) i like noobkit since it shows the source and you can also add comments

3 qri can also help

botp@pc4all:~$ qri kernel.readline
-------------------------------------------------------- Kernel#readline
     readline(separator=$/) => string

···

From: Tom Cloyd [mailto:tomcloyd@comcast.net]
------------------------------------------------------------------------
     Equivalent to Kernel::gets, except readline raises EOFError at end
     of file.

botp@pc4all:~$ qri readline
------------------------------------------------------ Multiple choices:

     DEBUGGER__::Context#readline, IO#readline, IRB::Locale#readline,
     Kernel#readline, StringIO#readline, Zlib::GzipReader#readline
botp@pc4all:~$ qri kernel.readline
-------------------------------------------------------- Kernel#readline
     readline(separator=$/) => string
------------------------------------------------------------------------
     Equivalent to Kernel::gets, except readline raises EOFError at end
     of file.

4 ruby-doc can help too

http://www.ruby-doc.org/core/classes/Kernel.html#M005997

there are other references on ruby but they are scattered. there's even one that's very interactive, you can type/edit/execute the examples given.

the book of matz and flanagan is also a great reference, but you'll have to buy it.

kind regards -botp

5

Tom Cloyd wrote:

An example of a puzzle I've run into many times before -

I'm wanting to use the readline module. I go to Homepage - Got API - All about APIs, and look it up, and get a page that tells me essentially nothing that I can use. THIS is documentation? I don't see the point.

I don't see where else to go to find out how to use this module. I seem to be missing some essential resource.

First hit on google "ruby require readline" gives this code:

require "readline"
include Readline

while line = readline("Prompt> ", TRUE)
   print line, "\n"
end

···

--
       vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

6

# I'm playing with various ways of using readline, like

i see you want readline's readline http://tiswww.case.edu/php/chet/readline/rltop.html#TOCDocumentation

botp@botp-desktop:~$ cat /usr/local/src/ruby/ext/readline/README
Extension for GNU Readline Library

Example:

  require "readline"
  include Readline

  line = readline("Prompt> ", true)

[Readline]

<module function>

readline(prompt, add_history=nil)

  Reads one line with line editing. The inputted line is added to the
  history if add_history is true.

<class methods>

completion_proc = proc

  Specifies a Proc object to determine completion behavior. It
  should take input-string, and return an array of completion
  candidates.

completion_proc

  Returns the completion Proc object.

completion_case_fold = bool

  Sets whether or not to ignore case on completion.

completion_case_fold

  Returns true if completion ignores case.

completion_append_character = char

  Specifies a character to be appended on completion.
  Nothing will be appended if an empty string ("") or nil is
  specified.

completion_append_character

  Returns a string containing a character to be appended on
  completion. The default is a space (" ").

vi_editing_mode

  Specifies VI editing mode.

emacs_editing_mode

  Specifies Emacs editing mode.

HISTORY

The history buffer. It behaves just like an array.

~$

irb makes a lot of use of readline, so you may want to take that as a big example :wink:

kind regards -botp

···

From: Tom Cloyd [mailto:tomcloyd@comcast.net]

7

# I'm playing with various ways of using readline, like

···

From: Tom Cloyd [mailto:tomcloyd@comcast.net]
#
# require 'readline'
# puts 'test under way'
# opt = readline( "=--> \n")
# puts( opt)
#
# Nothing works, so far. The code above seems to stop at line
# 2. Or maybe it's 3, but there's no prompt output.
# We surely never get to line 4.

that is because, the line

opt = readline( "=--> \n") will call ruby's Kernel.readline and not readline's readline (if i may say that ;-). So, what is happening is that ruby will treat "=--> \n" not as a prompt, but as your input ender, ergo it is waiting for the string "=--> \n" wc you never type obviously.

you really want

opt = Readline::readline( "=--> \n")

Eg,

botp@pc4all:~$ cat test.rb
require 'readline'
puts 'test under way'
opt = Readline::readline( "=-->\n")
puts( opt)

botp@pc4all:~$ ruby test.rb
test under way
=-->
is this ok?
is this ok?
botp@pc4all:~$

kind regards -botp

8

Peña wrote:

From: Tom Cloyd [mailto:tomcloyd@comcast.net] # I'm playing with various ways of using readline, like

i see you want readline's readline The GNU Readline Library

botp@botp-desktop:~$ cat /usr/local/src/ruby/ext/readline/README
Extension for GNU Readline Library

Example:

  require "readline"
  include Readline

  line = readline("Prompt> ", true)

[Readline]

<module function>

readline(prompt, add_history=nil)

  Reads one line with line editing. The inputted line is added to the
  history if add_history is true.

<class methods>

completion_proc = proc

  Specifies a Proc object to determine completion behavior. It
  should take input-string, and return an array of completion
  candidates.

completion_proc

  Returns the completion Proc object.

completion_case_fold = bool

  Sets whether or not to ignore case on completion.

completion_case_fold

  Returns true if completion ignores case.

completion_append_character = char

  Specifies a character to be appended on completion.
  Nothing will be appended if an empty string ("") or nil is
  specified.

completion_append_character

  Returns a string containing a character to be appended on
  completion. The default is a space (" ").

vi_editing_mode

  Specifies VI editing mode.

emacs_editing_mode

  Specifies Emacs editing mode.

HISTORY

The history buffer. It behaves just like an array.

~$

irb makes a lot of use of readline, so you may want to take that as a big example :wink:

kind regards -botp

Pena,

Helpful. Thanks. I can see that part of the problem is that isn't just one "readline". There appears to be a whole herd of 'em. Hop on the wrong one and you end up in a very strange place. Whoever designed this corner of the universe might consider laying off the beer for a while. Please.

t.

···

--

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

9

Peña wrote:

From: Tom Cloyd [mailto:tomcloyd@comcast.net] # I'm playing with various ways of using readline, like
#
# require 'readline'
# puts 'test under way'
# opt = readline( "=--> \n")
# puts( opt)
# # Nothing works, so far. The code above seems to stop at line # 2. Or maybe it's 3, but there's no prompt output. # We surely never get to line 4.

that is because, the line

opt = readline( "=--> \n") will call ruby's Kernel.readline and not readline's readline (if i may say that ;-). So, what is happening is that ruby will treat "=--> \n" not as a prompt, but as your input ender, ergo it is waiting for the string "=--> \n" wc you never type obviously.

you really want

opt = Readline::readline( "=--> \n")

Eg,

botp@pc4all:~$ cat test.rb
require 'readline'
puts 'test under way'
opt = Readline::readline( "=-->\n")
puts( opt)

botp@pc4all:~$ ruby test.rb
test under way
=-->
is this ok?
botp@pc4all:~$

kind regards -botp

Thanks. This is good. I now know more about "readline" than I thought it possible to know. Another surprising Ruby adventure.

Thank for you patience with my great ignorance!

t.

···

--

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

10

# Whoever designed this corner of the universe might consider
# laying off the beer for a while.

some things to remember when coding ruby

1 object-oriented (object first before methods )

2 method lookups (there may be many objects w the same method. If you don't specify the object, you need to know the order of the lookups so you'll know wc object will be called first)

and btw, whenever i have a problem w the documentation, i always remember Guy Decoux's words,

documentation is just for anglois :slight_smile: -Guy Decoux (http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/132690)

kind regards -botp

···

From: Tom Cloyd [mailto:tomcloyd@comcast.net]

11

# Thank for you patience with my great ignorance!

you're welcome. and pls look at the bright side, ignorance is bliss http://www.aish.com/seminars/matrix/ignorance_is_bliss.asp

i'm ignorant in ruby too, but i'm happy w it. It's the happiness and fun that is important to me :wink:

kind regards -botp

···

From: Tom Cloyd [mailto:tomcloyd@comcast.net]

12

Tom Cloyd wrote:

Thanks. This is good. I now know more about "readline" than I thought it possible to know. Another surprising Ruby adventure.

Can you write something up and post it someplace for others?

Maybe submit a patch to the source so it becomes part of the documentation?

···

--
James Britt

"Serious engineering is only a few thousand years old. Our attempts at
deliberately producing very complex robust systems are immature at best."
  - Gerald Jay Sussman

13

Peña wrote:

From: Tom Cloyd [mailto:tomcloyd@comcast.net] # Whoever designed this corner of the universe might consider # laying off the beer for a while.

some things to remember when coding ruby

1 object-oriented (object first before methods )

2 method lookups (there may be many objects w the same method. If you don't specify the object, you need to know the order of the lookups so you'll know wc object will be called first)

and btw, whenever i have a problem w the documentation, i always remember Guy Decoux's words,

documentation is just for anglois :slight_smile: -Guy Decoux (http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/132690\)

kind regards -botp

AHA! That explains my penchant for documentation. I actually want to accomplish work. For a true son of Gaul, it's not what you do, but how that counts. Matz, of course, often manage to get a lot done AND look good doing it.
t.

···

--

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

14

James Britt wrote:

Tom Cloyd wrote:

Thanks. This is good. I now know more about "readline" than I thought it possible to know. Another surprising Ruby adventure.

Can you write something up and post it someplace for others?

Maybe submit a patch to the source so it becomes part of the documentation?

Well, James, I know a fair challenge when I see one. I keep decent notes on all my Ruby learning, and this is no exception, so I've already got a start on this. At this point I have no idea how to "submit a patch to the source", but I'll investigate. This will all be good learning for me. Thanks for the push.

~ t.

···

--

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

15

# I actually want to accomplish work.

here's my psycho on ruby and docs. Almost all commonly used methods/classes in ruby are documented.

If a certain method/class has zero doc, it's probably because
1 it's not used often
2 or deprecated
3 or too new
4 or there's a better ruby way

if you ever you get to the point that your ruby coding is getting discouraging/tormenting, then by all means, stop, it's not supposed to be that way (because of the ruby way is fun :). Open your email asap, and post your problem and a pseudocode snippet of what you want to accomplish to the ruby ml... I assure you, you'll get very brilliant answers from this community... a lot better than google :wink:

kind regards -botp

···

From: Tom Cloyd [mailto:tomcloyd@comcast.net]

16

It's easy: Ruby Documentation Submission Guidelines
If anything of it is unclear, just ask.

···

On Tue, Mar 18, 2008 at 8:10 AM, Tom Cloyd <tomcloyd@comcast.net> wrote:

James Britt wrote:
> Maybe submit a patch to the source so it becomes part of the
> documentation?
>
>
Well, James, I know a fair challenge when I see one. I keep decent notes
on all my Ruby learning, and this is no exception, so I've already got a
start on this. At this point I have no idea how to "submit a patch to
the source", but I'll investigate. This will all be good learning for
me. Thanks for the push.

17

Peña wrote:

From: Tom Cloyd [mailto:tomcloyd@comcast.net] # I actually want to accomplish work.

here's my psycho on ruby and docs. Almost all commonly used methods/classes in ruby are documented.

If a certain method/class has zero doc, it's probably because
1 it's not used often 2 or deprecated 3 or too new
4 or there's a better ruby way

if you ever you get to the point that your ruby coding is getting discouraging/tormenting, then by all means, stop, it's not supposed to be that way (because of the ruby way is fun :). Open your email asap, and post your problem and a pseudocode snippet of what you want to accomplish to the ruby ml... I assure you, you'll get very brilliant answers from this community... a lot better than google :wink:

kind regards -botp

I'm finding that out. This is an incredible resource. It's already saved me about 5 times in the last 3 weeks.

Thanks for your thoughts and support.

Tom

···

--

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

18

Jano Svitok wrote:

···

On Tue, Mar 18, 2008 at 8:10 AM, Tom Cloyd <tomcloyd@comcast.net> wrote:
  

James Britt wrote:
> Maybe submit a patch to the source so it becomes part of the
> documentation?
>
Well, James, I know a fair challenge when I see one. I keep decent notes
on all my Ruby learning, and this is no exception, so I've already got a
start on this. At this point I have no idea how to "submit a patch to
the source", but I'll investigate. This will all be good learning for
me. Thanks for the push.
    
It's easy: http://ruby-doc.org/documentation-guidelines.html
If anything of it is unclear, just ask.

Ah. thank you. I figured something like this existed, and made a note to go looking for it, as soon as I begin this little project...in a few hours. Thanks very much.

~ t.

--

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