Add doc generation support, core.fail

FrontEnd/EVIL.evil/EVIL.evil.csproj

@@ -4,7 +4,7 @@
     <TargetFramework>net7.0</TargetFramework>
     <Nullable>enable</Nullable>
     <AssemblyName>evil</AssemblyName>
-    <Version>1.4.0</Version>
+    <Version>1.5.0</Version>
   </PropertyGroup>
 
   <ItemGroup>

FrontEnd/EVIL.evil/EvmFrontEnd.cs

@@ -30,10 +30,12 @@ public partial class EvmFrontEnd
             { "h|help", "display this message and quit.", (h) => _displayHelpAndQuit = h != null },
             { "v|version", "display compiler and VM version information.", (v) => _displayVersionAndQuit = v != null },
             { "I|include-dir=", "add include directory to the list of search paths.", (I) => _includeHandler.AddIncludeSearchPath(I) },
+            { "g|gen-docs", "generate documentation for all detected native modules.", (g) => _generateModuleDocsAndQuit = g != null }
         };
 
         private static bool _displayHelpAndQuit;
         private static bool _displayVersionAndQuit;
+        private static bool _generateModuleDocsAndQuit; 
 
         public async Task Run(string[] args)
         {
@@ -49,6 +51,12 @@ public async Task Run(string[] args)
                 Terminate(BuildVersionBanner());
             }
 
+            if (_generateModuleDocsAndQuit)
+            {
+                GenerateModuleDocs();
+                Terminate();
+            }
+
             if (!extra.Any())
             {
                 Terminate(
@@ -127,24 +135,7 @@ public async Task Run(string[] args)
                 Console.WriteLine(_compiler.Log.ToString());
             }
 
-            _runtime.RegisterBuiltInModules();
-
-            var moduleStorePath = Path.Combine(AppContext.BaseDirectory, "modules");
-            if (Directory.Exists(moduleStorePath))
-            {
-                try
-                {
-                    _runtimeModuleLoader.RegisterUserRuntimeModules(moduleStorePath);
-                }
-                catch (RuntimeModuleLoadException rmle)
-                {
-                    var sb = new StringBuilder();
-                    sb.AppendLine($"Failed to load user runtime module '{rmle.FilePath}'.");
-                    sb.AppendLine(rmle.ToString());
-
-                    Terminate(sb.ToString(), exitCode: ExitCode.ModuleLoaderFailed);
-                }
-            }
+            RegisterAllModules();
 
             var initChunks = new List<Chunk>();
             foreach (var chunk in script.Chunks)
@@ -209,6 +200,54 @@ private List<string> InitializeOptions(string[] args)
             return fileNames;
         }
 
+        private void GenerateModuleDocs()
+        {
+            var modules = RegisterAllModules();
+            var docsPath = Path.Combine(
+                AppContext.BaseDirectory,
+                "docs"
+            );
+
+            Directory.CreateDirectory(docsPath);
+
+            foreach (var module in modules)
+            {
+                var filePath = Path.Combine(docsPath, $"evrt_{module.FullyQualifiedName}.doc.md");
+                Console.WriteLine($"Generating '{filePath}'...");
+
+                using (var sw = new StreamWriter(filePath))
+                {
+                    sw.WriteLine(module.Describe());
+                }
+            }
+        }
+
+        private List<RuntimeModule> RegisterAllModules()
+        {
+            var ret = new List<RuntimeModule>();
+
+            ret.AddRange(_runtime.RegisterBuiltInModules());
+
+            var moduleStorePath = Path.Combine(AppContext.BaseDirectory, "modules");
+            if (Directory.Exists(moduleStorePath))
+            {
+                try
+                {
+                    ret.AddRange(_runtimeModuleLoader.RegisterUserRuntimeModules(moduleStorePath));
+                }
+                catch (RuntimeModuleLoadException rmle)
+                {
+                    var sb = new StringBuilder();
+                    sb.AppendLine($"Failed to load user runtime module '{rmle.FilePath}'.");
+                    sb.AppendLine(rmle.ToString());
+
+                    Terminate(sb.ToString(), exitCode: ExitCode.ModuleLoaderFailed);
+                }
+            }
+
+            return ret;
+        }
+
         private bool IsValidInitChunk(Chunk chunk)
             => chunk.HasAttribute(AttributeNames.VmInit);
 

Shared/Shared.projitems

@@ -12,6 +12,9 @@
     <Content Include="$(MSBuildThisFileDirectory)..\README.md">
       <Link>README.md</Link>
     </Content>
+    <Content Include="$(MSBuildThisFileDirectory)..\.github\workflows\build-frontend-with-runtime.yml">
+      <Link>.github/workflows/build-frontend-with-runtime.yml</Link>
+    </Content>
     <Content Include="$(MSBuildThisFileDirectory)highlighters\evil_katepart.xml" />
     <Content Include="$(MSBuildThisFileDirectory)highlighters\evil_npp.xml" />
   </ItemGroup>

VirtualMachine/Ceres.Runtime/Ceres.Runtime.csproj

@@ -4,7 +4,7 @@
         <Nullable>enable</Nullable>
         <LangVersion>11.0</LangVersion>
 
-        <Version>0.6.0</Version>
+        <Version>0.7.0</Version>
         <AssemblyName>Ceres.Runtime</AssemblyName>
         <AssemblyTitle>Ceres.Runtime</AssemblyTitle>
         <AllowUnsafeBlocks>true</AllowUnsafeBlocks>

VirtualMachine/Ceres.Runtime/Modules/CoreModule.cs

@@ -148,5 +148,21 @@ private static DynamicValue StackTraceString(Fiber fiber, params DynamicValue[]
 
             return fiber.StackTrace(skipNativeFrames);
         }
+
+        [RuntimeModuleFunction("fail")]
+        [EvilDocFunction(
+            "Terminates VM execution with a user-requested runtime failure. This function does not return."
+        )]
+        [EvilDocArgument(
+            "message",
+            "The message that should be displayed for the failure.",
+            DynamicValueType.String,
+            DefaultValue = "no details provided"
+        )]
+        private static DynamicValue Fail(Fiber fiber, params DynamicValue[] args)
+        {
+            args.OptionalStringAt(0, "no details provided", out var message);
+            throw new UserFailException(message, fiber, args);
+        }
     }
 }

VirtualMachine/Ceres.Runtime/Modules/StringModule.cs

@@ -129,7 +129,7 @@ private static DynamicValue Split(Fiber _, params DynamicValue[] args)
             ReturnType = DynamicValueType.String,
             IsVariadic = true
         )]
-        [EvilDocArgument("separator", "A separator to be inserted between each given value during concatenation.")]
+        [EvilDocArgument("separator", "A separator to be inserted between each given value during concatenation.", DynamicValueType.String)]
         [EvilDocArgument("...", "An arbitrary amount of values to be concatenated into a String.")]
         private static DynamicValue Join(Fiber _, params DynamicValue[] args)
         {
@@ -140,6 +140,13 @@ private static DynamicValue Join(Fiber _, params DynamicValue[] args)
         }
 
         [RuntimeModuleFunction("rep")]
+        [EvilDocFunction(
+            "Repeats the provided String `count` times.",
+            Returns = "A String containing `str` repeated `count` times.",
+            ReturnType = DynamicValueType.String
+        )]
+        [EvilDocArgument("str", "A String to be repeated.", DynamicValueType.String)]
+        [EvilDocArgument("count", "An integer specifying the amount of times to repeat `str`.", DynamicValueType.Number)]
         private static DynamicValue Repeat(Fiber _, params DynamicValue[] args)
         {
             args.ExpectExactly(2)