standard library documentation

[Tom Cloyd]

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
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[7stud --]

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.

 

[Tom Cloyd]

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.

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

 

[Peña, Botp]

From: Tom Cloyd [mailto:[email protected]]=20
# I don't see where else to go to find out how to use this=20
# 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=3D$/) =3D> 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=3D$/) =3D> 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

 

[Peña, Botp]

From: Tom Cloyd [mailto:[email protected]]=20
# 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 =3D readline("Prompt> ", true)

[Readline]

<module function>

readline(prompt, add_history=3Dnil)

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

<class methods>

completion_proc =3D 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 =3D bool

Sets whether or not to ignore case on completion.

completion_case_fold

Returns true if completion ignores case.

completion_append_character =3D 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

 

[Joel VanderWerf]

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

 

[Tom Cloyd]

From: Tom Cloyd [mailto:[email protected]]
# 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

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
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[Peña, Botp]

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

that is because, the line

opt =3D readline( "=3D--> \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 "=3D--> \n" not as a prompt, but as your input =
ender, ergo it is waiting for the string "=3D--> \n" wc you never type =
obviously.

you really want

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


Eg,

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

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


kind regards -botp

 

[Tom Cloyd]

From: Tom Cloyd [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

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
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[Peña, Botp]

From: Tom Cloyd [mailto:[email protected]]=20
# Whoever designed this corner of the universe might consider=20
# laying off the beer for a while.=20

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

 

[Peña, Botp]

From: Tom Cloyd [mailto:[email protected]]=20
# 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

 

[Tom Cloyd]

From: Tom Cloyd [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

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
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[Peña, Botp]

From: Tom Cloyd [mailto:[email protected]]=20
# I actually want to accomplish work.=20

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

If a certain method/class has zero doc, it's probably because
1 it's not used often=20
2 or deprecated=20
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

 

[Tom Cloyd]

From: Tom Cloyd [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

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
<< (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]

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

 

[Tom Cloyd]

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
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

[Jano Svitok]

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.

 

[Tom Cloyd]

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
<< (e-mail address removed) >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~