prehistoric-systems/CLIte
1
0
Fork 0
mirror of https://codeberg.org/TicklishHoneyBee/CLIte.git synced 2026-03-11 09:04:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

documentation update

Browse source
This commit is contained in:
Lisa Milne 2023-12-13 19:18:50 +10:00
parent e842848027
commit be72d029b5
3 changed files with 85 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
readme-internals.txt
View file

@ -16,6 +16,15 @@ This means that some areas are still very much a work in progress, but
At its core, CLIte is made up of the follow parts:
The BIOS:
The basic input and output system of CLIte, the bios provides a simplified
api for reading input (keyboard, mouse, etc) and writing output (
displaying text, playing sound) as well as uploading and downloading
files to and from the CLIte system. It provides a basic interface for
reading in keyboard input, as well as setting up the browser to provide
a VGA textmode style graphics display, ensuring CLIte and its programs
need never directly interact with HTML or raw events.
The Core:
Effectively CLIte's 'kernel', this consists of functions needed to do
basic tasks, such as loading files, loading scripts, safely running
@ -23,13 +32,18 @@ The Core:
Most of this is either abstracted away to higher level functions, or
otherwise need never be used by user-level programs.
The Terminal:
The terminal handles user input, and displays program output. Most of
which is abstracted away to standard io calls on /dev/tty, and even
further abstracted to standard io calls on the standard input, output,
and error filedescriptors that every program has. Additionally the
term library offers some advanced functionality which is subject to
change.
The Console:
The console provides an interface between the BIOS graphics system, and
CLIte's TTY subystem. Handling input and output to and from the currently
active TTY. The console is located at /dev/console
The TTY:
The tty provides a Posix-compatible terminal interface, and is linked to
the process manager to maintain the controlling tty for each process
group.
Each process can interact directly with /dev/tty as a shortcut for its
own controlling tty, which can also be found at /dev/ttyN, where N is
the internal tty id.
The VFS: (Virtual File Sytem)
CLIte's virtual file system bares no relation to the file system of the

75
readme-libs.txt
View file

