Changes in / [81da3da4:1c85ffc]

File:

• doc/proposals/enum.tex (modified) (10 diffs)

doc/proposals/enum.tex

@@ -135 +135 @@
 \section{\CFA-Style Enum}
 
-A \CFA enumeration is parameterized by a type specifying each enumerator's type.
+A \CFA enumeration is parameterized by a type, which specifies the type for each enumerator.
 \CFA allows any object type for the enumerators, and values assigned to enumerators must be from the declared type.
 \begin{lstlisting}[label=lst:color]
@@ -154 +154 @@
 \end{lstlisting}
 where the @'!'@ implies the enumerators are \emph{not} projected.
-The enumerators of a scoped enumeration are accessed using qualifications, like the fields of an aggregate.
+The enumerators of a scoped enumeration are accessed using qualification, like the fields of an aggregate.
 % The syntax of $qualified\_expression$ for \CFA-enum is the following:
 % $$<qualified\_expression> := <enum\_type>.<enumerator>$$
@@ -162 +162 @@
 \end{lstlisting}
 
-\section{Enumeration Pseudo-functions}
-Pseudo-functions are function-like operators that do not result in any run-time computations, i.e., like @sizeof@. Instead, the call to functions will be substituted into other expressions in compilation time.
-
 \subsection{Enumerator Attributes}
-The attributes of an enumerator are accessed by pseudo-functions @position@, @value@, and @label@. 
+
+The attributes of an enumerator are accessed by pseudo-functions @position@, @value@, and @label@, i.e., like @sizeof@. 
 \begin{lstlisting}
 int green_pos = @position@( Colour.Green );     // 1
-char * green_value = @value@( Colour.Green ); / "G"
-char * green_label = @label@( Colour.Green ); // "Green"
-\end{lstlisting}
-
-\subsection{enumerate()}
-\begin{lstlisting}[label=lst:c_switch]
-enum(int) C_ENUM { First, Second, Third = First, Fourth };
-int v(C_ENUM e) { 
-    switch( e ) {
-        case First: return 0; break;
-        case Second: return 1; break;
-        // case Thrid: return 2; break;
-        // case Fourth: return 3; break;
-    };
-};
-\end{lstlisting}
-In the @C_ENUM@ example, @Third@ is an alias of @First@ and @Fourth@ is an alias of @Second@. Programmers cannot make case branches for @Third@ and @Fourth@ because the switch statement matches cases by the enumerator's value. Case First and Third, or Second and Fourth, has duplicate case values. 
-
-@enumerate()@ is a pseudo-function that makes the switch statement match by an enumerator instead. 
-\begin{lstlisting}[label=lst:c_switch_enumerate]
-enum(double) C_ENUM { First, Second, Third = First, Fourth };
-C_ENUM variable_a = First, variable_b = Second, variable_c = Thrid, variable_d = Fourth;
-int v(C_ENUM e) { 
-    switch( enumeratate( e ) ) {
-        case First: return e; break;
-        case Second: return value( e ); break;
-        case Thrid: return label( e ); break;
-        case Fourth: return position( e ); break;
-    };
-};
-p(variable_a); // 0
-p(variable_b); // 1
-p(variable_c); // "Third"
-p(variable_d); // 3
-\end{lstlisting}
-
-\section{Enumeration Characteristic}
+char * green_value = @value@( Colour.Green );   // "G"
+char * green_label = @label@( Colour.Green );   // "Green"
+\end{lstlisting}
+There are implicit conversions from an enumerator to its attributes.
+\begin{lstlisting}[label=lst:enum_inst_assign_int]
+int green_pos = Colour.Green;  // 1
+char * green_value = Colour.Green;  // ambiguous
+char * green_label = Colour.Green;  // ambiguous
+\end{lstlisting}
+where a conversion is ambiguous, if the enumerator's type is same as an attribute's type.
+For example, @value( Colour.Green )@ and @label( Colour.Green )@ both have type @char *@.
+Further examples are:
+\begin{cquote}
+\begin{tabular}{ll}
+\begin{lstlisting}
+int monday_pos = Monday;  // ambiguous
+int monday_value = Monday;  // ambiguous
+char * monday_label = Monday;  // "Monday"
+
+\end{lstlisting}
+&
+\begin{lstlisting}
+enum(double) Math { PI = 3.14159, E = 2.718 };
+int pi_pos = PI;  // 0
+double pi_value = PI;  // 3.14159
+char * pi_label = PI;  // "PI"
+\end{lstlisting}
+\end{tabular}
+\end{cquote}
+Here, @position( Monday )@ and @value( Monday )@ both have type @int@, while all attribute types are unique for enumerator @PI@.
+
+When a resolution is ambiguous, a \textit{resolution precedence} applies: $$value > position > label$$
+\CFA uses resolution distance to describe if one type can be used as another. While \CFA calculates the resolution distance between the expected type and types of all three attributes, it would not choose the attribute with the closest distance. Instead, when resolving an enumeration constant, \CFA always chooses value whenever it is a possible resolution (resolution distance is not infinite), followed by position, then label. 
+\begin{lstlisting}[label=lst:enum_inst_precedence]
+enum(double) Foo { Bar };
+int tee = Foo.Bar; // value( Bar );
+\end{lstlisting}
+In the example~\ref{lst:enum_inst_precedence}, while $position( Bar )$ has the closest resolution among the three attributes, $Foo.Bar$ is resolved as $value( Bar )$ because of the resolution precedence.
+
+\PAB{Not sure this is going to work.}
 
 \subsection{Enumerator Storage}
