Continued documenting the code (#16)

new/AutoItInterpreter/AssemblyInfo.cs

@@ -1,15 +1,15 @@
 
 //////////////////////////////////////////////////////////////////////////
-// Auto-generated 2020-07-26 17:04:48.009                               //
+// Auto-generated 2020-07-27 01:57:30.012                               //
 // ANY CHANGES TO THIS DOCUMENT WILL BE LOST UPON RE-GENERATION         //
 //////////////////////////////////////////////////////////////////////////
 
 using System.Reflection;
 using System;
 
-[assembly: AssemblyVersion("0.6.1256.7328")]
-[assembly: AssemblyFileVersion("0.6.1256.7328")]
-[assembly: AssemblyInformationalVersion("cdfd24e8c9341f9fc41540bef89d37e540605174")]
+[assembly: AssemblyVersion("0.6.1257.7329")]
+[assembly: AssemblyFileVersion("0.6.1257.7329")]
+[assembly: AssemblyInformationalVersion("f3c8f7753e53011c5fac5224b49c3724c68f2759")]
 [assembly: AssemblyCompany("Unknown6656")]
 [assembly: AssemblyCopyright("Copyright © 2018 - 2020, Unknown6656")]
 [assembly: AssemblyProduct("AutoIt3 Interpreter by Unknown6656")]
@@ -35,11 +35,11 @@ public static class __module__
     /// <summary>
     /// The interpreter's current version.
     /// </summary>
-    public static Version? InterpreterVersion { get; } = Version.Parse("0.6.1256.7328");
+    public static Version? InterpreterVersion { get; } = Version.Parse("0.6.1257.7329");
     /// <summary>
     /// The Git hash associated with the current build.
     /// </summary>
-    public const string GitHash = "cdfd24e8c9341f9fc41540bef89d37e540605174";
+    public const string GitHash = "f3c8f7753e53011c5fac5224b49c3724c68f2759";
     /// <summary>
     /// The URL of this project's Git(Hub) repository.
     /// </summary>

new/AutoItInterpreter/MainProgram.cs

@@ -135,7 +135,7 @@ public static int Start(string[] argv)
 
             Console.CancelKeyPress += (_, e) =>
             {
-                Interpreter[] instances = Interpreter.Instances;
+                Interpreter[] instances = Interpreter.ActiveInstances;
 
                 e.Cancel = instances.Length > 0;
 

new/AutoItInterpreter/Runtime/Interpreter.cs

@@ -1,5 +1,4 @@
-using System.Collections.Concurrent;
-using System.Collections.Generic;
+using System.Collections.Generic;
 using System.Linq;
 using System;
 
@@ -17,7 +16,11 @@ namespace Unknown6656.AutoIt3.Runtime
 {
     using static AST;
 
-
+    /// <summary>
+    /// Represents the core management logic of the AutoIt interpreter.
+    /// <br/>
+    /// The interpreter consists of threads, the global object storage, service connector, telemetry parser, the plugin loading system etc.
+    /// </summary>
     public sealed class Interpreter
         : IDisposable
         , IDebugPrintingService
@@ -29,22 +32,47 @@ public sealed class Interpreter
         private volatile int _error;
 
 
-        internal static Interpreter[] Instances => _instances.ToArray();
+        /// <summary>
+        /// <b>[UNSAFE!]</b>
+        /// Returns a collection of currently active interpreter instances.
+        /// </summary>
+        public static Interpreter[] ActiveInstances => _instances.ToArray();
 
+        /// <summary>
+        /// The interpreter's random number generator. The used generator can be reset and seeded using the methods <see cref="ResetRandom"/> and <see cref="ResetRandom(int)"/>.
+        /// </summary>
         public Random Random { get; private set; }
 
+        /// <summary>
+        /// The interpreter's main thread.
+        /// </summary>
         public AU3Thread? MainThread { get; private set; }
 
+        /// <summary>
+        /// A collection of currently active threads.
+        /// </summary>
         public AU3Thread[] Threads => _threads.ToArray();
 
+        /// <summary>
+        /// The interpreter's <i>global</i> <see cref="VariableScope"/>. This scope contains all global variables.
+        /// </summary>
         public VariableScope VariableResolver { get; }
 
+        /// <summary>
+        /// The command line options used to launch this interpreter.
+        /// </summary>
         public CommandLineOptions CommandLineOptions { get; }
 
+        /// <summary>
+        /// The interpreter's global object storage.
+        /// </summary>
         public GlobalObjectStorage GlobalObjectStorage { get; }
 
         public COMConnector? COMConnector { get; }
 
+        /// <summary>
+        /// Indicates whether COM interoperability is available to the interpreter.
+        /// </summary>
         public bool IsCOMAvailable => COMConnector is { };
 
         //public WinAPIConnector? Win32APIConnector { get; }
@@ -53,12 +81,18 @@ public sealed class Interpreter
 
         //public bool IsWin32APIAvailable => Win32APIConnector is { };
 
+        /// <summary>
+        /// The interpreter's script scanner and caching unit.
+        /// </summary>
         public ScriptScanner ScriptScanner { get; }
 
         public PluginLoader PluginLoader { get; }
 
         public ParserProvider ParserProvider { get; }
 
+        /// <summary>
+        /// The interpreter's telemetry logger.
+        /// </summary>
         public Telemetry Telemetry { get; }
 
         public LanguageLoader LanguageLoader { get; }
@@ -76,11 +110,22 @@ public int ErrorCode
         public Variant ExtendedValue { get; set; }
 
 
+        /// <summary>
+        /// Creates a new interpreter instance using the given command line options and language pack loader.
+        /// </summary>
+        /// <param name="opt">Command line options to initialize the interpreter.</param>
+        /// <param name="lang_loader">Language pack loader instance.</param>
         public Interpreter(CommandLineOptions opt, LanguageLoader lang_loader)
             : this(opt, new Telemetry(), lang_loader)
         {
         }
 
+        /// <summary>
+        /// Creates a new interpreter instance using the given command line options, telemetry logger, and language pack loader.
+        /// </summary>
+        /// <param name="opt">Command line options to initialize the interpreter.</param>
+        /// <param name="telemetry">Existing telemetry logger instance.</param>
+        /// <param name="lang_loader">Language pack loader instance.</param>
         public Interpreter(CommandLineOptions opt, Telemetry telemetry, LanguageLoader lang_loader)
         {
             _instances.Add(this);
@@ -119,14 +164,22 @@ public Interpreter(CommandLineOptions opt, Telemetry telemetry, LanguageLoader l
             ResetRandom();
         }
 
+        /// <summary>
+        /// Resets the random number generator (<see cref="Random"/>) to a new non-deterministic seed.
+        /// </summary>
         public void ResetRandom() => ResetRandom(Guid.NewGuid().GetHashCode());
 
+        /// <summary>
+        /// Resets the random number generator (<see cref="Random"/>) to the given seed.
+        /// </summary>
+        /// <param name="seed">New seed</param>
         public void ResetRandom(int seed)
         {
             lock (_main_thread_mutex)
                 Random = new XorShift(seed); // BuiltinRandom
         }
 
+        /// <inheritdoc/>
         public void Dispose()
         {
             foreach (AU3Thread thread in Threads)
@@ -144,24 +197,19 @@ public void Dispose()
             _instances.Remove(this);
         }
 
+        /// <inheritdoc/>
+        public override string ToString() => $"[{_threads.Count} Threads] {CommandLineOptions}";
+
+        /// <summary>
+        /// Halts the interpreter and all currently running threads with the given exit code.
+        /// </summary>
+        /// <param name="exitcode">Exit code.</param>
         public void Stop(int exitcode)
         {
             foreach (AU3Thread thread in Threads)
                 thread.Stop(exitcode);
         }
 
-        public void AddFolderToEnvPath(string dir)
-        {
-            char separator = NativeInterop.DoPlatformDependent(';', ':');
-            List<string> path = Environment.GetEnvironmentVariable("PATH", EnvironmentVariableTarget.Process)?
-                                           .Split(separator, StringSplitOptions.RemoveEmptyEntries)
-                                           .ToList() ?? new();
-
-            path.Add(dir);
-
-            Environment.SetEnvironmentVariable("PATH", string.Join(separator, path.Distinct()), EnvironmentVariableTarget.Process);
-        }
-
         public AU3Thread CreateNewThread() => new AU3Thread(this);
 
         internal void AddThread(AU3Thread thread) => _threads.Add(thread);
@@ -172,8 +220,22 @@ public void AddFolderToEnvPath(string dir)
 
         public void Print(CallFrame current_frame, object? value) => MainProgram.PrintScriptMessage(current_frame.CurrentThread.CurrentLocation?.FullFileName, value?.ToString() ?? "");
 
+        /// <inheritdoc/>
         void IDebugPrintingService.Print(string channel, string message) => MainProgram.PrintChannelMessage(channel, message);
 
+        /// <summary>
+        /// Runs the global function of the script file, with which the interpreter has been initialized
+        /// (This essentially executes the script stored in <see cref="CommandLineOptions.FilePath"/> of the interpreter's <see cref="CommandLineOptions"/>-property),
+        /// </summary>
+        /// <returns>The interpreter result of the script invocation.</returns>
+        public InterpreterResult Run() => CommandLineOptions.FilePath is string s ? Run(s) : new InterpreterResult(-1, InterpreterError.WellKnown(null, "error.unresolved_script", "<null>"));
+
+        /// <summary>
+        /// Creates a new (anonymous) interpreter, which invokes the given function with the given arguments.
+        /// </summary>
+        /// <param name="entry_point">The function (entry point) to be invoked.</param>
+        /// <param name="args">Arguments to be passed to the invoked function.</param>
+        /// <returns>The interpreter result of the function invocation.</returns>
         public InterpreterResult Run(ScriptFunction entry_point, Variant[] args)
         {
             try
@@ -196,11 +258,19 @@ public InterpreterResult Run(ScriptFunction entry_point, Variant[] args)
             }
         }
 
+        /// <summary>
+        /// Creates a new (anonymous) interpreter, which invokes the global function of the given script. This essentially executes the given script.
+        /// </summary>
+        /// <param name="script">The script to be executed.</param>
+        /// <returns>The interpreter result of the script invocation.</returns>
         public InterpreterResult Run(ScannedScript script) => Run(script.MainFunction, Array.Empty<Variant>());
 
+        /// <summary>
+        /// Creates a new (anonymous) interpreter, which invokes the global function of the given script. This essentially executes the given script.
+        /// </summary>
+        /// <param name="path">The path of the script to be executed.</param>
+        /// <returns>The interpreter result of the script invocation.</returns>
         public InterpreterResult Run(string path) => ScriptScanner.ScanScriptFile(SourceLocation.Unknown, path, false).Match(err => new InterpreterResult(-1, err), Run);
-
-        public InterpreterResult Run() => CommandLineOptions.FilePath is string s ? Run(s) : new InterpreterResult(-1, InterpreterError.WellKnown(null, "error.unresolved_script", "<null>"));
     }
 
     public sealed class InterpreterResult

new/AutoItInterpreter/Runtime/NativeInterop.cs

@@ -1,14 +1,17 @@
 using System.Runtime.InteropServices.ComTypes;
 using System.Runtime.InteropServices;
+using System.Collections.Generic;
 using System.Threading.Tasks;
 using System.Diagnostics;
 using System.Linq;
-using System;
 using System.Text;
-using System.Runtime.CompilerServices;
+using System;
 
 namespace Unknown6656.AutoIt3.Runtime.Native
 {
+    /// <summary>
+    /// A static module containing functions and constants for native interop.
+    /// </summary>
     public static class NativeInterop
     {
         public const uint TOKEN_READ = 0x00020008;
@@ -149,6 +152,18 @@ public static class NativeInterop
         public static extern bool SetSuspendState(bool hiberate, bool forceCritical, bool disableWakeEvent);
 
 
+        public static void AddFolderToEnvPath(string dir)
+        {
+            char separator = NativeInterop.DoPlatformDependent(';', ':');
+            List<string> path = Environment.GetEnvironmentVariable("PATH", EnvironmentVariableTarget.Process)?
+                                           .Split(separator, StringSplitOptions.RemoveEmptyEntries)
+                                           .ToList() ?? new();
+
+            path.Add(dir);
+
+            Environment.SetEnvironmentVariable("PATH", string.Join(separator, path.Distinct()), EnvironmentVariableTarget.Process);
+        }
+
         public static (string stdout, int code) Bash(string command) => DoPlatformDependent(
             delegate
             {

new/AutoItInterpreter/Runtime/ScriptScanner.cs

@@ -11,13 +11,14 @@
 using Unknown6656.AutoIt3.Extensibility;
 using Unknown6656.Common;
 using Unknown6656.IO;
+using Unknown6656.AutoIt3.Runtime.Native;
 
 namespace Unknown6656.AutoIt3.Runtime
 {
     using static AST;
 
     /// <summary>
-    /// Represents an AutoIt3 script scanning module.
+    /// Represents an AutoIt3 script scanning and caching module.
     /// </summary>
     public sealed class ScriptScanner
     {
@@ -292,7 +293,7 @@ private Union<InterpreterError, ScannedScript> ProcessScriptFile(FileInfo file,
                     _cached_scripts.TryAdd(script.GetHashCode(), script);
 
                     if (file.Directory is { Exists: true, FullName: string dir })
-                        Interpreter.AddFolderToEnvPath(Path.GetFullPath(dir));
+                        NativeInterop.AddFolderToEnvPath(Path.GetFullPath(dir));
                 }
 
                 return script;

new/AutoItInterpreter/Runtime/Variable.cs

@@ -326,7 +326,7 @@ public readonly bool EqualsCaseInsensitive(Variant other)
             _ => "",
         };
 
-        private readonly string ToDebugStringPrivate() => ToDebugString(Interpreter.Instances.First());
+        private readonly string ToDebugStringPrivate() => ToDebugString(Interpreter.ActiveInstances.First());
 
         public readonly string ToDebugString(Interpreter interpreter)
         {

new/AutoItInterpreter/version.txt

@@ -1,2 +1,2 @@
-0.6.1256.7328
-cdfd24e8c9341f9fc41540bef89d37e540605174
+0.6.1257.7329
+f3c8f7753e53011c5fac5224b49c3724c68f2759