@ -13,7 +13,7 @@ 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
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:
@ -51,7 +51,7 @@ stdlib (libstd.so): io.include('stdlib')
arguments, this is where the new process begins.
function newProc(env,io) {
io.write('this is a new process!');
stdio.write(io.stdout,'this is a new process!\n');
io.exit(0);
}
var pid = fork(env,io,newProc);
@ -92,10 +92,10 @@ stdlib (libstd.so): io.include('stdlib')
Returns false on error.
getuid()
Returns the numeric user id of the current user.
Returns the numeric user id of the current process.
getgid()
Returns teh numeric group id of the current user.
Returns the numeric group id of the current process.
getpwuid(uid)
Returns a pw object, containing the passwd file data of the user
@ -103,7 +103,7 @@ stdlib (libstd.so): io.include('stdlib')
getpwnam(name)
Returns a pw object, containing the passwd file data of the user
who's user name = name
who's username = name
getgrgid(gid)
Returns a gr object, containing the group file data of the group
@ -111,7 +111,7 @@ stdlib (libstd.so): io.include('stdlib')
getgrnam(name)
Returns a gr object, containing the group file data of the group
who's group name = name
who's groupname = name
clite (libclite.so): io.include('clite')
Provides provides special functions used in CLIte.
@ -148,6 +148,23 @@ stdio (libio.so): io.include('stdio')
stdio.flags:
object containing flags for use in io functions
O_EXEC: open for executing only, no op on directories
O_RDONLY: open for reading only
O_RDWR: open for reading and writing
O_SEARCH: open for directory search only, no op on non-directories
O_WRONLY: open for writing only
O_APPEND: append to the file, sets pos to content.length, requires O_RDONLY or O_RDWR
O_CLOEXEC: close on exec
O_CREAT: create if file does not exist
O_DIRECTORY: only open if directory
O_EXCL: if O_CREAT is set, fail if file exists
O_NOCTTY: no op
O_NOFOLLOW: if file is a symlink, don't follow it
AT_SYMLINK_NOFOLLOW: if file is a symlink, don't follow it
O_NONBLOCK: no callbacks, return immediately
O_SYNC: write immediately (may fail on remote data)
O_TRUNC: set file size to 0 before writing, requires O_RDWR or O_WRONLY
O_TTY_INIT: no op
creat('path','-')
creates a new file at path
@ -186,8 +203,7 @@ stdio (libio.so): io.include('stdio')
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).
a special key value (such as escape).
null if the tty cannot be read from.
var c = stdio.read(fd);
@ -289,6 +305,20 @@ stdio (libio.so): io.include('stdio')
st.size: file size, or 0 for non text files
st.perms: the permissions string for the file, see chmod below.
st.name: string containing the file namefd.node.name,
st.type: file type identifier, see stdio.types above for more info
st.st_dev: device id, always 0
st.st_ino: file serial number, always 0
st.st_mode: future integer mode (permission) value
st.st_nlink: number of hard links to the file, always 0
st.st_uid: numeric id of the file owner
st.st_gid: numeric id of the file group
st.st_size: file size, or 0 for non-text files
st.st_atim: timeval object, the file's last access time
st.st_mtim: timeval object, the file's last modify time
st.st_ctim: timeval object, the file's last change time
st.perms: the permissions string for the file, see chmod below.
chmod('path','mode')
fchmod(fd,'mode')
Change a file's mode (permissions).
@ -334,25 +364,22 @@ stdio (libio.so): io.include('stdio')
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
Clears the current tty, 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.
data, as well as providing special tty mode calls.
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
@ -362,11 +389,10 @@ curses (libcurses.so): io.include('curses')
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.
Sets up the tty in addressable mode, ready for use by curses.
endwin()
Exits curses and switches the terminal back to the main frambuffer
Exits curses and switches the tty back to default mode.
cbreak()
Sets input to raw unbuffered mode, so that each key press is received
@ -409,13 +435,22 @@ curses (libcurses.so): io.include('curses')
as arguments. See clite.ptr*() functions for how to create,
read, and write with pointers.
move(y,x)
Moves the cursor to the provided coordinates, where the next text
will be printed to.
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()
Converts a time Object, as returned by gmtime() or localtime(),
into a human readable string.
ctime(time)
Converts a time, as returned by time(), into a human readable
string.
gmtime(time)
Converts an integer containing the number of seconds since epoch
into a time Object.
@ -437,5 +472,9 @@ time (libtime.so): io.include('time')
Converts a time Object into an integer containing the number of
seconds since epoch.
strftime(fmt,timeptr)
Converts a time Object into a human readable string, using the
specified format.
time()
Returns the current time, as seconds since epoch.

17
readme-programs.txt
View file

@ -31,10 +31,6 @@ The function in the second argument is roughly equivalent to main() in C.
io.stdin
file descriptor for standard input
Note that writing 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'
function.
@ -57,7 +53,8 @@ Synchronous Program:
Here's a "Hello World" as an example:
clite.commands.load('hello',function(args,env,io) {
io.write("Hello World!");
var stdio = io.include('stdio');
stdio.printf("Hello World!\n");
return 0;
}
@ -76,7 +73,7 @@ clite.commands.load('show',function(args,env,io) {
// check there's a file to read from
if (args.length != 2) {
io.error('Specify a file to read');
stdio.write(io.stderr,'Specify a file to read\n');
return 1; // not asyncronous yet, so just return
}
@ -88,7 +85,7 @@ clite.commands.load('show',function(args,env,io) {
function fcb(fd) {
if (!fd) {
// print an error, exit the program, then end
io.error('could not open file');
stdio.write(io.stderr,'could not open file\n');
io.exit(1);
return;
}
@ -101,20 +98,20 @@ clite.commands.load('show',function(args,env,io) {
// check there's something there
if (!data) {
// print an error, exit the program, then end
io.error('could not read file');
stdio.write(io.stderr,'could not read file\n');
io.exit(1);
return;
}
// write to stdout
io.write(data);
stdio.write(io.stdout,data);
// and exit successfully
io.exit(0);
}
// open the file, and set the callback
var fd = stdio.open(file,fcb);
var fd = stdio.open(file,stdio.flags.O_RDONLY,fcb);
// we don't want to exit the program yet,
// so return null to let the system know that the