Curriculum to Lever

This guide will present a learning path to Lever programming.

Prerequisite for working through this guide is that you have
setup your programming environment. It is important that you
can write and run Lever programs. The earlier guides provide
a starting point for obtaining such environment.

After you've worked through this guide, you'll be on your
way to learning Lever language and programming.

1. Introduction

Some other languages, in odd cases even fringe ones, have
tens to hundreds of contributors. Lever has so far only few
active contributors. At the current rate that we are capable
of publishing documentation we cannot form manuals that are
comparable to those of established programming languages.

Having your resources tight and constrained is a relative state.
Perspective you take either makes it a flaw or benefit. Many
great properties in Lever have originated from the attempts
to do better than others with what you have dealt at hand.

It is also important to understand that you, as a reader of
this guide necessarily do not have all resources to put into
learning a new and still unproven language.

We will be updating this part of a guide as we figure out
better ways to learn Lever. Overall it may be good idea to
return to this guide from time to time. Read it again and
see if you forgot anything. It is meant that there is lot of
things in this guide, condensed and available for you when
you need it.

2. What is programming?

To learn programming, it is important to understand what it
is. Even if you think you know what programming is, it is
good idea to revisit those ideas from time to time.

Everyone knows that programmers write programs. Some know
that programmers troubleshoot and debug programs. Few know
that programmers discover problems.

Most important thing to understand about programming is how
much it extends beyond writing commands to a screen. And
nothing of it happens in particular order.

How a program should have been written is commonly discovered
along writing the program. Programmers rewrite and reiterate
their code for this reason. And they write down what they
found out.

Programmers constantly discover patterns in problems they
solve. With the little information they get they can make
complex deductions. Then they put these deductions into test
and see which part of it was wrong. If there is too little
or irrelevant information to do conclusions, they conceive
ways to filter and obtain relevant information.

Little anything of this can be learned in single sitting.
And nothing can be learned by standing. You learn your most
important lessons when you work.

To learn it, you want to make sure you acknowledge that
programming is all of this above, including teaching what
you learnt. And it needs to be learned short steps at a
time.

The teachers also have to acknowledge it.

3. Curriculum

A good programming curriculum would acknowledge that
programmer must build up more than one skill. And the build
up of these skills should happen gradually and in parallel.
You might categorize these skills like this:

Knowledge of a programming language

Writing instructions in that language

Observation and analysis

Filtering and extraction of cues for deduction

Deduction of what's going on

Verification that you are correct about your
deductions

Writing explanations and informational notes

Writing documentation

Learning skills and techniques

Vast collection of mathematics and theory to fuel
deduction

Teaching of the skills ahead

Learning of these skills should generally happen in
parallel, such that it builds up together into a complex
composite skill.

To step it down, you could learn little bit of each at a
time, and then combine all of it into one as you progress.

4. Resources

Here I have listed most notable resources there are for
learning Lever.

There are links to guides on the frontpage. There will be
more of them over the time. This is meant as a centralized
location for Lever related guides. They will be roughly in
order they are meant to be read.

4-1. Grammar files

Lever programs consists of sequence of tokens. These tokens
form structures. They have a syntax that is rigid during
reading of the file.

Lever's syntax changes frequently, and can be changed.
Therefore it is insufficient to learn just the syntax.

At some point you will want to learn the syntax in its
entirety though. To do that you need to learn about
Context-free grammars. Then you need to know that Lever's
context-free grammar is found at
lever-0.8.0.grammar.

When you change this grammar, the syntax of Lever changes.
Those grammar rules are labelled with the respective semantics.

4-2. Semantics documentation

Semantics documentation tells you exactly how Lever programs
fit together. It can be considered that semantics of
Lever will rarely change. This is the part of the language
that stays put. As long as it is Lever that you read.

For now the semantics are documented in a text file called
semantics_documentation.txt.
It is sectioned by semantic labels from the simplest
construct to most difficult one, and should be feasible to
read from top to down without problems.

Semantics of any language extend to language references. It
is not even limited to the language. The programmers create
more semantics to their languages.

4-3. Internal documentation

Lever's documentation start from the source code. It first
flows into internal documentation files, and soon into
reference documentation. From there it flows to guides.

For now the internal documentation is in a text file called
internal_documentation.txt.
This documentation is sectioned by source files. It is not
perfect setting to learn, but it has large role in how the
documentation will form.

There's no reference documentation yet. This would be the
most valuable documentation of Lever and it will be
accessible in the runtime. For now the internal
documentation contains a quick reference that contains all
built-in functions.

4-4. Source code

When you understand the source code, you can discover lot of
things by reading the Lever sources. The documentation is
gradually starting to be longer than the source code. So if
you can, it's a good resource in itself.

Especially the .lc files in the lib/ directory are worth
reading through.

4-5. Sample programs

Sample programs are the next in the queue of what's going to
change and improve. You can find some of these in samples/
directory.