add a readme file, mostly for git

data/filesys.txt

@@ -9,8 +9,9 @@
 # permissions is CLIte's Unix-like file permissions for the file, such as -rwxrwxrwx
 # empty lines, or lines beginning with a # are ignored
 
-clite/core.js:/usr/clite/core.js:0:0:-rw-r-----
+clite/core.js:/usr/clite/core.js:0:0:-rw-r--r--
 clite/core.css:/usr/clite/web/core.css:0:0:-rw-r-----
 data/intro.txt:/usr/share/introduction:0:0:-rw-rw-r--
 data/about.txt:/usr/share/site/about:0:0:-rw-rw-r--
 data/lipsum.txt:/usr/share/site/lipsum:0:0:-rw-rw-r--
+readme.txt:/usr/clite/readme.txt:0:0:-rw-r--r--

readme.txt

@@ -0,0 +1,346 @@
+
+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().