Re: PDD 2, vtables

Front page | perl.perl6.internals | Postings from February 2001

From:

Tim Bunce

Date:

February 6, 2001 03:27

Subject:

Re: PDD 2, vtables

Message ID:

20010206112657.J3454@ig.co.uk

[First off: I've not really been paying attention so forgive me if I'm
being dumb here.  And many thanks for helping to drive this forwards.]

On Mon, Feb 05, 2001 at 05:14:44PM -0500, Dan Sugalski wrote:
> 
> =head2 Core datatypes
> 
> For ease of use, we define the following semi-abstract data types

Probably worth stating upfront that it'll be easy to add new types
to avoid people argusing for their favorite type to be added here.

> =item INT
> =item NUM
> =item STR
> =item BOOL

What about references?

Arrays and hashes should probably be at least mentioned here.

> =head3 String data types
> 
> =item binary buffer

'Binary string'

> =item UTF-32 string
> =item Native string
> =item Foreign string

I'm a little surprised not to see UTF-8 there, but since I'm also
confused about what Native string and Foreign string are I'll skip it.
Except to say that some clarification here may help, and explicitly
mentioning UTF-8 (even to say it won't be a core type and provide a
reference to why) would be good.

> The functions are divided into two broad categories, those that perl
> will use the value of internally (for example the type functions) and
> those that produce or modify a PMC, such as the add function.

So possibly a good idea to explicitly group them that way.

> =head2 Functions in detail
> 
> =item type
> 
> =item name
> 
>    STR		name(PMC[, key]);
> 
> Returns the name of the class the PMC belongs to.

So I'd call it type_name (or maybe class_name as you seem to be useing
the words interchangably. If type != class then clarify somewhere.).

> =item move_to
> 
>    BOOL		move_to(void *, PMC);
> 
> Tells the PMC to move its contents to a block of memory starting at
> the passed address. Used by the garbage collector to compact memory,
> this call can return a false value if the move can't be done for some
> reason. The pointer is guaranteed to point to a chunk of memory at
> least as large as that returned by the C<real_size> vtable function.

Shouldn't the PMC be the first arg for consistency?

> =item real_size
> 
>    IV		real_size(PMC[, key]);
> 
> Returns an integer value that represents the real size of the data
> portion, excluding the vtable, of the PMC.

Contiguous? Sum of parts (allowing for allignment) if it contains
multiple chunks of data?

> =item destroy
> 
>    void		destroy(PMC[, key]);
> 
> Destroys the variable the PMC represents, leaving it undef.

Using the word 'variable' here probably isn't a good idea.
Maybe "Destroys the contents of the PMC leaving it undef."

> =item is_same
> 
>    BOOL		is_same(PMC1, PMC2[, key]);
> 
> Returns TRUE if C<PMC1> and C<PMC2> refer to the same value, and FALSE
> otherwise.

I think that needs more clarification, especially where they are of
different types. Contrast with is_equal() below.

> =item concatenate
> 
>    void		concatenate(PMC1, PMC2, PMC3[, key]); ##
> 
> Concatenates the strings in C<PMC2> and C<PMC3>, storing the result in
> C<PMC1>.

and insert (ala sv_insert)  etc?

> =item is_equal

Contrast with is_same() above.

> =item logical_or
> =item logical_and
> =item logical_not

Er, why not just use get_bool? The only reason I can think of is to
support three-value-logic but that would probably be better handled
via a higher-level overloading kind of mechanism. Either way, clarify.

> =item match
> 
>    void		match(PMC1, PMC2, REGEX[, key]);
> 
> Performs a regular expression match on C<PMC2> against the expression
> C<REGEX>, placing the results in C<PMC1>.

Results, plural => container => array or hash. Needs clarifying.

> =item repeat (x)
> 
>    void		repeat(PMC1, PMC2, PMC3[, key]); ##
> 
> Performs the following sequence of operations: finds the string value
> from C<PMC2>; finds an integer value I<n> from C<PMC3>; replicates the
> string I<n> times; stores the resulting string in C<PMC1>.

So call it replicate? Could also work for arrays.

> =item nextkey (x)
> 
>    void		nextkey(PMC1, PMC2, start_key[, key]);
> 
> Looks up the key C<start_key> in C<PMC2> and then stores the key after
> it in C<PMC1>. If start_key is C<undef>, the first key is returned,
> and C<PMC1> is set to undef if there is no next key.

Containers again.  And I'd call it key_next()

> =item exists (x)

Likewise, key_exists()

> =head1 TODO
> 
> The effects of each function on scalar, array, hash, list, and IO
> PMCs needs to be hashed out.

Before that I think a section on containers need to be added.

> =head1 REFERENCES
> 
> PDD 3: Perl's Internal Data Types.

Some references to any other vtable based languages would be good.
(I presume people have looked at some and learnt lessons.)

Tim.