CLIte/readme-libs.txt

CLIte 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:

var fd = stdio.open('/path/to/file',stdio.flags.O_RDONLY);

 There is no need to name the variable the same as the library name, however
 this is considered good practice.
 A library's 'header' name, as used in include() is not the same as its
 file name /lib/lib*.so. For instance for the standard io library, you
 would include 'stdio' but the filename is libio.so

The libraries, and their API functions are listed below:

stdlib (libstd.so): 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'

 uname()
	 returns an object containing system information:
	 {
		sysname:'CLIte',	// system name, always 'CLIte'
		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
	}

	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
	  arguments, this is where the new process begins.

	 function newProc(env,io) {
		io.write('this is a new process!');
		io.exit(0);
	 }
	 var pid = fork(env,io,newProc);

 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
	  original program should do nothing more, including not exiting.

	 path is the fully resolved file path of the program to be
	  executed, such as '/bin/ls'.
	 args is the argument array created by passing a command line to
	  strToArgs, see above.
	 env and io, are the current environment and io data.

	 var command = "ls -l";
	 var args = stdlib.strToArgs(command);
	 var path = stdlib.resolvePath(args[0],'/bin');
	 var r = stdlib.exec(path,args,env,io);
	 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.

 getpwuid(uid)
	Returns a pw object, containing the passwd file data of the user
	 who's numeric user id = uid

 getpwnam(name)
	Returns a pw object, containing the passwd file data of the user
	 who's user name = name

 getgrgid(gid)
	Returns a gr object, containing the group file data of the group
	 who's numeric group id = gid

 getgrnam(name)
	Returns a gr object, containing the group file data of the group
	 who's group name = name

clite (libclite.so): io.include('clite')
 Provides provides special functions used in CLIte.

 resolvePath('path','base')
	Resolves a relative path to a full path, using the present
	 working directory or 'base':

	clite.resolvePath('file.txt') -> '/usr/home/guest/file.txt'
	clite.resolvePath('file.txt','/etc') -> '/etc/file.txt'
	clite.resolvePath('~/../file.txt') -> '/usr/home/file.txt'

 strToArgs('string')
	Splits a string into an array of arguments for passing to
	 exec(), supports quotes and so on:

	clite.strToArgs('ls -l /var') -> ['ls','-l','var']


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

 stdio.types:
  object for mapping 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

 stdio.flags:
  object containing flags for use in io functions

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

 open('path',flags,callback)
	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, this allows remote data to be loaded for the
	 file before beginning read or write operations.
	If callback is false or not set, open will return directly, without loading
	 remote data. this is equivalent to setting stdio.flags.O_SYNC in flags.
	flags is a bitwise or group of flags from stdio.flags.O_*. Consisting
	 of at least one mode (O_RDONLY/O_RDWR/O_WRONLY/O_SEARCH/O_EXEC),
	 and any other flag or flags.

	 var fd = stdio.open('path',stdio.flags.O_RDONLY|stdio.flags.O_SYNC); // opens the file without loading data
	 var fd = stdio.open('path',stdio.flags.O_RDONLY,callback); // calls callback(fd) when data is loaded
	 var fd = stdio.open('path',stdio.flags.O_RDONLY|stdio.flags.O_NOFOLLOW,callback); // as above, but will not follow a link
	 var fd = stdio.open('path'); // fails without a valid mode (O_RDONLY/O_RDWR/O_WRONLY/O_SEARCH/O_EXEC)

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

		stdio.close(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.

	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,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);

 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')
 lstat('path')
 fstatat(fd,flags)
	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.

	fstatat returns data for the file descriptor fd.
		flags may be either 0 or stdio.flags.AT_SYMLINK_NOFOLLOW

	stat returns data for the file specified by path, or if the file
	 is a symbolic link, for the file the link points to.
	 equivalent to:
		var fd = stdio.open('path',stdio.flags.O_RDONLY|stdio.flags.O_NOFOLLOW);
		var st = stdio.fstatat(fd,stdio.flags.AT_SYMLINK_NOFOLLOW);

	lstat returns data for the file specified by path, or if the file
	 is a symbolic link, for the link itself.
	 equivalent to:
		var fd = stdio.open('path',stdio.flags.O_RDONLY);
		var st = stdio.fstatat(fd,0);

	var st = stdio.stat('/usr/home/guest/file.txt');
	var st = stdio.lstat('/usr/home/guest/file.txt');
	var st = stdio.fstatat(fd,0);

	Stat object contents:
	st.name:  string containing the file name
	st.type:  file type identifier, see stdio.types above for more info
	st.uid:   numeric id of the file owner
	st.gid:   numeric id of the file group
	st.size:  file size, or 0 for non text files
	st.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 not cause the function to fail, 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.

 isatty(fd)
	returns true if fd refers to a tty.

 vfprintf(fd,format,args)
	Print formatted text to the file at fd.
	args is an array of arguments for inserting into the formatted
	 output.
	Returns true on success.

 fprintf(fd,format,...)
	Similar to vfprintf, but accepts the format arguments as a
	 variable number of arguments to the function itself.

 printf(fmt,...)
	Equivalent to fprintf(io.stdout,fmt,...);

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

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

 ttyctrl(func,v)
	Special function for setting and accessing CLIte-specific tty
	 data. Such as interacting directly with the form used for user
	 input.
	func is a string containing the intended function.
	v is the value to set.
	Many functions of this are abstracted away in the curses library.
	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

