Author: lwall
Date: 2009-11-28 21:56:54 +0100 (Sat, 28 Nov 2009)
New Revision: 29204
Modified:
docs/Perl6/Spec/S12-objects.pod
Log:
[S12] major rethink of enums, which are no longer roles (but may still imply
them)
Enum types now supply an explicit .mapping method for masak++
Got rid of stupid translation methods in favor of just using .mapping variants.
(kept normal coercion syntax where it makes sense, though)
Modified: docs/Perl6/Spec/S12-objects.pod
===
--- docs/Perl6/Spec/S12-objects.pod 2009-11-27 17:16:22 UTC (rev 29203)
+++ docs/Perl6/Spec/S12-objects.pod 2009-11-28 20:56:54 UTC (rev 29204)
@@ -13,8 +13,8 @@
Created: 27 Oct 2004
-Last Modified: 25 Nov 2009
-Version: 92
+Last Modified: 28 Nov 2009
+Version: 93
=head1 Overview
@@ -1624,44 +1624,117 @@
=head1 Enums
-An enum is a low-level class that can function as a role or property.
-A given enum value can function as a subtype, a method, or as an ordinary
-value. The names of the values are specified as a parenthesized list, or
-an equivalent angle bracket list:
+An enum 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
+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,
+enum E a b c;
+
+is largely syntactic sugar for:
+
+package E {
+constant a = 0;
+constant b = 1;
+constant c = 2;
+}
+
+(However, the enum 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.
+
+In the Cenum declaration, the keys are specified as a parenthesized
+list, or an equivalent angle bracket list:
+
my enum Day ('Sun','Mon','Tue','Wed','Thu','Fri','Sat');
my enum Day Sun Mon Tue Wed Thu Fri Sat;
-If the first value is unspecified, it defaults to 0. To specify the
-first value, use pair notation (see below).
+The values are generated implicitly by default, but may be also be
+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 type name begins with an uppercase letter, the default
-type is CInt or CStr, depending on the type of the first value.
-If the declared type is lowercase, the default return type is Cint or Cbuf.
+If the declared enum typename (the outer name) 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
+set of native values, so the default value type is Cint or Cbuf.
-The type can be specified:
+The base type can be specified if desired:
my bit enum maybe no yes;
my Int enum day ('Sun','Mon','Tue','Wed','Thu','Fri','Sat');
-my enum day of uint4 Sun Mon Tue Wed Thu Fri Sat;
+our enum day of uint4 Sun Mon Tue Wed Thu Fri Sat;
-For any enum value of an object type, the object itself knows its own
-type, so the C.perl method will return its long name, while C.name
-returns its short name. Other than that, number valued enums act
-just like numbers, while string valued enums act just like strings.
+The declared base type automatically distributes itself to the individual
+constant values. For non-native types, the enum objects are guaranteed
+only to be derived from and convertible to the specified type. The
+actual type of the enum object returned by using the symbol is the enum type
itself.
+Fri.WHAT# Day, not Int.
++Fri# 5
+Fri ~~ Int # True, because derived from Int
+Fri.perl# 'Day::Fri'
+Fri.name# 'Fri'
+Fri.defined # True
+
+Other than that, number valued enums act just like numbers, while
+string valued enums act just like strings. CFri.true is true
+because its value is 5 rather than 0. CSun.true is false.
+
Enums based on native types may be used only for their value, since a
-native value doesn't know its own type. To translate such a value back to its
name
-requires a call to the name method, which must be qualified by the type:
+native value doesn't know its own type.
-3.day::name # returns Wed
+Since methods on native types delegate to their container's type,
