document scripting

1 files changed, 234 insertions, 17 deletions

diff --git a/ShiftOS_TheReturn/Scripting.cs b/ShiftOS_TheReturn/Scripting.cs
index d96bc98..dd5acfd 100644
--- a/ShiftOS_TheReturn/Scripting.cs
+++ b/ShiftOS_TheReturn/Scripting.cs
@@ -38,31 +38,65 @@ using System.Net;
 
 namespace ShiftOS.Engine.Scripting
 {
+    /// <summary>
+    /// Brings some C# goodies to the Lua system.
+    /// </summary>
     [Exposed("strutils")]
     public class StringUtils
     {
+        /// <summary>
+        /// Checks if a string ends with a specified string.
+        /// </summary>
+        /// <param name="operand">The string to operate on</param>
+        /// <param name="value">The string to check for</param>
+        /// <returns>Whether <paramref name="operand"/> ends with <paramref name="value"/>.</returns>
         public bool endswith(string operand, string value)
         {
             return operand.EndsWith(value);
         }
 
+
+        /// <summary>
+        /// Checks if a string starts with a specified string.
+        /// </summary>
+        /// <param name="operand">The string to operate on</param>
+        /// <param name="value">The string to check for</param>
+        /// <returns>Whether <paramref name="operand"/> starts with <paramref name="value"/>.</returns>
         public bool startswith(string operand, string value)
         {
             return operand.StartsWith(value);
         }
 
+        /// <summary>
+        /// Checks if a string contains a specified string.
+        /// </summary>
+        /// <param name="operand">The string to operate on</param>
+        /// <param name="value">The string to check for</param>
+        /// <returns>Whether <paramref name="operand"/> contains <paramref name="value"/>.</returns>
         public bool contains(string operand, string value)
         {
             return operand.Contains(value);
         }
     }
 
-
+    /// <summary>
+    /// DynamicLua wrapper for the ShiftOS engine.
+    /// </summary>
     public class LuaInterpreter
     {
+        /// <summary>
+        /// The DynamicLua backend.
+        /// </summary>
         public dynamic Lua = new DynamicLua.DynamicLua();
+
+        /// <summary>
+        /// Boolean representing whether the script is running.
+        /// </summary>
         public bool Running = true;
 
+        /// <summary>
+        /// Static constructor for the <see cref="LuaInterpreter"/> class. 
+        /// </summary>
         static LuaInterpreter()
         {
             ServerManager.MessageReceived += (msg) =>
@@ -83,12 +117,21 @@ namespace ShiftOS.Engine.Scripting
             };
         }
 
+        /// <summary>
+        /// Create a .SFT representation of a Lua script.
+        /// </summary>
+        /// <param name="lua">The Lua code to convert</param>
+        /// <returns>Base64 SFT representation.</returns>
         public static string CreateSft(string lua)
         {
             byte[] bytes = Encoding.UTF8.GetBytes(lua);
             return Convert.ToBase64String(bytes);
         }
 
+        /// <summary>
+        /// Run a compressed .SFT file as a lua script.
+        /// </summary>
+        /// <param name="sft">The .sft file to run.</param>
         public static void RunSft(string sft)
         {
             if (Utils.FileExists(sft))
@@ -108,8 +151,14 @@ namespace ShiftOS.Engine.Scripting
             }
         }
 
+        /// <summary>
+        /// Get the current working directory of the script.
+        /// </summary>
         public static string CurrentDirectory { get; private set; }
 
+        /// <summary>
+        /// Creates a new instance of the <see cref="LuaInterpreter"/> class. 
+        /// </summary>
         public LuaInterpreter()
         {
             Lua(@"function totable(clrlist)
@@ -128,6 +177,9 @@ end");
             };
         }
 
+        /// <summary>
+        /// Scans the engine, frontend, and all mods for Lua-exposed classes and functions.
+        /// </summary>
         public void SetupAPIs()
         {
             Lua.currentdir = (string.IsNullOrWhiteSpace(CurrentDirectory)) ? "0:" : CurrentDirectory;
@@ -233,7 +285,10 @@ end");
             });
         }
 
