Author: lwall
Date: 2009-12-04 20:39:23 +0100 (Fri, 04 Dec 2009)
New Revision: 29256
Modified:
docs/Perl6/Spec/S12-objects.pod
Log:
[S12] rename Enum.name to Enum.key as suggested by david.green++
Distinguish enumeration from enum when discussing enumish types
clarify that the anon enum still evaluates the list at compile time
Modified: docs/Perl6/Spec/S12-objects.pod
===
--- docs/Perl6/Spec/S12-objects.pod 2009-12-04 07:48:20 UTC (rev 29255)
+++ docs/Perl6/Spec/S12-objects.pod 2009-12-04 19:39:23 UTC (rev 29256)
@@ -14,7 +14,7 @@
Created: 27 Oct 2004
Last Modified: 3 Dec 2009
-Version: 94
+Version: 95
=head1 Overview
@@ -1622,13 +1622,14 @@
and other subsets are dynamic. We may refine this in subsequent
versions of Perl.
-=head1 Enums
+=head1 Enumerations
-An enum is a type that facilitates the use of a set of symbols to
+An enumeration is a type that facilitates the use of a set of symbols to
represent a set of constant values. Its most obvious use is the translation
-of those symbols to their corresponding values. Each enum constant
-associates an Ienum key with an Ienum value. Semantically therefore,
-an enum is operates like a constant hash, but since it uses a
+of those symbols to their corresponding values. Each enumeration association
+is a constant pair known as an Ienum, which is of type CEnum.
+Each enum associates an Ienum key with an Ienum value. Semantically
therefore,
+an enumeration operates like a constant hash, but since it uses a
package CStash to hold the entries, it presents itself to the
user's namespace as a typename package containing a set of constant
declarations. That is,
@@ -1643,15 +1644,18 @@
constant c = 2;
}
-(However, the enum declaration supplies extra semantics.)
+(However, the Cenum declaration supplies extra semantics.)
Such constant declarations allow the use of the declared names to
stand in for the values where a value is desired. In addition, since
a constant declaration introduces a name that behaves as a subtype
matching a single value, the enum key can function as a typename in
certain capacities where a typename is required. The name of the
-enum package as a whole is also considered a typename, and may be
-used to represent the set of values.
+enumeration as a whole is also considered a typename, and may be
+used to represent the set of values. (Note that when we wish to
+verbally distinguish the enumeration as a whole from each individual
+enum pair, we use the long term enumeration for the former, despite
+the fact that it is declared using the Cenum keyword.)
In the Cenum declaration, the keys are specified as a parenthesized
list, or an equivalent angle bracket list:
@@ -1663,9 +1667,9 @@
specified explicitly. If the first value is unspecified, it defaults
to 0. To specify the first value, use pair notation (see below).
-If the declared enum typename (the outer name) begins with an uppercase
letter, the enum values
+If the declared enumeration typename begins with an uppercase letter, the enum
values
will be derived from CInt or CStr as appropriate.
-If the enum typename is lowercase, the enum is assumed to be representing a
+If the enumeration typename is lowercase, the enumeration is assumed to be
representing a
set of native values, so the default value type is Cint or Cbuf.
The base type can be specified if desired:
@@ -1683,7 +1687,7 @@
+Fri# 5
Fri ~~ Int # True, because derived from Int
Fri.perl# 'Day::Fri'
-Fri.name# 'Fri'
+Fri.key # 'Fri'
Fri.defined # True
Other than that, number valued enums act just like numbers, while
@@ -1697,7 +1701,7 @@
a variable typed with a native type will know which method to call:
my day $d = 3;
-$d.name # returns Wed
+$d.key # returns Wed
Such declarational forms are not always convenient; to translate
native enum values back to their names operationally, you can pull
@@ -1706,7 +1710,7 @@
constant %dayname := Day.enums.invert;
%dayname{3} # Wed
-The enum type itself is an undefined type object, but supplies convenient
+The enumeration type itself is an undefined type object, but supplies
convenient
methods:
Day.defined # False
@@ -1723,7 +1727,7 @@
CoinFace.enums.invert # (0 = 'Heads', 1 = 'Tails')
CoinFace.enums.[1]# Tails = 1
-The enum typename itself may be used as a coercion operator from either
+The enumeration typename itself may be used as a coercion operator from either
the key name or a value. First the argument is looked up as a key;
if that is found, the enum object is returned. If the key name lookup
fails, the value is looked up using an inverted mapping table (which
@@ -1735,7 +1739,7 @@
Day(3) # Wed constant, found as value
Day.enums.invert{3} # (same thing)
-An anonymous enum just
