version bump, documentation

clite/core.js

@@ -1,6 +1,6 @@
 var clite = {
 	state:{
-		version:'0.1-15',
+		version:'0.2-1',
 		isinit:false
 	},
 	core:{
@@ -8,7 +8,7 @@ var clite = {
 			try{
 				f();
 			} catch(e) {
-				clite.log.write(e.message+':'+e.lineNumber);
+				clite.log.write(e.message);
 				return false;
 			}
 			return true;
@@ -17,7 +17,7 @@ var clite = {
 			try{
 				setTimeout(f,10);
 			} catch(e) {
-				clite.log.write(e.message+':'+e.lineNumber);
+				clite.log.write(e.message);
 				return false;
 			}
 			return true;

clite/shell.js

@@ -304,9 +304,7 @@ clite.commands.load('sh',function(args,env,io) {
 		}
 	}
 
-	// TODO: something something waitall()
 	stdlib.waitall(inputRead);
-	//inputRead();
 
 	return null;
 });

readme.txt

@@ -94,18 +94,21 @@ The function in the second argument is roughly equivalent to main() in C.
   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' contains file descriptors for accessing standard input, output,
+  and error, as well as a method for loading in libraries:
 
- io.write('string') writes to standard output, each call writes a line,
-  with a newline character added.
+ io.stdout
+	file descriptor for standard output
 
- io.error('string') writes to standard error, each call writes a line,
-  with a newline character added.
+ io.stderr
+	file descriptor for standard error
 
- 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.stdin
+	file descriptor for standard input
+
+	Note that writting to stdout or stderr, when it is a tty, will
+	 currently always print that output as a line, with a newline
+	 appended. This may change in the future.
 
  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'
@@ -114,11 +117,6 @@ The function in the second argument is roughly equivalent to main() in C.
  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:
 
@@ -140,37 +138,42 @@ The libraries, and their API functions are listed below:
 stdlib: io.include('stdlib')
  Provides a growing standard unix-like library.
 
-	basename('path')
+ basename('path')
 	 returns the base name of a file path:
 	 '/usr/home/guest/file.txt' -> 'file.txt'
 
-	dirname('path')
+ dirname('path')
 	 returns the directory name of a file path:
 	 '/usr/home/guest/file.txt' -> '/usr/home/guest'
 
-	resolvePath('path','base')
+ 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'
 
-	strToArgs('string')
+ 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']
 
-	uname()
+ uname()
 	 returns an object containing system information:
 	 {
 		sysname:'CLIte',	// system name, always 'CLIte'
-		nodename:'localhost',	// network hostname, currently always 'localhost'
+		nodename:'localhost',	// network hostname
 		release:'0.1...',	// contains the current CLIte version as stored in clite.state.version
 		version:'0.1...',	// same as release
 		machine:navigator.userAgent // contains the browser user agent string
 	}
 
-	fork(env,io,call)
+	nodename is either the website domain, or 'localhost' if loaded
+	 without a webserver. This allows programs to test if the system
+	 is running locally or not (example is `cat -l' which does not
+	 print unloaded files if running without a webserver).
+
+ fork(env,io,call)
 	 Creates a new process, with environment and io data passed to it.
 	 Returns the pid of the new process, or 0 on failure.
 	 call should be a function that accepts the env and io as
@@ -182,7 +185,7 @@ stdlib: io.include('stdlib')
 	 }
 	 var pid = fork(env,io,newProc);
 
-	exec(path,args,env,io)
+ exec(path,args,env,io)
 	 Executes a new program, replacing the current one.
 	 Returns 0 on success, non-zero on failure.
 	 Unlike typical unix exec(), this always returns. On success the
@@ -201,6 +204,29 @@ stdlib: io.include('stdlib')
 	 if (r == 0)
 		return;
 
+ wait(cb)
+	Calls cb(pid) once any child of the current process has exited.
+	 Calls immediately if the are no child processes.
+	Returns false on error.
+
+ waitpid(pid,cb)
+	Calls cb(pid) when the process with id pid has exited. Calls
+	 immediately if the process does not exist.
+	If pid is less than 0, functions like wait(cb)
+	Returns false on error.
+
+ waitall(cb)
+	Calls cb(pid) once all child processes of the current process
+	 group have exited. Calls immediately if the are no child processes.
+	Returns false on error.
+
+ getuid()
+	Returns the numeric user id of the current user.
+
+ getgid()
+	Returns teh numeric group id of the current user.
+
+
 stdio: io.include('stdio')
  Provides access to io functions and types for file access
 
@@ -241,24 +267,35 @@ stdio: io.include('stdio')
 
 		stdio.close(fd);
 
- read(fd)
+ read(fd,callback)
 	Reads a single character or keystroke from a file.
+	callback is an optional callback function, used soley for
+	 asynchronously reading from a tty.
 	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.
+
+	When reading from a regular file, will return a single character.
+	When reading from a tty:
+		Returns true on success or false on failure.
+		Calls callback() and passes as an argument either:
+			A full line of text as entered by the user.
+			\1 (start of header) followed by a special key
+			 name (such as ArrowUp).
+			null if the tty cannot be read from.
 
 	var c = stdio.read(fd);
 
- readLine(fd)
+ readLine(fd,callback)
 	Reads a line from a file, up to the next newline, or end of file.
 	Returns null if there is no data to read.
 
+	When reading from a tty, functions the same as read().
+
 	var line = stdio.readLine(fd);
 
  readAll(fd)
 	Returns the entire content of a file.
 	Returns null if there is no data to read.
+	Works only on regular files (and some non-tty devices).
 
 	var data = stdio.readAll(fd);
 
@@ -359,6 +396,14 @@ stdio: io.include('stdio')
  isattty(fd)
 	returns true if fd refers to a tty.
 
+ fprintf(fd,format,args)
+	Print formatted text to the file at fd.
+	Actually formatting is a work in progress, ignore the args.
+	Returns true on success.
+
+ printf(fmt,args)
+	Equivalent to fprintf(io.stdout,fmt,args);
+
 term: io.include('term')
  Provides access to raw terminal and tty functions.
 
@@ -377,6 +422,18 @@ term: io.include('term')
  closetty(tty)
 	Closes a tty created with opentty().
 
+ ttyctrl(func,v)
+	Special function for setting and accessing CLIte-specific tty
+	 data. Specifically for interacting directly with the form used
+	 for user data input.
+	func is a string containing the intended function.
+	v is the value to set.
+	Returns either the requested data, or false on error.
+
+	term.ttyctrl('iset',string);	// sets the current input value
+	var txt = term.ttyctrl('iget');	// gets the current input value
+	term.ttyctrl('prompt',string);	// sets the current prompt text
+
 
 Example Programs:
  Due to the nature of javascript, it is not possible to simply stop half