Welcome to CLIte (pronounced like 'site' with an added L, or like 'slight').

CLIte is an experimental javascript project based on answering the
 question no one asked: "What if a website worked like a Unix Terminal?"

CLIte is licensed under the GNU Affero General Public License, V3.
 Though this may change.

A functioning test instance of CLIte is available at
	http://www.ltmnet.com/clite/index.html
CLite has also been designed, with some work-arounds, to work locally
 without a web server. Just download or clone the git repository
 locally and open index.html in your browser.

The following commands are currently available in the CLIte shell:

help	- a simple help command for new users, gives a basic introduction
	to "What do I do now?"

ls	- list directory contents, accepts the -l argument for showing
	output in long form, with more detail.

cat	- prints files to either the terminal, or with the -d argument
	to the local device (downloads the file)

touch	- create a new file, or load a file's remote data

less	- simple text file viewer, up and down arrows will scroll the
	text, q or escape to exit

file	- determines the file type

reboot	- reboots the system, this will force-reload all javascript, so
	helps get around issues with browser cache


Under Development:
view	- file viewer, should display files something like the way a
	text mode browser would, so is for actually viewing the website
	content
edit	- text file editor, will probably work similar to nano, unless
	it ends up being a vi clone

Running any command with the argument -? will give you help for that
 program.

The shell supports argument in "quotes" and 'single quotes', as well as
  $VARIABLES (environment variables include PATH, USER, PWD, and HOME).
 Support for `command substitution` is in progress.
 Some tabfill support is functional, but more work is needed to tabfill
  paths.
 Shell paths support tilde (~) for the user's home directory, as well as
  dot (.) and dot dot (..) for current and parent directories. The
  asterisk (*) wildcard is not currently supported
 The following shell builtin commands or macros are available:

