Fixed multiple telemetry issues and began documenting the code (#16)

new/AutoItInterpreter/AssemblyInfo.cs

@@ -1,15 +1,15 @@
 
 //////////////////////////////////////////////////////////////////////////
-// Autogenerated 2020-07-17 17:36:47.613                                //
+// Autogenerated 2020-07-19 19:09:25.672                                //
 // ANY CHANGES TO THIS DOCUMENT WILL BE LOST UPON RE-GENERATION         //
 //////////////////////////////////////////////////////////////////////////
 
 using System.Reflection;
 using System;
 
-[assembly: AssemblyVersion("0.6.1103.7319")]
-[assembly: AssemblyFileVersion("0.6.1103.7319")]
-[assembly: AssemblyInformationalVersion("c70b2e80486f4c1c89945e71e61e7322d5562ced")]
+[assembly: AssemblyVersion("0.6.1137.7321")]
+[assembly: AssemblyFileVersion("0.6.1137.7321")]
+[assembly: AssemblyInformationalVersion("fdf6b485c3d0a452c05cbc0438991ef1fbe0dcf3")]
 [assembly: AssemblyCompany("Unknown6656")]
 [assembly: AssemblyCopyright("Copyright © 2018 - 2020, Unknown6656")]
 [assembly: AssemblyProduct("AutoIt3 Interpreter by Unknown6656")]
@@ -20,6 +20,6 @@ public static class __module__
     public static string Author { get; } = "Unknown6656";
     public static string Year { get; } = "2018 - 2020";
     public static string Copyright { get; } = "Copyright © 2018 - 2020, Unknown6656";
-    public static Version? InterpreterVersion { get; } = Version.Parse("0.6.1103.7319");
-    public static string GitHash { get; } = "c70b2e80486f4c1c89945e71e61e7322d5562ced";
+    public static Version? InterpreterVersion { get; } = Version.Parse("0.6.1137.7321");
+    public static string GitHash { get; } = "fdf6b485c3d0a452c05cbc0438991ef1fbe0dcf3";
 }

new/AutoItInterpreter/AutoItInterpreter.csproj

@@ -24,8 +24,7 @@
         <PackageLicenseFile>LICENSE.md</PackageLicenseFile>
         <RepositoryUrl>https://github.com/Unknown6656/AutoIt-Interpreter</RepositoryUrl>
         <AssemblyName>autoit3</AssemblyName>
-    </PropertyGroup>
-    <PropertyGroup>
+        <OutputPath>$(SolutionDir)bin</OutputPath>
         <SatelliteResourceLanguages>en</SatelliteResourceLanguages>
     </PropertyGroup>
     <ItemGroup>
@@ -85,6 +84,11 @@
             <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
         </None>
     </ItemGroup>
+    <ItemGroup>
+      <None Update="autoit3">
+        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+      </None>
+    </ItemGroup>
     <Target Name="PreBuild" BeforeTargets="PreBuildEvent">
         <Exec Command="dotnet &quot;$(OutDir)../bin-util/incr.dll&quot; &quot;$(ProjectPath)&quot;" />
     </Target>

new/AutoItInterpreter/Properties/launchSettings.json

@@ -2,7 +2,7 @@
   "profiles": {
     "AutoItInterpreter": {
       "commandName": "Project",
-      "commandLineArgs": "-vv -t ../test/unittest-vartypes"
+      "commandLineArgs": "-vq -t ../test/test --help"
     }
   }
 }

new/AutoItInterpreter/Runtime/Variable.cs

@@ -18,48 +18,133 @@ namespace Unknown6656.AutoIt3.Runtime
     using static AST;
 
 
