┌───┐ ┌───┐ ┌─┬─┐ ┌   ┐ ┌───┐
└───┐ ├───┤   │   └───┤ │    
└───┘ └   ┘   └    ───┘ └    

DOCUMENTATION

Jon S. <jon@bzap.org>

http://www.centaur.pw/ | https://www.bzap.org/

TABLE OF CONTENTS

1. User Commands (Base)
2. Administrator Commands (Base)
3. Disk Access Commands (mod_disk)
4. Building & Movement Commands (mod_build)
5. Binary Conversion Commands (mod_bin)
6. Network Interface Commands (mod_network)
7. Editor Interface Commands (mod_editor)
8. Online Help Commands (mod_help)

Appendixes

A. Server Options & User Properties
B. Command Index

ABOUT THIS GUIDE

	Required arguments are enclosed in arrow brackets <>.
	Optional arguments are enclosed in square brackets [].
	[path] does not require / as the first character, but can be used in the middle of a string.
	File and directory names are case-sensitive.
	A space must be placed between a path and a file name.
	Wildcard characters such as * and ? cannot be used.

1. USER COMMANDS

	say <message>
	
		Outputs <message> to all online users if their talk option is set to 'on' (default).
	
		It is never necessary to use this command, as any text that does not begin
		with @ or ; is automatically passed to the 'say' verb. Only write a message.

	@mail <user> [message]
	
		Send mail to <user>. If [message] is not provided, the user is prompted to input
		multiple lines of text.
	
	@rmail [message-number]
	
		Read mail messages. If [message-number] is not provided, all mail is shown in short
		form by index number.
	
	@delmail <message-number>
	
		Delete a mail message. Message numbers can be viewed with '@rmail'.
	
	@password
	
		Prompt for and sets a new password.
	
	@who
	
		Display a list of connected users and their account types.
	
	@users
	
		Display a list of registered users and their account types.
	
	@color <on|off>
	
		Turn ANSI color on or off. Default: on
	
	@talk <on|off>
	
		Turn output of 'say' on or off. Default: on

	@prompt <on|off>
	
		Turn the echo prompt on or off. Default: on
	
	@quit
	
		Disconnect from the server.
	
2. ADMINISTRATOR COMMANDS

	;<expression>
	
		Evaluate an expression as a single line of code.
	
	@create <parent-object> <name>
	
		Create an object from <parent-object> and set its name. Default location is #-1.
	
	@delete | @del <object>
	
		Delete an object, unless that object is listed in $protected.
	
	@mkuser <name> <password> <email-address>
	
		Create a new user, setting name, password and e-mail address.
	
	@mkadmin <name> <password> <email-address>
	
		Create a new administrator, setting name, password and e-mail address.

	@obj

		Display a list of all objects in the database.
	
	@move <object> <location>
	
		Move an object to a location.
	
	@dd
	
		Save a copy of the database from memory to disk.
	
	@verb <object> <name> <args1> <args2> <args3>
	
		Create a new verb on an object and sets its arguments. <args> may be
		any combination of 'this', 'any', and 'none'.
		It is recommended to use 'any any any' for most commands, and
		'this none this' for functions.
	
	@verbinfo <object> <verb> [owner] [permissions] [verb-name]
	
		Display or set verb owner, permissions, and name(s).
		All optional arguments must be provided to change verb information.
	
	@args <object> <verb> [args1] [args2] [args3]
	
		Display or set verb arguments for a verb.
 		All optional arguments must be provided to change verb arguments.
	
	@cfile <object> <verb> [path] <filename>
	
		Create a file containing the code for <verb>. This file can then be used
		by '@fcode' or '@script'.
	
	@fcode [path] <file> <object> <verb>
	
		Set the program of a verb using a properly formatted code file generated
		by '@cfile' or written manually.
		The first and last line of this file is ignored, and there can be nothing
		at all after the '.' line in this file.
	
	@verbs <object>
	
		Display a list and count of verbs on an object.
	
	@cpverb <obj> <verb> <target-obj>
	
		Copy a verb from an object to <target-obj>. The verb must not already exist
		on <target-obj>.
	
	@rmverb <object> <verb>
	
		Delete a verb from an object.
	
	@code | @ncode <obj> <verb>
	
		@code displays the code of a verb; @ncode provides line numbers for each line.
	
	@script [path] <file>
	
		Read the contents of a file and executes each line as a command.
		If <file> is a verb code file, this command works the same as '@fcode'.
		If a line does not begin with '@' or ';', it will be interpreted as a 'say' command.
	
	@prop <obj> <name> <value>
	
		Create a property on an object and set its initial value and type.
		NOTE: A property cannot be initialized as a list with this command. Use '0', then
		change with ';'.
		Strings (and not numbers) should be enclosed in double quotes "".
	
	@props <object>
	
		Display a list and the contents of all properties on an object.
	
	@rmprop <property> <object>
	
		Delete a property from an object.
	
	.program <object>:<verb>
	
		Set the code for for a verb.