@@ -216 +217 @@
 a \CFA enumeration is always statically typed;
 \item
-it is always resolved as one of its attributes regarding real usage.
+it is always resolved as one of its attributes in terms of real usage.
 \end{enumerate}
 When creating an enumeration instance @colour@ and assigning it with the enumerator @Color.Green@, the compiler allocates an integer variable and stores the position 1.
@@ -231 +232 @@
 These generated functions are $Companion Functions$, they take an $companion$ object and the position as parameters.
 
-\subsection{Enumeration as Value}
-An \CFA enumeration with base type T can be used seamlessly as T. 
-\begin{lstlisting}[label=lst:implicit_conversion]
-char * green_value = Colour.Green; // "G"
-// Is equivalent to 
-char * green_value = value( Color.Green ); "G"
-\end{lstlisting}
-\CFA recognizes @Colour.Green@ as an Expression with enumeration type. [reference to resolution distance] An enumeration type can be safely converted into its value type T, @char *@ in the example. When assigning @Colour.Green@ to a reference @green_value@, which has type @char *@, the compiler adds the distance between an enumeration and type T, and the distance between type T and @char *@. If the distance is safe, \CFA will replace the expression @Colour.Green@ with @value( Colour.Green )@.
-
-\subsection{Variable Overloading}
-\begin{lstlisting}[label=lst:variable_overload]
-void foo(Colour c) { return value( c ); }
-void bar(char * s) { return s; }
-Colour green = Colour.Green; // "G"
-char * green = "Green";
-foo( green ); // "G"
-bar( green ); // "Green"
-\end{lstlisting}
-
-\subsection{Function Overloading}
-\begin{lstlisting}[label=lst:function_overload]
-void foo(Colour c) { return "It is an enum"; }
-void foo(char * s) { return "It is a string"; }
-foo( green ); // "It is an enum"
-\end{lstlisting}
-
-As a consequence, the semantics of using \CFA enumeration as a flag for selection is identical to C enumeration.
-
+\subsection{Companion Object and Companion Function}
+
+\begin{lstlisting}[caption={Enum Type Functions}, label=lst:cforall_enum_functions]
+forall( T )
+struct Companion {
+        const T * const values;
+        const char ** const labels;
+        int length;
+};
+\end{lstlisting}
+\CFA creates a @Companion@ object for every \CFA enumeration.
+A companion object has the same name as the enumeration is defined for.
+A companion object stores values and labels of enumeration constants, in the order of the constants defined in the enumeration.
+
+\CFA generates the definition of companion functions.
+Because \CFA implicitly stores enumeration instance as its position, the companion function @position@ does nothing but return the position it is passed.
+Companions function @value@ and @label@ return the array item at the given position of @values@ and @labels@, respectively.
+\begin{lstlisting}[label=lst:companion_definition]
+int position( Companion o, int pos ) { return pos; }
+T value( Companion o, int pos ) { return o.values[ pos ]; }
+char * label( Companion o, int pos ) { return o.labels[ pos ]; }
+\end{lstlisting}
+Notably, the @Companion@ structure definition, and all companion objects, are visible to users.
+A user can retrieve values and labels defined in an enumeration by accessing the values and labels directly, or indirectly by calling @Companion@ functions @values@ and @labels@
+\begin{lstlisting}[label=lst:companion_definition_values_labels]
+Colour.values; // read the Companion's values
+values( Colour ); // same as Colour.values
+\end{lstlisting}
+
+\subsection{User Define Enumeration Functions}
+
+Companion objects make extending features for \CFA enumeration easy. 
+\begin{lstlisting}[label=lst:companion_user_definition]
+char * charastic_string( Companion o, int position ) { 
+        return sprintf( "Label: %s; Value: %s", label( o, position ), value( o, position) ); 
+}
+printf( charactic_string ( Color, 1 ) );
+>>> Label: Green; Value: G
+\end{lstlisting}
+Defining a function takes a Companion object effectively defines functions for all \CFA enumeration.
+
+The \CFA compiler turns a function call that takes an enumeration instance as a parameter into a function call with a companion object plus a position.
+Therefore, a user can use the syntax with a user-defined enumeration function call:
+\begin{lstlisting}[label=lst:companion_user_definition]
+charactic_string( Color.Green ); // equivalent to charactic_string( Color, 1 )
+>>> Label: Green; Value: G
+\end{lstlisting}
+Similarly, the user can work with the enumeration type itself: (see section ref...)
+\begin{lstlisting}[ label=lst:companion_user_definition]
+void print_enumerators ( Companion o ) { 
+        for ( c : Companion o ) {
+                sout | label (c) | value( c ) ;
+        } 
+}
+print_enumerators( Colour );
+\end{lstlisting}
+
+% \subsection{Runtime Enumeration}
+
+% The companion structure definition is visible to users, and users can create an instance of companion object themselves, which effectively constructs a \textit{Runtime Enumeration}.
+% \begin{lstlisting}[ label=lst:runtime_enum ]
+% const char values[$\,$] = { "Hello", "World" };
+% const char labels[$\,$] = { "First", "Second" };
+% Companion(char *) MyEnum = { .values: values, .labels: labels, .length: 2 };
+% \end{lstlisting}
+% A runtime enumeration can be used to call enumeration functions.
+% \begin{lstlisting}[ label=lst:runtime_enum_usage ]
+% sout | charatstic_string( MyEnum, 1 );
+% >>> Label: Second; Value: World
+% \end{lstlisting}
+% However, a runtime enumeration cannot create an enumeration instance, and it does not support enum-qualified syntax.
+% \begin{lstlisting}[ label=lst:runtime_enum_usage ]
+% MyEnum e = MyEnum.First; // Does not work: cannot create an enumeration instance e, 
+%                                   // and MyEnum.First is not recognizable
+% \end{lstlisting}
+% During the compilation, \CFA adds enumeration declarations to an enumeration symbol table and creates specialized function definitions for \CFA enumeration.
+% \CFA does not recognize runtime enumeration during compilation and would not add them to the enumeration symbol table, resulting in a lack of supports for runtime enumeration.
+
+% \PAB{Not sure how useful this feature is.}
 
 % \section{Enumeration Features}
