[svn:parrot] r40124 - trunk/examples/tutorial
allison at svn.parrot.org
allison at svn.parrot.org
Thu Jul 16 21:36:58 UTC 2009
Author: allison
Date: Thu Jul 16 21:36:57 2009
New Revision: 40124
URL: https://trac.parrot.org/parrot/changeset/40124
Log:
[examples] Documentation fixes for the PIR tutorial examples.
Modified:
trunk/examples/tutorial/01_temp_var.pir
trunk/examples/tutorial/02_local_var.pir
trunk/examples/tutorial/03_temp_var_basic_pmcs.pir
trunk/examples/tutorial/04_pod_comments.pir
trunk/examples/tutorial/10_math_ops.pir
trunk/examples/tutorial/13_logical_ops.pir
trunk/examples/tutorial/20_string_ops.pir
trunk/examples/tutorial/22_string_ops_length.pir
trunk/examples/tutorial/23_string_ops_substr.pir
trunk/examples/tutorial/30_arrays_basic.pir
trunk/examples/tutorial/33_hashes.pir
trunk/examples/tutorial/34_multikey.pir
trunk/examples/tutorial/40_file_ops.pir
Modified: trunk/examples/tutorial/01_temp_var.pir
==============================================================================
--- trunk/examples/tutorial/01_temp_var.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/01_temp_var.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -3,15 +3,15 @@
=head1 Simple Variables
-PIR has two kinds of variables. The most simple kind are Parrot
-registers. Registers are named with a dollar sign followed by a single
-letter type indicator and an integer. The letter in the name corresponds
-to the type of the variable, I for integer, N for number (float), S for
-string, and P for PMC (any kind of object). There are an unlimited
-number of each type of register per call frame, and you can use them
-in any order.
+PIR has two kinds of variables. The most simple kind are
+Parrot register variables. Register variables are named with
+a dollar sign followed by a single letter and an integer.
+The letter corresponds to the type of the variable, I for
+integer, N for number (float), S for string, and P for PMC
+(any kind of object).
-The C<=> symbol can be used to assign a value to one of these registers.
+The C<=> symbol can be used to assign a value to one of
+these register variables.
=cut
Modified: trunk/examples/tutorial/02_local_var.pir
==============================================================================
--- trunk/examples/tutorial/02_local_var.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/02_local_var.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -4,17 +4,17 @@
=head1 Named Variables
The other kind of variables in PIR are named variables.
-You declare these with the .local directive, followed by
-the type of the variable, followed by the name. The types
-of named variables are the same set as the types of
-temporary variables, int for integer, num for numbers
-(floats), string for strings, and pmc for PMCs (objects).
-
-A simple rule of thumb is to use temporary variables
-for variables that are used on 3 or fewer lines of
-code, and named variables for any longer-lived variables.
-This is just a suggestion, but we think it really helps
-improve code readability.
+You declare these with the .local directive, with the type
+of the variable, followed by the name. The types of named
+variables are the same set as the types of register
+variables, int for integer, num for numbers (floats), string
+for strings, and pmc for PMCs (objects).
+
+A simple rule of thumb is to use register variables for
+variables that are used on 3 or fewer lines of code, and
+named variables for any longer-lived variables. This is
+just a suggestion, but we think it really helps improve code
+readability.
=cut
Modified: trunk/examples/tutorial/03_temp_var_basic_pmcs.pir
==============================================================================
--- trunk/examples/tutorial/03_temp_var_basic_pmcs.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/03_temp_var_basic_pmcs.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -3,17 +3,19 @@
=head1 Basic PMC Types
-PMCs are objects, so to use a PMC, you first have to instantiate an object for
-the PMC using the 'new' opcode and the name of the class to instantiate it
-in.
-
-The simple data types have a corresponding PMC type. The Integer type is like
-$I0, the Float type is like $N0, and the String type is like $S0.
-
-Any data type more complex than a simple integer, float, or string (such as an
-array or hash) is also a PMC. Some PMC types are built into Parrot directly.
-Some can be loaded as a dynpmc. Some types are defined as classes in PIR
-code. We'l talk about some of these other types later.
+PMCs are objects, so to use a PMC, you first have to
+instantiate an object for the PMC using the 'new' opcode and
+the name of a class.
+
+The simple data types have a corresponding PMC type. The
+Integer type is like $I0, the Float type is like $N0, and
+the String type is like $S0.
+
+Any data type more complex than a simple integer, float, or
+string (such as an array or hash) is also a PMC. Some PMC
+types are built into Parrot directly. Some can be loaded
+dynamically. Some types are defined as classes in PIR code.
+We'll talk about some of these other types later.
=cut
Modified: trunk/examples/tutorial/04_pod_comments.pir
==============================================================================
--- trunk/examples/tutorial/04_pod_comments.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/04_pod_comments.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -3,7 +3,7 @@
=head1 Pod Documentation
-As you may have noticed, PIR files can contain POD documentation.
+As you may have noticed, PIR files can contain Pod documentation.
=cut
Modified: trunk/examples/tutorial/10_math_ops.pir
==============================================================================
--- trunk/examples/tutorial/10_math_ops.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/10_math_ops.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -3,13 +3,10 @@
=head1 Math Operations
-Many common math operations have simple operator syntax in PIR. Operators
-like C<+>, C<->, C</> and C<*> are all implemented in PIR, but so are a
-few others: C<<< << >>>, C<<< >> >>>, C<|>, C<&>, C<^> and C<%> are some
-examples.
-
-These math operation symbols are all I<infix operators> and are used the
-way most people would expect.
+Many common math operations have simple operator syntax in
+PIR. Operators like C<+>, C<->, C</> and C<*> are all
+implemented in PIR, but so are a few less common ones such
+as C<<< << >>>, C<<< >> >>>, C<|>, C<&>, C<^> and C<%>.
=cut
Modified: trunk/examples/tutorial/13_logical_ops.pir
==============================================================================
--- trunk/examples/tutorial/13_logical_ops.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/13_logical_ops.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -3,14 +3,15 @@
=head1 Logical Operations
-The logical operations are short-circuiting, so if the first argument to an
-'or' is true, the second will never be evaluated because it never needs to
-be. If the first argument to an 'and' operation is false, the other
-arguments are never evaluated either. This is a common logical optimization
-used by compiler designers. PIR only allows variables as arguments to
-operations, so the short-circuiting is only relevant if the argument is a
-PMC that has side-effects on access to the boolean value. We'll talk about
-these side effects later.
+The logical operations are short-circuiting, so if the first
+argument to an 'or' is true, the second will never be
+evaluated. If the first argument to an 'and' operation is
+false, the other arguments are never evaluated either. This
+is a common logical optimization used by compiler designers.
+PIR only allows variables as arguments to operations, so the
+short-circuiting is only relevant if the argument is a PMC
+that has side-effects on access to the boolean value. We'll
+talk about these side effects later.
=cut
Modified: trunk/examples/tutorial/20_string_ops.pir
==============================================================================
--- trunk/examples/tutorial/20_string_ops.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/20_string_ops.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -3,11 +3,12 @@
=head1 String Operations
-Some operations aren't mathematical at all. Concatenation is an example
-of this type of operation that joins two strings together to form a
-larger string. Like the other operations we've seen, concatenation also
-has one form that returns the result, and one form that modifies the
-result in place.
+Some operations are specifically for strings. Concatenation
+is an example of this type of operation; it joins two
+strings together to form a larger string. Like the other
+operations we've seen, concatenation also has one form that
+returns the result, and one form that modifies the result in
+place.
=cut
Modified: trunk/examples/tutorial/22_string_ops_length.pir
==============================================================================
--- trunk/examples/tutorial/22_string_ops_length.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/22_string_ops_length.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -4,8 +4,8 @@
=head1 String Operations (continued)
To find the length of a string in PIR, use the length opcode. It works on
-any register containing a basic Parrot string, but not the String PMC.
-C<length> returns an integer value with 0 being an empty string.
+any variable containing a basic Parrot string, but not the String PMC.
+C<length> returns an integer value, and 0 means an empty string.
=cut
Modified: trunk/examples/tutorial/23_string_ops_substr.pir
==============================================================================
--- trunk/examples/tutorial/23_string_ops_substr.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/23_string_ops_substr.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -10,7 +10,7 @@
position is left out, C<substr> returns all the characters until the
end of the string.
-An optional fourth argument can be a string that will be used to
+An optional fourth argument is a string that will be used to
replace the characters between the start and end positions.
=cut
Modified: trunk/examples/tutorial/30_arrays_basic.pir
==============================================================================
--- trunk/examples/tutorial/30_arrays_basic.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/30_arrays_basic.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -3,15 +3,16 @@
=head1
-PMC registers can contain instances of array or hash data types, or
-more advanced types based on these two. If a PMC type implements the
-array or hash interfaces, they can be accessed using integer or string
-keys.
-
-An array is a type of PMC that contains elements that are indexed by
-number. Array indices must be integer values, not floating point ones.
-Arrays also have a large group of special opcodes that operate on them:
-C<push>, C<pop>, C<shift>, and C<unshift>.
+PMC registers can contain array or hash data types, or more
+advanced types based on these two. If a PMC type implements
+the array or hash interfaces, they can be accessed using
+integer or string keys.
+
+An array is a type of PMC that contains a collection
+elements indexed by number. Array indices must be integer
+values, not floating point ones. Arrays also have a large
+group of special opcodes that operate on them: C<push>,
+C<pop>, C<shift>, and C<unshift>.
=cut
Modified: trunk/examples/tutorial/33_hashes.pir
==============================================================================
--- trunk/examples/tutorial/33_hashes.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/33_hashes.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -1,21 +1,21 @@
# Copyright (C) 2007-2009, Parrot Foundation.
# $Id$
-=head1 Hashes
+=head1 Associative Arrays
-Hashes, also known in some places as "dictionaries" or "associative arrays"
-are like array structures except they are indexed by strings instead of
-integers. There are dedicated Hash PMCs, and a number of other PMCs that
-implement the hash interface as well.
-
-Hash PMCs are indexed using C<[ ]> square brackets with a string inside them.
-
-Arrays are typically considered to be homogeneous structures where all
-elements in the array are of the same type. This is why Parrot has types
-like "FixedIntegerArray" and "ResizableStringArray", which only contain
-integers or strings respectively. Hashes are usually treated as being
-heterogeneous, where each bucket in the hash can contain an element of a
-different type.
+Associative arrays, also known in some places as "dictionaries" or
+"hashes" are like ordered arrays except they are indexed by strings
+instead of integers. Parrot has a dedicated Hash PMC, and a number of
+other PMCs that implement the associative array interface as well.
+
+Associative arryas are indexed using C<[ ]> square brackets with a
+string inside them.
+
+Ordered arrays are often homogeneous structures where all elements in
+the array are of the same type. This is why Parrot has types like
+"FixedIntegerArray" and "ResizableStringArray", which only contain
+integers or strings respectively. Associative arrays are often
+heterogeneous, where each element may be a different type.
=cut
Modified: trunk/examples/tutorial/34_multikey.pir
==============================================================================
--- trunk/examples/tutorial/34_multikey.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/34_multikey.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -3,14 +3,15 @@
=head1 Multi-Level Keys
-Hashes and arrays can be combined in a number of ways to make interesting
-and complex data structures. A hash bucket may contain an array PMC, which
-in turn can contain other arrays or hashes. In these cases, the keys for
-each level can be combined together to form a single unique key for
-a data element in the structure.
+Hashes and arrays can be combined in a number of ways to
+make interesting and complex data structures. A hash may
+contain an array PMC, which in turn can contain other arrays
+or hashes. In these cases, the keys for each level can be
+combined together to form a single unique key for a data
+element in the structure.
-This technique works equally well for arrays-of-arrays, hashes-of-hashes,
-and combination structures as well.
+This technique works equally well for arrays-of-arrays,
+hashes-of-hashes, and combination structures as well.
=cut
Modified: trunk/examples/tutorial/40_file_ops.pir
==============================================================================
--- trunk/examples/tutorial/40_file_ops.pir Thu Jul 16 20:05:06 2009 (r40123)
+++ trunk/examples/tutorial/40_file_ops.pir Thu Jul 16 21:36:57 2009 (r40124)
@@ -3,7 +3,7 @@
=head1 File Operations
-This example demonstrates basic file operations. Note the readmode.
+This example demonstrates basic file operations.
=cut
More information about the parrot-commits
mailing list