OAKLISP(1)

✨ OAKLISP(1) ✨

okay bestie, pull up a chair 🎀 this is the manual page for oaklisp, section 1 of your General Commands Manual. It's an implementation of the Oaklisp object-oriented Scheme dialect, and yeah, it's a whole vibe. Let's get into it 💅

---

🌸 NAME 🌸

oaklisp — an implementation of the Oaklisp object-oriented Scheme dialect. That's it, that's the name section, she's concise 👑

---

🦋 SYNOPSIS 🦋

oaklisp [ emulator-options ... [ -- oaklisp-options ... ]]

note the double dash bestie, she's the wall between the two option worlds 😭

---

💖 DESCRIPTION 💖

So, Oaklisp is an object-oriented dialect of Scheme. This particular implementation? Super portable, no cap — it compiles down to a virtual machine, and that VM gets emulated by a C program. And before you come for her about speed: reasonable speed is achieved through a variety of sophisticated techniques. She ate. Periodt ✨

---

💅 OPTIONS 💅

Okay so the lore here first, because it matters:

• Every option is a long option. Starting it with one dash or two dashes makes no difference — - and -- are the same thing, she does not care 🙈
• Every option can be abbreviated to a unique prefix. Short queen energy.
• There are two sorts of options: ones for the bytecode emulator, and ones for the Oaklisp world.
• You must use a -- to separate them. That's the divider, that's the boundary, respect it 🫶

---

🌈 EMULATOR OPTIONS 🌈

• --help — show a summary of emulator options and exit. bye bestie 👋
• --version — print the version of the emulator and exit.
• --world file — file is the world to load 🌍
• --dump file — dump the world to file upon exit.
• --d file — synonym for --dump. Same girl, shorter name 💁
• --dump-base b — 0=ascii, 2=binary; default=2.
• --predump-gc b — 0=no, 1=yes; default=1.
• --size-heap n — n is in kilo-refs, default 128.
• --size-val-stk n — value stack buffer, n is in refs.
• --size-cxt-stk n — context stack buffer, n is in refs.
• --size-seg-max n — maximum flushed segment len, n is in refs.
• --trace-gc v — 0=quiet, 3=very detailed; default=0. spill the tea, GC ☕
• --verbose-gc v — synonym for --trace-gc.
• --trace-traps — trace traps. That's the whole description, she's mysterious 🕵️
• --trace-files — trace filesystem operations.

---

💀 UNOPTIMIZED EMULATOR OPTIONS 💀

heads up: these are the unoptimized ones. They're here, they're real, they're just not the fast lane 🐌

• --trace-segs — trace stack segment writes/reads.
• --trace-valcon — print the entire value stack at each instr.
• --trace-cxtcon — print the entire context stack at each instr.
• --trace-stks — print the size of the stacks at each instr.
• --trace-instructions — trace each bytecode executed.
• --trace-methods — trace each method lookup.
• --trace-mcache — trace method cache.

---

👑 OAKLISP OPTIONS 👑

• --help — show a summary of Oaklisp options. (Yes, another one. Different world, different help 🫠)
• --eval expr — evaluate the Oaklisp expression expr, which is one arg, so be sure to quote it for the shell. Do not forget the quotes bestie, the shell will humble you 😭
• --load file — load a file.
• --compile file — compile file.oak yielding file.oa ✨
• --locale x — switch to locale x, eg system-locale (default), compiler-locale, scheme-locale (for RnRS compatibility).
• --exit — exit upon processing this option.

---

🌟 EXAMPLES 🌟

This one will compile the file myfile.oak in the scheme locale, and then leave the user in a read-eval-print loop in the scheme locale. Look at her go 🏃‍♀️💨

oaklisp -- --locale scheme-locale --compile myfile

---

🧚 ENVIRONMENT 🧚

The environment variable OAKWORLD will override the default compiled into the executable — but she herself can be overridden on the command line. it's a hierarchy, it's giving succession drama 👑

---

🍓 FILES 🍓

/usr/lib/x86_64-linux-gnu/oaklisp/oakworld.bin holds the world image 🌍

It is portable between machines of the same endianity. And, important caveat: the location can vary depending upon installation-time decisions. So like, check your own install, iykyk 💅

---

😭 BUGS 😭

okay gathering the girls because this section is a lot:

• Floating point numbers are not implemented. Not a drill 🚨 Rationals can be used to make up for this lack, because rationals can be told to print in floating point format, and floating point format input can be made to read as rational numbers. (There are a couple floating point implementations, but they are not merged into the distributed release.)
• In contrast to the error handling system, which is Industrial Strength 💪, the debugger is virtually nonexistent. the way that is so real and so scary 💀
• There is no foreign function interface for loading and calling C routines from a running Oaklisp. (Again, there are a couple implementations of foreign function interfaces which are not merged in.)
• The memory format does not support uninterpreted "blobs".
• Porting the system to 64-bit machines has not been done, and would be quite difficult. 😬
• POSIX threads in the emulator never got quite finished. She's in progress forever, iconic behavior honestly 🙈

Bug reports and enhancements can be filed on the github issue tracker ⟨https://github.com/barak/oaklisp⟩ 🫶

---

📚 REFERENCES 📚

The programs are documented more fully in the language and implementation manuals lang.pdf and lim.pdf, along with OaklispSummary.pdf — whose source is included with the distribution, and installed in /usr/share/doc/oaklisp/.

The Oaklisp home page is old location ⟨http://barak.pearlmutter.net/oaklisp/⟩ to github ⟨https://github.com/barak/oaklisp⟩.

The Implementation of Oaklisp is a chapter in Topics in Advanced Language Implementation, edited by Peter Lee, pp 189-215, MIT Press, 1991.

Oaklisp: an Object-Oriented Dialect of Scheme appears in the journal Lisp and Symbolic Computation 1(1):39-51, published by Klewer Associates, May 1988.

Oaklisp: an Object-Oriented Scheme with First Class Types appeared in proceedings of the ACM conference OOPSLA-86, pp30-37, published as a special issue of SIGPLAN Notices.

Garbage collection with pointers to single cells, an article on the Oaklisp garbage collector, appeared in Communications of the ACM, 39(12):202-206 (online edition), December 1996.

The Revised^n Report on Scheme is a useful piece of documentation, and is widely available online. go read it bestie, it's the blueprint 📖✨

---

🎀 DISTRIBUTION 🎀

The Oaklisp copyright belongs to its authors. It is distributed under the GNU General Public License, a copy of which is included in the source distribution in the file COPYING. For further information, or to make alternate arrangements, please contact the authors — who are surprisingly reasonable people 🫶😭 (that's a direct quote and honestly the most endearing thing in this whole manpage)

---

✨ AUTHOR ✨

Oaklisp was originally designed, implemented, and documented by Barak A. Pearlmutter and Kevin J. Lang. Legends only 👑👑

---

and that's the whole page, bestie 🌸 this was OAKLISP(1) from the General Commands Manual, section 1 — a real one, a classic, she's been around. now go compile something and slay 💖✨🦋