That-One-Nerd/SrcMod
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects Releases 9 Wiki Activity
Page: Commands
Pages
Commands Home Modules
Clone
10
Commands
That_One_Nerd edited this page 2023-04-25 18:05:53 -04:00
Table of Contents

Overview

Commands are methods inside a module that the shell will execute when a command that fits its module ID (if applicable) and name ID is run. A command can have as many parameters as required and the types for those parameters vary.

How to Use

Commands must be in a module to be recognized. Any commands not inside their respective modules will be ignored. Commands are declared by applying the CommandAttribute attribute in the namespace SrcMod.Shell.Modules.ObjectModels to a method. The method can be static and must always have a body. The return type must be void and all parameters must have the following types:

Allowed Types
  • sbyte (System.SByte)
  • byte (System.Byte)
  • short (System.Int16)
  • ushort (System.UInt16)
  • int (System.Int32)
  • uint (System.UInt32)
  • long (System.Int64)
  • ulong (System.UInt64)
  • System.Int128
  • System.UInt128
  • nint (System.IntPtr)
  • nuint (System.UIntPtr)
  • System.Half
  • float (System.Single)
  • double (System.Double)
  • decimal (System.Decimal)
  • char (System.Char)
  • System.DateOnly
  • System.DateTime
  • System.DateTimeOffset
  • System.Enum
  • System.Guid
  • System.TimeOnly
  • System.TimeSpan

Here is an example:

// Used for the `CommandAttribute` and `ModuleAttribute`.
using SrcMod.Shell.Modules.ObjectModels;

[Module("example")]
public static class ExampleModule1
{
    [Command("command")]
    public static void ExampleCommand()
    {
        // Invoked by executing "example command"
    }
}

As said earlier, commands can have parameters as long as they fit the earlier given types or can be implicitly or explicitly casted from them. During the parsing process, parameters are split by spaces (except if in quotations).

One method can also have multiple command names. This is how to add aliases to a command. Simply add another command attribute and give it another name.

Here is an example:

// Used for the `CommandAttribute` and `ModuleAttribute`.
using SrcMod.Shell.Modules.ObjectModels;

[Module("example")]
public static class ExampleModule2
{
    [Command("command")]
    [Command("test")]
    public static void ExampleCommand()
    {
        // Invoked by executing "example command" or
        //                      "example test"
    }
}

SrcMod allows the user to terminate commands prematurely by pressing the terminal cancel key (Ctrl+C or Ctrl+Break on Windows Terminal). However, this can be overriden by adding the CanCancelAttribute attribute to your command. The attribute takes in a boolean that represents whether it can be cancelled or not. A value of true means it can be cancelled. If a CanCancelAttribute attribute is not provided, it is assumed that the command does support cancelling.

Here is an example:

// Used for the `CommandAttribute` and `ModuleAttribute`.
using SrcMod.Shell.Modules.ObjectModels;

[Module("example")]
public static class ExampleModule3
{
    [Command("command1")]
    public static void ExampleCommandA()
    {
        // This command CAN be cancelled.
    }

    [Command("command2")]
    [CanCancel(false)]
    public static void ExampleCommandB()
    {
        // This command CANNOT be cancelled.
    }

    [Command("command3")]
    [CanCancel(true)]
    public static void ExampleCommandC()
    {
        // This command CAN be cancelled.
    }
}

If a user of the shell attempts to cancel a command that does not support cancelling, an error sound will play.

Default Commands

These are each command that has been implemented by default in SrcMod.

base

cd

Changes the current working directory to a specified new directory.

Parameters:

  • newLocalPath: string
    • The new directory to switch to (directory can be relative)

clear

Clears the shell buffer.

copy

Copies a file or directory to a new location.

Parameters:

  • source: string
    • The original location of the file or directory.
  • destination: string
    • The new location for the file or directory.

cut, move

Moves a file or directory to a new location on the computer.

Parameters:

  • source: string
    • The original location of the file or directory.
  • destination: string
    • The new location for the file or directory.

del

Deletes a file or directory

Parameters:

  • path: string
    • The file or directory to delete.

dir

Lists every directory and file in the path given. This does not include subdirectories.

Parameters:

  • path: string
    • The path to search.
    • Default Value: .

echo

Prints a given message.

Parameters:

  • msg: string
    • The message to print.

exit, quit

Exit the shell.

Parameters:

  • code: int
    • The exit code to close with.
    • Default Value: 0

explorer

Opens a given directory in File Explorer.

Parameters:

  • path: string
    • The path to open in File Explorer.
    • Default Value: .

history

Prints the history of all reversable commands executed by the shell.

makedir, mkdir

Creates a directory at the given location.

Parameters:

  • name: string
    • The directory to create.

makefile, mkfile

Creates a file at the given location with some optional text.

Parameters:

  • name: string
    • The file to create.
  • text: string?
    • Optional text to write to the file. If set to null, no text will be written.
    • Default Value: null

permdel

Permanently deletes a file or directory.

Parameters:

  • path: string
    • The path to permanently delete.

print, type

Prints the contents of a given file to the console.

Parameters:

  • file: string
    • The path of the file to print.

run

Executes an external process in the shell. This command cannot be prematurely cancelled because even when cancelled, the process will continue to run in the shell. In the future, this may be fixed.

Parameters:

  • name: string
    • The name or location of the process to execute.
  • args: string
    • The arguments to be supplied to the process.
    • Default Value: ""

sleep

Wait for a given amount of milliseconds.

Parameters:

  • timeMs: int
    • The amount of time to wait in milliseconds.

srcmod

How about you find out for yourself.

undo

Undoes a command or commands in the history that can be undone.