-        
+        /// <summary>
+        /// Executes the specified file as an uncompressed Lua script.
+        /// </summary>
+        /// <param name="file">The file to execute.</param>
         public void ExecuteFile(string file)
         {
             if (Utils.FileExists(file))
@@ -247,6 +302,10 @@ end");
             }
         }
 
+        /// <summary>
+        /// Executes the specified string as a Lua script.
+        /// </summary>
+        /// <param name="lua">The Lua code to execute.</param>
         public void Execute(string lua)
         {
             try
@@ -279,24 +338,46 @@ end");
         }
     }
 
+    /// <summary>
+    /// Lua functions for .sft files.
+    /// </summary>
     [Exposed("sft")]
     public class SFTFunctions
     {
+        /// <summary>
+        /// Make a .sft file from a lua code string
+        /// </summary>
+        /// <param name="lua">The Lua code</param>
+        /// <returns>The resulting .sft string</returns>
         public string make(string lua)
         {
             return LuaInterpreter.CreateSft(lua);
         }
 
+        /// <summary>
+        /// Make a .sft string and save to a specified file.
+        /// </summary>
+        /// <param name="lua">The Lua code to compress</param>
+        /// <param name="outpath">The path to save the compressed .sft file to.</param>
         public void makefile(string lua, string outpath)
         {
             Utils.WriteAllText(outpath, make(lua));
         }
 
+        /// <summary>
+        /// Run a compressed .sft file in the <see cref="LuaInterpreter"/>. 
+        /// </summary>
+        /// <param name="inpath">The .sft file to run.</param>
         public void run(string inpath)
         {
             LuaInterpreter.RunSft(inpath);
         }
 
+        /// <summary>
+        /// Reads the specified .sft file and decompresses to it's Lua form.
+        /// </summary>
+        /// <param name="sft">The .sft file to uncompress</param>
+        /// <returns>The resulting Lua code.</returns>
         public string unmake(string sft)
         {
             if (Utils.FileExists(sft))
@@ -310,9 +391,17 @@ end");
         }
     }
 