@@ -283 +335 @@
 trait AutoInitializable {
         void ?()( T & t, zero_t );
-        S ?++( T & t);
+        void ?()( T & t, one_t );
+        S ?+?( T & t, one_t );
 };
 \end{lstlisting}
@@ -290 +343 @@
 struct Odd { int i; };
 void ?()( Odd & t, zero_t ) { t.i = 1; };
-Odd ?++( Odd t1 ) { return Odd( t1.i + 2); };
+void ?()( Odd & t, one_t ) { t.i = 2; };
+Odd ?+?( Odd t1, Odd t2 ) { return Odd( t1.i + t2.i); };
 \end{lstlisting}
 When the type of an enumeration is @AutoInitializable@, implicit initialization is available. 
@@ -298 +352 @@
 };
 \end{lstlisting}
-In the example, no initializer is specified for the first enumeration constant @A@, so \CFA initializes it with the value of @zero_t@, which is 1.
-@B@ and @D@ have the values of their $predecessor++$, where @one_t@ has the value 2.
+In the example, there is no initializer specified for the first enumeration constant @A@, so \CFA initializes it with the value of @zero_t@, which is 1.
+@B@ and @D@ have the values of their $predecessor + one_t$, where @one_t@ has the value 2.
 Therefore, the enumeration is initialized as follows:
 \begin{lstlisting}[label=lst:sample_auto_Initializable_usage_gen]
@@ -456 +510 @@
 In the later discussion, we will use @EnumDecl<T>@ to symbolize a @EnumDecl@ parameterized by type T, and @EnumInstType<T>@ is a declared instance of @EnumDecl<T>@.
 