+    /// <summary>
+    /// An enum containing all possible data types that an instance of <see cref="Variant"/> can represent.
+    /// </summary>
     public enum VariantType
         : int
     {
+        /// <summary>
+        /// The constant Null-value (typically only used using the static member <see cref="Variant.Null"/>.
+        /// </summary>
         Null = 0,
+        /// <summary>
+        /// Represents a boolean data value.
+        /// </summary>
         Boolean,
+        /// <summary>
+        /// Represents a numerical data value.
+        /// </summary>
         Number,
+        /// <summary>
+        /// Represents a data value of the type <see cref="string"/>.
+        /// </summary>
         String,
+        /// <summary>
+        /// Represents a binary data value.
+        /// </summary>
         Binary,
+        /// <summary>
+        /// Represents an array of zero or more elements.
+        /// </summary>
         Array,
+        /// <summary>
+        /// Represents an injective map.
+        /// </summary>
         Map,
+        /// <summary>
+        /// Represents a pointer to a native or user function.
+        /// </summary>
         Function,
-        //NETObject,
+        /// <summary>
+        /// Represents an <see cref="uint"/>-handle pointing towards a COM object instance.
+        /// </summary>
         COMObject,
+
+        //NETObject,
+
+        /// <summary>
+        /// Represents an <see cref="uint"/>-handle pointing towards a managed object instance.
+        /// </summary>
         Handle,
+        /// <summary>
+        /// Represents a reference to an instance of <see cref="Variable"/> (This is only used in <see langword="ByRef"/>-parameters).
+        /// </summary>
         Reference,
+        /// <summary>
+        /// The constant Default-value (typically only used using the static member <see cref="Variant.Default"/>.
+        /// </summary>
         Default = -1,
     }
 
