More fun with C

ruby-talk
1

Keep us informed just how bad things are, Eric.
People really appreciate it !!

daz

Haha, I'm not sure whether you're serious or not, but the readme.ext and pickaxe book are not adequate documentation. They'll get you started, but there are quite a few API's that are not even mentioned at all, or if so only briefly. An example would be the -1 calling sequence, which the readme.ext describes, but it does not mention anything at all about formatting the args until the appendix. When I think of documentation, I think of listing a description for every API that there is telling you everything you need to know when using it. I'm not trying to complain; obviously C extensions aren't a necessity for ruby, it's just that trial and error is not a fun way to make a simple program.

···

---------------------------------
Yahoo! FareChase - Search multiple travel sites in one click.

2

Haha, I'm not sure whether you're serious or not, but the readme.ext and
pickaxe book are not adequate documentation.

The latter's purpose was never intended solely to document the C extension
API for Ruby. The former is a convenience file that doesn't get much
attention.

They'll get you started, but there are quite a few API's that are not
even mentioned at all, or if so only briefly.

Not that many that you can actually call from a C extension, although tons
of internal ones for Ruby's own use only.

An example would be the -1 calling sequence, which the readme.ext
describes, but it does not mention anything at all about formatting
the args until the appendix.

So... it does describe it? I'm confused.

At any rate, page 292 of Programming Ruby, 2nd Edition describes what you
are referring to in blindingly insightful detail. See the section entitled
"API: Defining Methods".

When I think of documentation, I think of listing a description for
every API that there is telling you everything you need to know when
using it.

Certainly, the C extension docs are incomplete. No one is arguing against
that sentiment. But Ruby itself is pretty small and easily grepped for
things. (since they use the utterly repugnant C style that has function
names starting at the beginnings of lines) For example:

adidas~/code/ruby-1.8.3> grep -rn '^rb_thread_select' *
eval.c:10682:rb_thread_select(max, read, write, except, timeout)
adidas~/code/ruby-1.8.3>

Great for grepping, bad for writing. But, since you're not ruby-core, that
won't really be an issue.

I'm not trying to complain;

You are.

obviously C extensions aren't a necessity for ruby,

Sometimes they are.

it's just that trial and error is not a fun way to make a simple program.

C extensions aren't supposed to be for simple programs. That's what Ruby
is for :wink:

···

On Sun, Nov 13, 2005 at 01:19:35PM +0900, Eric Hofreiter wrote:

--
Toby DiPasquale

3

Eric Hofreiter just won't give up:

An example would be the -1 calling sequence, which the readme.ext
describes, but it does not mention anything at all about formatting
the args until the appendix.

<Programming Ruby I>

In some of the function definitions that follow, the parameter argc
specifies how many arguments a Ruby method takes.
It may have the following values.

   argc Function prototype

···

----------------------------------------------------------------------
   0..17 VALUE func(VALUE self, VALUE arg...)
           The C function will be called with this many actual arguments.

      -1 VALUE func(int argc, VALUE *argv, VALUE self)
           The C function will be given a variable number of arguments
           passed as a C array.

      -2 VALUE func(VALUE self, VALUE args)
           The C function will be given a variable number of arguments
           passed as a Ruby array.
   ----------------------------------------------------------------------
</>

When I think of documentation, I think of [...]

Document one API call that you had to work out for yourself
and post it here, and well see. Thanks.

I'm not trying to complain [...]

Thanks for purging that idea from our heads :wink:

daz