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