Added enum documentation and end-to-end output.txt (#634)

Fixes #303. Fixes #555. Continues #506.

SUMMARY.md

@@ -10,6 +10,7 @@
   * [Arrays and Lists](docs/syntax/arrays-and-lists.md)
     * [Sorting](docs/syntax/lists/sorting.md)
   * [Dictionaries](docs/syntax/dictionaries.md)
+  * [Enums](docs/syntax/enums.md)
   * [Classes](docs/syntax/classes.md)
     * [Member Variables](docs/syntax/classes/member-variables.md)
     * [Member Functions](docs/syntax/classes/member-functions.md)

docs/omissions.md

@@ -44,6 +44,24 @@ If any target language doesn't reasonably support a feature, GLS cannot support
             <td></td>
             <td></td>
         </tr>
+        <tr>
+            <th>Enum Values as Numbers</th>
+            <td></td>
+            <td><em>Abnormal</em></td>
+            <td></td>
+            <td></td>
+            <td></td>
+            <td></td>
+        </tr>
+        <tr>
+            <th>Enum Values as Strings</th>
+            <td><em>Missing</em></td>
+            <td></td>
+            <td></td>
+            <td></td>
+            <td></td>
+            <td></td>
+        </tr>
         <tr>
             <th>Enums Without Values</th>
             <td></td>

docs/syntax/enums.md

@@ -0,0 +1,87 @@
+# Enums
+
+An "enum" is a container for a specific set of constant names that should be referenced by variables.
+Languages vary in their understanding of how to represent these fixed values, but all can achieve some equivalent.
+
+Start an enum with `enum start`, which takes in a PascalCase name of an enum.
+Ed an enum with `enum end`.
+
+Each enum value is declared with `enum member`, which takes in a PascalCase name of a member value, an integer value, and if not the last in the enum, a `,` comma.
+
+```gls
+enum start : Direction
+    enum member : Unknown 0 ,
+    enum member : Horizontal 1 ,
+    enum member : Vertical 2
+enum end
+```
+
+In C#:
+
+```csharp
+enum Direction
+{
+    Unknown = 0,
+    Horizontal = 1,
+    Vertical = 2
+}
+```
+
+In Python:
+
+```python
+class Direction(Enum):
+    Unknown = 0
+    Horizontal = 1
+    Vertical = 2
+```
+
+Enum types can be treated as their own type in type declarations.
+Later on, you can reference these enum values using the `enum` command, which takes in a name of an enum and a name of one of its values.
+
+```gls
+variable : direction Direction { enum : Direction Horizontal }
+```
+
+* In C#: `Direction direction = Direction.Horizontal;`
+* In Python: `direction = Direction.Horizontal`
+
+## Exports
+
+You can export enums from the current file by including the `export` keyword before the enum's name.
+
+```gls
+enum start : export Direction
+    enum member : Unknown 0 ,
+    enum member : Horizontal 1 ,
+    enum member : Vertical 2
+enum end
+```
+
+In C#:
+
+```csharp
+public enum Direction
+{
+    Unknown = 0,
+    Horizontal = 1,
+    Vertical = 2
+}
+```
+
+In Python:
+
+```python
+class Direction(Enum):
+    Unknown = 0
+    Horizontal = 1
+    Vertical = 2
+```
+
+## Notes
+
+Enums are fairly non-standard across languages.
+Don't assume member values to be anything more than a visual suggestion:
+
+* Some languages such as C# will sometimes later treat the values as string-likes, such as in string contatenation.
+* Some languages such as Java will skip printing them altogether.

docs/syntax/files.md

@@ -39,5 +39,6 @@ Note that because of [Java](https://docs.oracle.com/javase/specs/jls/se8/html/jl
 You can use any of:
 
 * `class start : export` to export a [class](./classes.md)
+* `enum start : export` to export an [enum](./enums.md)
 * `interface start : export` to export an [interface](./interfaces.md)
 * `standalone functions declare start : export` to export a [standalone function group](./standalone-functions.md)

src/Rendering/Commands/ClassStartCommand.ts

@@ -106,20 +106,20 @@ export class ClassStartCommand extends Command {
      */
     private getForExport(remainingParameters: string[]): string {
         if (remainingParameters[0] !== KeywordNames.Export) {
-            return this.language.syntax.classes.exports.internal;
+            return this.language.syntax.exports.internal;
         }
 
         remainingParameters.shift();
-        let exported = this.language.syntax.classes.exports.exportedLeft;
+        let exported = this.language.syntax.exports.exportedLeft;
 
-        if (this.language.syntax.classes.exports.exportedIncludesName) {
+        if (this.language.syntax.exports.exportedIncludesName) {
             if (remainingParameters[0] === KeywordNames.Abstract) {
                 exported += remainingParameters[1];
             } else {
                 exported += remainingParameters[0];
             }
 
-            exported += this.language.syntax.classes.exports.exportedMiddle;
+            exported += this.language.syntax.exports.exportedMiddle;
         }
 
         return exported;

src/Rendering/Commands/EnumMemberCommand.ts

@@ -1,7 +1,9 @@
 import { LineResults } from "../LineResults";
 import { CommandNames } from "../Names/CommandNames";
+import { KeywordNames } from "../Names/KeywordNames";
 import { Command } from "./Command";
 import { CommandMetadata } from "./Metadata/CommandMetadata";
+import { KeywordParameter } from "./Metadata/Parameters/KeywordParameter";
 import { SingleParameter } from "./Metadata/Parameters/SingleParameter";
 
 /**
@@ -16,7 +18,7 @@ export class EnumMemberCommand extends Command {
         .withParameters([
             new SingleParameter("memberName", "A member of the container enum.", true),
             new SingleParameter("memberValue", "A value for the enum member.", true),
-            new SingleParameter("comma", "Whether a comma is needed.", false),
+            new KeywordParameter([KeywordNames.CommaSymbol], "Whether a comma is needed.", false),
         ]);
 
     /**
@@ -36,9 +38,12 @@ export class EnumMemberCommand extends Command {
         let output = "";
 
         output += parameters[1];
-        output += this.language.syntax.enums.declareValueLeft;
-        output += parameters[2];
-        output += this.language.syntax.enums.declareValueRight;
+
+        if (this.language.syntax.enums.declareValues) {
+            output += this.language.syntax.enums.declareValueLeft;
+            output += parameters[2];
+            output += this.language.syntax.enums.declareValueRight;
+        }
 
         if (parameters.length === 4) {
             output += this.language.syntax.enums.declareCommaRight;

src/Rendering/Commands/EnumStartCommand.ts

@@ -1,8 +1,11 @@
+import { GlsUtilities } from "../../GlsUtilities";
 import { LineResults } from "../LineResults";
 import { CommandNames } from "../Names/CommandNames";
+import { KeywordNames } from "../Names/KeywordNames";
 import { Command } from "./Command";
 import { CommandResult } from "./CommandResult";
 import { CommandMetadata } from "./Metadata/CommandMetadata";
+import { KeywordParameter } from "./Metadata/Parameters/KeywordParameter";
 import { SingleParameter } from "./Metadata/Parameters/SingleParameter";
 import { addLineEnder } from "./Utilities";
 
@@ -16,7 +19,10 @@ export class EnumStartCommand extends Command {
     private static metadata: CommandMetadata = new CommandMetadata(CommandNames.EnumStart)
         .withDescription("Starts an enum declaration")
         .withIndentation([1])
-        .withParameters([new SingleParameter("name", "The name of the enum.", true)]);
+        .withParameters([
+            new KeywordParameter([KeywordNames.Export], "Keyword to export this enum publicly.", false),
+            new SingleParameter("name", "Name of the enum.", true),
+        ]);
 
     /**
      * @returns Metadata on the command.
@@ -32,14 +38,34 @@ export class EnumStartCommand extends Command {
      * @returns Line(s) of code in the language.
      */
     public render(parameters: string[]): LineResults {
-        let line = "";
+        const remainingParameters = parameters.slice(1);
+        const isExported = this.getForExport(remainingParameters);
+        const lines: CommandResult[] = [new CommandResult("", 0)];
+        let lineStart = "";
 
-        line += this.language.syntax.enums.declareStartLeft;
-        line += parameters[1];
+        if (isExported) {
+            lineStart += GlsUtilities.stringReplaceAll(this.language.syntax.enums.declareExternal, "{0}", remainingParameters[0]);
+        } else {
+            lineStart += GlsUtilities.stringReplaceAll(this.language.syntax.enums.declareInternal, "{0}", remainingParameters[0]);
+        }
 
-        const lines: CommandResult[] = [new CommandResult(line, 0)];
-        addLineEnder(lines, this.language.syntax.enums.declareStartRight, 1);
+        addLineEnder(lines, lineStart, 1);
 
-        return new LineResults(lines);
+        return new LineResults(lines).withImports(this.language.syntax.enums.requiredImports);
+    }
+
+    /**
+     * Removes any parameters for exporting the enum.
+     *
+     * @param remainingParameters   Remaining input parameters.
+     * @returns Whether the enum is exported.
+     */
+    private getForExport(remainingParameters: string[]): boolean {
+        if (remainingParameters[0] !== KeywordNames.Export) {
+            return false;
+        }
+
+        remainingParameters.shift();
+        return true;
     }
 }

src/Rendering/Commands/InterfaceStartCommand.ts

@@ -20,7 +20,7 @@ export class InterfaceStartCommand extends Command {
         .withDescription("Starts an interface declaration")
         .withIndentation([1])
         .withParameters([
-            new KeywordParameter([KeywordNames.Export], "Keyword to export this class publicly.", false),
+            new KeywordParameter([KeywordNames.Export], "Keyword to export this interface publicly.", false),
             new SingleParameter("InterfaceName", "The interface name.", true),
             new RepeatingParameters("Parent interfaces", [new SingleParameter("parentInterfaceName", "Names of parent interfaces.", true)]),
         ]);
@@ -75,15 +75,15 @@ export class InterfaceStartCommand extends Command {
      */
     private getForExport(remainingParameters: string[]): string {
         if (remainingParameters[0] !== KeywordNames.Export) {
-            return this.language.syntax.classes.exports.internal;
+            return this.language.syntax.exports.internal;
         }
 
         remainingParameters.shift();
-        let exported = this.language.syntax.classes.exports.exportedLeft;
+        let exported = this.language.syntax.exports.exportedLeft;
 
-        if (this.language.syntax.classes.exports.exportedIncludesName) {
+        if (this.language.syntax.exports.exportedIncludesName) {
             exported += remainingParameters[0];
-            exported += this.language.syntax.classes.exports.exportedMiddle;
+            exported += this.language.syntax.exports.exportedMiddle;
         }
 
         return exported;

src/Rendering/Commands/StandaloneFunctionDeclareStartCommand.ts

@@ -77,11 +77,11 @@ export class StandaloneFunctionDeclareStartCommand extends Command {
         }
 
         if (parameters[1] === KeywordNames.Public) {
-            declaration += this.language.syntax.classes.exports.exportedLeft;
+            declaration += this.language.syntax.exports.exportedLeft;
 
-            if (this.language.syntax.classes.exports.exportedIncludesName) {
+            if (this.language.syntax.exports.exportedIncludesName) {
                 declaration += functionName;
-                declaration += this.language.syntax.classes.exports.exportedMiddle;
+                declaration += this.language.syntax.exports.exportedMiddle;
             }
         }
 

src/Rendering/Commands/StandaloneFunctionsDeclareStartCommand.ts

@@ -59,11 +59,11 @@ export class StandaloneFunctionsDeclareStartCommand extends Command {
         }
 
         if (parameters[1] === KeywordNames.Export) {
-            let declaration: string = this.language.syntax.classes.exports.exportedLeft;
+            let declaration: string = this.language.syntax.exports.exportedLeft;
             declaration += results.commandResults[0].text;
 
-            if (this.language.syntax.classes.exports.exportedIncludesName) {
-                declaration += this.language.syntax.classes.exports.exportedMiddle;
+            if (this.language.syntax.exports.exportedIncludesName) {
+                declaration += this.language.syntax.exports.exportedMiddle;
                 declaration += results.commandResults[0].text;
             }
 

src/Rendering/Languages/CSharp.ts

@@ -7,7 +7,6 @@ import { ProjectProperties } from "./Properties/ProjectProperties";
 import { ArrayNewSizedSyntax } from "./Properties/Syntax/ArrayNewSizedSyntax";
 import { ArraySyntax } from "./Properties/Syntax/ArraySyntax";
 import { BooleanSyntax } from "./Properties/Syntax/BooleanSyntax";
-import { ClassExportSyntax } from "./Properties/Syntax/ClassExportSyntax";
 import { ClassGenericSyntax } from "./Properties/Syntax/ClassGenericSyntax";
 import { ClassMemberFunctionSyntax } from "./Properties/Syntax/ClassMemberFunctionSyntax";
 import { ClassMemberVariableSyntax } from "./Properties/Syntax/ClassMemberVariableSyntax";
@@ -19,6 +18,7 @@ import { ConditionalSyntax } from "./Properties/Syntax/ConditionalSyntax";
 import { DictionarySyntax } from "./Properties/Syntax/DictionarySyntax";
 import { EnumSyntax } from "./Properties/Syntax/EnumSyntax";
 import { ExceptionSyntax } from "./Properties/Syntax/ExceptionSyntax";
+import { ExportSyntax } from "./Properties/Syntax/ExportSyntax";
 import { FileSyntax } from "./Properties/Syntax/FileSyntax";
 import { FunctionSyntax } from "./Properties/Syntax/FunctionSyntax";
 import { ImportSyntax } from "./Properties/Syntax/ImportSyntax";
@@ -136,16 +136,6 @@ export class CSharp extends Language {
         booleans.className = "bool";
     }
 
-    /**
-     * Generates metadata on exported classes.
-     *
-     * @param members   A property container for metadata on exported classes.
-     */
-    protected generateClassExportSyntax(exports: ClassExportSyntax): void {
-        exports.exportedLeft = "public ";
-        exports.internal = "";
-    }
-
     /**
      * Generates metadata on class member functions.
      *
@@ -340,17 +330,18 @@ export class CSharp extends Language {
      * @param enums   A property container for metadata on enums.
      */
     protected generateEnumSyntax(enums: EnumSyntax): void {
-        enums.declareStartLeft = "enum ";
+        enums.declareCommaRight = ",";
+        enums.declareLastRight = "";
+        enums.declareExternal = "public enum {0}\n{";
+        enums.declareInternal = "enum {0}\n{";
         enums.declareValueLeft = " = ";
         enums.declareValueRight = "";
-        enums.declareCommaRight = ",";
+        enums.declareValues = true;
+        enums.isObject = false;
+        enums.requiredImports = [];
         enums.valueLeft = "";
         enums.valueMiddle = ".";
         enums.valueRight = "";
-
-        enums.declareStartRight = "\n{";
-        enums.declareLastRight = "";
-        enums.isObject = false;
     }
 
     /**
@@ -381,6 +372,16 @@ export class CSharp extends Language {
         exceptions.variablePrefix = "";
     }
 
+    /**
+     * Generates metadata on exported constructs.
+     *
+     * @param members   A property container for metadata on exported constructs.
+     */
+    protected generateExportSyntax(exports: ExportSyntax): void {
+        exports.exportedLeft = "public ";
+        exports.internal = "";
+    }
+
     /**
      * Generates metadata on file contents.
      *