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	100010 ----- get_user_string (string.pvvs)
	59	101xxx - logic functions
	60	101000 ----- not (logic.pvvs)
	61	101001 ----- and (logic.pvvs)
	62	101010 ----- or (logic.pvvs)
	63	101011 ----- xor (logic.pvvs)
	64	101100 ----- rshift (logic.pvvs)
	65	101101 ----- lshift (logic.pvvs)
	66	110xxx - conversion functions
	67	110000 ----- atoi (convert.pvvs)
	68	111xxx - debug functions
	69	111000 ----- dump heap (debug.pvvs)
	70	111001 ----- dump stack (debug.pvvs)
	71	111010 ----- print sign (debug.pvvs)
	72	111011 ----- print magnitude (debug.pvvs)
	73	111100 ----- print string (debug.pvvs)
	74	111101 ----- print signed number (debug.pvvs)
	75	111110 ----- stdlib version (debug.pvvs)
	76	1xxxxxx - reserved for less common entry points
	77	1000000 ----- lowbitand (logic.pvvs)
	78	1000001 ----- <empty>
	79	1000010 ----- print sign of number (stdio.pvvs)
	80	1000011 ----- print magnitude of number (stdio.pvvs)
	81	1000100 ----- print string from stack (stdio.pvvs)
	82	1000101 ----- print string from heap (stdio.pvvs)
	83
	84	# Misc #
	85
	86	## Private Label Space ##
	87
	88	By convention, each public stdlib label will have 8 bits of private label space
	89	associated with it, formed as follows:
	90
	91	00001000 xxxxxxxx - for use by 1000
	92	00001001 xxxxxxxx - for use by 1001
	93	...etc
	94
	95	## Extending Heap Reservation ##
	96
	97	By default, the stdlib uses the first 16 heap addresses. All heap access (other
	98	than heap[0] as a seed) occurs through `stackrotate` and `stackrotatereverse`.
	99	Edit these functions to increase the stdlib's heap reservation.
	100
	101	The remainder of the stdlib is written to automatically use the new allocation.
	102	Functions like `printf`, for example, allow more substitutions when the heap
	103	allocation is increased.