[perl #21759] Documentation for PMCS
Alberto Simões/epl
--
Departamento de Informatica - Universidade do Minho
"The C Programming Language -- A language which combines the
flexibility of assembly language with the power of assembly language."
Alberto Simões/epl
New versions for the three PODs I started writting. I __NEED__ feedback, please.
And, adding the files to CVS could make it simpler to send diffs. This way, I'm
sending new versions, each time...
Here they go.
Alberto
Steve Fink
> Hi... again
>
> New versions for the three PODs I started writting. I __NEED__
> feedback, please. And, adding the files to CVS could make it simpler
> to send diffs. This way, I'm sending new versions, each time...
Any votes on where to put them? I was thinking of docs/dev (and adding
a pointer to them in the .pmc files). The top-level docs seems to be
for less specific docs.
Thank you very much for the documentation! Since it's been a while and
everyone's been ignoring you, I'll do a full proofreading:
> =head2 Creation
>
> To create a new PMC with a PerlArray on register C<P0> use:
s/on/in/
> =head2 Index access
s/Index/Indexed/ ?
>
> You can set the value 3 on the position 5 from the array using
>
> set P0[5] 3
missing comma
>
> In the same mood, to access the element use
>
> set I0, P0[5]
>
> As in Perl, negative indexes are seen as indexes from the end of the
> array. This way, you can set the last element of the array to the
> value 7 using
>
> set P0[-1], 7
>
> Note that these arrays are polymorphic: array elements can store any
> kind of element.
>
> =head2 Multidimensional arrays
>
> You can use Perl arrays inside Perl arrays:
>
> new P0, .PerlArray
> new P1, .PerlArray
> set P1[0], "el1"
> set P1[1], "el2"
> set P0[0], P1 # First element for P0 is a perl array.
> set P0[1], P1 # Second element for P0 is a perl array.
>
> This code creates a table like this:
>
> el1 el2
> el1 el2
>
> TODO: Will this be possible?
Isn't it already? Oh, wait -- is that comment for the section before
it or the section after it? If it's for the one after, I believe the
answer is "yes, it will be possible if it isn't already." It isn't?
>
> While you can do this manually, as shown in the above example, it is
> possible to use the following syntax:
>
> new P0, .PerlArray
> set P0[0;0], "el1"
> set P0[0;1], "el2"
> set P0[1;0], "el1"
> set P0[1;1], "el2"
>
> This code would construct the same table.
That's not the same table. At the very least, the first version stores
the same PMC twice, so any change to an element would be reflected in
the other element. The P0[0;0] stuff would create four unrelated
cells.
> To fetch the elements you can use the same syntax:
>
> set S0, P0[0;1]
I'm not sure whether this syntax would work for the first way you
constructed the table. I think it would, though.
> =head2 Stacking
>
> You can use the Perl arrays as stacks, where elements are added to
> higher positions on the array:
>
> new P0, .PerlArray
> push P0, 2 # set P0[0], 2
> push P0, 3 # set P0[1], 3
>
> pop I0, P0 # set I0, P0[1]; set 1, P0
You mean 'set P0, 1'
>
> =head2 Shifting
>
> If you want to add or remove elements from the beginning of the array,
> use the shift or unshift commands:
>
> new P0, .PerlArray
> unshift P0, 2 # set P0[0], 2
> unshift P0, 3 # set P0[1], 2; set P0[0], 3
>
> shift I0, P0 # set I0, P0[0]; set P0[0], P0[1]; set 1, P0
and again here. Destination first.
> =head2 Trueness
>
> You can get a boolean value from a Perl Array. If you use an empty
> Perl Array in a condition, it will return false (no elements).
>
> new P0, .PerlArray
> if P0, JUMP # This will never succeed
>
> After adding a value (for example, P0[0] = 1), it will return a true
> value (the Perl Array has elements).
>
> new P0, .PerlArray
> set P0, 0, 1
> if P0, JUMP # This will succeed
>
> If you don't add a value, but force a size different from zero the the
> array, it will return a true value:
>
> new P0, .PerlArray
> set P0, 1
> if P0, JUMP # This will succeed
>
> You can test if there is a defined element on some array position using
>
> defined I0, P0[1]
>
> for the position you want to test. On the other hand, if you want only
> to test if there is an element (rather than testing if it is defines)
> you should use the C<exists> keyword:
>
> exists I0, P0[0]
This discussion is missing something. If you set the size of an array
to something larger than its current value, are the extra elements
defined? Do they exist? Are they (implicitly or explicitly)
initialized to something (eg PerlUndef) by default? (I'm not sure if
the current implementation matches the intended answer, btw.)
> =head2 Cloning
>
> As other PMCs, you can clone Perl arrays. If you try something like
>
> new P0, .PerlArray
> set P0[0], 1
> set P0[1], 2
>
> clone P1, P0
>
> C<P1> is a copy of C<P0>, where you can do whatever you want without
> changing the other array.
Is the copy deep or shallow?
> # -*- cperl -*-
>
> =head1 Perl Hash PMC
>
> =head2 Synopsis
>
> ...
>
> Notice that hashes are polymorphic on the value it holds.
s/hashes/a hash/ or s/it/they/
> When using a key which does not exist in the hash, the value returned
> depends on the register used to retrieve the element.
s/which/that/ (okay, that was nitpicky)
> You can check if an hash element exists before accessing it, using the
> C<exists> command:
>
> exists I0, P0["a"]
>
> This example will set the value one in register C<I0> if the key
> exists, the value zero if it does not exist.
>
> Notice that this tests if there is anything. In fact, the C<exists>
> command will return true if the element in that position if a
s/if/is/
> PerlUndef PMC. To check if that element is defined, use the C<defined>
> command:
>
> defined I0, P0["a"]
And if there were a keys() method, then 'defined' and 'exists' are
very different. (And there ought to be, and would be if we weren't all
ignoring Leo's iterator proposal.)
> =head2 Cloning
>
> As other PMCs, you can clone Perl hashes. If you try something like
>
> new P0, .PerlHash
> set P0["a"], 1
> set P0["b"], 2
>
> clone P1, P0
>
> C<P1> is a copy of C<P0>, where you can do whatever you want without
> changing the other hash.
Deep or shallow?
> # -*- cperl -*-
>
> =head1 Array base class
>
> This pod file documents the Array base class usage. For implementation
> details you should look inside the class file, found on
s/on/at/ ?
> C<classes/array.pmc> in the parrot source code.
>
> =head2 Synopsis
>
> new P0, .Array # initialize P0 as an array
>
> set I0, P0 # get to I0 size of the array P0
> set P0, 2 # set array P0 size to 2
>
> set P0[0], "foo" # put "foo" on array position 0
> set I1, P0[1] # get value from array position 1
>
> defined I2, P0[1] # value on position 1 is defined?
> exists I3, P0[0] # there is an element on position 0?
>
> =head2 Creation
>
> As any other PMC, the following line creates an array PMC on register C<P0>.
>
> new P0, .Array
>
> As soon the array is created, you can test if it is defined using:
>
> defined I0, P0
>
> which will put C<1> on C<I0> if it is defined, otherwise, C<0>.
What does that mean? I assume the only way to get a true value back
from defined on a PMC is to call it on a PerlUndef. Your wording is a
little confusing -- what happens if I test if the array is defined
*before* I create it? Oh, wait, that makes no sense...
My point is that using 'defined' like that really has nothing to do
with Arrays (or PerlArrays or PerlHashes) -- it has to do with PMCs in
general (and maybe PerlUndef in particular.) I think we'll need to
invent a non-perl undef, btw. (I don't know if we'll need to keep the
perl undef.)
> =head2 Array sizes
>
> When used on numeric context the PMC register containing the array
s/on/in/
> object contains the size of the array. You can use
Misleading wording. You're saying that it might contain two different
things depending on the context it's being used in. (So what does it
contain when it's not being used at all?) I'd prefer to think of it as
the 'set' operation retrieving the size of the array in numeric
context.
> =head2 Accessing elements
>
> Elements are accessed using indexes, as in any programming
> language. Notice that these arrays do not expand as Perl arrays, when
Spurious comma and that should probably be "...do not expand as Perl
arrays do..." or "...do not expand like Perl arrays..."
> you access non-existing indexes.
nonexistent
>
> The following code initializes an array on C<P0> with size two, and
s/on/in/
> sets the first position with an integer C<-8> and second position with
s/with/to/g
> a real, C<3.1415>.
s/a real,/the real number/
> To retrieve the elements we use the same syntax, switching registers:
>
> set N1, P0[1]
> set I1, P0[0]
>
> These two lines retrieve the values from the array back to registers.
s/These/Those/
s/to/into/
> Whenever you want, it is possible to change the value type on some
> position:
s/on/at/ (sorry, I just can't leave your "on"s alone!)
>
> set P0[1], "A string"
>
> Accessing an out-of-bounds array element, an exception will be raised
> (as soon as we have exceptions).
"When accessing..." or "If you access..."
All in all, very nice documentation, especially since I'm guessing
that English isn't even your native language. What country code is
.pt? I can't even imagine writing documentation in anything but my
first language.
Brent Dax
# All in all, very nice documentation, especially since I'm
# guessing that English isn't even your native language. What
# country code is .pt? I can't even imagine writing
# documentation in anything but my first language.
Between the name (tilde over the vowel especially) and the .pt, I
suspect it's Portugal. If Portuguese is as close to Spanish as I think
it is, the English words "in", "on" and "at" are all rolled into one
word ("en" in Spanish), and from what I've heard the distinction can be
hard to grasp for people with such a language.
BTW, well done, Alberto--if I hadn't recognized the in/on/at thing, I
probably wouldn't have known English was a second language for you. You
write better than a lot of native speakers. ;^)
--Brent Dax <bren...@cpan.org>
@roles=map {"Parrot $_"} qw(embedding regexen Configure)
>How do you "test" this 'God' to "prove" it is who it says it is?
"If you're God, you know exactly what it would take to convince me. Do
that."
--Marc Fleury on alt.atheism
Alberto Simões/epl
| On Apr-14, Alberto Sim?es/EPL wrote:
| > Hi... again
| >
| > New versions for the three PODs I started writting. I __NEED__
| > feedback, please. And, adding the files to CVS could make it simpler
| > to send diffs. This way, I'm sending new versions, each time...
|
| Any votes on where to put them? I was thinking of docs/dev (and adding
| a pointer to them in the .pmc files). The top-level docs seems to be
| for less specific docs.
|
| Thank you very much for the documentation! Since it's been a while and
| everyone's been ignoring you, I'll do a full proofreading:
Substitutions done. Some pertinent (I hope this word exists in/at/on English!)
comments are hold still I have time to test them on parrot.
I'll put current version somewhere soon.
Thanks a lot for the corrections.
Alberto