curses (libcurses.so): io.include('curses')
 provides an ncurses-like library, which functions for terminal management

 curses.types:
	A_NULL	0 NO OP / do nothing
	A_BOLD	1 apply a bold face to text

 initscr()
	Switches the terminal to an alternate framebuffer, and resets io
	 ready for curses library calls.

 endwin()
	Exits curses and switches the terminal back to the main frambuffer

 cbreak()
	Sets input to raw unbuffered mode, so that each key press is received
	 individually, rather than the usual line buffering.
 nocbreak()
	Returns the input to line buffered mode.

 clear()
	Clears the framebuffer.

 echo()
	Causes key strokes to be echoed to the terminal (default)
 noecho()
	Causes key strokes to not be echoed to the terminal

 printw(fmt)
	A printf-like function for writing to the alternate framebuffer

 getch(cb)
	Receive input from stdin

 refresh()
	No op function for ncurses compatibility

 attron(a)
	Enable attribute 'a' for future input, see curses.types

 attroff(a)
	Disable attribute 'a' for future input, see curses.types

 getmaxx()
	Returns the width of the frambuffer in characters.

 getmaxy()
	Returns the height of the framebuffer in characters/lines.

 getmaxyx(ptry,ptrx)
	Gets the width and height of the framebuffer, as per getmaxx()
	 and getmaxy(), but writes the results to the pointers passed
	 as arguments. See clite.ptr*() functions for how to create,
	 read, and write with pointers.

time (libtime.so): io.include('time')
	Provides functions for interacting with system time.

 asctime(timeptr)
	Converts a time Object, as returned by gmtime() or localtime()
	 into a human readable string.

 gmtime(time)
	Converts an integer containing the number of seconds since epoch
	 into a time Object.
		tm_sec:0,	// seconds (0-60)
		tm_min:0,	// minutes (0-59)
		tm_hour:0,	// hour (0-23)
		tm_mday:0,	// day of month (0-31)
		tm_mon:0,	// month of year (0-11)
		tm_year:0,	// years since 1900
		tm_wday:0,	// day of week (0-6, sunday = 0)
		tm_yday:0,	// day of year (0-365)
		tm_isdst:0	// 1 if daylight savings

 localtime(time)
	Converts an integer containing the number of seconds since epoch
	 into a time Object, taking into account the current time zone.

 mktime(timeptr)
	Converts a time Object into an integer containing the number of
	 seconds since epoch.

 time()
	Returns the current time, as seconds since epoch.