Ignore:
Timestamp:
Nov 27, 2023, 1:06:19 PM (7 months ago)
Author:
JiadaL <j82liang@…>
Branches:
master
Children:
5ddb8bf, da5ac2e
Parents:
69e06ff
Message:

Update enum.tex

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/proposals/enum.tex

    r69e06ff r2d373440  
    289289\end{lstlisting}
    290290
    291 \subsection{Runtime Enumeration}
    292 
    293 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}.
    294 \begin{lstlisting}[ label=lst:runtime_enum ]
    295 const char values[$\,$] = { "Hello", "World" };
    296 const char labels[$\,$] = { "First", "Second" };
    297 Companion(char *) MyEnum = { .values: values, .labels: labels, .length: 2 };
    298 \end{lstlisting}
    299 A runtime enumeration can be used to call enumeration functions.
    300 \begin{lstlisting}[ label=lst:runtime_enum_usage ]
    301 sout | charatstic_string( MyEnum, 1 );
    302 >>> Label: Second; Value: World
    303 \end{lstlisting}
    304 However, a runtime enumeration cannot create an enumeration instance, and it does not support enum-qualified syntax.
    305 \begin{lstlisting}[ label=lst:runtime_enum_usage ]
    306 MyEnum e = MyEnum.First; // Does not work: cannot create an enumeration instance e,
    307                                     // and MyEnum.First is not recognizable
    308 \end{lstlisting}
    309 During the compilation, \CFA adds enumeration declarations to an enumeration symbol table and creates specialized function definitions for \CFA enumeration.
    310 \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.
    311 
    312 \PAB{Not sure how useful this feature is.}
    313 
    314 \section{Enumeration Features}
     291% \subsection{Runtime Enumeration}
     292
     293% 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}.
     294% \begin{lstlisting}[ label=lst:runtime_enum ]
     295% const char values[$\,$] = { "Hello", "World" };
     296% const char labels[$\,$] = { "First", "Second" };
     297% Companion(char *) MyEnum = { .values: values, .labels: labels, .length: 2 };
     298% \end{lstlisting}
     299% A runtime enumeration can be used to call enumeration functions.
     300% \begin{lstlisting}[ label=lst:runtime_enum_usage ]
     301% sout | charatstic_string( MyEnum, 1 );
     302% >>> Label: Second; Value: World
     303% \end{lstlisting}
     304% However, a runtime enumeration cannot create an enumeration instance, and it does not support enum-qualified syntax.
     305% \begin{lstlisting}[ label=lst:runtime_enum_usage ]
     306% MyEnum e = MyEnum.First; // Does not work: cannot create an enumeration instance e,
     307%                                   // and MyEnum.First is not recognizable
     308% \end{lstlisting}
     309% During the compilation, \CFA adds enumeration declarations to an enumeration symbol table and creates specialized function definitions for \CFA enumeration.
     310% \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.
     311
     312% \PAB{Not sure how useful this feature is.}
     313
     314% \section{Enumeration Features}
    315315
    316316A trait is a collection of constraints in \CFA that can be used to describe types.
    317317The \CFA standard library defines traits to categorize types with related enumeration features.
    318318
     319\section{Enumerator Initialization}
     320An enumerator must have a deterministic immutable value, either be explicitly initialized in the enumeration definition, or implicitly initialized by rules.
     321
     322\subsection{C Enumeration Rule}
     323A C enumeration has an integral type. If not initialized, the first enumerator implicitly has the integral value 0, and other enumerators have a value equal to its $predecessor + 1$.
     324
    319325\subsection{Auto Initializable}
    320326\label{s:AutoInitializable}
    321327
    322 TODO: make the initialization rule a separate section.
    323 
    324 If no explicit initializer is given to an enumeration constant, C initializes the first enumeration constant with value 0, and the next enumeration constant has a value equal to its $predecessor + 1$.
     328
    325329\CFA enumerations have the same rule in enumeration constant initialization.
    326330However, only \CFA types that have defined traits for @zero_t@, @one_t@, and an addition operator can be automatically initialized by \CFA.
     
    356360};
    357361\end{lstlisting}
    358 Note, there is no mechanism to prevent an even value for the direct initialization, such as @C = 6@.
     362Note that there is no mechanism to prevent an even value for the direct initialization, such as @C = 6@.
    359363
    360364In \CFA, character, integral, float, and imaginary types are all @AutoInitialiable@.
     
    367371>>> F, o, z
    368372\end{lstlisting}
    369 
     373\section{Enumeration Features}
    370374\subsection{Iteration and Range}
    371375
    372 It is convenient to iterate over a \CFA enumeration, e.g.:
     376It is convenient to iterate over a \CFA enumeration value, e.g.:
    373377\begin{lstlisting}[label=lst:range_functions]
    374 for ( Alphabet alph; Alphabet ) {
    375         printf( "%d ", alph );
    376 }
    377 >>> A B C ...
     378for ( Alphabet alph; Alphabet ) { sout | alph; }
     379>>> A B C ... D
    378380\end{lstlisting}
    379381The for-loop uses the enumeration type @Alphabet@ its range, and iterates through all enumerators in the order defined in the enumeration.
    380382@alph@ is the iterating enumeration object, which returns the value of an @Alphabet@ in this context according to the precedence rule.
    381383
    382 \CFA offers a shorthand for iterating all enumeration constants:
     384\textbullet\ \CFA offers a shorthand for iterating all enumeration constants:
    383385\begin{lstlisting}[label=lst:range_functions]
    384 for ( Alphabet alph ) {
    385         printf( "%d ", alph );
    386 }
    387 >>> A B C ...
    388 \end{lstlisting}
    389 The following different loop-control syntax is supported:
    390 \begin{lstlisting}[label=lst:range_functions]
    391 for ( Alphabet.D )
    392 for ( alph; Alphabet.g ~ Alphabet.z )
    393 for ( Alphabet alph; Alphabet.R ~ Alphabet.X ~ 2 )
    394 \end{lstlisting}
    395 \PAB{Explain what each loop does.}
    396 Notably, the meaning of ``step'' for an iteration has changed for enumeration.
    397 Consider the following example:
    398 \begin{lstlisting}[label=lst:range_functions]
    399 enum(int) Sequence {
    400         A = 10, B = 12, C = 14; 
    401 }
    402 for ( s; Sequence.A ~ Sequence.C ) {
    403         printf( "%d ", s );
    404 }
    405 >>> 10 12 14
    406 
    407 for ( s; Sequence.A ~ Sequence.A ~ 2 ) {
    408         printf( "%d ", s );
    409 }
    410 >>> 10 14
    411 \end{lstlisting}
    412 The range iteration of enumeration does not return the @current_value++@ until it reaches the upper bound.
    413 The semantics is to return the next enumeration constant.
    414 If a stepping is specified, 2 for example, it returns the 2 enumeration constant after the current one, rather than the @current+2@.
     386for ( Alphabet alph ) { sout | alph; }
     387>>> A B C ... D
     388\end{lstlisting}
     389
     390The following are examples for constructing for-control using an enumeration. Note that the type declaration of the iterating variable is optional, because \CFA can infer the type as EnumInstType based on the range expression, and possibly convert it to one of its attribute types.
     391
     392\textbullet\ H is implicit up-to exclusive range [0, H).
     393\begin{lstlisting}[label=lst:range_function_1]
     394for ( alph; Alphabet.D ) { sout | alph; }
     395>>> A B C
     396\end{lstlisting}
     397
     398\textbullet\ ~= H is implicit up-to inclusive range [0,H].
     399\begin{lstlisting}[label=lst:range_function_2]
     400for ( alph; ~= Alphabet.D ) { sout | alph; }
     401>>> A B C D
     402\end{lstlisting}
     403
     404\textbullet\ L ~ H is explicit up-to exclusive range [L,H).
     405\begin{lstlisting}[label=lst:range_function_3]
     406for ( alph; Alphabet.B ~ Alphabet.D  ) { sout | alph; }
     407// for ( Alphabet alph = Alphabet.B; alph < Alphabet.D; alph += 1  ); 1 is one_t
     408>>> B C
     409\end{lstlisting}
     410
     411\textbullet\ L ~= H is explicit up-to inclusive range [L,H].
     412\begin{lstlisting}[label=lst:range_function_4]
     413for ( alph; Alphabet.B ~= Alphabet.D  ) { sout | alph; }
     414>>> B C D
     415\end{lstlisting}
     416
     417\textbullet\ L -~ H is explicit down-to exclusive range [H,L), where L and H are implicitly interchanged to make the range down-to.
     418\begin{lstlisting}[label=lst:range_function_5]
     419for ( alph; Alphabet.D -~ Alphabet.B  ) { sout | alph; }
     420>>> D C
     421\end{lstlisting}
     422
     423\textbullet\ L -~= H is explicit down-to exclusive range [H,L], where L and H are implicitly interchanged to make the range down-to.
     424\begin{lstlisting}[label=lst:range_function_6]
     425for ( alph; Alphabet.D -~= Alphabet.B  ) { sout | alph; }
     426>>> D C B
     427\end{lstlisting}
     428
     429A user can specify the ``step size'' of an iteration. There are two different stepping schemes of enumeration for-loop.
     430\begin{lstlisting}[label=lst:range_function_stepping]
     431enum(int) Sequence { A = 10, B = 12, C = 14, D = 16, D  = 18 };
     432for ( s; Sequence.A ~= Sequence.D ~ 1  ) { sout | alph; }
     433>>> 10 12 14 16 18
     434for ( s; Sequence.A ~= Sequence.D; s+=1  ) { sout | alph; }
     435>>> 10 11 12 13 14 15 16 17 18
     436\end{lstlisting}
     437The first syntax is stepping to the next enumeration constant, which is the default stepping scheme if not explicitly specified. The second syntax, on the other hand, is to call @operator+=@ @one_type@ on the @value( s )@. Therefore, the second syntax is equivalent to
     438\begin{lstlisting}[label=lst:range_function_stepping_converted]
     439for ( typeof( value(Sequence.A) ) s=value( Sequence.A ); s <= Sequence.D; s+=1  ) { sout | alph; }
     440>>> 10 11 12 13 14 15 16 17 18
     441\end{lstlisting}
     442
     443% \PAB{Explain what each loop does.}
    415444
    416445It is also possible to iterate over an enumeration's labels, implicitly or explicitly:
     
    424453\end{lstlisting}
    425454
     455
     456% \subsection{Non-uniform Type}
     457% TODO: Working in Progress, might need to change other sections. Conflict with the resolution right now.
     458
     459% \begin{lstlisting}
     460% enum T( int, char * ) {
     461%     a=42, b="Hello World"
     462% };
     463% \end{lstlisting}
     464% The enum T declares two different types: int and char *. The enumerators of T hold values of one of the declared types.
     465
     466\subsection{Enumeration Inheritance}
     467
     468\begin{lstlisting}[label=lst:EnumInline]
     469enum( char * ) Name { Jack = "Jack", Jill = "Jill" };
     470enum /* inferred */ Name2 { inline Name, Sue = "Sue", Tom = "Tom" };
     471\end{lstlisting}
     472\lstinline{Inline} allows Enumeration Name2 to inherit enumerators from Name1 by containment, and a Name enumeration is a subtype of enumeration Name2. An enumeration instance of type Name can be used where an instance of Name2 is expected.
     473\begin{lstlisting}[label=lst:EnumInline]
     474Name Fred;
     475void f( Name2 );
     476f( Fred );
     477\end{lstlisting}
     478If enumeration A declares @inline B@ in its enumeration body, enumeration A is the "inlining enum" and enumeration B is the "inlined enum".
     479
     480An enumeration can inline at most one other enumeration. The inline declaration must be placed before the first enumerator of the inlining enum. The inlining enum has all the enumerators from the inlined enum, with the same labels, values, and position.
     481\begin{lstlisting}[label=lst:EnumInline]
     482enum /* inferred */ Name2 { inline Name, Sue = "Sue", Tom = "Tom" };
     483// is equivalent to enum Name2 { Jack = "Jack", Jill="Jill", Sue = "Sue", Tom = "Tom" };
     484\end{lstlisting}
     485Name.Jack is equivalent to Name2.Jack. Their attributes are all identical. Opening both Name and Name2 in the same scope will not introduce ambiguity.
     486\begin{lstlisting}[label=lst:EnumInline]
     487with( Name, Name2 ) { Jack; } // Name.Jack and Name2.Jack are equivalent. No ambiguity
     488\end{lstlisting}
     489
    426490\section{Implementation}
    427491
    428 \CFA places the definition of Companion structure and non-parameterized Companion functions in the prelude, visible globally.
     492\subsection{Compiler Representation}
     493The definition of an enumeration is represented by an internal type called @EnumDecl@. At the minimum, it stores all the information needed to construct the companion object. Therefore, an @EnumDecl@ can be represented as the following:
     494\begin{lstlisting}[label=lst:EnumDecl]
     495forall(T)
     496class EnumDecl {
     497    T* values;
     498    char** label;
     499};
     500\end{lstlisting}
     501
     502The internal representation of an enumeration constant is @EnumInstType@.
     503An @EnumInstType@ has a reference to the \CFA-enumeration declaration and the position of the enumeration constant.
     504\begin{lstlisting}[label=lst:EnumInstType]
     505class EnumInstType {
     506    EnumDecl enumDecl;
     507    int position;
     508};
     509\end{lstlisting}
     510In 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>@.
     511
     512% \subsection{Preluede}
     513% \CFA places the definition of Companion structure and non-parameterized Companion functions in the prelude, visible globally.
    429514
    430515\subsection{Declaration}
     
    479564If the @aggregation_name@ is identified as a \CFA enumeration, the compiler checks if @field@ presents in the declared \CFA enumeration.
    480565
    481 \subsection{\lstinline{with} Statement}
    482 
    483 \emph{Work in Progress}
    484 
     566\subsection{\lstinline{with} Clause/Statement}
    485567Instead of qualifying an enumeration expression every time, the @with@ can be used to expose enumerators to the current scope, making them directly accessible.
     568\begin{lstlisting}[label=lst:declaration]
     569enum Color( char * ) { Red="R", Green="G", Blue="B" };
     570enum Animal( int ) { Cat=10, Dog=20 };
     571with ( Color, Animal ) {
     572    char * red_string = Red; // value( Color.Red )
     573    int cat = Cat; // value( Animal.Cat )
     574}
     575\end{lstlisting}
     576The \lstinline{with} might introduce ambiguity to a scope. Consider the example:
     577\begin{lstlisting}[label=lst:declaration]
     578enum Color( char * ) { Red="R", Green="G", Blue="B" };
     579enum RGB( int ) { Red=0, Green=1, Blue=2 };
     580with ( Color, RGB ) {
     581    // int red = Red;
     582}
     583\end{lstlisting}
     584\CFA will not try to resolve the expression with ambiguity. It would report an error. In this case, it is necessary to qualify @Red@ even inside of the \lstinline{with} clause.
    486585
    487586\subsection{Instance Declaration}
    488587
    489 \emph{Work in Progress}
    490 
    491 \begin{lstlisting}[label=lst:declaration]
     588
     589\begin{lstlisting}[label=lst:var_declaration]
    492590enum Sample s1;
    493 Sample s2;
    494 \end{lstlisting}
    495 A declaration of \CFA enumeration instance that has no difference than a C enumeration or other \CFA aggregation.
    496 The compiler recognizes the type of a variable declaration by searching the name in all possible types.
    497 The @enum@ keyword is not necessary but helps to disambiguate types (questionable).
    498 The generated code for a \CFA enumeration declaration is utterly an integer, which is meant to store the position.
    499 \begin{lstlisting}[label=lst:declaration]
     591\end{lstlisting}
     592
     593The declaration \CFA-enumeration variable has the same syntax as the C-enumeration. Internally, such a variable will be represented as an EnumInstType.
     594\begin{lstlisting}[label=lst:declaration_code]
    500595int s1;
    501 int s2;
    502 \end{lstlisting}
    503 
    504 \subsection{Compiler Representation}
    505 
    506 \emph{Work in Progress}
    507 
    508 The internal representation of an enumeration constant is @EnumInstType@.
    509 The minimum information an @EnumInstType@ stores is a reference to the \CFA-enumeration declaration and the position of the enumeration constant.
    510 \begin{lstlisting}[label=lst:EnumInstType]
    511 class EnumInstType {
    512         EnumDecl enumDecl;
    513         int position;
    514 };
    515 \end{lstlisting}
     596\end{lstlisting}
     597The generated code for an enumeration instance is simply an int. It is to hold the position of an enumeration. And usage of variable @s1@ will be converted to return one of its attributes: label, value, or position, with respect to the @Unification@ rule
    516598
    517599\subsection{Unification and Resolution }
    518600
    519 \emph{Work in Progress}
    520601
    521602\begin{lstlisting}
     
    604685@unification( EnumInstType<Colour>, int )@: @position( EnumInstType< Colour > )@
    605686\item
    606 return the enumeration constant at the position 1
     687return the enumeration constant at position 1
    607688\end{enumerate}
    608689\begin{lstlisting}
     
    623704The downside of the precedence rule: @EnumInstType@ $\Rightarrow$ @int ( value )@ $\Rightarrow$ @EnumInstType@ may return a different @EnumInstType@ because the value can be repeated and there is no way to know which one is expected $\Rightarrow$ want uniqueness
    624705
     706\subsection{Casting}
     707Casting an EnumInstType to some other type T works similarly to unify the EnumInstType with T. For example:
     708\begin{lstlisting}
     709enum( int ) Foo { A = 10, B = 100, C = 1000 };
     710(int) Foo.A;
     711\end{lstlisting}
     712The \CFA-compiler unifies @EnumInstType<int>@ with int, with returns @value( Foo.A )@, which has statically known value 10. In other words, \CFA-compiler is aware of a cast expression, and it forms the context for EnumInstType resolution. The expression with type @EnumInstType<int>@ can be replaced by the compile with a constant expression 10, and optionally discard the cast expression.
     713
     714\subsection{Value Conversion}
     715As discussed in section~\ref{lst:var_declaration}, \CFA only saves @position@ as the necessary information. It is necessary for \CFA to generate intermediate code to retrieve other attributes.
     716
     717\begin{lstlisting}
     718Foo a; // int a;
     719int j = a;
     720char * s = a;
     721\end{lstlisting}
     722Assume stores a value x, which cannot be statically determined. When assigning a to j in line 2, the compiler @Unify@ j with a, and returns @value( a )@. The generated code for the second line will be
     723\begin{lstlisting}
     724int j = value( Foo, a )
     725\end{lstlisting}
     726Similarly, the generated code for the third line is
     727\begin{lstlisting}
     728char * j = label( Foo, a )
     729\end{lstlisting}
     730
    625731\end{document}
    626732
Note: See TracChangeset for help on using the changeset viewer.