Standard library documentation

tbcox23 · March 15, 2008, 7:17am

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 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 15, 2008, 7:58am

Tom C. wrote:

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?

I’m with you. Totally pathetic.

tbcox23 · March 15, 2008, 8:14am

Tom C. wrote:

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 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 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 15, 2008, 8:18am

From: Tom C. [mailto:[email protected]]

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

 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

tbcox23 · March 15, 2008, 8:49am

Tom C. wrote:

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.

First hit on google “ruby require readline” gives this code:

require “readline”
include Readline

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

tbcox23 · March 15, 2008, 9:00am

Peña wrote:

Returns true if completion ignores case.
completion. The default is a space (" ").
HISTORY

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 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 15, 2008, 8:45am

From: Tom C. [mailto:[email protected]]

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

i see you want readline’s readline

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]

readline(prompt, add_history=nil)

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

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

kind regards -botp

tbcox23 · March 15, 2008, 9:20am

Peña wrote:

We surely never get to line 4.

Eg,
is this ok?
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 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 15, 2008, 9:26am

From: Tom C. [mailto:[email protected]]

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 -Guy Decoux
(http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/132690)

kind regards -botp

tbcox23 · March 15, 2008, 9:34am

From: Tom C. [mailto:[email protected]]

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

kind regards -botp

tbcox23 · March 15, 2008, 9:02am

From: Tom C. [mailto:[email protected]]

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?
is this ok?
botp@pc4all:~$

kind regards -botp

tbcox23 · March 15, 2008, 10:36am

From: Tom C. [mailto:[email protected]]

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

kind regards -botp

tbcox23 · March 15, 2008, 11:31am

Peña wrote:

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

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 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 15, 2008, 10:55pm

Tom C. 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 B.

“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

tbcox23 · March 18, 2008, 8:11am

James B. 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.

~ 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 15, 2008, 10:01am

Peña wrote:

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

documentation is just for anglois -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 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 18, 2008, 10:31am

Jano S. wrote:

the source", but I’ll investigate. This will all be good learning for
me. Thanks for the push.

It’s easy: Ruby Documentation Submission Guidelines
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 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 18, 2008, 8:24am

On Tue, Mar 18, 2008 at 8:10 AM, Tom C. [email protected] wrote:

James B. 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: Ruby Documentation Submission Guidelines
If anything of it is unclear, just ask.

Standard library documentation

I don’t see where else to go to find out how to use this

module. I seem to be missing some essential resource.

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

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

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

We surely never get to line 4.

Whoever designed this corner of the universe might consider

laying off the beer for a while.

Thank for you patience with my great ignorance!

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.

I actually want to accomplish work.

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

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