Name is TBD; Joss for now.

# Inspiration

[Worse Is Better](https://www.dreamsongs.com/WIB.html): A long essay on
Lisp, programming languages, and what we can do to make lisp better
today. Not much of this has been realized.

[Learnable programming: Designing a programming system for understanding programs](http://worrydream.com/#!/LearnableProgramming).

[Programming as Theory Building](https://gist.github.com/jakeisnt/d06220e4dcfa66b217272331701e1089):
We should architect a programming system that respects such a model.
Programming reflects the act of building up a programmer's knowledge,
and programs contain both the ideas behind some software development
practice and the results of the practice - that is, they produce both
functions that encode models of the world and runnable code that can
abstract over such models. I think there is space for a pedagogical
cirriculum based on developing functional programs: we accumulate
functions in some function store, and continue to iterate on them - or
develop new functions - to accumulate knowledge, because the best way to
learn something is to do it and to demonstrate that it works.

[Computers and Creativity · Molly Mielke](https://www.mollymielke.com/cc): What do people want to use their tools for to express themselves?

Mindstorms. Logo. Hungarian method. Let the user both build from first
principles and dissect the interfaces they've been given.

Today's journal has some useful thoughts here.

Build on top of NixOS: existing command line programs can be dispatched
to, but those without a "JOSS" interface don't 'feel good' to use; might
be able to leverage 'nushell' information to get some of this
automatically as JOSS. Building on Linux is super important for scale,
though.

[Tracery](https://tracery.io/): Graphics language for students.

# Goals

- Strong and secure type system. Static types are excellent and help
  programmers, but they should stay out of the way as much as possible.
- Practical to program in. Programmers shouldn't have to dig into types,
  macros or system guts to grok things.
- Offload as much codebase management, tech debt, refactoring work to
  the system as you can.
- No default concrete syntax - the language can use whatever syntax
  you'd prefer. The concrete syntax used in this document is going to be
  the s-expression based syntax provided with the language

# Codebase Management

Forget about files, modules, all of that garbage. A Joss system is a bag
of functions. The end user pulls types and tools out of that bag to use
in their programs. The system should recommend these tools to the end
user as frequently as possible.

## Program Exportation

To export a program from Joss is to provide a single Joss function to
export. This creates a program tree and exports a database that contains
everything in the program tree. Any functions that aren't used just
don't show up in the tree, so there is no notion of codebase bloat.

## <span class="todo TODO">TODO</span> Version Control

This is a big problem

# Projections

Projections are mappings from the Joss AST to concrete syntax. A default
s-expression based projection is provided. Another name could be
\`syntax\`, but \`projection\` sounds much cooler.

Once a projection is defined, error messages should print with respect
to that projection as well.

# Exceptions

# Types

Statically typed; makes heavy use of row polymorphism. Supports type
inference of course. Users should not have to write types for most
things. This gives programmers incredible flexibility while preserving a
strong type system.

## Primitives

### Numbers

Support arbitrary precision arithmetic. End-user programmers should not
have to worry about numbers at all. Make the number type as flexible as
possible.

### Strings

I would like to discourage language users from using strings whenever
possible; how can this be done while still retaining practicality? Maybe
abstracting this idea of custom deserializers to make types look nice
can also be leveraged in this way? Or **guaranteeing** that strings can
not be used inline?

## Enumerations

``` joss
```

## Pair

## Number

## Function Types

Syntax is inspired by Racket's contract system

``` joss
(-> number bool)
(-> (mapping number string) number)

;; named function
(function add-nums (a1     a2) ;; name, arg1, arg2
          (->      number  number number) ;; optional contract
          "Add two numbers together." ;; optional docstring
          (+ a1 a2)) ;; function body

;; having the docstring in the function body gives us lots of information:
;; - we're guaranteed that it's affiliated with the function
;; - can compute edit distance from other purpose statements to identify similar functions

;; alternative for signature
(function ([a1 string] [a2 number])
          )

;; anonymous function
(function (a1 a2)
          (+ a1 a2))

(function get-keys (mp)
          (->      )
)

;; can add types to functions after the fact in different contexts to 'concretize' them
(: add-nums (-> number number number))

```

## Expressiveness Requirements

### Algebraic Data Types

This is syntactic sugar for adding a tag to a union type!

``` joss
(type Name (name 'a 'b 'c 'd)
  (map 'a 'b
       'c 'd))
```

Desugared, this looks like

``` joss
(type (name 'a 'b 'c 'd)
  (map 'a 'b
       'c 'd
       "__type": "Name"))
```

### <span class="todo TODO">TODO</span> Flexible Map

``` joss
(type (map 'a 'b 'c 'd ..)
  (pair
   (pair 'a 'b)
   (pair 'c 'd)))
```

### <span class="todo TODO">TODO</span> Mapping

All keys are of the same type; so are all values.

``` joss
(type (mapping 'a 'b)
  )
```

### List

``` joss
(type (list 'a)
   (OR (pair 'a (list 'a))
       #empty))
```

### Array

``` joss
(type (array 'a)
  (mapping 'number 'a))
```

### Boolean

``` joss
(type bool
  (or #true #false))
```

### <span class="todo TODO">TODO</span> Tuple

``` joss
(type (tuple 'a 'b  'c ...)
  (pair 'a (pair 'b) ...)
```