+    /// <summary>
+    /// Network functions for Lua.
+    /// </summary>
     [Exposed("net")]
     public class NetFunctions
     {
+        /// <summary>
+        /// Submit a GET request to the specified URL.
+        /// </summary>
+        /// <param name="url">The URL to open</param>
+        /// <returns>The result from the server</returns>
         public string get(string url)
         {
             return new WebClient().DownloadString(url);
@@ -320,26 +409,48 @@ end");
         
     }
 
+    /// <summary>
+    /// Console functions for Lua.
+    /// </summary>
     [Exposed("console")]
     public class ConsoleFunctions
     {
+        /// <summary>
+        /// Write text to the console.
+        /// </summary>
+        /// <param name="text">The text to write.</param>
         public void write(dynamic text)
         {
             Console.Write(text.ToString());
         }
 
+        /// <summary>
+        /// Write text to the console, followed by a new line.
+        /// </summary>
+        /// <param name="text">The text to write.</param>
         public void writeLine(dynamic text)
         {
             Console.WriteLine(text.ToString());
         }
     }
 
+    /// <summary>
+    /// The main ShiftOS API.
+    /// </summary>
     [Exposed("sos")]
     public class SystemFunctions
     {
+        /// <summary>
+        /// Retrieves the user's Codepoints from the save file.
+        /// </summary>
+        /// <returns>The user's Codepoints.</returns>
         public long getCodepoints() { return SaveSystem.CurrentSave.Codepoints; }
 
-
+        /// <summary>
+        /// Run a command in the Terminal.
+        /// </summary>
+        /// <param name="cmd">The command to run, using regular ShiftOS syntax.</param>
+        /// <returns>Whether the command was found and ran.</returns>
         public bool runCommand(string cmd)
         {
             var args = TerminalBackend.GetArgs(ref cmd);
@@ -347,6 +458,10 @@ end");
             return TerminalBackend.RunClient(cmd, args);
         }
 
+        /// <summary>
+        /// Adds the specified amount of Codepoints to the save flie.
+        /// </summary>
+        /// <param name="cp">The codepoints to add.</param>
         public void addCodepoints(int cp)
         {
             if (cp > 100 || cp <= 0)
@@ -361,128 +476,227 @@ end");
         }
     }
     
-    [Exposed("mud")]
-    public class MUDFunctions
-    {
-        public void sendDiagnostic(string src, string cat, object val)
-        {
-            ServerManager.SendMessage("diag_log", $"[{src}] <{cat}>: {val}");
-        }
-    }
-
+    /// <summary>
+    /// User information API.
+    /// </summary>
     [Exposed("userinfo")]
     public class UserInfoFunctions
     {
+        /// <summary>
+        /// Gets the user name of the currently logged in user.
+        /// </summary>
+        /// <returns>The user's username.</returns>
         public string getUsername()
         {
-            return SaveSystem.CurrentSave.Username;
+            return SaveSystem.CurrentUser.Username;
         }
 
+        /// <summary>
+        /// Retrieves the user's system name.
+        /// </summary>
+        /// <returns>The user's system name.</returns>
         public string getSysname()
         {
             return SaveSystem.CurrentSave.SystemName;
         }
 
+        /// <summary>
+        /// Gets the user's ShiftOS email (username@sysname).
+        /// </summary>
+        /// <returns>The user's email.</returns>
         public string getEmail()
         {
             return getUsername() + "@" + getSysname();
         }
     }
 
-
+    /// <summary>
+    /// Infobox API for Lua.
+    /// </summary>
     [Exposed("infobox")]
     public class InfoboxFunctions
     {
+        /// <summary>
+        /// Show a message to the user in an Infobox.
+        /// </summary>
+        /// <param name="title">The title of the Infobox</param>
+        /// <param name="message">The infobox's message</param>
+        /// <param name="callback">A function to run when the user clicks "OK"</param>
         public void show(string title, string message, Action callback = null)
         {
             Infobox.Show(title, message, callback);
         }
 
+        /// <summary>
+        /// Ask a simple yes/no question to the user using an Infobox.
+        /// </summary>
+        /// <param name="title">The title of the Infobox</param>
+        /// <param name="message">The infobox's message</param>
+        /// <param name="callback">A function to run when they choose an option. The boolean argument will be true if the user clicks Yes, and false if they click No.</param>
         public void question(string title, string message, Action<bool> callback)
         {
             Infobox.PromptYesNo(title, message, callback);
         }
 
-        public void input(string title, string message, Action<string> callback)
+        /// <summary>
+        /// Prompt the user for text using an Infobox.
+        /// </summary>
+        /// <param name="title">The infobox's title</param>
+        /// <param name="message">The infobox's message</param>
+        /// <param name="callback">A function to run when the user clicks "OK". The string value is the text entered by the user.</param>
+        /// <param name="isPassword">Whether the text box should hide its characters as if it were a password box.</param>
+        public void input(string title, string message, Action<string> callback, bool isPassword = false)
         {
-            Infobox.PromptText(title, message, callback);
+            Infobox.PromptText(title, message, callback, isPassword);
         }
     }
 
+    /// <summary>
+    /// File Skimmer API for Lua.
+    /// </summary>
     [Exposed("fileskimmer")]
     public class FileSkimmerFunctions
     {
+        /// <summary>
+        /// Opens a File Skimmer "Open File" dialog.
+        /// </summary>
+        /// <param name="extensions">Semicolon-separated list of file extensions that the opener should let through the filter.</param>
+        /// <param name="callback">Function to be called when the user chooses a file. The string value is the file's path.</param>
         public void openFile(string extensions, Action<string> callback)
         {
             FileSkimmerBackend.GetFile(extensions.Split(new[] { ";" }, StringSplitOptions.RemoveEmptyEntries), FileOpenerStyle.Open, callback);
         }
 
+        /// <summary>
+        /// Opens a File Skimmer "Save File" dialog.
+        /// </summary>
+        /// <param name="extensions">Semicolon-separated list of file extensions that the opener should let through the filter.</param>
+        /// <param name="callback">Function to be called when the user chooses a file. The string value is the file's path.</param>
         public void saveFile(string extensions, Action<string> callback)
         {
             FileSkimmerBackend.GetFile(extensions.Split(new[] { ";" }, StringSplitOptions.RemoveEmptyEntries), FileOpenerStyle.Save, callback);
         }
     }
 
+    /// <summary>
+    /// ShiftFS API for Lua.
+    /// </summary>
     [Exposed("fs")]
     public class ShiftFSFunctions
     {
+        /// <summary>
+        /// Read all text in a file to a string.
+        /// </summary>
+        /// <param name="path">The file path to read</param>
+        /// <returns>The string containing the file's contents.</returns>
         public string readAllText(string path)
         {
             return Utils.ReadAllText(path);
         }
 
+        /// <summary>
+        /// Copy a file from one place to another.
+        /// </summary>
+        /// <param name="i">The source file</param>
+        /// <param name="o">The destination path</param>
         public void copy(string i, string o)
         {
             Utils.WriteAllBytes(o, Utils.ReadAllBytes(i));
         }
 
+        /// <summary>
+        /// Gets all files in the specified directory.
+        /// </summary>
+        /// <param name="dir">The directory to search</param>
+        /// <returns>A string array containing all file paths in the directory.</returns>
         public string[] getFiles(string dir)
         {
             return Utils.GetFiles(dir);
         }
 
+        /// <summary>
+        /// Gets all directories inside a directory.
+        /// </summary>
+        /// <param name="dir">The directory to search</param>
+        /// <returns>A string array containing all directory paths in the directory.</returns>
         public string[] getDirectories(string dir)
         {
             return Utils.GetDirectories(dir);
         }
 
+        /// <summary>
+        /// Read the binary contents of a file to a <see cref="byte"/> array. 
+        /// </summary>
+        /// <param name="path">The file path to read.</param>
+        /// <returns>The resulting byte array.</returns>
         public byte[] readAllBytes(string path)
         {
             return Utils.ReadAllBytes(path);
         }
 
+        /// <summary>
+        /// Writes the specified text to a file.
+        /// </summary>
+        /// <param name="path">The file path</param>
+        /// <param name="contents">The text to write</param>
         public void writeAllText(string path, string contents)
         {
             Utils.WriteAllText(path, contents);
         }
 
+        /// <summary>
+        /// Writes the specified binary data to a file.
+        /// </summary>
+        /// <param name="path">The file path.</param>
+        /// <param name="contents">The binary data</param>
         public void writeAllBytes(string path, byte[] contents)
         {
             Utils.WriteAllBytes(path, contents);
         }
 
+        /// <summary>
+        /// Determines whether the specified path exists and is a file.
+        /// </summary>
+        /// <param name="path">The path to search</param>
+        /// <returns>The result of the search.</returns>
         public bool fileExists(string path)
         {
             return Utils.FileExists(path);
         }
 
+        /// <summary>
+        /// Determines whether the specified path exists and is a directory.
+        /// </summary>
+        /// <param name="path">The path to search</param>
+        /// <returns>The result of the search.</returns>
         public bool directoryExists(string path)
         {
             return Utils.DirectoryExists(path);
         }
 
+        /// <summary>
+        /// Deletes the file/directory at the specified path.
+        /// </summary>
+        /// <param name="path">The path to delete</param>
         public void delete(string path)
         {
             Utils.Delete(path);
         }
 
+        /// <summary>
+        /// Creates a new directory at the specified path.
+        /// </summary>
+        /// <param name="path">The path to create</param>
         public void createDirectory(string path)
         {
             Utils.CreateDirectory(path);
         }
     }
 
-
+    /// <summary>
+    /// Marks the specified class as a Lua API object.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Class, AllowMultiple = false)]
     public class ExposedAttribute : Attribute
     {
         /// <summary>
@@ -494,6 +708,9 @@ end");
             Name = name;
         }
 
+        /// <summary>
+        /// The API object's name
+        /// </summary>
         public string Name { get; private set; }
     }
 }