bleedsa/k12: portable k implementation - Codeberg.org

K12
	NOT YO GRANNY'S K.
2*k6
	For too long, we have lived in a dark age of open source k. While some
	have sought to remedy the situation plaguing programmers of today with
	their new-fangled notions of "atomic strings" and "graphics", there
	remains an empty hole in the heart of those of us who love k6 but
	refuse to be limited to simple leetcode and single-file programs. K12
	is the light at the end of the tunnel; the fusion of true vector progr-
	amming and modern features for the more ambitious programmer. It is the
	intention of The Author to usher in a New Era of open source k. At long
	last, we shall be blessed by the touch of modularized k, of embedded k,
	the portable k, the practical k, the new k, the special k, the k of the
	future, God's k. Behold the Splendor of my beginning, for He guides my
	loving hands and imbues this program with His touch.
BUILDING
	setup cosmopolitan
	% ape/ape.sh
	run the repl
	% etc/rel.sh # build the release
	% rlwrap out/repl.com # run the repl
	build and run tests (native gnu linux)
	% cargo t
DIRECTORY
	.........______________________________________________________________
	| etc misc scripts/various files.
	| > lns.sh show the line count.
	|______________________________________________________________________
	| ape APE scripts and cosmocc.
	| > apelink.sh wrapper around apelink for rust.
	|______________________________________________________________________
	| com common modules.
	| > tag.rs repl taglines.
	| > rng.rs random number generation.
	| > sym.rs Syms: interned symbol tables.
	| > A.rs a refcounted vector type.
	| > T.rs a table type.
	|______________________________________________________________________
	| k12 high level k12 modules.
	| > bc.rs bytecode types.
	| > B.rs B::B boxed object type.
	| > ops.rs operator functions.
	| > vm.rs virtual machine types and functions.
	| > M.rs M::M m-expr representation and associated types.
	| > lex.rs k12 lexer.
	| > prs.rs k12 parser.
	| > cmp.rs M::M bytecode compiler.
	| > test.rs k12 test framework.
	|______________________________________________________________________
	| bin misc binaries (mostly testbeds).
	| > repl.rs k12 full read, eval, print, loop.
	| > k12.rs k12!!
	~======================================================================
READING THIS CODE
	This code uses a healthy mix of traditional rust style (and is put
	under rustfmt) as well as a more k-friendly arthur whitney style with
	terse variable names and macros that change the rust syntax to make it
	more terse. A lot of this code is formatted into what are essentially
	just tables of functions and return types. A lot of this code uses 
	variables with 1-3 letter variable names, with an exception for things
	like functions and constants/statics. As this style is not familiar for
	most rust programmers, a roadmap is provided here. You will also find
	that the code includes numerous helpful comments. `cargo doc` is recom-
	mended for hackers.
	Naming Conventions
		Variable names generally follow a set of conventions:
		,_______.______________________________________________________
		| S | size/usize
		| i I | int/int vec
		| f F | float/float vec
		| c C | char/char vec
		| g G | function/function vec
		| L | length
		| r | return
		| x | this/rhs (monad)/lhs (dyad)
		| y | that/rhs (dyad)
		| z | arg 3 (triad)
		~=======-======================================================
	Starting the Interpreter
		Binaries are provided which go through all or partial steps of
		the compilation process. This process is as follows:
			* lex
			* parse
			* compile
			* build vm
			* execute bodies and functions
		These steps should all be done in the same scope, which is
		referred to generally by types and functions in this program
		as 'a.
		Lexing, parsing, and compilation are performed by the `k12`
		package within this workspace, under the modules `lex`, `prs`,
		and `cmp`, respectively.
		The `Bld<'a>` struct in cmp which is produced by compiling M::M
		objs is then used to create a VM<'a> with Bld::mk().
	com::A::A
		A::A represents a flat, static sized vector. It is refcounted
		using a stack of ptr counts called A_REFS. For more information
		on A::A, read the documentation generated by `cargo doc`.
	k12::M::M
		M::M is an algebraic datatype representing a k M-expr, ie an
		expression in k, similar to the S-expr of lisp, but with the
		form v[x;y;z].
		The module M includes other object wrapper types for storing
		various verb and function representations, like M::U, M::V,
		and M::W for monads, dyads, and polyads respectfully, as well
		as M::G for function pointers.
	k12::B::B
		B::B is a boxed object representation for the k12 vm stack. It
		represents unboxed atomic objects with lowercase letters and to
		boxed vector objects with uppercase letters.
		B::BG represents a vm function ptr object, and thus contains a
		args counter as well as a body index, but also a string slice
		repr showing its representation in the original source code for
		err reporting.
EXTENSIONS
	TODO: document ext@.
LICENSE
	This source code is provided under the terms of the MPL/2.0.