names
The names page explains the basis and origin of naming conventions used, like extremely short class names.
purpose
This page and ones under it aim to explain aspects of the C++ code in þ which aren't directly obvious from just reading the code itself (assuming you fathom C++). No exhaustive spec for þ is planned, and one might not be feasible as long as the library evolves.
why
Instead, the idea is to supply more of the why factor that's missing from the what and how you can see in the code. Some of the why appears in comments (exactly what I intend for comments), but code comments often have a very local scope; seeing the trees, you miss the forest.
focus
So when I document a class, the plan is a very broad outline to focus on essential detail, to distinguish core concepts from the incidental C++ bureaucracy. I'll try to convey what I was thinking when I wrote something: my intent.
brevity
The result might seem all too brief because I won't explain in detail, and I'll want very few words to appear per defined entity, so it isn't an ocean of stuff to read. If I do it right, you'll want more. A feeling you've been shorted is intended, but I hope you still get value in high density.
matrix
The matrix of obviously desirable features will likely have many holes, simply because time is short, and not every cell of the matrix has the right item already added to each niche. The desirability is clear to fill in the entire matrix uniformly and consistently; please don't point out every thorn. It'll come along slowly.
vector
Example type: in þ the word vector means contiguous array: a sequence of things indexed by integer key where contiguous is the operative word. (In contrast, the word array means potentially scatter/gather sequence.)
When v appears in a class name, this usually refers to a physically contiguous sequence of elements, physically adjacent in the address space. The class (actually struct) whose name is just two letter yv is one of the most simple in þ — it's a pointer and length describing physically contiguous memory. That elements are octets is implied. (It's iovec with methods.)
In naked simplicity, yv is as primitive as char* in C and C++, and nothing is implied about memory management or lifetime. Unless implied by context, you can't even assume the memory fragment is allocated or even mapped. It just describes a physically contiguous subset of the address space. But most of the time, it's a moral equivalent of char*.
State of yv consists of only two public member vars: a pointer named v_p of type u8*, and a length named v_n of type n32.
There are many basic utility operations you can write given just a pointer and length, and I tend to add them to yv as quickly as I need to use them. It's like the set of standard C library calls for null terminated strings.
thorn: todo, names, fd, iovec, assert, log, run, hex, crc, buf, in, out, quote, escape, compare, file, deck, cow, arc, blob, tree, slice, rand, time, stat, hash, heap, node, primes, page, book, pile, stack, atomic, lock, mutex, thread, map, meter, list, iter, ctype
(mu: toy, peg, imm, tag, box, symbol, token, number, bigint, class, method, reader, writer, eval, env, vm, gc, world, pcode, compiler, asm, lathe, lisp, smalltalk, design, weight, jar, card, harp, debug, profile)
Some demos are stubs: todo is a demo guide. See toy for mu updates on language pages; names introduces naming schemes.
The thorn glyph looks like two glyphs — a b and a p — made one. In fact, this is sometimes how one is told to make a good thorn glyph: start with a p, then add a b ascender. Having a "Briar Pig" monogram in one glyph seemed awfully convenient to briarpig, especially when thorn means the same thing as briar.
(An idea to name this library "þ" only blossomed after seeing the glyph looks like b+p for briarpig, some days after first use as a favicon just for "briar" — then it seemed hard to avoid. So þ it is. If only I had nerve to invent a gratuitous new language too.)
doublets
As described on λσπ, implementations of Scheme, Smalltalk, and Python are dreamed on top of þ — in that order, as time permits — and these implementations will unsurprisingly be called λþ, σþ, and πþ — pronounced lambda thorn, sigma thorn, and pi thorn. They might be slow to mature, but they'll interoperate well. I'm likely to add breadth with Tcl (etc) before depth in maturity.
languages
When documenting þ I'll assume you remember half the idea is to implement dynamic languages on top. I might only rarely emphasize when some feature is aimed specifically at speed, simplicity, scaling, or reliability in the context of higher level, garbage collected languages. If I don't remind you, remind yourself.
structure
Most content appears on subpages beneath this one, as indexed in the upper right sidebar as well as the table above. But just as a starter, I might begin by describing one class anecdotally — the basic contiguous octet sequence class named yv for (byte) vector — so you don't feel cheated when new subpages appear slowly. However, this anecdote will be much longer than future treatments. Though fun, it's not brief enough.
anecdote
Under other (longer) names I've been using yv for years. Once a CTO ordered me to give it a painfully long name (which I did of course), and then he suggested I make it more abstract so it could refer to stretchy discontiguous things because that would be powerful, and somehow this would suddenly make the whole system more flexible, as if by magic.
I told him, yes, those stretchy powerful things were a good idea, but something had to be primitive at the very bottom, and deal with plain old memory fragments. If I made yv abstract and high level, then to implement it, somewhere inside I'd have to define a new object that described individual fragments. And these, obvious to say, would be identical to the current yv. So it was just a shellgame in class names: I needed yv someplace.
intro « Þ
