git.subgeniuskitty.com - vvhitespace/.git/blame_incremental

... / ...

Commit	Line	Data
	1	# Overview #
	2
	3	This folder contains a library of useful functions written in VVhitespace.
	4	Standard include guards are used with `cpp` to include the stdlib in user
	5	programs. For an example, see `examples/hello-stdlib`. This also means
	6	`cpp` syntax must be respected.
	7
	8	# Reservations #
	9
	10	Since all labels share a global namespace, the standard library makes the
	11	following reservations:
	12
	13	## Label ##
	14
	15	00000000 0xxxxxxx - reserved for stdlib function entry points
	16	00000000 1xxxxxxx - available for use in user programs
	17	0xxxxxxx xxxxxxxx - reserved for private use by stdlib
	18	1xxxxxxx xxxxxxxx - available for use in user programs
	19
	20	## Heap and Pointers ##
	21
	22	The first 16 heap addresses (`0-15`) are reserved when using the stdlib.
	23	Within that reservation, heap[0] is used by `random` and the block
	24	heap[1]-heap[15] by the stack rotation subroutines which time-share
	25	pseudo-registers between the various stdlib subroutines.
	26
	27	By convention, functions which return a pointer will use the address `0` to
	28	represent a `NULL` pointer.
	29
	30	# Entry Points #
	31
	32	The following labels are entry points to stdlib functions. Read the
	33	header comment for each function to learn the call and return stack.
	34
	35	000xxx - reserved
	36	001xxx - core functions
	37	1000 ----- printf (stdio.pvvs)
	38	1001 ----- print number from stack (stdio.pvvs)
	39	1010 ----- stackrotate (stack.pvvs)
	40	1011 ----- stackrotatereverse (stack.pvvs)
	41	1100 ----- deepdup (stack.pvvs)
	42	010xxx - math functions
	43	10000 ----- random (math.pvvs)
	44	10001 ----- absolute value (math.pvvs)
	45	10010 ----- greatest common divisor (math.pvvs)
	46	011xxx - heap functions
	47	11000 ----- memset (heap.pvvs)
	48	11001 ----- memcpy (heap.pvvs)
	49	11010 ----- memrand (heap.pvvs)
	50	11011 ----- memcmp (heap.pvvs)
	51	11100 ----- memsrch (heap.pvvs)
	52	11101 ----- <empty>
	53	11110 ----- slurp (heap.pvvs)
	54	11111 ----- spew (heap.pvvs)
	55	100xxx - string functions
	56	100000 ----- strlen (string.pvvs)
	57	100001 ----- isdigit (string.pvvs)
	58	101xxx - logic functions
	59	101000 ----- not (logic.pvvs)
	60	101001 ----- and (logic.pvvs)
	61	101010 ----- or (logic.pvvs)
	62	101011 ----- xor (logic.pvvs)
	63	101100 ----- rshift (logic.pvvs)
	64	101101 ----- lshift (logic.pvvs)
	65	110xxx - conversion functions
	66	110000 ----- atoi (convert.pvvs)
	67	111xxx - debug functions
	68	111000 ----- dump heap (debug.pvvs)
	69	111001 ----- dump stack (debug.pvvs)
	70	111010 ----- print sign (debug.pvvs)
	71	111011 ----- print magnitude (debug.pvvs)
	72	111100 ----- print string (debug.pvvs)
	73	111101 ----- print signed number (debug.pvvs)
	74	1xxxxxx - reserved for less common entry points
	75	1000000 ----- lowbitand (logic.pvvs)
	76	1000001 ----- <empty>
	77	1000010 ----- print sign of number (stdio.pvvs)
	78	1000011 ----- print magnitude of number (stdio.pvvs)
	79	1000100 ----- print string from stack (stdio.pvvs)
	80	1000101 ----- print string from heap (stdio.pvvs)
	81
	82	# Misc #
	83
	84	## Private Label Space ##
	85
	86	By convention, each public stdlib label will have 8 bits of private label space
	87	associated with it, formed as follows:
	88
	89	00001000 xxxxxxxx - for use by 1000
	90	00001001 xxxxxxxx - for use by 1001
	91	...etc
	92
	93	## Extending Heap Reservation ##
	94
	95	By default, the stdlib uses the first 16 heap addresses. All heap access (other
	96	than heap[0] as a seed) occurs through `stackrotate` and `stackrotatereverse`.
	97	Edit these functions to increase the stdlib's heap reservation.
	98
	99	The remainder of the stdlib is written to automatically use the new allocation.
	100	Functions like `printf`, for example, allow more substitutions when the heap
	101	allocation is increased.