3. DISK ACCESS COMMANDS

	@mkfile [path] <filename>

		Create a blank file.

	@read [path] <filename>

		Display the contents of a file.

	@nread [path] <filename>

		Display the contents of a file and include line numbers.

	@write [path] <filename>

		Prompt user for a block of text to write to a file. If it does not exist, create it first.
		Warning: This overwrites the contents of a file if it already exists.

	@append [path] <filename>

		Prompt user for a block of text to add to the end of a file. If it does not exist, create it first.
		This command will not overwrite the contents of a file if it already exists.

	@insert [path] <filename> <before-line-number>

		Prompt user for a block of text to insert into a file before the line number given.

	@rmline [path] <filename> <line-number>

		Delete a given line number from a file.

	@ls [path]

		List all files and directories in the current working directory, unless [path] is provided.
		File sizes are listed for each file.

	@cd [path]

		Change current working directory to [path].
		Change current working directory to / if [path] is not provided.

	@pwd

		Display the current working directory.

	@cp [path] <filename> [path] <new-filename>

		Create a copy of a file in the same directory if the second [path] is not provided.
		To copy a file to another directory, all path and file arguments must be provided.

	@rename [path] <filename> <new-filename>

		Rename a file or directory.

	@mkdir [path] <dir-name>

		Create a directory.

	@rmdir [path] <dir-name>

		Delete a directory, only if it is empty.
		If $server_options.confirm_delete is TRUE (1), prompts for confirmation first.

	@rm [path] <filename>

		Delete a file.
		If $server_options.confirm_delete is TRUE (1), prompts for confirmation first.

	@chmod [path] <file> [new-mode-number]

		Change file permissions to the new mode number provided.
		Note: A string expression cannot be entered for the mode number.

	@sh <shell-command-string>

		Run a shell command as root and display the output, if any.
		Does not work on Windows systems by default.
		Warning: Do not run full-screen programs or programs that require keyboard input.

4. BUILDING & MOVEMENT COMMANDS
	
	NOTE: @look, @selfdesc, and the movement commands can be used by all users.
          Only administrators should have this module in their properties.

	north|south|east|west|northeast|northwest|southeast|southwest|up|down
	n|s|e|w|ne|nw|se|sw|u|d
	
		Move through an exit to another room.
		
	@look [object]
	
		By itself, shows the contents of a room, including users, objects and exits.
	
	@selfdesc <description>
	
		Set your description.

	@build <name>

		Create a new room.

	@mkexit <full-direction> <destination-object>

		Create an exit in the room to another room. This automatically creates a return exit in <destination-object>
		pointing to the opposite of <full-direction>.
		The room object must exist before the exit is created.

	@rmexit <full-direction>

		Remove an exit in the room. This will not delete the object pointed to.

	@rdesc <description>

		Set the description of the current room.
		This affects the .desc property of that room.

	@desc <object> <description>

		Set the description of an object.
		This affects the .lookdesc property of that object.