-\begin{lstlisting}[caption={Enum Type Functions}, label=lst:cforall_enum_data]
-const T * const values;
-const char * label;
-int length;
-\end{lstlisting}
-Companion data are necessary information to represent an enumeration. They are stored as standalone pieces, rather than a structure. Those data will be loaded "on demand".
-Companion data are needed only if the according pseudo-functions are called. For example, the value of the enumeration Workday is loaded only if there is at least one compilation that has call $value(Workday)$. Once the values are loaded, all compilations share these values array to reduce memory usage.
-
-<Investiage: how to implement this is huge>
-
-\subsection{(Rework) Companion Object and Companion Function}
-
-\begin{lstlisting}[caption={Enum Type Functions}, label=lst:cforall_enum_functions]
-forall( T )
-struct Companion {
-        const T * const values;
-        const char * label;
-        int length;
-};
-\end{lstlisting}
-\CFA generates companion objects, an instance of structure that encloses @necessary@ data to represent an enumeration. The size of the companion is unknown at the compilation time, and it "grows" in size to compensate for the @usage@.
-
-The companion object is singleton across the compilation (investigation).  
-
-\CFA generates the definition of companion functions.
-Because \CFA implicitly stores an enumeration instance as its position, the companion function @position@ does nothing but return the position it is passed.
-Companions function @value@ and @label@ return the array item at the given position of @values@ and @labels@, respectively.
-\begin{lstlisting}[label=lst:companion_definition]
-int position( Companion o, int pos ) { return pos; }
-T value( Companion o, int pos ) { return o.values[ pos ]; }
-char * label( Companion o, int pos ) { return o.labels[ pos ]; }
-\end{lstlisting}
-Notably, the @Companion@ structure definition, and all companion objects, are visible to users.
-A user can retrieve values and labels defined in an enumeration by accessing the values and labels directly, or indirectly by calling @Companion@ functions @values@ and @labels@
-\begin{lstlisting}[label=lst:companion_definition_values_labels]
-Colour.values; // read the Companion's values
-values( Colour ); // same as Colour.values
-\end{lstlisting}
-
-\subsection{Companion Traits (experimental)}
-Not sure its semantics yet, and it might replace a companion object.
-\begin{lstlisting}[label=lst:companion_trait]
-forall(T1) {
-    trait Companion(otype T2<otype T1>) {
-        T1 value((otype T2<otype T1> const &);
-        int position(otype T2<otype T1> const &);
-        char * label(otype T2<otype T1> const &);
-    }
-}
-\end{lstlisting}
-All enumerations implicitly implement the Companion trait, an interface to access attributes. The Companion can be a data type because it fulfills to requirements to have concrete instances, which are:
-
-\begin{enumerate}
-  \item The instance of enumeration has a single polymorphic type.
-  \item Each assertion should use the type once as a parameter.
-\end{enumerate}
-
-\begin{lstlisting}
-enum(int) Weekday {
-    Monday=10, Tuesday, ...
-};
-
-T value( enum Weekday<T> & this);
-int position( enum Weekday<T> & this )
-char * label( enum Weekday<T> & this )
-
-trait Companion obj = (enum(int)) Workday.Weekday;
-value(obj); // 10
-\end{lstlisting}
-The enumeration comes with default implementation to the Companion traits functions. The usage of Companion functions would make \CFA allocates and initializes the necessary companion arrays, and return the data at the position represented by the enumeration.
-(...)
-
-\subsection{User Define Enumeration Functions}
-
-Companion objects make extending features for \CFA enumeration easy. 
-\begin{lstlisting}[label=lst:companion_user_definition]
-char * charastic_string( Companion o, int position ) { 
-        return sprintf( "Label: %s; Value: %s", label( o, position ), value( o, position) ); 
-}
-printf( charactic_string ( Color, 1 ) );
->>> Label: Green; Value: G
-\end{lstlisting}
-Defining a function takes a Companion object effectively defines functions for all \CFA enumeration.
-
-The \CFA compiler turns a function call that takes an enumeration instance as a parameter into a function call with a companion object plus a position.
-Therefore, a user can use the syntax with a user-defined enumeration function call:
-\begin{lstlisting}[label=lst:companion_user_definition]
-charactic_string( Color.Green ); // equivalent to charactic_string( Color, 1 )
->>> Label: Green; Value: G
-\end{lstlisting}
-Similarly, the user can work with the enumeration type itself: (see section ref...)
-\begin{lstlisting}[ label=lst:companion_user_definition]
-void print_enumerators ( Companion o ) { 
-        for ( c : Companion o ) {
-                sout | label (c) | value( c ) ;
-        } 
-}
-print_enumerators( Colour );
-\end{lstlisting}
-
+% \subsection{Preluede}
+% \CFA places the definition of Companion structure and non-parameterized Companion functions in the prelude, visible globally.
 
 \subsection{Declaration}
@@ -773 +729 @@
 \end{lstlisting}
 
-
 \end{document}