+    /// <summary>
+    /// Represents the <see cref="Variant"/> data type which is the fundamental data type for all AutoIt <see cref="Variable"/>s.
+    /// The default value of this type resolves to <see cref="Null"/>.
+    /// <para/>
+    /// Data is internally stored using a <see cref="VariantType"/> (to resolve the semantic type), a <see cref="object"/> containing the actual data, and an optional <see cref="Variable"/> reference.
+    /// </summary>
     [DebuggerDisplay("{" + nameof(ToDebugString) + "(),nq}")]
     public readonly struct Variant
         : IEquatable<Variant>
         , IComparable<Variant>
     {
         #region STATIC PROPERTIES
 
+        /// <summary>
+        /// Represents the constant <see cref="Null"/>-value which is accessible using the AutoIt keyword '<see langword="Null"/>'.
+        /// <para/>
+        /// The internally stored data is (<see cref="VariantType.Null"/>, <see langword="null"/>).
+        /// </summary>
         public static Variant Null { get; } = GetTypeDefault(VariantType.Null);
 
+        /// <summary>
+        /// Represents the constant <see cref="Default"/>-value which is accessible using the AutoIt keyword '<see langword="Default"/>'.
+        /// <para/>
+        /// The internally stored data is (<see cref="VariantType.Default"/>, <see langword="null"/>).
+        /// </summary>
         public static Variant Default { get; } = GetTypeDefault(VariantType.Default);
 
-        public static Variant EmptyString { get; } = FromString("");
+        /// <summary>
+        /// Represents an empty string.
+        /// <para/>
+        /// The internally stored data is (<see cref="VariantType.String"/>, <see cref="string.Empty"/>).
+        /// </summary>
+        public static Variant EmptyString { get; } = FromString(string.Empty);
 
+        /// <summary>
+        /// Represents an empty binary string / empty byte array.
+        /// <para/>
+        /// The internally stored data is (<see cref="VariantType.Binary"/>, <see langword="new byte"/>[<see cref="0"/>]).
+        /// </summary>
         public static Variant EmptyBinary { get; } = FromBinary(Array.Empty<byte>());
 
+        /// <summary>
+        /// Represents the constant boolean <see cref="True"/>-value which is accessible using the AutoIt keyword '<see langword="True"/>'.
+        /// <para/>
+        /// The internally stored data is (<see cref="VariantType.Boolean"/>, <see langword="true"/>).
+        /// </summary>
         public static Variant True { get; } = FromBoolean(true);
 
+        /// <summary>
+        /// Represents the constant boolean <see cref="False"/>-value which is accessible using the AutoIt keyword '<see langword="False"/>'.
+        /// <para/>
+        /// The internally stored data is (<see cref="VariantType.Boolean"/>, <see langword="true"/>).
+        /// </summary>
         public static Variant False { get; } = FromBoolean(false);
 
+        /// <summary>
+        /// Represents the constant numeric <see cref="Zero"/>-value.
+        /// <para/>
+        /// The internally stored data is (<see cref="VariantType.Number"/>, <see cref="0m"/>).
+        /// </summary>
         public static Variant Zero { get; } = FromNumber(0m);
 
         #endregion
         #region INSTANCE PROPERTIES
 
+        /// <summary>
+        /// Returns the semantic data type represent this instance.
+        /// </summary>
         public readonly VariantType Type { get; }
 
         /// <summary>
@@ -128,24 +213,54 @@ public readonly struct Variant
         /// </summary>
         internal readonly object? RawData { get; }
 
+        /// <summary>
+        /// Returns the optional <see cref="Variable"/> to which this value has been assigned.
+        /// </summary>
         public readonly Variable? AssignedTo { get; }
 
+        /// <summary>
+        /// Indicates whether this value is indexable.
+        /// </summary>
         public readonly bool IsIndexable => RawData is IEnumerable || IsObject;
 
+        /// <summary>
+        /// Indicates whether this value is a reference to an instance of <see cref="Variable"/> (This is only used in <see langword="ByRef"/>-parameters).
+        /// </summary>
         public readonly bool IsReference => Type is VariantType.Reference;
 
+        /// <summary>
+        /// Returns the referenced <see cref="Variable"/> if the current <see cref="Type"/> has the value "<see cref="VariantType.Reference"/>" - otherwise returns <see langword="null"/>.
+        /// </summary>
         public readonly Variable? ReferencedVariable => IsReference ? RawData as Variable : null;
 
+        /// <summary>
+        /// Indicates whether the current instance is equal to <see cref="Null"/>.
+        /// </summary>
         public readonly bool IsNull => Type is VariantType.Null;
 
+        /// <summary>
+        /// Indicates whether the current instance is equal to <see cref="Default"/>.
+        /// </summary>
         public readonly bool IsDefault => Type is VariantType.Default;
 
+        /// <summary>
+        /// Indicates whether the current instance contains an handle to an (internally managed) object. This is not to be confused with an handle of the type "<see cref="VariantType.COMObject"/>" or "<see cref="VariantType.NETObject"/>".
+        /// </summary>
         public readonly bool IsHandle => Type is VariantType.Handle;
 
+        /// <summary>
+        /// Returns the semantic length of this value (e.g. elements in an array/map, length of a regular or binary string, etc.)
+        /// </summary>
         public readonly int Length => (RawData as IEnumerable)?.Count() ?? 0; // TODO : com object
 
+        /// <summary>
+        /// Indicates whether this value represents a binary string.
+        /// </summary>
         public readonly bool IsBinary => Type is VariantType.Binary;
 
+        /// <summary>
+        /// Indicates whether the current instance represents an object (namely "<see cref="VariantType.COMObject"/>" or "<see cref="VariantType.NETObject"/>"). This is not to be confused with <see cref="IsHandle"/>.
+        /// </summary>
         public readonly bool IsObject => Type is VariantType.COMObject; // TODO : or .netobject
 
         #endregion
@@ -163,6 +278,7 @@ private Variant(VariantType type, object? data, Variable? variable)
 
         public readonly bool IsFunction([MaybeNullWhen(false), NotNullWhen(true)] out ScriptFunction? function) => (function = RawData as ScriptFunction) is { };
 
+        /// <inheritdoc/>
         public readonly int CompareTo(Variant other) =>
             RawData is string s1 && other.RawData is string s2 ? string.Compare(s1, s2, StringComparison.InvariantCultureIgnoreCase) : ToNumber().CompareTo(other.ToNumber());
 
@@ -180,12 +296,21 @@ public readonly bool EqualsCaseInsensitive(Variant other)
 
         public readonly bool EqualsCaseSensitive(Variant other) => Equals(other); // TODO : unit tests
 
+        /// <inheritdoc/>
         public readonly bool Equals(Variant other) => Type.Equals(other.Type) && Equals(RawData, other.RawData);
 
+        /// <inheritdoc/>
         public readonly override bool Equals(object? obj) => obj is Variant variant && Equals(variant);
 
+        /// <inheritdoc/>
         public readonly override int GetHashCode() => HashCode.Combine(Type, RawData);
 
+        /// <summary>
+        /// Returns the string representation of the current instance in accordance with the official AutoIt specification.
+        /// Use <see cref="ToDebugString(Interpreter)"/> for a more detailed string representation.
+        /// </summary>
+        /// <inheritdoc/>
+        /// <returns>String representation</returns>
         public readonly override string ToString() => Type switch
         {
             VariantType.Default => "Default",
@@ -216,7 +341,7 @@ public readonly string ToDebugString(Interpreter interpreter)
             else if (RawData is Variant[] arr)
                 return $"[{string.Join(", ", arr.Select(e => e.ToDebugString(interpreter)))}]";
             else if (Type is VariantType.Map)
-                return $"[{string.Join(", ", ToMap(interpreter).Select(kvp => $"{kvp.Key.ToDebugString(interpreter)}={kvp.Value.ToDebugString(interpreter)}"))}]";
+                return $"[{string.Join(", ", ToMap(interpreter).Select(pair => $"{pair.Key.ToDebugString(interpreter)}={pair.Value.ToDebugString(interpreter)}"))}]";
             else if (RawData is string or StringBuilder)
                 return '"' + string.Concat(ToString().ToArray(sanitize)) + '"';
             else if (RawData is Variable v)
@@ -238,6 +363,10 @@ public readonly string ToDebugString(Interpreter interpreter)
                 return ToString();
         }
 
+        /// <summary>
+        /// Returns the boolean representation of the current instance in accordance with the official AutoIt specification.
+        /// </summary>
+        /// <returns>Boolean representation</returns>
         public readonly bool ToBoolean() => RawData switch
         {
             _ when Type is VariantType.Null or VariantType.Default => false,
@@ -250,6 +379,10 @@ public readonly string ToDebugString(Interpreter interpreter)
             _ => true,
         };
 
+        /// <summary>
+        /// Returns the numerical representation of the current instance in accordance with the official AutoIt specification.
+        /// </summary>
+        /// <returns>Numerical representation</returns>
         public readonly decimal ToNumber() => RawData switch
         {
             _ when Type is VariantType.Default => -1m,
@@ -264,6 +397,10 @@ string s when s.StartsWith("0x", StringComparison.InvariantCultureIgnoreCase) =>
 
         private readonly decimal ToNumber(decimal min, decimal max) => Math.Max(min, Math.Min(ToNumber(), max));
 
+        /// <summary>
+        /// Returns the binary representation of the current instance in accordance with the official AutoIt specification.
+        /// </summary>
+        /// <returns>Binary representation</returns>
         public readonly byte[] ToBinary() => RawData switch
         {
             bool b => new[] { (byte)(b ? 1 : 0) },

new/AutoItInterpreter/Telemetry.cs

@@ -76,7 +76,7 @@ public Telemetry()
 
         // TODO : other stuff, such as exceptions, mem usage, cpu usage, etc.
 
-        public void SubmitTimings(TelemetryCategory category, long ticks) => _recorded_timings.Add((category, new TimeSpan(ticks)));
+        public void SubmitTimings(TelemetryCategory category, in TimeSpan span) => _recorded_timings.Add((category, span));
 
         public void Measure(TelemetryCategory category, Action function) => Measure<__empty>(category, delegate
         {
@@ -94,7 +94,7 @@ public T Measure<T>(TelemetryCategory category, Func<T> function)
             result = function();
             sw.Stop();
 
-            SubmitTimings(category, sw.ElapsedTicks);
+            SubmitTimings(category, sw.Elapsed);
 
             return result;
         }
@@ -238,12 +238,12 @@ public static TelemetryTimingsNode FromTelemetry(Telemetry telemetry)
 
             nd_runtime.AddChild("Script Resolution", get_timings(TelemetryCategory.ResolveScript));
             nd_runtime.AddChild("Script Scan", get_timings(TelemetryCategory.ScanScript));
+            nd_runtime.AddChild("COM Connection", get_timings(TelemetryCategory.COMConnection));
             nd_codeexec = nd_runtime.AddChild("Script Execution", get_timings(TelemetryCategory.ScriptExecution));
 
             nd_thread = nd_codeexec.AddChild("Run/Start Thread", get_timings(TelemetryCategory.ThreadRun));
             nd_codeexec.AddChild("On Start", get_timings(TelemetryCategory.OnAutoItStart));
             nd_codeexec.AddChild("On Exit", get_timings(TelemetryCategory.OnAutoItExit));
-            nd_codeexec.AddChild("COM Connection", get_timings(TelemetryCategory.COMConnection));
 
             nd_au3 = nd_thread.AddChild("Au3", get_timings(TelemetryCategory.Au3ScriptExecution));
             nd_native = nd_thread.AddChild("Native", get_timings(TelemetryCategory.NativeScriptExecution));

new/AutoItInterpreter/autoit3

@@ -0,0 +1,2 @@
+#!/bin/sh
+dotnet autoit3.dll "$@"

new/AutoItInterpreter/version.txt

@@ -1,2 +1,2 @@
-0.6.1103.7319
-c70b2e80486f4c1c89945e71e61e7322d5562ced
+0.6.1137.7321
+fdf6b485c3d0a452c05cbc0438991ef1fbe0dcf3