5. BINARY CONVERSION COMMANDS

	@dstrbin <string>

		Convert a string to a bit sequence; each byte is delimited by a space.

	@strbin <string>

		Convert a string to a bit sequence with no delimiters.

	@binstr <string>

		Convert a bit sequence string to human-readable characters.

	@listbin

		Prompt for text, then convert each line to a bit sequence with no delimiters.

	@binlist

		Prompt for non-delimited bit sequences, then convert each line to human-readable characters.

	@filebin [path] <file> [path] <file>

		Read text from a file, then output bit sequences with no delimiters to another file.

	@binfile [path] <file> [path] <file>

		Read bit sequences from a file, then output characters to another file.

6. NETWORK INTERFACE COMMANDS

	@open <host> <port>

		Initiate a connection and hold its output until @net is entered.
		Note: An object number pointing to this connection is stored in the .open_connection property of the
		user who entered it, and the user may only have one active connection at a time.

	@net [input-line]

		Without [input-line]: Display output from remote connection (if any).
		
		With [input-line]: Send [input-line] to the remote connection, then displays the resulting output (if any).

	@close

		Terminate an active connection and reset the user's .open_connection property to #-1.

7. EDITOR INTERFACE COMMANDS

	@editverb <object> <verb>

		Open a verb in the Editor and move into it.

	@editprop <object> <property>

		Open a property composed of strings in the Editor and move into it.
		Only list-type properties composed of strings can be opened.

	@editfile [path] <file>

		Open a disk file in the Editor and move into it.

	@eclose

		Close the currently open verb/property/file.
		This must be done before exiting the Editor or disconnecting from the server.

	@save

		Save the currently open verb/property/file.

	@autoview <on|off>

		Turn auto-view on or off.
		Autoview will display the Editor's contents when loading or making a change to the currently open verb/property/file.

	@view

		Display the contents of the currently open verb/property/file.

	@nview

		Display the contents of the currently open verb/property/file with line numbers.

	@ins <before-line> <text>

		Insert <text> before <before-line> in the currently open verb/property/file.
		Line numbers are displayed if auto-view is on, or can be viewed with @nview.

	@d <line-number>

		Delete <line-number> in the currently open verb/property/file.

	@exit
		Exit the Editor.
		Any open verb/property/file must first be closed with @eclose.

	Entering a line that does not begin with '@' in the Editor will cause that line to be appended to
	the verb/property/file currently loaded.

	Commands beginning with '@edit' are to be used outside of the Editor; you are
	automatically moved to the Editor when opening a verb, property, or file for editing.
	The others will only work within the Editor.
	
	Before leaving the Editor or disconnecting from the server, always use @eclose to close your session.
	
	Only one user may be in the Editor at a time, and only one session may be active at a time.

	It is best to enter and exit the Editor with the described commands rather than using @move.
	Moving out of the Editor without using @eclose and @exit will cause any open session to remain open.
	
8. ONLINE HELP COMMANDS

	@help [topic]

		Without [topic], displays a list of all indexes and topics.
		With [topic], displays the help available for [topic]. This can be one of the entries listed
		in "Indexes" or "Topics" shown by '@help'.

APPENDIX A: SERVER OPTIONS & USER PROPERTIES