clear	- clears the terminal window
cd	- changes the present working directory
pwd	- prints the present working directory (equivalent to `echo $PWD')
echo	- prints text or variables
which	- prints the full path of a command: `which ls' - > "ls is /bin/ls"
type	- similar to which, but also tells if a command is a shell builtin
whoami	- prints the current username (equivalent to `echo $USER')
export	- without arguments: will print all environment variables and their
		values.
	- with argument: allows an environment variable to be changed or
		created. `export FOO=bar'


Command details and API:

Commands are currently all contained in clite/commands.js and are loaded in
 at runtime. Each command looks something like:


clite.commands.load('name',function(args,env,io) {
	// executable code
	io.write("Hello World!");
	return 0; // exits the program, return null if the program is
		  // asyncronous (reads user data, or loads remote data)
		  // see io.exit() below for how to exit in such a case
}

The load function is only available during boot time, and will:
 1. load the program into the vfs at /bin/name
 2. load the source of the program into /usr/src/name

The function in the second argument is roughly equivalent to main() in C.
 This function takes 3 arguments:
 'args' is equivalent to argv in C, being an array of strings containing
  the command line arguments, args[0] is the command itself, args.length
  is equivalent to argc in C.
 'env' contains the current environment variables: env.PWD contains the
  present working directory, and so on.
 'io' contains functions for accessing standard input, output, and error,
  as well as for loading in libraries:

 io.write('string') writes to standard output, each call writes a line,
  with a newline character added.

 io.error('string') writes to standard error, each call writes a line,
  with a newline character added.

 io.read(callback) reads a line up to the next newline (or Enter key press)
  from standard input, the result of which is sent to the function passed
  as an argument. Returns null if there is no data to read.

 io.exit(value) exits the program, equivalent to the C exit() function.
  A program can also be exited by returning a non-null value from the 'main'
  function.

 io.include('name') loads a library into the current scope for use. See
  below for more details.

 io.istty.stdin boolean value indicating whether standard input (io.read)
  is a tty.

 io.istty.stdout boolean value indicating whether standard output (io.write)
  is a tty.

Libraries:

System libraries may be loaded into a program for use of their API using the
 io.include() function:

var stdio = io.include('stdio');

 This returns a reference to the library which can be stored in a variable as
 seen above. Calls to library functions can then be made using that reference:

stdio.open('/path/to/file');

 There is no need to name the variable the same as the library name, however
 this is considered good practice.

The libraries, and their API functions are listed below:

stdlib: io.include('stdlib')
 Provides a growing standard unix-like library.

	basename('path')
	 returns the base name of a file path:
	 '/usr/home/guest/file.txt' -> 'file.txt'

	dirname('path')
	 returns the directory name of a file path:
	 '/usr/home/guest/file.txt' -> '/usr/home/guest'

	resolvePath('path','base')
	 special function that resolves a relative path to a full path,
	 using the present working directory or 'base':
	 resolvePath('file.txt') -> '/usr/home/guest/file.txt'
	 resolvePath('file.txt','/etc') -> '/etc/file.txt'
	 resolvePath('~/../file.txt') -> '/usr/home/file.txt'

	getFileType(fd)
	 special function that returns the type of file that a file
	 descriptor refers to. See stdio.types for return values.
	 Likely to be removed, as stdio.stat('path') or stdio.fstat(fd)
	 includes this data.

	strToArgs('string')
	 special function that splits a string into an array of arguments
	 for passing to exec(), supports quotes and so on:
	 'ls -l /var' -> ['ls','-l','var']

	fork()
	 work in progress

	exec(path,args,io)
	 work in progress

stdio: io.include('stdio')
 Provides access to io functions and types for file access

 stdio.types:
  object for mapping return values of stdlib.getFileType() or values of
  stat.type:
	FT_UNKOWN:	0 Unknown file type
	FT_TEXT:	1 Plain text file
	FT_BINARY:	2 Binary file, likely a javascript function
	FT_DIR:		3 Directory
	FT_LINK:	4 Symbolic link
	FT_DEV:		5 Device
	FT_REMOTE:	6 Unloaded remote data (will change after loading)
	FT_SCRIPT:	7 Plain text file beginning with #!
	FT_IMAGE:	8 Image file, specifically a javascript Image object

 creat('path','-')
	creates a new file at path
	returns true on success

 open('path',callback,open_link)
	Open the file at path, returns a file descriptor.
	 On error returns null, and calls callback(null) if set.
	If callback is set, will call the function at callback with the
	 file descriptor if provided, this allows remote data to be
	 loaded for the file before beginning read or write operations.
	If callback is false, open will return directly, without loading
	 remote data.
	If open_link is set and true, and 'path' is a symbolic link, the
	  returned file descriptor is for the link, not the file pointed to.

	 var fd = stdio.open('path',false); // opens the file without loading data
	 var fd = stdio.open('path',callback); // calls callback(fd) when data is loaded
	 var fd = stdio.open('path',callback,true); // as above, but will not follow a link
	 var fd = stdio.open('path'); // as a general rule, don't do this

 close(fd)
	Closes a file opened with open()

		stdio.close(fd);

 read(fd)
	Reads a single character or keystroke from a file.
	Returns null if there is no data to read.
   As a rule, if the string length of the return value is greater than 1,
   then the input is a special key (such as ArrowUp or Escape). Otherwise
   it is a single character.

	var c = stdio.read(fd);

 readLine(fd)
	Reads a line from a file, up to the next newline, or end of file.
	Returns null if there is no data to read.

	var line = stdio.readLine(fd);

 readAll(fd)
	Returns the entire content of a file.
	Returns null if there is no data to read.

	var data = stdio.readAll(fd);

 write(fd,data)
	Write data to a file.
	Returns true on success.

	if (stdio.write(fd,'string')) {
		// it worked
	}else{
		// it failed
	}

 ftruncate(fd,length)
 truncate('path',length)
	Truncates a file's size to no more than length.
	Does not increase a file's size to length.
	Returns true on success.

	var result = stdio.ftruncate(fd,10);
	var result = stdio.truncate('/usr/home/guest/file.txt',10);

 seek(fd,pos)
	Moves the read/write position of an open file to pos.
	If pos is less than 0, then returns the current position without
	 changing, otherwise returns the new position.
	pos is always relative to the start of the file. When a file is
	 first opened, pos will be set to the start of the file.
	To set the position to the end of a file, first get the file size
	using stat() or fstat().

	var p = stdio.seek(fd,10);

 remove('path')
	Deletes a file or directory.
	Returns true on success.
	To delete a directory, the directory must be empty.

	if (stdio.remove('/usr/home/guest/file.txt'))
		// success!

 link('path','target')
	Creates a new symbolic link at 'path' which points to 'target'.
	'target' must exist.
	If 'path' exists, and is already a link, will update the link.
	Returns true on success.

	if (stdio.link('/usr/home/guest/logfile','/vr/logs'))
		// success!

 stat('path')
 fstat(fd)
	Returns a stat object with infomation about a file.
	Returns null on error.
	Editing the returned object does not change anything for the
	 actual file, it just means your stat object is now wrong.

	var st = stdio.stat('/usr/home/guest/file.txt');
	var st = stdio.fstat(fd);

	Stat object contents:
	st.name: string containing the file name
	st.type: file type identifier, see stdio.types above for more info
	uid:     numeric id of the file owner
	gid:     numeric id of the file group
	size:    file size, or 0 for non text files
	perms:   the permissions string for the file, see chmod below.

 chmod('path','mode')
 fchmod(fd,'mode')
	Change a file's mode (permissions).
	Returns true on success.

	The mode string, is a 9 or 10 character string describing the
	 file permissions. The optional first character describes the
	 file type, and cannot be changed. Attempting to change the first
	 character will still succeed, but only the permissions will be
	 changed.

	 10 character string: -rwxrwxrwx
	 9 character string: rwxrwxrwx

	After the option first character, the mode string is comprised of
	 3 sets of permissions for Read, Write, and eXecute, one each for
	 the user, group, and others.

	rwx		permissions for the file's owner
	   rwx		permissions for users in the file's group
	      rwx	permissions for other users

	Replacing any of the permissions with a dash '-' will remove that
	 permission from that set:

	rwxr-xr--
	The user has all permissions, the group has read and execute
	 permissions, others have only read permissions.

term: io.include('term')
 Provides access to raw terminal and tty functions.

 clear()
	Clears the current terminal, equivalent to running `clear' from
	 the shell.

 createTTY()
	Creates a new 'tty' with raw key events, for custom displays and
	 interactions. (The less command uses this).
	Returns a reference object for interacting with the new tty.
	Returns null on error.

	var tty = term.createTTY();

 closeTTY(tty)
	Closes a tty opened with createTTY().