Update docs and example

README.md

@@ -1,37 +1,9 @@
 # mul
 
-mat's untitled language
+## mat's untitled language
 
-## goals
+see [`example.mul`](/example.mul) for a syntax sample.
 
-### start simple and grow
+see [`GOALS.md`](/docs/GOALS.md) for guiding principles and inspirations.
 
-while mul's implementation is still getting started, i want to implement features atomically, one at a time, in an end to end manner.
-
-for example, we'll start with a simple system-f/bidirectional system, implement a parser, typechecker, interpreter, and code generator, then gradually layer features onto that, supporting them at every "level" of the compiler.
-
-### orthogonal and discoverable
-
-avoid overly redundant or unrelated functionality. make the core set of functionality well documented and easy to inspect. taking cues here from [fish shell](https://fishshell.com/docs/current/design.html).
-
-### robust static type system
-
-without going to the extent of dependent types, mul's type system should be expressive and flexible.
-
-### application-friendly ergonomics without sacrificing performance
-
-mul will take cues from visions for a "smaller" rust that is able to focus on a different set of problems by not specializing in systems programming.
-
-[Notes on a smaller Rust](https://without.boats/blog/notes-on-a-smaller-rust/)
-
-[Revisiting a 'smaller Rust'](https://without.boats/blog/revisiting-a-smaller-rust/)
-
-[Rust's Ugly Syntax](https://matklad.github.io/2023/01/26/rusts-ugly-syntax.html)
-
-in short, we want to take parts of rust's syntax and semantics that work well and are amenable to both machine and human analysis, while leaving behind the components that are designed around control of memory layout + representation, explicit mentions of ownership and borrowing, and other more complicated concepts.
-
-while not prioritizing it in the early implementation, mul will try to learn from rust (and its progeny) to sacrifice as little performance as possible while still offering a substantially simpler interface.
-
-### incremental, interactive, intelligent
-
-parsing, typechecking, evaluating, compiling, etc should be usable across a batch compiler, interactive REPL, and IDE tooling. program information should be preserved where possible.
+see [`ROADMAP.md`](/docs/ROADMAP.md) for specific implementation plans and progress.

docs/GOALS.md

@@ -0,0 +1,61 @@
+# goals
+
+## learning!
+
+the primary goal with mul is for me to work through implementing a compiler, something i have long wanted to do, but never actually succeeded in.
+
+## start simple and grow
+
+while mul's implementation is still getting started, i want to implement features atomically, one at a time, in an end to end manner.
+
+for example, we'll start with a simple system-f/bidirectional system, implement a parser, typechecker, interpreter, and code generator, then gradually layer features onto that, supporting them at every "level" of the compiler.
+
+## orthogonal and discoverable
+
+avoid overly redundant or unrelated functionality. make the core set of functionality well documented and easy to inspect. 
+
+inspiration:
+- [fish shell design](https://fishshell.com/docs/current/design.html)
+
+## robust static type system
+
+without going to the extent of dependent types, mul's type system should be expressive and flexible.
+
+### experiment with capabilities and/or effects
+
+one specific feature of the type system will be a focus on safety and security through control of side effects. two interesting avenues to explore for these aspects will be capabilities and effect handling.
+
+capabilities:
+- [Lambda Capabilities](https://roscidus.com/blog/blog/2023/04/26/lambda-capabilities)
+- [What Are Capabilities?](http://habitatchronicles.com/2017/05/what-are-capabilities/)
+- [Spritely - What is CapTP, and what does it enable?](https://spritelyproject.org/news/what-is-captp.html)
+- [Cap'n Proto](https://capnproto.org/)
+
+effects:
+- [Unison's Introduction to Abilities: A Mental Model](https://www.unison-lang.org/learn/fundamentals/abilities/)
+- [Algebraic Effects for the Rest of Us](https://overreacted.io/algebraic-effects-for-the-rest-of-us/)
+- [The Koka Programming Language](https://koka-lang.github.io/koka/doc/book.html)
+- [Eff's An Introduction to Algebraic Effects and Handlers](https://www.eff-lang.org/handlers-tutorial.pdf)
+- [Exotic Programming Ideas: Effect Systems](https://www.stephendiehl.com/posts/exotic03.html)
+
+open question: how should this design interact with a trait system? can/should effects subsume traits?
+
+## application-friendly ergonomics without sacrificing performance
+
+mul will take cues from visions for a "smaller" rust that is able to focus on a different set of problems by not specializing in systems programming.
+
+inspiration:
+- [Notes on a smaller Rust](https://without.boats/blog/notes-on-a-smaller-rust/)
+- [Revisiting a 'smaller Rust'](https://without.boats/blog/revisiting-a-smaller-rust/)
+- [Rust's Ugly Syntax](https://matklad.github.io/2023/01/26/rusts-ugly-syntax.html)
+
+in short, we want to take parts of rust's syntax and semantics that work well and are amenable to both machine and human analysis, while leaving behind the components that are designed around control of memory layout + representation, explicit mentions of ownership and borrowing, and other more complicated concepts.
+
+while not prioritizing it in the early implementation, mul will try to learn from rust (and its progeny) to sacrifice as little performance as possible while still offering a substantially simpler interface.
+
+## incremental, interactive, intelligent
+
+parsing, typechecking, evaluating, compiling, etc should be usable across a batch compiler, interactive REPL, and IDE tooling. program information should be preserved where possible.
+
+inspiration:
+- [Query-based compiler architectures](https://ollef.github.io/blog/posts/query-based-compilers.html)

docs/ROADMAP.md

@@ -24,5 +24,6 @@
   - [ ] sum types
     - [ ] variant types
 - [ ] pattern matching
-- [ ] traits
+- [ ] traits (?)
   - [ ] operator overloading
+- [ ] capabilities/effects

example.mul

@@ -1,9 +1,8 @@
-let main = || {
-  let result = sum_equals(1, 2, 3);
-  print(result)
-};
-
+fn main() {
   let sum_equals = |x, y, expected| {
-  let sum = add(x, y);
-  equals(sum, expected)
+    let sum = _add(x, y);
+    _equals(sum, expected)
   };
+  let result = sum_equals(1, 2, 3);
+  _print(result)
+}