The server options should be set appropriately by an administrator.

	#4.login_screen = {"Satyr Server", "", "Login Commands", "--------------", "<user> <password> -- Connect to an existing account.", "create <username> <password> <email-address> -- Create a new account", "quit -- Disconnect from the server"}
	#4.directory = "/satyr"
	#4.site = "site.com"
	#4.port = 2000
	#4.huh_msg = "<Unknown command.>"
	#4.confirm_delete = 1
	#4.connect_msg = "User connected."
	#4.boot_msg = "User disconnected."
	#4.create_msg = "User created."
	#4.recycle_msg = "Your account has been deleted."
	#4.redirect_from_msg = "Account logged in from another location. Redirecting connection to that port."
	#4.redirect_to_msg = "Account logged in from another location. Redirecting connection to this port."
	#4.timeout_msg = "Authentication timeout."
	#4.use_login_file = 0
	#4.login_create = 1
	#4.salt = "C2"
	#4.bin = "/satyr/bin"
	#4.bg_seconds = 120
	#4.fg_seconds = 120
	#4.bg_ticks = 2000000
	#4.fg_ticks = 2000000
	#4.dbfile = "Satyr.current.db"

User properties can be modified by any user, with the exception of .email and .realname.
These will be different between users and should therefore not be modified on $user.

	#5.color = 1
	#5.modules = {}
	#5.password = "(encrypted password)"
	#5.prompt = 1
	#5.email = "(not set)"
	#5.mail = {}
	#5.newmail = 0
	#5.talk = 1
	#5.rootdir = "/satyr"
	#5.realname = "(not set)"

APPENDIX B: COMMAND INDEXES

USER

	say <message>
	@mail <user> [message]
	@rmail [message-number]
	@delmail <message-number>
	@password
	@who
	@users
	@color <on|off>
	@talk <on|off>
	@prompt <on|off>
	@quit

ADMINISTRATOR

	;<expression>
	@create <parent-object> <name>
	@delete <object>
	@mkuser <name> <password> <email-address>
	@mkadmin <name> <password> <email-address>
	@obj
	@move <object> <location>
	@dd
	@verb <object> <name> <args1> <args2> <args3>
	@verbinfo <object> <verb> [owner] [permissions] [verb-name]
	@args <object> <verb> [args1] [args2] [args3]
	@cfile <object> <verb> [path] <filename>
	@fcode [path] <file> <object> <verb>
	@verbs <object>
	@cpverb <obj> <verb> <target-obj>
	@rmverb <object> <verb>
	@code <obj> <verb>
	@ncode <obj> <verb>
	@script [path] <file>
	@prop <obj> <name> <value>
	@props <object>
	@rmprop <property> <object>
	.program <object>:<verb>

DISK ACCESS

	@mkfile [path] <filename>
	@read [path] <filename>
	@nread [path] <filename>
	@write [path] <filename>
	@append [path] <filename>
	@insert [path] <filename> <before-line-number>
	@rmline [path] <filename> <line-number>
	@ls [path]
	@cd [path]
	@pwd
	@cp [path] <filename> [path] <new-filename>
	@rename [path] <filename> <new-filename>
	@mkdir [path] <dir-name>
	@rmdir [path] <dir-name>
	@rm [path] <filename>
	@chmod [path] <file> [new-mode-number]
	@sh <shell-command-string>

BUILDING & MOVEMENT

	north|south|east|west|northeast|northwest|southeast|southwest|up|down
	n|s|e|w|ne|nw|se|sw|u|d
	@look [object]
	@selfdesc <description>
	@build <name>
	@mkexit <full-direction> <destination-object>
	@rmexit <full-direction>
	@rdesc <description>
	@desc <object> <description>

BINARY CONVERSION

	@dstrbin <string>
	@strbin <string>
	@binstr <string>
	@listbin
	@binlist
	@filebin [path] <file> [path] <file>
	@binfile [path] <file> [path] <file>

NETWORK INTERFACE

	@open <host> <port>
	@net [input-line]
	@close

EDITOR INTERFACE

	@editverb <object> <verb>
	@editprop <object> <property>
	@editfile [path] <file>
	@eclose
	@save
	@autoview <on|off>
	@view
	@nview
	@ins <before-line> <text>
	@d <line-number>
	@exit

ONLINE HELP

	@help [topic]

----------------------------------------------------------------------
Revision 0
04/26/2020