Parameters:

  • amount: int
    • The amount of commands to undo.
    • Default Value: 1

clipboard

clipboard clear

Clears the clipboard of all data currently copied in it. This is technically an unsafe command, though it likely won't fail.

clipboard copy

Copies a given string of data into the clipboard. This is technically considered an unsafe command, though it likely won't fail.

This is kind of a redundant command, and might be deleted in the future.

Parameters:

  • text: string
    • The text to copy into the clipboard. Must be in the UTF-8 format.

clipboard view

View the text currently stored in your clipboard. Due to some issues with clipboard formats, the command can only view text in the clipboard, not any other data. This is technically an unsafe command, though it likely won't fail.

compress

compress gz, compress gzip

Compresses a single file into a GZip file.

Parameters:

  • source: string
    • The original location of the file.
  • destination: string?
    • The destination for the compressed file. If set to null, it will be determined automatically.
    • Default Value: null
  • level: CompressionLevel
    • The level of compression for the GZip file. The compression level also changes the time it takes to compress.
    • Default Value: Optimal
    • Possible Values:
      • Optimal
      • Fastest
      • NoCompression
      • SmallestSize

compress tar, compress tarball

Compresses a file or directory into a single Tar file. Tar files technically do not compress their contents and simply pack them. That is why they are usually compressed into a GZip file.

Parameters:

  • source: string
    • The original location of the file or directory.
  • destination: string?
    • The destination for the compressed file or directory. If set to null, it will be determined automatically.
    • Default Value: null

compress targz, compress tar.gz, compress tar-gz

First packs a file or directory into a single Tar file, then compresses that file into a GZip file.

Parameters:

  • source: string
    • The original location of the file or directory.
  • destination: string?
    • The destination for the compressed GZip file. If set to null, it will be determined automatically.
    • Default Value: null
  • level: CompressionLevel
    • The level of compression for the GZip file. The compression level also changes the time it takes to compress.
    • Default Value: Optimal
    • Possible Values:
      • Optimal
      • Fastest
      • NoCompression
      • SmallestSize

compress zip

Compresses a file or directory into a single Zip file.

Parameters:

  • source: string
    • The original location of the file or directory.
  • destination: string?
    • The destination for the compressed file or directory. If set to null, it will be determined automatically.
    • Default Value: null
  • level: CompressionLevel
    • The level of compression for the Zip file. The compression level also changes the time it takes to compress.
    • Default Value: Optimal
    • Possible Values:
      • Optimal
      • Fastest
      • NoCompression
      • SmallestSize

config

config add, config append

Appends a single item to a config variable. The variable in question must be a list.

Parameters:

  • name: string
    • The specific variable to append to. Should be the name of a config variable (not case sensitive).
  • value: string
    • The value to append to the list. Must be parsable into an object that has the same type as the list elements (or can cast to it).

config delete, config remove

Removes a single item to a config variable. The variable in question must be a list.

Parameters:

  • name: string
    • The specific variable to remove from. Should be the name of a config variable (not case sensitive).
  • value: string
    • The value to remove from the list. Must be parsable into an object that has the same type as the list elements (or can cast to it).

config display, config list

Displays config information about the shell.

Parameters:

  • display: string
    • The specific variable to display. Should be the name of a config variable (not case sensitive).
    • Special cases:
      • "all"
        • The command displays all config variables at once.
      • "raw"
        • The command displays the raw, JSON-formatted config.
    • Default Value: "all"

config reset

Resets a config variable or variables to their default value or values.

Parameters:

  • display: string
    • The specific variable to reset. Should be the name of a config variable (not case sensitive).
    • Special cases:
      • "all"
        • The command resets all config variables to their default values.
    • Default Value: "all"

config set

Sets a config variable to a new value. Cannot change a list config variable, the variable changed must have a single value.

Parameters:

  • name: string
    • The specific variable to change. Should be the name of a config variable (not case sensitive).
  • value: string
    • The new value to set the variable to. Must be parsable into an object that has the same type as the variable.

extract

extract gz, extract gzip

Extracts the contents of a GZip file and saves it to a file.

Parameters:

  • source: string
    • The original location of the GZip file.
  • destination: string?
    • The destination of the file extracted from the GZip file. If set to null, it will be determined automatically.
    • Default Value: null

extract rar

Extracts the contents of a Rar file and saves it to a directory.

Parameters:

  • source: string
    • The original location of the Rar file.
  • destination: string?
    • The destination of the files extracted from the Rar file. If set to null, it will be determined automatically.
    • Default Value: null

extract tar, extract tarball

Extracts the contents of a Tar file and saves it to a directory.

Parameters:

  • source: string
    • The original location of the Tar file.
  • destination: string?
    • The destination of the files extracted from the Tar file. If set to null, it will be determined automatically.
    • Default Value: null

extract targz, extract tar.gz, extract tar-gz

Extracts the contents of a Tar and GZip file combination and saves it to a directory.

Parameters:

  • source: string
    • The original location of the GZip file.
  • destination: string?
    • The destination of the files extracted from the Tar file. If set to null, it will be determined automatically.
    • Default Value: null

extract zip

Extracts the contents of a Zip file and saves it to a directory.

Parameters:

  • source: string
    • The original location of the Zip file.
  • destination: string?
    • The destination of the files extracted from the Zip file. If set to null, it will be determined automatically.
    • Default Value: null

extract rar

Extracts the contents of a 7Zip file and saves it to a directory.

Parameters:

  • source: string
    • The original location of the 7Zip file.
  • destination: string?
    • The destination of the files extracted from the 7Zip file. If set to null, it will be determined automatically.
    • Default Value: null