[svn:parrot] r39845 - trunk/docs/book/pir
allison at svn.parrot.org
allison at svn.parrot.org
Tue Jun 30 18:24:02 UTC 2009
Author: allison
Date: Tue Jun 30 18:24:00 2009
New Revision: 39845
URL: https://trac.parrot.org/parrot/changeset/39845
Log:
[book] Final cross-reference and page-break fixes.
Modified:
trunk/docs/book/pir/ch01_introduction.pod
trunk/docs/book/pir/ch02_getting_started.pod
trunk/docs/book/pir/ch03_basic_syntax.pod
trunk/docs/book/pir/ch04_variables.pod
trunk/docs/book/pir/ch05_control_structures.pod
trunk/docs/book/pir/ch06_subroutines.pod
trunk/docs/book/pir/ch07_objects.pod
trunk/docs/book/pir/ch08_io.pod
trunk/docs/book/pir/ch09_exceptions.pod
Modified: trunk/docs/book/pir/ch01_introduction.pod
==============================================================================
--- trunk/docs/book/pir/ch01_introduction.pod Tue Jun 30 16:42:20 2009 (r39844)
+++ trunk/docs/book/pir/ch01_introduction.pod Tue Jun 30 18:24:00 2009 (r39845)
@@ -26,6 +26,7 @@
=head2 Parrot Resources
+X<www.parrot.org website>
The starting point for all things related to Parrot is the main website
U<http://www.parrot.org/>. The site lists additional resources, well as recent
news and information about the project.
@@ -35,28 +36,31 @@
=head3 Documentation
+X<docs.parrot.org website>
+X<online documentation (docs.parrot.org)>
Parrot includes extensive documentation in the distribution. The full
documentation for the latest release is available online at
U<http://docs.parrot.org/>.
=head3 Mailing Lists
-X<parrot-dev (Parrot mailing list)>
+X<parrot-dev mailing list>
X<mailing lists>
-The primary mailing list for Parrot is I<parrot-dev at lists.parrot.org>. If
+The primary mailing list for Parrot is I<parrot-dev>.N<parrot-dev at lists.parrot.org> If
you're interested in developing Parrot, the I<parrot-commits> and
I<parrot-tickets> lists are useful. More information on the Parrot mailing
-lists, as well as subscription options, is available at
+lists, as well as subscription options, is available on the mailing list
+info page
U<http://lists.parrot.org/mailman/listinfo>.
-The archives for I<parrot-dev> are also available on Google Groups at
-U<http://groups.google.com/group/parrot-dev> and via NNTP at
+The archives for I<parrot-dev> are available on Google Groups at
+U<http://groups.google.com/group/parrot-dev> and as NNTP at
U<nntp://news.gmane.org/gmane.comp.compilers.parrot.devel>.
=head3 IRC
-X<#parrot (Parrot IRC channel)>
+X<#parrot (IRC channel)>
X<IRC channel (#parrot)>
Parrot developers and users congregate on IRC at C<#parrot> on the
@@ -68,10 +72,11 @@
X<trac.parrot.org website>
X<issue tracking (trac.parrot.org)>
-Parrot developers track issues with a Trac site at U<https://trac.parrot.org/>.
-Users can submit new tickets and track the status of existing tickets. The
-site also includes a wiki used in project development, a source code browser,
-and the project roadmap.
+Parrot developers track bugs, feature requests, and roadmap tasks at
+U<https://trac.parrot.org/>, the open source Trac issue tracker. Users
+can submit new tickets and track the status of existing tickets. The
+site also includes a wiki used in project development, a source code
+browser, and the project roadmap.
=head2 Parrot Development
Modified: trunk/docs/book/pir/ch02_getting_started.pod
==============================================================================
--- trunk/docs/book/pir/ch02_getting_started.pod Tue Jun 30 16:42:20 2009 (r39844)
+++ trunk/docs/book/pir/ch02_getting_started.pod Tue Jun 30 18:24:00 2009 (r39845)
@@ -5,11 +5,11 @@
The simplest way to install Parrot is to use a pre-compiled binary for your
operating system or distribution. Packages are available for many systems,
including Debian, Ubuntu, Fedora, Mandriva, FreeBSD, Cygwin, and MacPorts. The
-Parrot website lists all known packages at U<http://www.parrot.org/download>. A
-binary installer for Windows is also available at
-U<http://parrotwin32.sourceforge.net/>.
-
-If packages aren't available on your system, download the latest supported
+Parrot website lists all known packages.N<U<http://www.parrot.org/download>> A
+binary installer for Windows is also available from the Parrot Win32
+project on SourceForge.N<U<http://parrotwin32.sourceforge.net/>>
+If packages aren't available on your system, you can download a source
+tarball for the latest supported
release from U<http://www.parrot.org/release/supported>.
You need a C compiler and a make utility to build Parrot from source code --
@@ -17,6 +17,7 @@
toolchains on different operating systems. Perl 5.8 is also a prerequiste for
configuring and building Parrot.
+X<compiling>
If you have these dependencies installed, build the core virtual machine and
compiler toolkit and run the standard test suite with the commands:
@@ -24,6 +25,7 @@
$ make
$ make test
+X<installation>
By default, Parrot installs to directories F<bin/>, F<lib/>, and
F<include/> under F</usr/local>. If you have privileges to
write to these directories, install Parrot with:
@@ -43,6 +45,7 @@
$ make install-dev
+X<.pir files>
Once you've installed Parrot, create a test file called
F<news.pir>.N<Files containing PIR code use the F<.pir> extension.>
@@ -64,6 +67,7 @@
=cut
+X<tutorial>
The Parrot source distribution includes copious examples in its F<examples/>
directory. In particular, a PIR tutorial is available in
F<examples/tutorial/>.
Modified: trunk/docs/book/pir/ch03_basic_syntax.pod
==============================================================================
--- trunk/docs/book/pir/ch03_basic_syntax.pod Tue Jun 30 16:42:20 2009 (r39844)
+++ trunk/docs/book/pir/ch03_basic_syntax.pod Tue Jun 30 18:24:00 2009 (r39845)
@@ -5,7 +5,6 @@
Z<CHP-3>
X<PIR syntax>
-
PIR has a relatively simple syntax. Every line is a comment, a label, a
statement, or a directive. Each statement or directive stands on its own
line. There is no end-of-line symbol (such as a semicolon in C).
@@ -37,7 +36,7 @@
=head2 Labels
-X<PIR (Parrot intermediate representation);labels> X<labels (PIR)>
+X<labels>
A label attaches a name to a line of code so other statements can refer to it.
Labels can contain letters, numbers, and underscores. By convention, labels use
all capital letters to stand out from the rest of the source code. It's fine to
@@ -62,8 +61,7 @@
Z<CHP-3-SECT-1>
-X<statements (PIR)>
-X<PIR (Parrot intermediate representation);statements>
+X<statements>X<opcodes>
A statement is either an opcode or syntactic sugar for one or more opcodes. An
opcode is a native instruction for the virtual machine; it consists of the name
of the instruction followed by zero or more arguments.
@@ -82,6 +80,7 @@
=end PIR_FRAGMENT
+X<operators>
These special statement forms are just syntactic sugar for regular opcodes. The
C<+> symbol corresponds to the C<add> opcode, the C<-> symbol to the C<sub>
opcode, and so on. The previous example is equivalent to:
@@ -94,9 +93,7 @@
=head2 Directives
-X<directives (PIR)>
-X<PIR (Parrot intermediate representation);directives>
-
+X<directives>
Directives resemble opcodes, but they begin with a period (C<.>). Some
directives specify actions that occur at compile time. Other directives
represent complex operations that require the generation of multiple
@@ -110,9 +107,7 @@
=head2 Literals
-X<literals (PIR)>
-X<PIR (Parrot intermediate representation);literals>
-
+X<literals>
Integers and floating point numbers are numeric literals. They can be positive
or negative.
@@ -123,6 +118,7 @@
=end PIR_FRAGMENT
+X<integers>
Integer literals can also be binary, octal, or hexadecimal:
=begin PIR_FRAGMENT
@@ -133,6 +129,7 @@
=end PIR_FRAGMENT
+X<numbers (floating-point)>
Floating point number literals have a decimal point and can use scientific
notation:
@@ -143,7 +140,7 @@
=end PIR_FRAGMENT
-X<strings;in PIR>
+X<strings>
String literals are enclosed in single or double-quotes.N<See the
section on L<Strings> in Chapter 4 for an explanation of the differences
between the quoting types.>
@@ -157,10 +154,7 @@
=head2 Variables
-X<variables (PIR)>
-X<PIR (Parrot intermediate representation);variables>
-X<PMC; definition>
-
+X<variables>
PIR variables can store four different kinds of valuesE<mdash>integers,
numbers (floating point), strings, and objects. Parrot's objects are
called PMCs, for "I<P>olyI<M>orphic I<C>ontainer".
@@ -178,6 +172,7 @@
=end PIR_FRAGMENT
+X<named variables>
PIR also has named variables; the C<.local>
directive declares them. As with register variables, there are four valid types:
C<int>, C<num>, C<string>, and C<pmc>. You I<must> declare named variables;
@@ -193,9 +188,7 @@
=head2 Constants
-X<PIR (Parrot intermediate representation);constants>
-X<constants (PIR)>
-
+X<constants>
The C<.const> directive declares a named constant. Named constants are similar
to named variables, but the values set in the declaration may never change.
Like C<.local>, C<.const> takes a type and a name. It also requires a literal
@@ -203,9 +196,9 @@
=begin PIR_FRAGMENT
- .const int frog = 4 # integer constant
- .const string name = "Superintendent Parrot" # string constant
- .const num pi = 3.14159 # floating point constant
+ .const int frog = 4 # integer
+ .const string name = "Superintendent Parrot" # string
+ .const num pi = 3.14159 # floating point
=end PIR_FRAGMENT
@@ -222,9 +215,7 @@
=head2 Keys
-X<PIR (Parrot intermediate representation);keys>
-X<keys (PIR)>
-
+X<keys>
A key is a special kind of constant used for accessing elements in complex
variables (such as an array). A key is either an integer or a string; and it's
always enclosed in square brackets (C<[> and C<]>). You do not have to declare
@@ -249,9 +240,7 @@
=head2 Control Structures
-X<PIR (Parrot intermediate representation);control structures>
-X<control structures (PIR)>
-
+X<control structures>X<goto instruction>
Rather than providing a pre-packaged set of control structures like C<if> and
C<while>, PIR gives you the building blocks to construct your own.N<PIR has
many advanced features, but at heart it B<is> an assembly language.> The most
@@ -269,6 +258,7 @@
=end PIR_FRAGMENT
+X<conditional branch>
Variations on the basic C<goto> check whether a particular condition is
true or false before jumping:
@@ -282,9 +272,7 @@
=head2 Subroutines
-X<PIR (Parrot intermediate representation);subroutines>
-X<subroutines (PIR)>
-
+X<subroutines>
A PIR subroutine starts with the C<.sub> directive and ends with the C<.end>
directive. Parameter declarations use the C<.param> directive; they resemble
named variable declarations. This example declares a subroutine named
Modified: trunk/docs/book/pir/ch04_variables.pod
==============================================================================
--- trunk/docs/book/pir/ch04_variables.pod Tue Jun 30 16:42:20 2009 (r39844)
+++ trunk/docs/book/pir/ch04_variables.pod Tue Jun 30 18:24:00 2009 (r39845)
@@ -4,7 +4,7 @@
Parrot is a register-based virtual machine. It has four typed register sets --
integers, floating-point numbers, strings, and objects. All variables in PIR
-are one of these four types. Whether you work with register variables or named
+are one of these four types. When you work with register variables or named
variables, you're actually working directly with register storage locations in
the virtual machine.
@@ -18,23 +18,20 @@
=head2 Assignment
-X<variable assignment>
-X<PIR operators; =>
-
+X<assignment>
+X<= operator>
The most basic operation on a variable is assignment using the C<=>
operator:
=begin PIR_FRAGMENT
$I0 = 42 # set integer variable to the value 42
- $N3 = 3.14159 # set number variable to an approximation of pi
+ $N3 = 3.14159 # set number variable to approximation of pi
$I1 = $I0 # set $I1 to the value of $I0
=end PIR_FRAGMENT
-X<exchange>
-X<opcodes; exchange>
-
+X<exchange opcode>
The C<exchange> opcode swaps the contents of two variables of the same type.
This example sets C<$I0> to the value of C<$I1> and sets C<$I1> to the value
of C<$I0>.
@@ -45,9 +42,7 @@
=end PIR_FRAGMENT
-X<null>
-X<opcodes; null>
-
+X<null opcode>
The C<null> opcode sets an integer or number variable to a zero value,
and undefines a string or object.
@@ -62,6 +57,7 @@
=head2 Working with Numbers
+X<integers>X<numbers (floating-point)>
PIR has an extensive set of instructions that work with integers,
floating-point numbers, and numeric PMCs. Many of these instructions
have a variant that modifies the result in place:
@@ -73,6 +69,7 @@
=end PIR_FRAGMENT
+X<+ operator>
The first form of C<+> stores the sum of the two arguments in the result
variable, C<$I0>. The second variant, C<+=>, adds the single argument to
C<$I0> and stores the sum back in C<$I0>.
@@ -95,17 +92,14 @@
=end PIR_FRAGMENT
-There are many numeric opcodes; a complete list is available in "PIR Opcodes"
-in Chapter 11.
-
=head3 Unary numeric opcodes
X<unary numeric opcodes>
-
-Unary opcodes have a single argument. They either return a result or modify
-the argument in place. Some of the most common unary numeric opcodes are C<inc>
-(increment), C<dec> (decrement), C<abs> (absolute value), C<neg> (negate), and
-C<fact> (factorial):
+Unary opcodes have a single argument. They either return a result or
+modify the argument in place. Some of the most common unary numeric
+opcodes are C<inc> (increment)X<inc opcode>, C<dec> (decrement)X<dec
+opcode>, C<abs> (absolute value)X<abs opcode>, C<neg> (negate)X<neg
+opcode>, and C<fact> (factorial)X<fact opcode>:
=begin PIR_FRAGMENT
@@ -120,11 +114,13 @@
X<binary numeric opcodes>
Binary opcodes have two arguments and a result. Parrot provides
-addition (C<+> or C<add>), subtraction (C<-> or C<sub>), multiplication
-(C<*> or C<mul>), division (C</> or C<div>), modulus (C<%> or C<mod>),
-and exponent (C<pow>) opcodes, as well as C<gcd>X<gcd opcode>
-(greatest common divisor) and C<lcm>X<lcm opcode> (least common
-multiple).
+addition (C<+>X<+ operator> or C<add>X<add opcode>), subtraction
+(C<->X<- operator> or C<sub>X<sub opcode>), multiplication (C<*>X<*
+operator> or C<mul>X<mul opcode>), division (C</>X</ operator> or
+C<div>X<div opcode>), modulus (C<%>X<% operator> or C<mod>X<mod
+opcode>), and exponent (C<pow>X<pow opcode>) opcodes, as well as
+C<gcd>X<gcd opcode> (greatest common divisor) and C<lcm>X<lcm opcode>
+(least common multiple).
=begin PIR_FRAGMENT
@@ -135,16 +131,18 @@
=head3 Floating-point operations
-X<float opcodes>
-
-The most common floating-point operations are C<ln> (natural log), C<log2> (log
-base 2), C<log10> (log base 10), and C<exp> (I<e>G<x>), as well as a full set
-of trigonometric opcodes such as C<sin> (sine), C<cos> (cosine), C<tan>
-(tangent), C<sec> (secant), C<cosh> (hyperbolic cosine), C<tanh> (hyperbolic
-tangent), C<sech> (hyperbolic secant), C<asin> (arc sine), C<acos> (arc
-cosine), C<atan> (arc tangent), C<asec> (arc secant), C<exsec> (exsecant),
-C<hav> (haversine), and C<vers> (versine). All angle arguments for the
-X<trigonometric functions> trigonometric functions are in radians:
+The most common floating-point operations are C<ln>X<ln opcode> (natural
+log), C<log2>X<log2 opcode> (log base 2), C<log10>X<log10 opcode> (log
+base 10), and C<exp>X<exp opcode> (I<e>G<x>), as well as a full set of
+trigonometric opcodes such as C<sin>X<sin opcode> (sine), C<cos>X<cos
+opcode> (cosine), C<tan>X<tan opcode> (tangent), C<sec>X<sec opcode>
+(secant), C<cosh>X<cosh opcode> (hyperbolic cosine), C<tanh>X<tanh
+opcode> (hyperbolic tangent), C<sech>X<sech opcode> (hyperbolic secant),
+C<asin>X<asin opcode> (arc sine), C<acos>X<acos opcode> (arc cosine),
+C<atan>C<atan opcode> (arc tangent), C<asec>X<asec opcode> (arc secant),
+C<exsec>X<exsec opcode> (exsecant), C<hav>X<hav opcode> (haversine), and
+C<vers>X<vers opcode> (versine). All angle arguments for the
+X<trigonometric opcodes> trigonometric opcodes are in radians:
=begin PIR_FRAGMENT
@@ -160,13 +158,12 @@
=head3 Logical and Bitwise Operations
X<logical opcodes>
-
-The logical opcodes evaluate the truth of their arguments. They're most useful
-to make decisions for control flow. Integers and numeric PMCs support logical
-are false if they're 0 and true otherwise. Strings are false if they're the
-empty string or a single character "0", and true otherwise. PMCs are true when
-their C<get_bool>X<get_bool vtable method> vtable method returns a nonzero
-value.
+The logical opcodes evaluate the truth of their arguments. They are most
+useful to make decisions for control flow. Integers and numeric PMCs
+support logical are false if they're 0 and true otherwise. Strings are
+false if they're the empty string or a single character "0", and true
+otherwise. PMCs are true when their C<get_bool>X<get_bool vtable
+function> vtable function returns a nonzero value.
The C<and>X<and opcode> opcode returns the first argument if
it's false and the second argument otherwise:
@@ -218,8 +215,7 @@
=end PIR_FRAGMENT
-X<bitwise;opcodes>
-
+X<bitwise opcodes>
The bitwise opcodes operate on their values a single bit at a time.
C<band>X<band opcode>, C<bor>X<bor opcode>, and C<bxor>X<bxor opcode> return a
value that is the logical AND, OR, or XOR of each bit in the source arguments.
@@ -250,8 +246,9 @@
=end PIR_FRAGMENT
-X<shift opcodes>
-
+X<shl opcode>
+X<shr opcode>
+X<lsr opcode>
The logical and arithmetic shift operations shift their values by a specified
number of bits:
@@ -265,6 +262,7 @@
=head2 Working with Strings
+X<strings>
Parrot strings are buffers of variable-sized data. The most common use of
strings is to store text data. Strings can also hold binary or other
non-textual data, though this is rare.N<In general, a custom PMC is more
@@ -283,7 +281,8 @@
$S0 = "This string is \n on two lines"
$S0 = 'This is a \n one-line string with a slash in it'
-Parrot supports several escape sequences in double-quoted strings:
+Table 4.1 shows the escape sequences Parrot supports in double-quoted
+strings.
=begin table String Escapes
@@ -398,7 +397,6 @@
=head3 Heredocs
X<heredocs>
-
If you need more flexibility in defining a string, use a heredoc string
literal. The C<E<lt>E<lt>> operator starts a heredoc. The string terminator
immediately follows. All text until the terminator is part of the string. The
@@ -406,16 +404,14 @@
line, and may not have any trailing whitespace.
$S2 = << "End_Token"
-
This is a multi-line string literal. Notice that
it doesn't use quotation marks.
-
End_Token
=head3 Concatenating strings
-X<concat opcode>
-X<string concatenation>
+X<. operator>
+X<strings;concatenation>
Use the C<.> operator to concatenate strings. The following example
concatenates the string "cd" onto the string "ab" and stores the result in
@@ -429,6 +425,7 @@
=end PIR_FRAGMENT
+X<.= operator>
Concatenation has a C<.=> variant to modify the result in place. In the
next example, the C<.=> operation appends "xy" onto the string "abcd" in
C<$S1>.
@@ -442,6 +439,7 @@
=head3 Repeating strings
+X<repeat opcode>
The C<repeat> opcode repeats a string a specified number of times:
=begin PIR_FRAGMENT
@@ -457,6 +455,7 @@
=head3 Length of a string
+X<length opcode>
The C<length> opcode returns the length of a string in characters. This won't
be the same as the length in I<bytes> for multibyte encoded strings:
@@ -534,7 +533,7 @@
=begin PIR_FRAGMENT
$S0 = chr 65 # $S0 is "A"
- $I0 = ord $S0 # $I0 is 65, if $S0 is ASCII or UTF-8
+ $I0 = ord $S0 # $I0 is 65, if $S0 is ASCII/UTF-8
=end PIR_FRAGMENT
@@ -559,7 +558,7 @@
=head3 Formatting strings
-X<string formatting>
+X<strings;formatting>
The C<sprintf>X<sprintf opcode> opcode generates a formatted string from a
series of values. It takes two arguments: a string specifying the format, and
@@ -575,7 +574,7 @@
The format string is similar to C's C<sprintf> function with extensions for
Parrot data types. Each format field in the string starts with a C<%> and ends
-with a character specifying the output format. Table 4-2 lists the available
+with a character specifying the output format. Table 4.2 lists the available
output format characters.
=begin table Format characters
@@ -690,7 +689,7 @@
=end table
Each format field supports several specifier options: R<flags>, R<width>,
-R<precision>, and R<size>. Table 4-3 lists the format flags.
+R<precision>, and R<size>. Table 4.3 lists the format flags.
=begin table Format flags
@@ -742,8 +741,9 @@
If either R<width> or R<precision> is an asterisk (C<*>), it takes its
value from the next argument in the PMC.
-The R<size> modifier defines the type of the argument the field takes. Table
-4-4 lists the size flags.
+The R<size> modifier defines the type of the argument the field takes.
+Table 4.4 lists the size flags. The values in the aggregate PMC must
+have a type compatible with the specified R<size>.
=begin table Size flags
@@ -801,15 +801,6 @@
=end table
-The values in the aggregate PMC must have a type compatible with the specified
-R<size>.
-
-The format string of this C<sprintf> example has two format fields. The first,
-C<%#Px>, extracts a PMC argument (C<P>) from the aggregate C<$P2> and formats
-it as a hexadecimal integer (C<x>) with a leading 0x (C<#>). The second format
-field, C<%+2.3Pf>, takes a PMC argument (C<P>) and formats it as a
-floating-point number (C<f>) with a minimum of two whole digits and a maximum
-of three decimal places (C<2.3>) and a leading sign (C<+>):
=begin PIR_FRAGMENT
@@ -818,14 +809,22 @@
=end PIR_FRAGMENT
+The format string of this C<sprintf> example has two format fields. The first,
+C<%#Px>, extracts a PMC argument (C<P>) from the aggregate C<$P2> and formats
+it as a hexadecimal integer (C<x>) with a leading 0x (C<#>). The second format
+field, C<%+2.3Pf>, takes a PMC argument (C<P>) and formats it as a
+floating-point number (C<f>) with a minimum of two whole digits and a maximum
+of three decimal places (C<2.3>) and a leading sign (C<+>).
+
+
The test files F<t/op/string.t> and F<t/op/sprintf.t> have many more
examples of format strings.
=head3 Joining strings
-The C<join> opcode joins the elements of an array PMC into a single
-string. The first argument separates the individual elements of the
-PMC in the final string result.
+The C<join>X<join opcode> opcode joins the elements of an array PMC into
+a single string. The first argument separates the individual elements of
+the PMC in the final string result.
=begin PIR_FRAGMENT
@@ -882,9 +881,6 @@
C<index> also has a three-argument version, where the final argument
defines an offset position for starting the search.
-This example finds the second "eb" in "Beeblebrox" instead of the first,
-because the search skips the first three characters in the string:
-
=begin PIR_FRAGMENT
$I0 = index "Beeblebrox", "eb", 3
@@ -892,6 +888,9 @@
=end PIR_FRAGMENT
+This example finds the second "eb" in "Beeblebrox" instead of the first,
+because the search skips the first three characters in the string.
+
=head3 Bitwise Operations
The numeric bitwise opcodes also have string variants for AND, OR, and XOR:
@@ -913,10 +912,10 @@
=head3 Copy-On-Write
-Strings use copy-on-write (COW) optimizations. A call to C<$S1 = $S0>
-doesn't immediately make a copy of C<$S0>, it only makes both variables
-point to the same string. Parrot doesn't make a copy of the string until
-one of two strings is modified.
+Strings use copy-on-write (COW)X<copy-on-write>X<COW (copy-on-write)>
+optimizations. A call to C<$S1 = $S0> doesn't immediately make a copy of
+C<$S0>, it only makes both variables point to the same string. Parrot
+doesn't make a copy of the string until one of two strings is modified.
=begin PIR_FRAGMENT
@@ -936,27 +935,24 @@
=head3 Encodings and Charsets
X<charset>
-X<ASCII>
-
-Years ago, strings only needed to support the ASCII character set (or charset),
-a mapping of 128 bit patterns to symbols and English-language characters. This
-worked as long as everyone using a computer read and wrote English and only
-used a small handful of punctuation symbols. In other words, it was woefully
-insufficient. A modern string system must manage charsets in order to make
-sense out of all the string data in the world.
-
+X<ASCII character set>
X<encoding>
+Years ago, strings only needed to support the ASCII character set (or
+charset), a mapping of 128 bit patterns to symbols and English-language
+characters. This worked as long as everyone using a computer read and
+wrote English and only used a small handful of punctuation symbols. In
+other words, it was woefully insufficient. A modern string system must
+manage charsets in order to make sense out of all the string data in the
+world. A modern string system must also handle different encodings --
+ways to represent various charsets in memory and on disk.
-A modern string system must also handle different encodings -- ways to
-represent various charsets in memory and on disk.
-
-Every string in Parrot has an associated encoding and charset. The default
+Every string in Parrot has an associated encoding and character set. The default
charset is 8-bit ASCII, which is almost universally supported. Double-quoted
string constants can have an optional prefix specifying the string's encoding
and charset.N<As you might suspect, single-quoted strings do not support this.>
-Parrot tracks information about encoding and character set internally, and
+Parrot tracks information about encoding and charset internally, and
automatically converts strings when necessary to preserve these
-characteristics. Strings may have prefixes of the form C<encoding:charset:>.
+characteristics. Strings constants may have prefixes of the form C<encoding:charset:>.
=begin PIR_FRAGMENT
@@ -967,6 +963,11 @@
=end PIR_FRAGMENT
+X<ISO 8859-1 character set>
+X<Latin 1 character set>
+X<UCS-2 encoding>
+X<UTF-8 encoding>
+X<UTF-16 encoding>
Parrot supports the character sets C<ascii>, C<binary>, C<iso-8859-1>
(Latin 1), and C<unicode> and the encodings C<fixed_8>, C<ucs2>,
C<utf8>, and C<utf18>.
@@ -986,6 +987,8 @@
=head2 Working with PMCs
+X<Polymorphic Containers (PMCs)>
+X<PMCs (Polymorphic Containers)>
Polymorphic Containers (PMCs) are the basis for complex data types and
object-oriented behavior in Parrot. In PIR, any variable that isn't a
low-level integer, number, or string is a PMC. PMC variables act much
@@ -1006,9 +1009,9 @@
parrot", and prints it.
Every PMC has a type that indicates what data it can store and what
-behavior it supports. The C<typeof> opcode reports the type of a PMC.
-When the result is a string variable, C<typeof> returns the name of the
-type:
+behavior it supports. The C<typeof>X<typeof opcode> opcode reports the
+type of a PMC. When the result is a string variable, C<typeof> returns
+the name of the type:
=begin PIR_FRAGMENT
@@ -1023,9 +1026,8 @@
=head3 Scalars
-X<scalars>
X<scalar PMCs>
-
+X<PMCs (Polymorphic Containers);scalar>
In most of the examples shown so far, PMCs duplicate the behavior of integers,
numbers, and strings. Parrot provides a set of PMCs for this exact purpose.
C<Integer>, C<Number>, and C<String> are thin overlays on Parrot's low-level
@@ -1085,7 +1087,6 @@
=end PIR_FRAGMENT
X<unboxing>
-
In the reverse situation, when assigning a PMC to an integer, number, or
string variable, the PMC also has the ability to convert its value to
the low-level type.N<The reverse of "boxing" is "unboxing".>
@@ -1109,8 +1110,9 @@
=end PIR_FRAGMENT
-This example creates C<Integer>, C<Number>, and C<String> PMCs, and
-shows the effect of assigning each one back to a low-level type.
+This example creates C<Integer>X<Integer PMC>, C<Number>X<Number PMC>,
+and C<String>X<String PMC> PMCs, and shows the effect of assigning each
+one back to a low-level type.
Converting a string to an integer or number only makes sense when the contents
of the string are a number. The C<String> PMC will attempt to extract a number
@@ -1118,6 +1120,7 @@
=begin sidebar Type Conversions
+X<type conversions>
Parrot also handles conversions between the low-level types where
possible, converting integers to strings (C<$S0 = $I1>),
numbers to strings (C<$S0 = $N1>), numbers to integers (C<$I0 = $N1>),
@@ -1128,9 +1131,8 @@
=head3 Aggregates
-X<aggregates>
X<aggregate PMCs>
-
+X<PMCs (Polymorphic Containers);aggregate>
PMCs can define complex types that hold multiple values, commonly called
aggregates. Two basic aggregate types are ordered arrays and associative
arrays. The primary difference between these is that ordered arrays use integer
@@ -1141,10 +1143,12 @@
=head4 Ordered Arrays
-Parrot provides several ordered array PMCs, differentiated by what the array
-should store -- booleans, integers, numbers, strings, or other PMCs -- and
-whether the array should maintain a fixed size or dynamically resize for the
-number of elements it stores.
+X<arrays>
+X<ordered arrays>
+Parrot provides several ordered array PMCs, differentiated by whether
+the array should store booleans, integers, numbers, strings, or other
+PMCs, and whether the array should maintain a fixed size or dynamically
+resize for the number of elements it stores.
The core array types are C<FixedPMCArray>, C<ResizablePMCArray>,
C<FixedIntegerArray>, C<ResizableIntegerArray>, C<FixedFloatArray>,
@@ -1212,7 +1216,8 @@
=head4 Associative Arrays
X<associative arrays>
-
+X<hashes>
+X<dictionaries>
An associative array is an unordered aggregate that uses string keys to
identify elements. You may know them as "hash tables", "hashes", "maps", or
"dictionaries". Parrot provides one core associative array PMC, called C<Hash>.
@@ -1228,9 +1233,9 @@
=end PIR_FRAGMENT
-Assigning a C<Hash> PMC (without a key) to an integer result fetches the number
-of elements in the hash.N<You may not set a C<Hash> PMC directly to an integer
-value.>
+Assigning a C<Hash>X<Hash PMC> PMC (without a key) to an integer result
+fetches the number of elements in the hash.N<You may not set a C<Hash>
+PMC directly to an integer value.>
=begin PIR_FRAGMENT
@@ -1264,8 +1269,7 @@
=head4 Iterators
X<iterators>
-X<PMC iterators>
-
+X<PMCs (Polymorphic Containers); iterators>
An iterator extracts values from an aggregate PMC one at a time. Iterators are
most useful in loops which perform an action on every element in an aggregate.
The C<iter> opcode creates a new iterator from an aggregate PMC. It takes one
@@ -1277,8 +1281,9 @@
=end PIR_FRAGMENT
-Alternatively, you can also create an iterator by creating a new C<Iterator>
-PMC, passing the aggregate PMC as an initialization parameter to C<new>:
+Alternatively, you can also create an iterator by creating a new
+C<Iterator>X<Iterator PMC> PMC, passing the aggregate PMC as an
+initialization parameter to C<new>:
=begin PIR_FRAGMENT
@@ -1286,7 +1291,7 @@
=end PIR_FRAGMENT
-The C<shift> opcode extracts the next value from the iterator.
+The C<shift>X<shift opcode> opcode extracts the next value from the iterator.
=begin PIR_FRAGMENT
@@ -1309,9 +1314,9 @@
two constants have no effect on associative array iterators, as their elements
are unordered.
-Load the iterator constants with the C<.include> directive to include
-the file F<iterator.pasm>. To use them, set the iterator PMC to the
-value of the constant:
+Load the iterator constants with the C<.include>X<.include directive>
+directive to include the file F<iterator.pasm>. To use them, set the
+iterator PMC to the value of the constant:
=begin PIR_FRAGMENT
@@ -1385,6 +1390,8 @@
=head4 Multi-level Keys
+X<keys>
+X<multi-level keys>
Aggregates can hold any data type, including other aggregates.
Accessing elements deep within nested data structures is a common
operation, so PIR provides a way to do it in a single instruction.
@@ -1405,7 +1412,7 @@
=end PIR_FRAGMENT
This example builds up a data structure of an associative array
-containing an ordered array. The complex key C<$P0["answer";$I1]>
+containing an ordered array. The complex key C<["answer"; $I1]>
retrieves an element of the array within the hash. You can also set a
value using a complex key:
@@ -1420,9 +1427,7 @@
=head3 Copying and Cloning
-X<PMCs; copy>
-X<PMCs; clone>
-
+X<PMCs (Polymorphic Containers); copying vs. cloning>
PMC registers don't directly store the data for a PMC, they only store a
pointer to the structure that stores the data. As a result, the C<=>
operator doesn't copy the entire PMC, it only copies the pointer to the
@@ -1446,7 +1451,7 @@
C<$P1> refer to the C<String> PMC "Zaphod".
The C<clone> X<clone opcode> opcode makes a deep copy of a PMC, instead
-of copying the pointer like C<=> does.
+of copying the pointer like C<=>X<= operator> does.
=begin PIR_FRAGMENT
@@ -1462,8 +1467,8 @@
This example creates an identical, independent clone of the PMC in
C<$P0> and puts it in C<$P1>. Later changes to C<$P0> have no effect on
the PMC in C<$P1>.N<With low-level strings, the copies created by
-C<clone> are copy-on-write exactly the same as the copy created by
-C<=>.>
+C<clone> are copy-on-writeX<copy-on-write> exactly the same as the copy
+created by C<=>.>
To assign the I<value> of one PMC to another PMC that already exists, use the
C<assign>X<assign opcode> opcode:
@@ -1490,7 +1495,7 @@
=head3 Properties
X<properties>
-X<PMCs; properties>
+X<PMCs (Polymorphic Containers); properties>
PMCs can have additional values attached to them as "properties" of the
PMC. Most properties hold extra metadata about the PMC.
@@ -1558,9 +1563,7 @@
=head3 Vtable Functions
-X<vtables>
X<vtable functions>
-
You may have noticed that a simple operation sometimes has a different effect
on different PMCs. Assigning a low-level integer value to a C<Integer> PMC sets
its integer value of the PMC, but assigning that same integer to an ordered
@@ -1574,6 +1577,7 @@
... Parrot calls the C<set_integer_native> vtable function on the PMC referred
to by register C<$P0>.
+X<polymorphic substitution>
Parrot has a fixed set of vtable functions, so that any PMC can stand in for
any other PMC; they're polymorphic.N<Hence the name "Polymorphic Container".>
Every PMC defines some behavior for every vtable function. The default behavior
@@ -1585,7 +1589,7 @@
=head2 Namespaces
X<namespaces>
-
+X<global variables>
Parrot performs operations on variables stored in small register sets local to
each subroutine. For more complex tasks,N<...and for most high-level languages
that Parrot supports.> it's also useful to have variables that live beyond the
@@ -1593,7 +1597,8 @@
program or restricted to a particular library. Parrot stores long-lived
variables in a hierarchy of namespaces.
-The opcodes C<set_global> and C<get_global> store and fetch a variable in a
+The opcodes C<set_global>X<set_global opcode> and
+C<get_global>X<get_global opcode> store and fetch a variable in a
namespace:
=begin PIR_FRAGMENT
@@ -1665,10 +1670,11 @@
The C<set_global> and C<get_global> opcode operate on the currently selected
namespace. The default top-level namespace is the "root" namespace. The
-C<.namespace> directive allows you to declare any namespace for subsequent
-code. If you select the General Electric namespace, then store or retrieve the
-C<bill> variable without specifying a namespace, you will work with the General
-Electric bill, not the Duck bill.
+C<.namespace>X<.namespace directive> directive allows you to declare any
+namespace for subsequent code. If you select the General Electric
+namespace, then store or retrieve the C<bill> variable without
+specifying a namespace, you will work with the General Electric bill,
+not the Duck bill.
.namespace ["General";"Electric"]
#...
@@ -1682,10 +1688,12 @@
.namespace [ ]
When you need to be absolutely sure you're working with the root namespace
-regardless of what namespace is currently active, use the C<set_root_global>
-and C<get_root_global> opcodes instead of C<set_global> and C<get_global>. This
-example sets and retrieves the variable C<bill> in the Dollar namespace, which
-is directly under the root namespace:
+regardless of what namespace is currently active, use the
+C<set_root_global>X<set_root_global opcode> and
+C<get_root_global>X<get_root_global opcode> opcodes instead of
+C<set_global> and C<get_global>. This example sets and retrieves the
+variable C<bill> in the Dollar namespace, which is directly under the
+root namespace:
=begin PIR_FRAGMENT
@@ -1694,17 +1702,22 @@
=end PIR_FRAGMENT
-To prevent further collisions, each high-level language running on Parrot
-operates within its own virtual namespace root. The default virtual root is
-C<parrot>, and the C<.HLL> directive (for I<H>igh-I<L>evel I<L>anguage) selects
-an alternate virtual root for a particular high-level language:
+X<HLL namespaces>
+X<namespaces; hll>
+To prevent further collisions, each high-level language running on
+Parrot operates within its own virtual namespace root. The default
+virtual root is C<parrot>, and the C<.HLL>X<.HLL directive> directive
+(for I<H>igh-I<L>evel I<L>anguage) selects an alternate virtual root for
+a particular high-level language:
.HLL 'ruby'
-The C<set_hll_global> and C<get_hll_global> opcodes are like C<set_root_global>
-and C<get_root_global>, except they always operate on the virtual root for the
-currently selected HLL. This example stores and retrieves a C<bill> variable in
-the Euro namespace, under the Dutch HLL namespace root:
+The C<set_hll_global>X<set_hll_global opcode> and
+C<get_hll_global>X<get_hll_global opcode> opcodes are like
+C<set_root_global> and C<get_root_global>, except they always operate on
+the virtual root for the currently selected HLL. This example stores and
+retrieves a C<bill> variable in the Euro namespace, under the Dutch HLL
+namespace root:
.HLL 'Dutch'
#...
@@ -1713,15 +1726,17 @@
=head3 NameSpace PMC
+X<NameSpace PMC>
Namespaces are just PMCs. They implement the standard vtable functions
-and a few extra methods. The C<get_namespace> opcode retrieves the
-currently selected namespace as a PMC object:
+and a few extra methods. The C<get_namespace>X<get_namespace opcode>
+opcode retrieves the currently selected namespace as a PMC object:
$P0 = get_namespace
-The C<get_root_namespace> opcode retrieves the namespace object for the root
-namespace. The C<get_hll_namespace> opcode retrieves the virtual root for the
-currently selected HLL.
+The C<get_root_namespace>X<get_root_namespace opcode> opcode retrieves
+the namespace object for the root namespace. The
+C<get_hll_namespace>X<get_hll_namespace opcode> opcode retrieves the
+virtual root for the currently selected HLL.
$P0 = get_root_namespace
$P0 = get_hll_namespace
@@ -1741,46 +1756,50 @@
$P0 = get_hll_namespace ["Euro"]
$P1 = get_global $P0, "bill"
-Namespaces also provide a set of methods to provide more complex behavior than
-the standard vtable functions allow. The C<get_name> method returns the name of
-the namespace as a C<ResizableStringArray>:
+Namespaces also provide a set of methods to provide more complex
+behavior than the standard vtable functions allow. The
+C<get_name>X<get_name method> method returns the name of the namespace
+as a C<ResizableStringArray>:
$P3 = $P0.'get_name'()
-The C<get_parent> method retrieves a namespace object for the parent
-namespace that contains this one:
+The C<get_parent>X<get_parent method> method retrieves a namespace
+object for the parent namespace that contains this one:
$P5 = $P0.'get_parent'()
-The C<get_class> method retrieves any Class PMC associated with the
-namespace:
+The C<get_class>X<get_class method> method retrieves any Class PMC
+associated with the namespace:
$P6 = $P0.'get_class'()
-The C<add_var> and C<find_var> methods store and retrieve variables in a
-namespace in a language-neutral way:
+The C<add_var>X<add_var method> and C<find_var>X<find_var method>
+methods store and retrieve variables in a namespace in a
+language-neutral way:
$P0.'add_var'("bee", $P3)
$P1 = $P0.'find_var'("bee")
-The C<find_namespace> method looks up a namespace, just like the
-C<get_namespace> opcode:
+The C<find_namespace>X<find_namespace method> method looks up a
+namespace, just like the C<get_namespace> opcode:
$P1 = $P0.'find_namespace'("Duck")
-The C<add_namespace> method adds a new namespace as a child of the
-namespace object:
+The C<add_namespace>C<add_namespace method> method adds a new namespace
+as a child of the namespace object:
$P0.'add_namespace'($P1)
-The C<make_namespace> method looks up a namespace as a child of the
-namespace object and returns it. If the requested namespace doesn't
-exist, C<make_namespace> creates a new one and adds it under that name:
+The C<make_namespace>X<make_namespace method> method looks up a
+namespace as a child of the namespace object and returns it. If the
+requested namespace doesn't exist, C<make_namespace> creates a new one
+and adds it under that name:
$P1 = $P0.'make_namespace'("Duck")
=head3 Aliasing
+X<aliasing>
Just like regular assignment, the various operations to store a variable in a
namespace only store a pointer to the PMC. If you modify the local PMC after
storing in a namespace, those changes will also appear in the stored global. To
Modified: trunk/docs/book/pir/ch05_control_structures.pod
==============================================================================
--- trunk/docs/book/pir/ch05_control_structures.pod Tue Jun 30 16:42:20 2009 (r39844)
+++ trunk/docs/book/pir/ch05_control_structures.pod Tue Jun 30 18:24:00 2009 (r39845)
@@ -13,10 +13,12 @@
=head2 Conditionals and Unconditionals
-X<goto instruction> An unconditional branch always jumps to a specified label.
-PIR has only one unconditional branch instruction, C<goto>. In this example,
-the first C<print> statement never runs because the C<goto> always skips over
-it to the label C<skip_all_that>:
+X<goto instruction>
+X<unconditional branch>
+An unconditional branch always jumps to a specified label. PIR has only
+one unconditional branch instruction, C<goto>. In this example, the
+first C<print> statement never runs because the C<goto> always skips
+over it to the label C<skip_all_that>:
=begin PIR_FRAGMENT
@@ -28,13 +30,14 @@
=end PIR_FRAGMENT
+X<conditional branch>
A conditional branch jumps to a specified label only when a particular
condition is true. The condition may be as simple as checking the truth of a
particular variable or as complex as a comparison operation.
-In this example, the C<goto> skips to the label C<maybe_skip> only if the value
-stored in C<$I0> is true. If C<$I0> is false, it will print "might be printed"
-and then print "after branch":
+In this example, the C<if/goto>X<if instruction> skips to the label
+C<maybe_skip> only if the value stored in C<$I0> is true. If C<$I0> is
+false, it will print "might be printed" and then print "after branch":
=begin PIR_FRAGMENT
@@ -48,20 +51,18 @@
=head3 Boolean Truth
X<boolean truth>
-X<PIR values; boolean>
-
Parrot's C<if> and C<unless> instructions evaluate a variable as a boolean to
decide whether to jump. In PIR, an integer is false if it's 0 and true if it's
any non-zero value. A number is false if it's 0.0 and true otherwise. A string
is false if it's the empty string (C<"">) or a string containing only a zero
(C<"0">), and true otherwise. Evaluating a PMC as a boolean calls the vtable
-function C<get_bool> to check if it's true or false, so each PMC is free to
-determine what its boolean value should be.
+function C<get_bool>X<get_bool vtable function> to check if it's true or
+false, so each PMC is free to determine what its boolean value should
+be.
=head3 Comparisons
-X<PIR; comparison operators>
-
+X<comparison operators>
In addition to a simple check for the truth of a variable, PIR provides a
collection of comparison operations for conditional branches. These jump when
the comparison is true.
@@ -89,10 +90,10 @@
comparison, you must build up your condition with a series of instructions that
produce a final, single truth value.
-This example performs two operations, addition and multiplication, then uses
-C<and> to check if the results of both operations were true. The C<and> opcode
-stores a boolean value (0 or 1) in the integer variable C<$I2>; the code uses
-this value in an ordinary truth test:
+This example performs two operations, addition and multiplication, then
+uses C<and>X<and opcode> to check if the results of both operations were
+true. The C<and> opcode stores a boolean value (0 or 1) in the integer
+variable C<$I2>; the code uses this value in an ordinary truth test:
=begin PIR_FRAGMENT
@@ -108,9 +109,7 @@
=head2 If/Else Construct
-C<PIR; if>
-C<PIR; else>
-
+C<if control structure>
High-level languages often use the keywords I<if> and I<else> for simple
conditional control structures. These control structures perform an action when
a condition is true and skip the action when the condition is false. PIR's
@@ -136,7 +135,8 @@
code">. In an assembly language, it's often more straightforward to write
I<"if the condition is true, B<skip> the next few lines of code">. Because of
the reversed logic, you may find it easier to build a simple conditional
-construct using the C<unless> instruction instead of C<if>.
+construct using the C<unless>X<unless instruction> instruction instead
+of C<if>.
=begin PIR_FRAGMENT
@@ -151,6 +151,7 @@
conditional runs. When C<$I0> is false, C<unless> skips over the body of the
conditional by jumping to C<dont_do_it>.
+C<else control structure>
An I<if/else> control structure is easier to build using the C<if> instruction
than C<unless>. To build an I<if/else>, insert the body of the else right
after the first C<if> instruction.
@@ -171,9 +172,7 @@
=head2 Switch Construct
-X<switch>
-X<PIR; switch>
-
+X<switch control structure>
A I<switch> control structure selects one action from a list of possible
actions by comparing a single variable to a series of values until it finds one
that matches. The simplest way to achieve this in PIR is with a series of
@@ -252,15 +251,16 @@
=end PIR_FRAGMENT
Each time through the loop it multiplies C<product> by the current value of the
-C<counter >, decrements the counter, and jumps to the start of the loop. The
+C<counter>, decrements the counter, and jumps to the start of the loop. The
loop ends when C<counter> has counted down to 0.
=head2 While Loop
-X<while-style loop> A I<while> loop tests the condition at the start of the
-loop instead of at the end. This style of loop needs a conditional branch
-combined with an unconditional branch. This example also calculates a
-factorial, but with a I<while> loop:
+X<while loop>
+A I<while> loop tests the condition at the start of the loop instead of
+at the end. This style of loop needs a conditional branch combined with
+an unconditional branch. This example also calculates a factorial, but
+with a I<while> loop:
=begin PIR_FRAGMENT
@@ -290,7 +290,6 @@
=head2 For Loop
X<for loop>
-
A I<for> loop is a counter-controlled loop with three declared components: a
starting value, a condition to determine when to stop, and an operation to step
the counter to the next iteration. A I<for> loop in C looks something like:
Modified: trunk/docs/book/pir/ch06_subroutines.pod
==============================================================================
--- trunk/docs/book/pir/ch06_subroutines.pod Tue Jun 30 16:42:20 2009 (r39844)
+++ trunk/docs/book/pir/ch06_subroutines.pod Tue Jun 30 18:24:00 2009 (r39845)
@@ -2,16 +2,17 @@
=head1 Subroutines
-X<subroutine>
+X<subroutines>
Subroutines in PIR are roughly equivalent to the subroutines or methods
of a high-level language. They're the most basic building block of code
reuse in PIR. Each high-level language has different syntax and
semantics for defining and calling subroutines, so Parrot's subroutines
need to be flexible enough to handle a broad array of behaviors.
-A subroutine declaration starts with the C<.sub> directive and ends with
-the C<.end> directive. This example defines a subroutine named
-C<hello> that prints a string "Hello, Polly.":
+A subroutine declaration starts with the C<.sub>X<.sub directive>
+directive and ends with the C<.end>X<.end directive> directive. This
+example defines a subroutine named C<hello> that prints a string "Hello,
+Polly.":
=begin PIR
@@ -35,16 +36,15 @@
=head2 Modifiers
-X<modifier>
-X<subroutines; modifier>
-
+X<modifiers>
+X<subroutines; modifiers>
A modifier is an annotation to a basic subroutine declarationN<or parameter
declaration> that selects an optional feature. Modifiers all start with a colon
(C<:>). A subroutine can have multiple modifiers.
When you execute a PIR file as a program, Parrot normally runs the first
subroutine it encounters, but you can mark any subroutine as the first
-one to run with the C<:main> modifier:
+one to run with the C<:main>X<:main subroutine modifier> modifier:
=begin PIR
@@ -63,19 +63,23 @@
Parrot will never call C<first> in this program. If you remove the C<:main>
modifier, the code will print "Polly want a cracker?" instead.
-The C<:load> modifier tells Parrot to run the subroutine when it loads the
-current file as a library. The C<:init> modifier tells Parrot to run the
+The C<:load>X<:load subroutine modifier> modifier tells Parrot to run
+the subroutine when it loads the current file as a library. The
+C<:init>X<:init subroutine modifier> modifier tells Parrot to run the
subroutine only when it executes the file as a program (and I<not> as a
-library). The C<:immediate> modifier tells Parrot to run the subroutine as
-soon as it gets compiled. The C<:postcomp> modifier also runs the subroutine
-right after compilation, but only if the subroutine was declared in the main
-program file (when I<not> loaded as a library).
-
-By default, Parrot stores all subroutines in the namespace currently active at
-the point of their declaration. The C<:anon> modifier tells Parrot not to store
-the subroutine in the namespace. The C<:nsentry> modifier stores the subroutine
-in the currenly active namespace with a different name. For example, Parrot
-will store this subroutine in the current namespace as C<bar>, not C<foo>:
+library). The C<:immediate>X<:immediate subroutine modifier> modifier
+tells Parrot to run the subroutine as soon as it gets compiled. The
+C<:postcomp>X<:postcomp subroutine modifier> modifier also runs the
+subroutine right after compilation, but only if the subroutine was
+declared in the main program file (when I<not> loaded as a library).
+
+By default, Parrot stores all subroutines in the namespace currently
+active at the point of their declaration. The C<:anon>X<:anon subroutine
+modifier> modifier tells Parrot not to store the subroutine in the
+namespace. The C<:nsentry>X:nsentry subroutine modifier> modifier stores
+the subroutine in the currenly active namespace with a different name.
+For example, Parrot will store this subroutine in the current namespace
+as C<bar>, not C<foo>:
=begin PIR
@@ -89,6 +93,7 @@
=head2 Parameters and Arguments
+X<subroutines; parameters>
X<.param directive>
The C<.param> directive defines the parameters for the subroutine and
creates local named variables for them (similar to C<.local>):
@@ -141,11 +146,11 @@
=end PIR
-This example defines two local named variables, C<count> and C<product>, and
-assigns them the values 1 and 5. It calls the C<fact> subroutine with both
-variables as arguments. The C<fact> subroutine uses C<.param> to retrieve
-these parameters and C<.return> to return the result. The final printed result
-is 120.
+This example defines two local named variables, C<count> and C<product>,
+and assigns them the values 1 and 5. It calls the C<fact> subroutine
+with both variables as arguments. The C<fact> subroutine uses the
+C<.param> directive to retrieve these parameters and the C<.return>
+directive to return the result. The final printed result is 120.
=head3 Positional Parameters
@@ -180,17 +185,18 @@
=head3 Named Parameters
-X<named parameters> Named parameters are an alternative to positional
-parameters. Instead of passing parameters by their position in the string,
-Parrot assigns arguments to parameters by their name. Consequencly you may
-pass named parameters in any order. Declare named parameters with with the
-C<:named> modifier.
-
-This example declares two named parameters in the subroutine C<shoutout> --
-C<name> and C<years> -- each declared with C<:named> and followed by the name
-to use when pass arguments. The string name can match the parameter name (as
-with the C<name> parameter), but it can also be different (as with the C<years>
-parameter):
+X<named parameters>
+Named parameters are an alternative to positional parameters. Instead of
+passing parameters by their position in the string, Parrot assigns
+arguments to parameters by their name. Consequencly you may pass named
+parameters in any order. Declare named parameters with with the
+C<:named>X<:named parameter modifier> modifier.
+
+This example declares two named parameters in the subroutine C<shoutout>
+-- C<name> and C<years> -- each declared with the C<:named> modifier and
+followed by the name to use when pass arguments. The string name can
+match the parameter name (as with the C<name> parameter), but it can
+also be different (as with the C<years> parameter):
=begin PIR
@@ -229,18 +235,20 @@
=head3 Optional Parameters
-X<optional parameters> Another alternative to the required positional
-parameters is optional parameters. Some parameters are unnecessary for certain
-calls. Parameters marked with the C<:optional> modifier do not produce errors
-about invalid parameter counts if they are not present. A subroutine with
-optional parameters should gracefully handle the missing argument, either by
-providing a default value or by performing an alternate action that doesn't
-need that value.
-
-Checking the value of the optional parameter isn't enough to know whether the
-call passed such an argument, because the user might have passed a null or
-false value intentionally. PIR also provides an C<:opt_flag> modifier for a
-boolean check whether the caller passed an argument:
+X<optional parameters>
+Another alternative to the required positional parameters is optional
+parameters. Some parameters are unnecessary for certain calls.
+Parameters marked with the C<:optional>X<:optional parameter modifier>
+modifier do not produce errors about invalid parameter counts if they
+are not present. A subroutine with optional parameters should
+gracefully handle the missing argument, either by providing a default
+value or by performing an alternate action that doesn't need that value.
+
+Checking the value of the optional parameter isn't enough to know
+whether the call passed such an argument, because the user might have
+passed a null or false value intentionally. PIR also provides an
+C<:opt_flag>X<:opt_flag parameter modifier> modifier for a boolean check
+whether the caller passed an argument:
=begin PIR_FRAGMENT
@@ -278,8 +286,8 @@
Optional parameters can be positional or named parameters. Optional parameters
must appear at the end of the list of positional parameters after all the
-required parameters. An optional I<and> named parameter must immediately
-precede its C<:opt_flag> parameter:
+required parameters. An optional parameter must immediately
+precede its C<:opt_flag> parameter whether it's named or positional:
=begin PIR
@@ -302,13 +310,12 @@
=head3 Aggregating Parameters
-X<subroutines; aggregate>
-X<slurpy>
-
-Another alternative to a sequence of positional parameters is an aggregating
-parameter which bundles a list of arguments into a single parameter. The
-C<:slurpy> created a single array parameter containing all the provided
-arguments:
+X<aggregating parameters>
+X<:slurpy parameter modifier>
+Another alternative to a sequence of positional parameters is an
+aggregating parameter which bundles a list of arguments into a single
+parameter. The C<:slurpy> modifier creates a single array parameter
+containing all the provided arguments:
=begin PIR_FRAGMENT
@@ -348,9 +355,8 @@
=head3 Flattening Arguments
-X<subroutines; flattening>
-X<flattening>
-
+X<flattening arguments>
+X<:flat argument modifier>
A flattening argument breaks up a single argument to fill multiple parameters.
It's the complement of an aggregating parameter. The C<:flat> modifier splits
arguments (and return values) into a flattened list. Passing an array PMC to a
@@ -404,8 +410,7 @@
=head2 Compiling and Loading Libraries
-X<PIR; libraries>
-
+X<libraries>
In addition to running PIR files on the command-line, you can also load a
library of pre-compiled bytecode directly into your PIR source file. The
C<load_bytecode>X<load_bytecode opcode> opcode takes a single argument: the
@@ -421,7 +426,8 @@
=end PIR
-... and compile it to bytecode using the C<-o> command-line switch:
+... and compile it to bytecode using the C<-o> command-line switchX<-o
+command-line switch>:
$ parrot -o foo_file.pbc foo_file.pir
@@ -453,11 +459,10 @@
=head2 Sub PMC
-X<PMCs; Sub>
-
+X<Sub PMC>
Subroutines are a PMC type in Parrot. You can store them in PMC registers and
manipulate them just as you do with other PMCs. Parrot stores subroutines in
-namespaces; retrieve them with the C<get_global> opcode:
+namespaces; retrieve them with the C<get_global>X<get_global opcode> opcode:
=begin PIR_FRAGMENT
@@ -492,6 +497,7 @@
=end PIR_FRAGMENT
+X<inspect opcode>
You can get a hash of the complete metadata for the subroutine:
=begin PIR_FRAGMENT
@@ -539,8 +545,8 @@
=end PIR_FRAGMENT
-The C<arity> method on the sub object returns the total number of defined
-parameters of all varieties:
+The C<arity>X<arity method> method on the sub object returns the total
+number of defined parameters of all varieties:
=begin PIR_FRAGMENT
@@ -548,8 +554,8 @@
=end PIR_FRAGMENT
-The C<get_namespace> method on the sub object fetches the namespace PMC which
-contains the Sub:
+The C<get_namespace>X<get_namespace method> method on the sub object
+fetches the namespace PMC which contains the Sub:
=begin PIR_FRAGMENT
@@ -582,8 +588,10 @@
=begin PIR_FRAGMENT
.local pmc compiler, generated
- compiler = compreg "PIR"
- generated = compiler(".sub foo\n$S1 = 'in eval'\nprint $S1\n.end")
+ .local string source
+ source = ".sub foo\n$S1 = 'in eval'\nprint $S1\n.end"
+ compiler = compreg "PIR"
+ generated = compiler(source)
generated()
say "back again"
@@ -615,7 +623,7 @@
a scope for lexical variables.
While Parrot stores global variables in namespaces, it stores lexical variables
-in lexical padsN<Think of a pad like a house.>. Each lexical scope has its own
+in lexical padsN<Think of a pad like a box to hold a collection of lexical variables.>. Each lexical scope has its own
pad. The C<store_lex> opcode stores a lexical variable in the current pad. The
C<find_lex> opcode retrieves a variable from the current pad:
@@ -623,15 +631,15 @@
$P0 = new "Integer" # create a variable
$P0 = 10 # assign value to it
- store_lex "foo", $P0 # store the var with the variable name "foo"
+ store_lex "foo", $P0 # store with lexical name "foo"
# ...
- $P1 = find_lex "foo" # get the var "foo" into $P1
+ $P1 = find_lex "foo" # get the lexical "foo" into $P1
say $P1 # prints 10
=end PIR_FRAGMENT
-The C<.lex> command defines a local variable that follows these scoping
-rules:
+The C<.lex>X<.lex directive> directive defines a local variable that
+follows these scoping rules:
=begin PIR_FRAGMENT
@@ -642,6 +650,8 @@
=head3 LexPad and LexInfo PMCs
+X<LexPad PMC>
+X<LexInfo PMC>
Parrot uses two different PMCs to store information about a subroutine's
lexical variables: the C<LexPad> PMC and the C<LexInfo> PMC. Neither of these
PMC types are usable directly from PIR code; Parrot uses them internally to
@@ -662,8 +672,8 @@
for each invocation of the subroutine, which allows for recursive
subroutine calls without overwriting lexical variables.
-The C<get_lexinfo> method on a sub retrieves its associated C<LexInfo>
-PMC:
+The C<get_lexinfo>X<get_lexinfo method> method on a sub retrieves its
+associated C<LexInfo> PMC:
=begin PIR_FRAGMENT
@@ -672,12 +682,15 @@
=end PIR_FRAGMENT
-The C<LexInfo> PMC supports a few introspection operations:
+The C<LexInfo> PMC supports a few introspection operations. The
+C<elements> opcode retrieves the number of elements it contains. String
+key access operations retrieve entries from the C<LexInfo> PMC as if it
+were an associative array.
=begin PIR_FRAGMENT
- $I0 = elements $P1 # Get the number of lexical variables from it
- $P0 = $P1["name"] # Get the entry for lexical variable "name"
+ $I0 = elements $P1 # number of lexical variables
+ $P0 = $P1["name"] # lexical variable "name"
=end PIR_FRAGMENT
@@ -686,13 +699,14 @@
=head3 Nested Scopes
+X<nested lexical scopes>
PIR has no separate syntax for blocks or lexical scopes; subroutines
define lexical scopes in PIR. Because PIR disallows nested
C<.sub>/C<.end> declarations, it needs a way to identify which lexical
-scopes are the parents of inner lexical scopes. The C<:outer> modifier
-declares a subroutine as a nested inner lexical scope of another
-existing subroutine. The modifier takes one argument, the name of the
-outer subroutine:
+scopes are the parents of inner lexical scopes. The C<:outer>X<:outer
+subroutine modifier> modifier declares a subroutine as a nested inner
+lexical scope of another existing subroutine. The modifier takes one
+argument, the name of the outer subroutine:
=begin PIR
@@ -707,8 +721,9 @@
=end PIR
Sometimes a name alone isn't sufficient to uniquely identify the outer
-subroutine. The C<:subid> modifier allows the outer subroutine to declare a
-truly unique name usable with C<:outer>:
+subroutine. The C<:subid>X<:subid subroutine modifier> modifier allows
+the outer subroutine to declare a truly unique name usable with
+C<:outer>:
=begin PIR
@@ -722,7 +737,8 @@
=end PIR
-The C<get_outer> method on a C<Sub> PMC retrieves its C<:outer> sub.
+The C<get_outer>X<get_outer method> method on a C<Sub> PMC retrieves its
+C<:outer> sub.
=begin PIR_FRAGMENT
@@ -813,21 +829,21 @@
=head2 Multiple Dispatch
X<multiple dispatch>
-X<multis>
-X<signature>
-
+X<subroutines; signatures>
Multiple dispatch subroutines (or I<multis>) have several variants with the
same name but different sets of parameters. The set of parameters for a
subroutine is its I<signature>. When a multi is called, the dispatch operation
compares the arguments passed in to the signatures of all the variants and
invokes the subroutine with the best match.
-Parrot stores all multiple dispatch subs with the same name in a namespace
-within a single PMC called a C<MultiSub>. The C<MultiSub> is an invokable list
-of subroutines. When a multiple dispatch sub is called, the C<MultiSub> PMC
-searches its list of variants for the best matching candidate.
+Parrot stores all multiple dispatch subs with the same name in a
+namespace within a single PMC called a C<MultiSub>X<MultiSub PMC>. The
+C<MultiSub> is an invokable list of subroutines. When a multiple
+dispatch sub is called, the C<MultiSub> PMC searches its list of
+variants for the best matching candidate.
-The C<:multi> modifier on a C<.sub> declares a C<MultiSub>:
+The C<:multi>X<:multi subroutine modifier> modifier on a C<.sub>
+declares a C<MultiSub>:
=begin PIR
@@ -876,15 +892,15 @@
=begin PIR
- .sub 'Add' :multi(I, I) # Two integers
+ .sub 'Add' :multi(I, I) # two integers
#...
.end
- .sub 'Add' :multi(I, 'Float') # An integer and Float PMC
+ .sub 'Add' :multi(I, 'Float') # integer and Float PMC
#...
.end
- .sub 'Add' :multi('Integer', _) # An Integer PMC and a wildcard
+ .sub 'Add' :multi('Integer', _) # Integer PMC and wildcard
#...
.end
@@ -892,14 +908,13 @@
When you call a C<MultiSub>, Parrot will try to take the most specific
best-match variant, but will fall back to more general variants if it
-cannot find a perfect match. If you call C<'Add'(1, 2)>, Parrot will
-dispatch to the C<(I, I)> variant. If you call C<'Add'(1, "hi")>, Parrot
+cannot find a perfect match. If you call C<Add> with C<(1, 2)>, Parrot will
+dispatch to the C<(I, I)> variant. If you call it with C<(1, "hi")>, Parrot
will match the C<(I, _)> variant, as the string in the second argument
doesn't match C<I> or C<Float>. Parrot can also promote one of the I,
N, or S values to an Integer, Float, or String PMC.
-X<Manhattan distance>
-
+X<Manhattan Distance>
To make the decision about which multi variant to call, Parrot
calculates the I<Manhattan Distance> between the argument signature and
the parameter signature of each variant. Every difference between each
@@ -915,7 +930,7 @@
=head2 Continuations
X<continuations>
-
+X<subroutines; continuations>
Continuations are subroutines that take snapshots of control flow. They are
frozen images of the current execution state of the VM. Once you have a
continuation, you can invoke it to return to the point where the continuation
@@ -933,7 +948,7 @@
The new continuation starts in an undefined state. If you attempt to invoke a
new continuation without initializing it, Parrot will throw an exception. To
prepare the continuation for use, assign it a destination label with the
-C<set_addr> opcode:
+C<set_addr>X<set_addr opcode> opcode:
=begin PIR_FRAGMENT
@@ -959,9 +974,8 @@
=head3 Continuation Passing Style
-X<continuation passing style>
-X<CPS>
-
+X<continuation passing style (CPS)>
+X<CPS (continuation passing style)>
Parrot uses continuations internally for control flow. When Parrot
invokes a subroutine, it creates a continuation representing the current
point in the program. It passes this continuation as an invisible
@@ -971,7 +985,7 @@
to its point of creation any time you want.
This type of flow control -- invoking continuations instead of
-performing bare jumps -- is Continuation Passing Style (CPS).
+performing bare jumps -- is called Continuation Passing Style (CPS).
=head3 Tailcalls
@@ -997,7 +1011,6 @@
two subroutine calls can share a return continuation.
X<.tailcall directive>
-
PIR provides the C<.tailcall> directive to identify similar situations. Use it
in place of the C<.return> directive. C<.tailcall> performs this optimization
by reusing the return continuation of the parent subroutine to make the
@@ -1031,9 +1044,8 @@
=head2 Coroutines
-X<Coroutines>
+X<coroutines>
X<subroutines; coroutines>
-
Coroutines are similar to subroutines except that they have an internal
notion of I<state>. In addition to performing a normal C<.return> to
return control flow back to the caller and destroy the execution
@@ -1048,10 +1060,10 @@
means that the parameter values don't change, even if the next
invocation of the coroutine had different arguments passed in.
-Coroutines look like ordinary subroutines. They do not require any special
-modifier or any special syntax to mark them as being a coroutine. What sets
-them apart is the use of the C<.yield> directive. C<.yield> plays several
-roles:
+Coroutines look like ordinary subroutines. They do not require any
+special modifier or any special syntax to mark them as being a
+coroutine. What sets them apart is the use of the C<.yield>X<.yield
+directive> directive. C<.yield> plays several roles:
=over 4
@@ -1107,23 +1119,23 @@
=head2 Native Call Interface
-The X<NCI (Native Call Interface)> Native Call Interface (NCI) is a
+The X<NCI (native call interface)> Native Call Interface (NCI) is a
special version of the Parrot calling conventions for calling functions
-with a known signature in shared C libraries. This is a simplified
+in shared C libraries with a known signature. This is a simplified
version of the first test in F<t/pmc/nci.t>:
=begin PIR_FRAGMENT
.local pmc library
- library = loadlib "libnci_test" # get object for a shared lib
+ library = loadlib "libnci_test" # library object
say "loaded"
.local pmc ddfunc
- ddfunc = dlfunc library, "nci_dd", "dd" # obtain the function object
+ ddfunc = dlfunc library, "nci_dd", "dd" # function object
say "dlfunced"
.local num result
- result = ddfunc( 4.0 ) # the functions doubles its arg
+ result = ddfunc( 4.0 ) # call the function
ne result, 8.0, nok_1
say "ok 1"
@@ -1135,7 +1147,7 @@
=end PIR_FRAGMENT
-This example shows two new instructions: C<loadlib> and C<dlfunc>. The
+This example shows two new opcodes: C<loadlib> and C<dlfunc>. The
C<loadlib>X<loadlib opcode> opcode obtains a handle for a shared library. It
searches for the shared library in the current directory, in
F<runtime/parrot/dynext>, and in a few other configured directories. It also
@@ -1160,7 +1172,7 @@
=cell Character
-=cell Register set
+=cell Register
=cell C type
Modified: trunk/docs/book/pir/ch07_objects.pod
==============================================================================
--- trunk/docs/book/pir/ch07_objects.pod Tue Jun 30 16:42:20 2009 (r39844)
+++ trunk/docs/book/pir/ch07_objects.pod Tue Jun 30 18:24:00 2009 (r39845)
@@ -2,12 +2,14 @@
=head1 Classes and Objects
-Many of Parrot's core classes -- such as C<Integer> and C<ResizablePMCArray> --
-are written in C, but you can also write your own classes in PIR. PIR doesn't
-have the shiny syntax of high-level object-oriented languages, but it provides
-the necessary features to construct well-behaved objects every bit as powerful
-as those of high-level object systems.
+Many of Parrot's core classes -- such as C<Integer>, C<String>, or
+C<ResizablePMCArray> -- are written in C, but you can also write your
+own classes in PIR. PIR doesn't have the shiny syntax of high-level
+object-oriented languages, but it provides the necessary features to
+construct well-behaved objects every bit as powerful as those of
+high-level object systems.
+X<objects>
Parrot developers often use the word "PMCs" to refer to the objects defined in
C classes and "objects" to refer to the objects defined in PIR. In truth, all
PMCs are objects and all objects are PMCs, so the distinction is a community
@@ -25,8 +27,8 @@
=end PIR_FRAGMENT
-Just as with Parrot's core classes, the C<new> opcode instantiates a new object
-of a named class.
+Just as with Parrot's core classes, the C<new>X<new opcode> opcode
+instantiates a new object of a named class.
=begin PIR_FRAGMENT
@@ -96,8 +98,9 @@
X<methods>
X<classes;methods>
+X<subroutines;methods>
Methods in PIR are subroutines stored in the class object. Define a method with
-the C<.sub> directive and the C<:method> modifier:
+the C<.sub> directive and the C<:method>X<:method subroutine modifier> modifier:
=begin PIR
@@ -112,13 +115,14 @@
This method returns the integer value of the C<bar> attribute of the object
divided by two. Notice that the code never declares the named variable C<self>.
Methods always make the invocant object -- the object on which the method was
-invoked -- available in a local variable called C<self>.
+invoked -- available in a local variable called C<self>X<self variable>.
-The C<:method> modifier adds the subroutine to the class object associated with
-the currently selected namespace, so every class definition file must contain a
-C<.namespace> declaration. Class files for languages may also contain an
-C<.HLL> declaration to associate the namespace with the appropriate high-level
-language:
+The C<:method> modifier adds the subroutine to the class object
+associated with the currently selected namespace, so every class
+definition file must contain a C<.namespace>X<.namespace directive>
+declaration. Class files for languages may also contain an C<.HLL>X<.HLL
+directive> declaration to associate the namespace with the appropriate
+high-level language:
=begin PIR
@@ -155,7 +159,7 @@
you can't pass a C<String> PMC as the method name.
Methods can have multiple arguments and multiple return values just like
-subroutine:
+subroutines:
=begin PIR_FRAGMENT
@@ -163,8 +167,8 @@
=end PIR_FRAGMENT
-The C<can> opcode checks whether an object has a particular method. It
-returns 0 (false) or 1 (true):
+The C<can>X<can opcode> opcode checks whether an object has a particular
+method. It returns 0 (false) or 1 (true):
=begin PIR_FRAGMENT
@@ -222,6 +226,7 @@
=end PIR
+X<new opcode>
Object creation for subclasses is the same as for ordinary classes:
=begin PIR_FRAGMENT
@@ -251,14 +256,16 @@
=head2 Overriding Vtable Functions
-The C<Object> PMC is a core PMC written in C that provides basic
-object-like behavior. Every object instantiated from a PIR class
+X<overriding vtable functions>
+X<vtable functions;overriding>
+The C<Object> PMCX<Object PMC> is a core PMC written in C that provides
+basic object-like behavior. Every object instantiated from a PIR class
inherits a default set of vtable functions from C<Object>, but you can
override them with your own PIR subroutines.
-The C<:vtable> modifier marks a subroutine as a vtable override. As it does
-with methods, Parrot stores vtable overrides in the class associated with the
-currently selected namespace:
+The C<:vtable>X<:vtable subroutine modifier> modifier marks a subroutine
+as a vtable override. As it does with methods, Parrot stores vtable
+overrides in the class associated with the currently selected namespace:
=begin PIR
@@ -285,10 +292,11 @@
implicitly in multiple contexts. For example, creating a new object with C<$P3
= new 'Foo'> will call C<init> with the new C<Foo> object.
-As an example of some of the common vtable overrides, the C<=> operator (or
-C<set> opcode) calls C<Foo>'s C<set_integer_native> vtable function when its
-left-hand side is a C<Foo> object and the argument is an integer literal or
-integer variable:
+As an example of some of the common vtable overrides, the C<=>X<=
+operator> operator (or C<set>X<set opcode> opcode) calls C<Foo>'s
+vtable function C<set_integer_native> when its left-hand side is a
+C<Foo> object and the argument is an integer literal or integer
+variable:
=begin PIR_FRAGMENT
@@ -296,8 +304,8 @@
=end PIR_FRAGMENT
-The C<+> operator (or C<add> opcode) calls C<Foo>'s C<add> vtable function
-when it adds two C<Foo> objects:
+The C<+>X<+ operator> operator (or C<add>X<add opcode> opcode) calls
+C<Foo>'s C<add> vtable function when it adds two C<Foo> objects:
=begin PIR_FRAGMENT
@@ -312,8 +320,8 @@
=end PIR_FRAGMENT
-The C<inc> opcode calls C<Foo>'s C<increment> vtable function when it
-increments a C<Foo> object:
+The C<inc>X<inc opcode> opcode calls C<Foo>'s C<increment> vtable
+function when it increments a C<Foo> object:
=begin PIR_FRAGMENT
@@ -333,13 +341,16 @@
=head2 Introspection
+X<introspection>
+X<classes;introspection>
Classes defined in PIR using the C<newclass> opcode are instances of the
-C<Class> PMC. This PMC contains all the meta-information for the class, such as
-attribute definitions, methods, vtable overrides, and its inheritance
-hierarchy. The C<inspect> opcode provides a way to peek behind the curtain of
-encapsulation to see what makes a class tick. When called with no arguments,
-C<inspect> returns an associative array containing data on all characteristics
-of the class that it chooses to reveal:
+C<Class> PMCX<Class PMC>. This PMC contains all the meta-information for
+the class, such as attribute definitions, methods, vtable overrides, and
+its inheritance hierarchy. The opcode C<inspect>X<inspect opcode>
+provides a way to peek behind the curtain of encapsulation to see what
+makes a class tick. When called with no arguments, C<inspect> returns an
+associative array containing data on all characteristics of the class
+that it chooses to reveal:
=begin PIR_FRAGMENT
@@ -358,7 +369,7 @@
=end PIR_FRAGMENT
Table 7-1 shows the introspection characteristics supported by
-C<inspect> and C<inspect_str>.
+C<inspect>.
=begin table Class Introspection
Modified: trunk/docs/book/pir/ch08_io.pod
==============================================================================
--- trunk/docs/book/pir/ch08_io.pod Tue Jun 30 16:42:20 2009 (r39844)
+++ trunk/docs/book/pir/ch08_io.pod Tue Jun 30 18:24:00 2009 (r39845)
@@ -2,18 +2,15 @@
=head1 I/O
-X<FileHandle>
-X<PMCs; FileHandle>
-X<Socket>
-X<PMCs; Socket>
+X<FileHandle PMC>
Parrot handles all I/O in Parrot with a set of PMCs. The C<FileHandle> PMC
takes care of reading from and writing to files and file-like streams. The
C<Socket> PMC takes care of network I/O.
=head2 FileHandle Opcodes
-The C<open> opcode opens a new filehandle. It takes a string argument,
-which is the path to the file:
+The C<open>X<open opcode> opcode opens a new filehandle. It takes a
+string argument, which is the path to the file:
=begin PIR_FRAGMENT
@@ -38,11 +35,12 @@
C<rw>. A handle that can read and write but will not overwrite the existing
contents uses C<ra> instead.
-The C<close> opcode closes a filehandle when it's no longer needed.
-Closing a filehandle doesn't destroy the object, it only makes that
-filehandle object available for opening a different file.N<It's
-generally not a good idea to manually close the standard input, standard
-output, or standard error filehandles, though you can recreate them.>
+The C<close>X<close opcode> opcode closes a filehandle when it's no
+longer needed. Closing a filehandle doesn't destroy the object, it only
+makes that filehandle object available for opening a different
+file.N<It's generally not a good idea to manually close the standard
+input, standard output, or standard error filehandles, though you can
+recreate them.>
=begin PIR_FRAGMENT
@@ -50,8 +48,8 @@
=end PIR_FRAGMENT
-The C<print> opcode prints a string argument or the string form of an
-integer, number, or PMC to a filehandle:
+The C<print>X<print opcode> opcode prints a string argument or the
+string form of an integer, number, or PMC to a filehandle:
=begin PIR_FRAGMENT
@@ -68,10 +66,10 @@
=end PIR_FRAGMENT
-The C<say> opcode also prints to standard output, but it appends a
-trailing newline to whatever it prints. Another opcode worth mentioning
-is the C<printerr> opcode, which prints an argument to the standard
-error instead of standard output:
+The C<say>X<say opcode> opcode also prints to standard output, but it
+appends a trailing newline to whatever it prints. Another opcode worth
+mentioning is the C<printerr>X<printerr opcode> opcode, which prints an
+argument to the standard error instead of standard output:
=begin PIR_FRAGMENT
@@ -81,10 +79,11 @@
=end PIR_FRAGMENT
-The C<read> and C<readline> opcodes read values from a filehandle. C<read>
-takes an integer value and returns a string with that many characters (if
-possible). C<readline> reads a line of input from a filehandle and returns the
-string without the trailing newline:
+The C<read>X<read opcode> and C<readline>X<readline opcode> opcodes read
+values from a filehandle. C<read> takes an integer value and returns a
+string with that many characters (if possible). C<readline> reads a line
+of input from a filehandle and returns the string without the trailing
+newline:
=begin PIR_FRAGMENT
@@ -102,9 +101,10 @@
=end PIR_FRAGMENT
-The C<getstdin>, C<getstdout>, and C<getstderr> opcodes fetch the
-filehandle objects for the standard streams: standard input, standard
-output, and standard error:
+The C<getstdin>X<getstdin opcode>, C<getstdout>X<getstdout opcode>, and
+C<getstderr>X<getstderr opcode> opcodes fetch the filehandle objects for
+the standard streams: standard input, standard output, and standard
+error:
=begin PIR_FRAGMENT
@@ -152,8 +152,9 @@
=head3 open
-The C<open> method opens a stream in an existing filehandle object. It takes
-two optional string arguments: the name of the file to open and the open mode.
+The C<open>X<open method> method opens a stream in an existing
+filehandle object. It takes two optional string arguments: the name of
+the file to open and the open mode.
=begin PIR_FRAGMENT
@@ -173,8 +174,9 @@
=head3 close
-The C<close> method closes the filehandle. This does not destroy the filehandle
-object; you can reopen it with the C<open> method later.
+The C<close>X<close method> method closes the filehandle. This does not
+destroy the filehandle object; you can reopen it with the C<open> method
+later.
=begin PIR_FRAGMENT
@@ -184,9 +186,9 @@
=head3 is_closed
-The C<is_closed> method checks if the filehandle is closed. It returns
-true if the filehandle has been closed or was never opened, and false if
-it is currently open:
+The C<is_closed>X<is_closed method> method checks if the filehandle is
+closed. It returns true if the filehandle has been closed or was never
+opened, and false if it is currently open:
=begin PIR_FRAGMENT
@@ -196,8 +198,8 @@
=head3 print
-The C<print> method prints a given value to the filehandle. The argument
-can be an integer, number, string, or PMC.
+The C<print>X<print method> method prints a given value to the
+filehandle. The argument can be an integer, number, string, or PMC.
=begin PIR_FRAGMENT
@@ -207,8 +209,8 @@
=head3 puts
-The C<puts> method is similar to C<print>, but it only takes a string
-argument.
+The C<puts>X<puts method> method is similar to C<print>, but it only
+takes a string argument.
=begin PIR_FRAGMENT
@@ -218,7 +220,7 @@
=head3 read
-The C<read> method reads a specified number of bytes from the filehandle
+The C<read>X<read method> method reads a specified number of bytes from the filehandle
object and returns them in a string.
=begin PIR_FRAGMENT
@@ -232,9 +234,9 @@
=head3 readline
-The C<readline> method reads an entire line up to a newline character or
-the end-of-file mark from the filehandle object and returns it in a
-string.
+The C<readline>X<readline method> method reads an entire line up to a
+newline character or the end-of-file mark from the filehandle object and
+returns it in a string.
=begin PIR_FRAGMENT
@@ -244,9 +246,9 @@
=head3 readline_interactive
-The C<readline_interactive> method is useful for command-line scripts.
-It writes the single argument to the method as a prompt to the screen,
-then reads back a line of input.
+The C<readline_interactive>X<readline_interactive method> method is
+useful for command-line scripts. It writes the single argument to the
+method as a prompt to the screen, then reads back a line of input.
=begin PIR_FRAGMENT
@@ -256,9 +258,9 @@
=head3 readall
-The C<readall> method reads an entire file. If the filehandle is closed,
-it will open the file given by the passed in string argument, read the
-entire file, and then close the filehandle.
+The C<readall>X<readall method> method reads an entire file. If the
+filehandle is closed, it will open the file given by the passed in
+string argument, read the entire file, and then close the filehandle.
=begin PIR_FRAGMENT
@@ -278,8 +280,8 @@
=head3 mode
-The C<mode> method returns the current file access mode for the
-filehandle object.
+The C<mode>X<mode method> method returns the current file access mode
+for the filehandle object.
=begin PIR_FRAGMENT
@@ -289,8 +291,8 @@
=head3 encoding
-The C<encoding> method sets or retrieves the string encoding behavior of the
-filehandle.
+The C<encoding>X<encoding method> method sets or retrieves the string
+encoding behavior of the filehandle.
=begin PIR_FRAGMENT
@@ -304,11 +306,11 @@
=head3 buffer_type
-The C<buffer_type> method sets or retrieves the buffering behavior of the
-filehandle object. The argument or return value is one of: C<unbuffered> to
-disable buffering, C<line-buffered> to read or write when the filehandle
-encounters a line ending, or C<full-buffered> to read or write bytes when the
-buffer is full.
+The C<buffer_type>X<buffer_type method> method sets or retrieves the
+buffering behavior of the filehandle object. The argument or return
+value is one of: C<unbuffered> to disable buffering, C<line-buffered> to
+read or write when the filehandle encounters a line ending, or
+C<full-buffered> to read or write bytes when the buffer is full.
=begin PIR_FRAGMENT
@@ -319,8 +321,8 @@
=head3 buffer_size
-The C<buffer_size> method sets or retrieves the buffer size of the
-filehandle object.
+The C<buffer_size>X<buffer_size method> method sets or retrieves the
+buffer size of the filehandle object.
=begin PIR_FRAGMENT
@@ -334,8 +336,8 @@
=head3 flush
-The C<flush> method flushes the buffer if the filehandle object is
-working in a buffered mode.
+The C<flush>X<flush method> method flushes the buffer if the filehandle
+object is working in a buffered mode.
=begin PIR_FRAGMENT
@@ -345,9 +347,9 @@
=head3 eof
-The C<eof> method checks whether a filehandle object has reached the end of the
-current file. It returns true if the filehandle is at the end of the current
-file and false otherwise.
+The C<eof>X<eof method> method checks whether a filehandle object has
+reached the end of the current file. It returns true if the filehandle
+is at the end of the current file and false otherwise.
=begin PIR_FRAGMENT
@@ -357,8 +359,8 @@
=head3 isatty
-The C<isatty> method returns a boolean value whether the filehandle is a
-TTY terminal.
+The C<isatty>X<isatty method> method returns a boolean value whether the
+filehandle is a TTY terminal.
=begin PIR_FRAGMENT
@@ -368,9 +370,9 @@
=head3 get_fd
-The C<get_fd> method returns the integer file descriptor of the current
-filehandle object. Not all operating systems use integer file
-descriptors. Those that don't simply return C<-1>.
+The C<get_fd>X<get_fd method> method returns the integer file descriptor
+of the current filehandle object. Not all operating systems use integer
+file descriptors. Those that don't simply return C<-1>.
=begin PIR_FRAGMENT
Modified: trunk/docs/book/pir/ch09_exceptions.pod
==============================================================================
--- trunk/docs/book/pir/ch09_exceptions.pod Tue Jun 30 16:42:20 2009 (r39844)
+++ trunk/docs/book/pir/ch09_exceptions.pod Tue Jun 30 18:24:00 2009 (r39845)
@@ -17,8 +17,10 @@
=head2 Throwing Exceptions
-The C<throw> opcode throws an exception object. This example creates a new
-C<Exception> object in C<$P0> and throws it:
+X<exceptions; throwing>
+The C<throw>X<throw opcode> opcode throws an exception object. This
+example creates a new C<Exception>X<Exception PMC> object in C<$P0> and
+throws it:
=begin PIR_FRAGMENT
@@ -37,10 +39,11 @@
=end PIR_FRAGMENT
-Other parts of Parrot throw their own exceptions. The C<die> opcode throws a
-fatal (that is, uncatchable) exception. Many opcodes throw exceptions to
-indicate error conditions. The C</> operator (the C<div> opcode), for example,
-throws an exception on attempted division by zero.
+Other parts of Parrot throw their own exceptions. The C<die>X<die
+opcode> opcode throws a fatal (that is, uncatchable) exception. Many
+opcodes throw exceptions to indicate error conditions. The C</> operator
+(the C<div> opcode), for example, throws an exception on attempted
+division by zero.
When no appropriate handlers are available to catch an exception, Parrot treats
it as a fatal error and exits, printing the exception message followed by a
@@ -52,14 +55,15 @@
=head2 Catching Exceptions
X<exception handlers>
-X<exceptions;handling>
+X<exceptions; catching>
Exception handlers catch exceptions, making it possible to recover from
errors in a controlled way, instead of terminating the process entirely.
-The C<push_eh> opcode creates an exception handler and stores it in the list of
-currently active exception handlers. The body of the exception handler is a
-labeled section of code inside the same subroutine as the call to C<push_eh>.
-The opcode takes one argument, the name of the label:
+The C<push_eh>X<push_eh opcode> opcode creates an exception handler
+object and stores it in the list of currently active exception handlers.
+The body of the exception handler is a labeled section of code inside
+the same subroutine as the call to C<push_eh>. The opcode takes one
+argument, the name of the label:
=begin PIR_FRAGMENT
@@ -74,17 +78,17 @@
=end PIR_FRAGMENT
-This example creates an exception handler from the C<my_handler> label, then
-creates a new exception and throws it. At this point, Parrot checks to see if
-there are any appropriate exception handlers in the currently active list. It
-finds C<my_handler> and runs it, printing "caught an exception". The "never
-printed" line never runs, because the exceptional control flow skips right over
-it.
-
-Because Parrot scans the list of active handlers from newest to oldest, you
-don't want to leave exception handlers lying around when you're done with them.
-The C<pop_eh> opcode removes an exception handler from the list of currently
-active handlers:
+This example creates an exception handler with a destination address of
+the C<my_handler> label, then creates a new exception and throws it. At
+this point, Parrot checks to see if there are any appropriate exception
+handlers in the currently active list. It finds C<my_handler> and runs
+it, printing "caught an exception". The "never printed" line never runs,
+because the exceptional control flow skips right over it.
+
+Because Parrot scans the list of active handlers from newest to oldest,
+you don't want to leave exception handlers lying around when you're done
+with them. The C<pop_eh>X<pop_eh opcode> opcode removes an exception
+handler from the list of currently active handlers:
=begin PIR_FRAGMENT
@@ -113,10 +117,11 @@
skips over the code of the exception handler, as it's just a labeled unit of
code within the subruotine.
-The exception object provides access to various attributes of the exception for
-additional information about what kind of error it was, and what might have
-caused it. The C<.get_results()> directive retrieves the C<Exception> object
-from inside the handler:
+The exception object provides access to various attributes of the
+exception for additional information about what kind of error it was,
+and what might have caused it. The directive
+C<.get_results>X<.get_results directive> retrieves the C<Exception>
+object from inside the handler:
=begin PIR_FRAGMENT
@@ -161,7 +166,8 @@
=head2 Exception PMC
-X<exceptions;message>
+X<Exception PMC>
+X<Exception PMC;message>
C<Exception> objects contain several useful pieces of information about the
exception. To set and retrieve the exception message, use the C<message> key on
the exception object:
@@ -181,8 +187,8 @@
=end PIR_FRAGMENT
-X<exceptions;severity>
-X<exceptions;type>
+X<Exception PMC;severity>
+X<Exception PMC;type>
The severity and type of the exception are both integer values:
=begin PIR_FRAGMENT
@@ -192,7 +198,7 @@
=end PIR_FRAGMENT
-X<exceptions;payload>
+X<Exception PMC;payload>
The payload holds any user-defined data attached to the exception object:
=begin PIR_FRAGMENT
@@ -217,14 +223,15 @@
=end PIR_FRAGMENT
-=head2 Exception Handler PMC
+=head2 ExceptionHandler PMC
+X<ExceptionHandler PMC>
Exception handlers are subroutine-like PMC objects, derived from Parrot's
C<Continuation> type. When you use C<push_eh> with a label to create an
exception handler, Parrot creates the handler PMC for you. You can also create
it directly by creating a new C<ExceptionHandler> object, and setting
its destination address to the label of the handler using the
-C<set_addr> opcode:
+C<set_addr> opcodeX<set_addr opcode>:
=begin PIR_FRAGMENT
@@ -238,7 +245,7 @@
=end PIR_FRAGMENT
-X<can_handle>
+X<can_handle method>
C<ExceptionHandler> PMCs have several methods for setting or checking handler
attributes. The C<can_handle> method reports whether the handler is willing or
able to handle a particular exception. It takes one argument, the exception
@@ -250,8 +257,8 @@
=end PIR_FRAGMENT
-X<min_severity>
-X<max_severity>
+X<min_severity method>
+X<max_severity method>
The C<min_severity> and C<max_severity> methods set and retrieve the severity
attributes of the handler, allowing it to refuse to handle any exceptions whose
severity is too high or too low. Both take a single optional integer argument
@@ -265,6 +272,8 @@
=end PIR_FRAGMENT
+X<handle_types method>
+X<handle_types_except method>
The C<handle_types> and C<handle_types_except> methods tell the
exception handler what types of exceptions it should or shouldn't
handle. Both take a list of integer types, which correspond to the
@@ -308,16 +317,17 @@
=head2 Annotations
-X<annotations>
+X<bytecode annotations>
Annotations are pieces of metadata code stored in a bytecode file. This is
especially important when dealing with high-level languages, where annotations
contain information about the HLL's source code such as the current line number
and file name.
-Create an annotation with the C<.annotate> keyword. Annotations consist of a
-key/value pair, where the key is a string and the value is an integer, a
-number, or a string. Bytecode stores annotations as constants in the compiled
-bytecode. Consequently, you may not store PMCs.
+Create an annotation with the C<.annotate>X<.annotate directive>
+directive. Annotations consist of a key/value pair, where the key is a
+string and the value is an integer, a number, or a string. Bytecode
+stores annotations as constants in the compiled bytecode. Consequently,
+you may not store PMCs.
=begin PIR_FRAGMENT
@@ -327,10 +337,11 @@
=end PIR_FRAGMENT
-Annotations exist, or are "in force" throughout the entire subroutine or until
-their redefinition. Creating a new annotation with the same name as an old one
-overwrites it with the new value. The C<annotations> opcode retrieves the
-current hash of annotations:
+Annotations exist, or are "in force" throughout the entire subroutine or
+until their redefinition. Creating a new annotation with the same name
+as an old one overwrites it with the new value. The
+C<annotations>X<annotations opcode> opcode retrieves the current hash of
+annotations:
=begin PIR_FRAGMENT
@@ -350,9 +361,9 @@
=end PIR_FRAGMENT
-Exception objects contain information about the annotations that were in force
-when the exception was thrown. Retrieve them with the C<annotations> method on
-the exception PMC object:
+Exception objects contain information about the annotations that were in
+force when the exception was thrown. Retrieve them with the
+C<annotations>X<annotations method> method on the exception PMC object:
=begin PIR_FRAGMENT
@@ -361,8 +372,8 @@
=end PIR_FRAGMENT
-Exceptions can also include a backtrace to display the program flow to the
-point of the throw:
+Exceptions can also include a backtraceX<backtrace method> to display
+the program flow to the point of the throw:
=begin PIR_FRAGMENT
More information about the parrot-commits
mailing list