Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Document oplib PMC
  • Loading branch information
Benabik committed Oct 17, 2011
1 parent 2ebdb70 commit aca0054
Showing 1 changed file with 120 additions and 4 deletions.
124 changes: 120 additions & 4 deletions src/pmc/oplib.pmc
Expand Up @@ -3,11 +3,11 @@ Copyright (C) 2010-2011, Parrot Foundation.

=head1 NAME

src/pmc/oplib.pmc
src/pmc/oplib.pmc - Information about an opcode library

=head1 DESCRIPTION

Implements oplib VTABLEs.
The PMC provides introspection on the opcodes contained in a library.

=cut

Expand All @@ -23,11 +23,35 @@ Implements oplib VTABLEs.
pmclass OpLib auto_attrs {
ATTR op_lib_t *oplib;

/*

=head2 Vtable functions

=over 4

=item C<void init()>

Throws an error. OpLib requires an argument to init. See C<init_pmc>.

=cut

*/

VTABLE void init() {
Parrot_ex_throw_from_c_args(INTERP, NULL, EXCEPTION_INVALID_OPERATION,
"OpLib must be initialized with an oplib name");
}

/*

=item C<void init_pmc(PMC *name_pmc)>

Initializes the OpLib with information about an oplib.

=cut

*/

VTABLE void init_pmc(PMC *name_pmc) {
STRING * const name = VTABLE_get_string(INTERP, name_pmc);
char * const name_cstr = Parrot_str_to_cstring(INTERP, name);
Expand Down Expand Up @@ -55,8 +79,27 @@ pmclass OpLib auto_attrs {
SET_ATTR_oplib(INTERP, SELF, oplib);
}

/* Look up an opnumber given the name of the op. First we look for the
specific name, then the more general short name. */

/*

=item C<INTVAL get_integer_keyed_str(STRING *name)>

=item C<INTVAL get_integer_keyed(PMC *key)>

=item C<PMC* get_pmc_keyed_str(STRING *name)>

=item C<PMC* get_pmc_keyed(PMC *key)>

Look up an op number given the name of the op. First we look for the
specific name, then the more general short name.

The VTABLEs that return integers return -1 when an opcode could not be found.
The VTABLEs that return PMCs throw exceptions instead.

=cut

*/

VTABLE INTVAL get_integer_keyed_str(STRING *name) {
const op_lib_t *oplib;
char * const cstr = Parrot_str_to_cstring(INTERP, name);
Expand Down Expand Up @@ -87,6 +130,17 @@ pmclass OpLib auto_attrs {
return VTABLE_get_pmc_keyed_str(INTERP, SELF, strkey);
}

/*

=item C<PMC* get_pmc_keyed_int(INTVAL value)>

Returns an C<Opcode> PMC for a given opcode number. To find an opcode number
from a name, see C<get_integer_keyed_str()> above.

=cut

*/

VTABLE PMC* get_pmc_keyed_int(INTVAL value) {
op_lib_t *oplib;
GET_ATTR_oplib(INTERP, SELF, oplib);
Expand All @@ -103,6 +157,18 @@ pmclass OpLib auto_attrs {
}
}

/*

=item C<INTVAL elements()>

=item C<INTVAL get_integer()>

Returns the number of opcodes in the library.

=cut

*/

VTABLE INTVAL elements() {
const op_lib_t *oplib;
GET_ATTR_oplib(INTERP, SELF, oplib);
Expand All @@ -113,12 +179,39 @@ pmclass OpLib auto_attrs {
return STATICSELF.elements();
}

/*

=item C<void* get_pointer()>

Returns the C<op_lib_t> pointer for the opcode library.

=cut

*/

VTABLE void* get_pointer() {
op_lib_t *oplib;
GET_ATTR_oplib(INTERP, SELF, oplib);
return oplib;
}

/*

=back

=head2 Methods

=over 4

=item C<PMC *op_family(STRING *shortname)>

Returns an array of C<Opcode> PMCs for all the opcodes in the library that
share the given short name.

=cut

*/

METHOD op_family(STRING *shortname) {
char * const sname = Parrot_str_to_cstring(INTERP, shortname);
const op_lib_t *oplib;
Expand All @@ -139,6 +232,17 @@ pmclass OpLib auto_attrs {
RETURN(PMC *result);
}

/*

=item C<PMC *version()>

Returns an array containing the three version numbers (major, minor, patch) of
the library.

=cut

*/

METHOD version() {
const op_lib_t *oplib;
PMC * const version_array = Parrot_pmc_new(INTERP, enum_class_ResizableIntegerArray);
Expand All @@ -150,6 +254,18 @@ pmclass OpLib auto_attrs {
}
}

/*

=back

=head1 SEE ALSO

F<src/pmc/opcode.pmc>

=cut

*/

/*
* Local variables:
* c-file-style: "parrot"
Expand Down

0 comments on commit aca0054

Please sign in to comment.