Wil uses a naming scheme like one described on BriarPig's names, with strikingly short, cryptic names for classes. On this page Wil summarizes patterns in rules for names.
"It looks like individual letters are meaningful in þ names," guessed Stu. "Is that right?"
"Yes," confirmed Wil, "Some class names are composed almost entirely of single letter name clusters."
Stu rubbed his chin. "I suppose you haven't enough letters to go around, right?" asked Stu. "Are some letters re-used?"
"Yes," agreed Wil. "There's a bit of overloading where one letter can mean different things."
"Ew," Stu curled his lip. "Could be a memorization nightmare. Is it like one or two meanings per letter, or more like seven or nine? That would suck."
"More like a couple meanings per letter," assured Wil. "I use whole words too when long letter codes look wrong."
"Well," sighed Stu. "I guess you should get on with it. I hate memorizing."
Wil nodded sympathetically. "Libraries usually require learning some aribitrary names," he noted.
"I wonder," Stu pondered. "How do you tell apart class names using words from those using letter codes?"
Wil shrugged and offered, "Letter-based names look like gibberish. Names with a whole word inside are apparent."
"So you're saying it'll be obvious," Stu suggested. "Or at least I won't be stumped. Okay, we'll see."
"The letter y," began Wil, "means symbol and this is partly why all þ names start with y."
"Besides being an archaic way to write the þ glyph," noted Stu. "Does y appear in the name of symbol types?"
"Yes," nodded Wil, "The name yyb means thorn symbol box in the toy language runtime described under mu. It's a boxed symbol in gc memory. All boxes have a b suffix."
"I'd have thought b meant buffer," guessed Stu.
"It means buffer too," agreed Wil, "as you can see in the buf demo. But the yb buffer class isn't used all that much. So many classes end in b for box that yb looks like it might be the box base class when ybox is. If you squint and think of a box as a gc buffer, they seem related."
"Maybe you can go alphabetically," Stu suggested. "I might remember the names in a to z order.
"Some names are also based on specific integer values," Wil noted. "Just as a convention."
"Like what?" asked Stu. "Does digit 1 mean singleton?"
"That's a good example," agreed Wil. "I sometimes use 1 as part of singleton names. And digit 2 sometimes means pair. For example, y2t is a pair template not too different from std::pair."
"How about 0?" asked Stu. "How does zero mean something?"
"I use 0 to mean origin," explained Wil.
"Oh, I should have thought of that," blurted Stu.
"So 0 for origin appears in names of starting addresses," continued Wil, "as well as names of absract base classes, or in simpler primitive versions of more complex types."
"Other folks say base but you say zero," observed Stu.
"Okay, let's go back to a then," said Wil. "An a suffix usually means array for scatter/gather sequences, as opposed to v for vector, which is contiguous. One of the stack types in the toy language runtime is an a type because it's logically a sequence of gc pointers, but it's a chain of physical pieces.
"And b we just covered," observed Stu. "Box or buf."
"Yep," nodded Wil. "And c often means char in some sense, and I'm playing with an idea of using yc as a runtime reification of class. But I haven't yet."
"In nested classes," Wil continued, "c can mean cite as opposed to quote when choosing print format; cite means one line only, opposed to multiline dumps for quote."
"The letter d I haven't used much," Wil said, "but so far I use it in data objects like deck. And it might be part of database names. It needs to gel more."
"Does e stand for event?" guessed Stu.
"Yes, but only in more recent classes, which I won't describe until much later. For event types, a prefix of ye indicates one of many async event related types," Wil explained.
"I saw a lot of e names in non-event types," said Stu.
"Yes, a prefix e often means enum, and a suffix e usually means element denoting a member of some kind of collection," Wil waved in a vague gesture. "You can also think of e as meaning entry for the same purpose, for this e is nearly always a suffix."
"I suppose f is for file," Stu anticipated.
"Yes, exactly," Wil confirmed, "but f for file appears seldom when passed as a base out type instead. I also use f for formatted in method names with behavior similar to printf(). The generic yo method of() means out formatted."
"The letter g has a couple unrelated meanings," Will said, "including guard and generator."
Stu grimaced. "Starting to sound kind of arbitrary," he observed. "What does guard mean?"
"A guard," explained Wil, "is an automatic resource management object for resource acquisition is initialization (see RAII). So a g suffix often appears on the end of classes that cleanup after the type without the final g."
"What's a generator?" asked Stu. "A Python thing?"
"No," Wil shook his head. "A generator is informally like an in stream, but massages the stream in some way. Like a tokenizer might be a token generator."
"Is h for heap?" Stu guessed again.
"No, uppercase H is for heap, and lowercase h is for handle," Wil instructed. "Their purposes are related in the sense a handle manages refcounting (see refcounting) of a node, which is usually allocated by a heap."
"Wow," marveled Stu, "you actually stooped to using uppercase letters. Is that common?"
"Very few uppercase letters are used," Wil noted. "There is also P for page and B for book."
"Tsk, tsk," Stu reproved. "You should have included B for book in the b section. What's a book?"
"A book is a super page," Wil said. "It's a piece of memory much bigger than a virtual memory page, with memory alignment to book size, the same way pages are aligned to page boundaries. I use books to suballocate pages."
"Um," Stu shrugged without much interest. "So it's a very specialized kind of buffer: one handling your memory management."
"You might care more that books are the granularity of garbage collection," Wil suggested. "Space for gc lives in books so hashmaps of gc blocks are efficient."
Stu didn't care after all. "What's i — an input stream?"
"Good guess again," Wil nodded. "The base yi class is an abstract in stream api; subclasses use an i suffix to show they are yi types. For example, yvi is an in reading from yv."
"Letters j and l aren't used much yet," Wil noted. "But k means const most places. So k appears in most class names where a const version of something is distinguished from mutable — iterators for example."
"I meant to reserve l for something later," continued Wil, "partly because it looks so much like the digit one. A couple times I use it as a list synonym alternative for q for queue."
"And the letter j?" prompted Stu. "Just going to let it go to waste?"
"I nearly used j for job to mean thread, but threads appear rarely in code — they're more a latent effect," asserted Wil. "I think I use it as a cursor type at least one place now. Later I might use j for jar in storage APIs."
"The letter m for map appears a lot," Wil observed.
"Is there an abstract map interface?" asked Stu.
"I started writing a std::map clone," replied Wil, "but I don't use it because it's hard to make a one-size fits all map that isn't clunky. And I'm keen to allocate my maps inside pages and books, so it's been simpler so far to redo a map api on every object needing one. Basically, the behavior of maps tends to be rather usage specific — it depends on what a map is for."
"So my clue a thing is a map is letter m?" wondered Stu.
"Something like that," smiled Wil. "For example, the symbol hashmap for interning symbols in the toy language is named yym, meaning thorn symbol map. An m suffix usually means map."
"And a map entry class would use suffix me?" guessed Stu.
"Basically yeah," nodded Wil. "That's the idea."
"Let me guess," Stu continued. "Suffix mkrp might be map const reverse pointer for a reverse iterator over a const map."
"Sure," Wil agreed. "But hashmaps aren't ordered so reverse has no meaning for hashmaps."
"So maps aren't ordered trees like in STL?" probed Stu.
"Not so far," Wil replied. "I like constant time maps."
"I think I see why class names using whole words will look obvious to me," observed Stu. "Nearly all your vowels appear as suffixes, so letter based names often can't be pronounced. So when I see a, e, i, o, and u in the middle of class names, it might be an English word?"
"Yeah, okay," Wil considered. "I can see that. But u appears in the middle of some class names. Maybe it shouldn't though. I'm not completely consistent in names. In a couple cases I used u for octet when c for char might have been better."
"Oops," blurted Wil. "I just remembered. A toy language under mu uses upper M for machine, as in virtual machine. Uppercase tends to be used for objects responsible for storage."
"Glory," Stu waved off further detail.
All this code is available only under the BriarPig mu-babel license described fully on the rights page. You do not have permission to reprint this page in any way. Neither feeds nor repackaging is allowed. You can link this page if you want folks to read it.
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; here we introduce naming schemes.
"Let's go on to n," Stu said. "Is it number like in n32?"
"That's one meaning," confirmed Wil. "Another is node. The yn node base class is for refcounting, used in conjunction with h handles which are actual references."
"So n32 is like count and yn is node?" Stu asked.
"Yeah," agreed Wil. "And if you squint, the purpose of nodes is counting references, so yn and n32 are related."
"Forced," Stu charged. "Ten yard penalty."
"No football metaphors," Wil grimaced. "I hate sports."
"You already mentioned o for out," Stu prompted.
"Yes, the yo out stream class is used everywhere," Wil noted. "Everything prints with an out stream as a destination. So yo appears in the api of virtually every type."
"What's the obsession with printing?" asked Stu.
"Just evidence collection," Wil replied. "When everything debug prints, you can see state whenever you want, and send it off wherever you like."
"I use gdb to see state of objects," countered Stu.
"You can still do that," Wil reminded. "No one forces you to print things. I can't easily get detail in gdb I want."
"But I have to see printing methods using yo everywhere," noted Stu, "whether I want to use them or not."
"You could try ignoring methods using yo," mused Wil.
"Gah, if I wanted universal printing I'd use Lisp," complained Stu. "Almost everything prints in Lisp."
"That's the idea," agreed Wil. "It's an advantage."
"You said p means pointer," Stu decided to go on.
"Yes, but half the time that means iterator because þ iterators act like pointers to collection members," Wil said.
"So you overload the operator*() dereference operator," guessed Stu. "STL does that with iterators."
"Yes, exactly," agreed Wil, "and you can increment and decrement them too, like in STL."
"But you use p for pointer for iterators," mulled Stu.
"Well i for in was already taken," Wil justified, "and as the opposite of o for out, I really needed to use i for in."
"Besides," Wil noted, "the idea of pointer is quite general and it's useful to have a dedicated letter name. In the toy language under mu, I use yp as the pointer-sized reference type in garbage collected memory, but I refer to this as a peg."
"Why not just use a naked pointer there?" wondered Stu.
"A yp peg also encodes immediate values," explained Wil. "And to get better overloading and type safety in C++, it's a lot safer to use a struct wrapper for a pointer than an actual pointer."
"Does it make the code go slower?" asked Stu.
"Well," Wil temporized, "you'd hope a compiler would optimize access of pointer sized values regardless. If it turns out later to have a performance effect, I can always play with new representations of yp that go faster, once I have a large unit test suite that can detect variation in expected behavior."
"In other words, it's an exploratory toy and you don't care," summarized Stu.
"Not about small constant sized differences in speed," Wil agreed. "It's a toy til it matters whether it's fast."
"Now you're going all pragmatist on me," smiled Stu.
"Always," shrugged Wil. "Not just now. You're just used to language folks being a little nutty about detail."
"What's q mean? Maybe queue?" Stu guessed.
"Yes, very nearly," Wil confirmed. "Besides q for quote in nested classes, I use q to mean queue or more properly deque because it's a double-ended, bi directional, circular linked list."
"Why not use l for list for that?" Stu suggested.
"Then what would I use q for?" joked Wil. "I might use l for list later for singly linked lists. I tend to use doubly-linked lists for everything in early drafts of code, even though they touch more memory on each operation, with poor cache line behavior."
"Besides," noted Wil, "I often need to remove list members from the middle, and I'm unwilling to let it take linear time. I'd often rather have slightly slower but guaranteed constant time."
"Do your queues clone std::list?" Stu asked.
"No," Wil shook his head. "STL lists allocate space for each member added. Most queues of yq style assume intrinsic links are already allocated."
"More efficient, but more detail and mess?" Stu asked.
"Well yeah," Wil confirmed. "Most of þ is very manual."
"What about r?" Stu asked. "I saw you use r64 as a synonym for double."
"Yes, sometimes r means real for floating point," Wil replied. "For example, in the toy language under mu, I use yr64b as the boxed form of double, and yr64vb as the boxed form of double vectors. Other native types have similarly named box formats in single instance and vector forms."
"And I think you agreed earlier r also means reverse?" Stu reminded. "Is that just for iterators?"
"Yes," Wil agreed, "rp means reverse iterator. In the toy language under mu, r also sometimes means reader."
Stu smiled. "What if I get confused and think it means real or reader iterator? Never mind, let's go on to s."
"As you might guess, s means string," Wil began.
"A std::string or a Unicode string?" Stu asked.
"More like the former. The ys class doesn't care about character sets," Wil explained. "So I plan to also have a yS class for unicode with a similar api. So upper S means fancy string."
"You don't sound enthused," Stu noticed.
"Personally I rarely need either," Wil expanded, "Because I do more systems programming than UI code."
"But a programming language has a UI," Stu objected.
"Whatever," Wil dismissed. "I'll worry about what other folks like later. I have to be paid to do things off my own agenda. I had a job where I wrote code parsing utf16 unicode codepoints correctly, utf8 too, and it's just a bunch of detail."
"What's the main idea of þ strings if not character sets?" Stu wondered. "Just memory management?"
"Basically memory management," Wil agreed, "for use when folks want a lazy approach to storing yv octet sequences. It's a familiar STL model where you don't worry about storage."
"Are strings arrays or vectors according to your terminology? Scatter gather or contiguous?" Stu asked.
"You're catching on," Wil smiled. "A long term plan is array so large strings can be allocated discontiguously, for better fragmentation behavior and also copy-on-write optimizations. But I'll put off both those until I need them. The toy language under mu will have scatter gather array strings, and I think I'll code that first. Contiguous vector ys strings will do for now."
"What about t," Stu proceeded. "Maybe t for type?"
"Close — it abbreviates type a couple times. But most of þ says t for template," Wil explained. "A t suffix means a class is a template type or method. For example, yvt<T> is a vector of type T — a partial clone of std::vector, except I haven't used it much. Maybe I'll test it thoroughly this time. There's not much use of templates in þ except handles using yht<N> to reference a node subclass N."
"But," Wil continued just when Stu thought he was done, "in the toy language under mu, I use t for tag: a four byte marker before each box in gc memory describing the type and format of the following box. The struct wrapping this four byte value is named yt, and in this context it almost means type — type of box."
"In the yo out stream api," Wil added, "the letter t means tab when indent level increases."
"I have no guess for u," Stu admitted.
"Other than u for untab in yo out stream methods, u means unsigned most of the time," Wil considered. "I've used it instead of c for char when I mean to use memory as raw binary octet blobs. So u almost means unspecified. Almost the absence of a name."
"Well v for vector is easy since we've seen it several times already," Stu noted. "Is it usually a suffix?"
"Yes, appending v usually means vector of whatever type appears to the left," Wil expanded.
"And a vector is basically just a C array?" Stu asked.
"Yes, a primitive contiguous sequence," Wil agreed.
"Alrighty then," Stu skipped ahead, "what about w?"
"The letter w is little used yet in the rest of þ," Wil said. "But in the toy language under mu, I use w for writer, and uppercase W for world. An M machine instance runs in the context of a W world which holds state in common to all the virtual machines."
"However," Wil continued, "in docs and sample code I can use w for wrapper when re-packaging system standard types to emulate a new api. For example, yfdw can mean thorn file descriptor wrapper in stream examples; here it also doubles as writer."
"Does x mean extended?" Stu presumed.
"No, actually the opposite," Wil countered. "I use x to mean an extent limit, or max. In integer names, x means the max physical capacity. In pointer values, x is one more than the last element used in some extent."
"So x subtract origin 0 is total length?" supposed Stu.
"Actually yes, that's exactly right," beamed Wil.
"At the start you said y means symbol," Stu recalled.
"Yes, in two senses not really related to each other," Wil said. "Almost all code symbol names with global scope start with y. In addition, y also means an interned string type corresponding to symbol in both Lisp and Smalltalk."
"Groovy," accepted Stu. "Find a non-arbitrary use for z?"
"I use z to mean slice," Wil replied. "It's a little arbitrary, unless you think of z as an alternative s — but s means string."
"What's a slice?" asked Stu. "Is it like a Python slice?"
"A little," nodded Wil. "A slice is a sequence subset specified by offset and length. For example ysz is a slice of a string, subclassing the base yz struct by adding a string reference."
"Slices might be useful for editing," observed Stu.
"I hope so," agreed Wil. "That's the idea."
demos « Þ
+ 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