diff --git a/docs/source/index.rst b/docs/source/index.rst
index 1fcb2557c..63097375b 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -143,6 +143,7 @@ Design principles and features
still able to directly use memory addresses, CPU registers and ROM subroutines,
and inline assembly to have full control when every cycle or byte matters
- Arbitrary number of subroutine parameters (constrained only by available memory)
+- Nested subroutines can access variables from outer scopes, this avoids the need and overhead to pass everything via parameters
- Complex nested expressions are possible
- Values are typed. Types supported include signed and unsigned bytes and words, arrays, strings and floats.
- No dynamic memory allocation or sizing! All variables stay fixed size as determined at compile time.
@@ -158,7 +159,7 @@ Design principles and features
- The compiler tries to optimize the program and generated code, but hand-tuning of the
performance or space-critical parts will likely still be required. This is supported by
the ability to easily write embedded assembly code directly in the program source code.
-- There are many built-in functions such as ``sin``, ``cos``, ``rnd``, ``abs``, ``min``, ``max``, ``sqrt``, ``msb``, ``rol``, ``ror``, ``swap``, ``memset``, ``memcopy``, ``sort`` and ``reverse``
+- There are many built-in functions, such as ``sin``, ``cos``, ``rnd``, ``abs``, ``min``, ``max``, ``sqrt``, ``msb``, ``rol``, ``ror``, ``swap``, ``memset``, ``memcopy``, ``sort`` and ``reverse``
.. _requirements:
@@ -167,26 +168,25 @@ Required tools
--------------
`64tass `_ - cross assembler. Install this on your shell path.
-A recent .exe version of this tool for Windows can be obtained from my `clone `_ of this project.
-For other platforms it is very easy to compile it yourself (make ; make install).
+It's very easy to compile yourself.
+A recent precompiled .exe for Windows can be obtained from my `clone `_ of this project.
-A **Java runtime (jre or jdk), version 8 or newer** is required to run the packaged compiler.
-If you're scared of Oracle's licensing terms, most Linux distributions ship OpenJDK instead
-and for Windows it's possible to get that as well. Check out `AdoptOpenJDK `_ for
-downloads.
+A **Java runtime (jre or jdk), version 8 or newer** is required to run the prog8 compiler itself.
+If you're scared of Oracle's licensing terms, most Linux distributions ship OpenJDK instead.
+Fnd for Windows it's possible to get that as well. Check out `AdoptOpenJDK `_ .
-Finally: a **C-64 emulator** (or a real C-64 ofcourse) to run the programs on. The compiler assumes the presence
-of the `Vice emulator `_.
+Finally: a **C-64 emulator** (or a real C-64 ofcourse) can be nice to test and run your programs on.
+The compiler assumes the presence of the `Vice emulator `_.
.. important::
**Building the compiler itself:** (*Only needed if you have not downloaded a pre-built 'fat-jar'*)
- (re)building the compiler itself requires a recent Kotlin SDK.
- The compiler is developed using the `IntelliJ IDEA `_
- IDE from Jetbrains, with the Kotlin plugin (free community edition of this IDE is available).
- But a bare Kotlin SDK installation should work just as well.
+ (Re)building the compiler itself requires a recent Kotlin SDK.
+ The compiler is developed using `IntelliJ IDEA `_ ,
+ but only a Kotlin SDK installation should work as well, because the gradle tool is
+ used to compile everything from the commandline.
- Instructions on how to obtain a working compiler are in :ref:`building_compiler`.
+ Instructions on how to obtain a prebuilt compiler are in :ref:`building_compiler`.
.. toctree::
diff --git a/docs/source/programming.rst b/docs/source/programming.rst
index 031a24258..9ba8f4de0 100644
--- a/docs/source/programming.rst
+++ b/docs/source/programming.rst
@@ -12,57 +12,56 @@ Elements of a program
---------------------
Program
- Consists of one or more *modules*.
+ Consists of one or more *modules*.
Module
- A file on disk with the ``.p8`` suffix. It contains *directives* and *code blocks*.
- Whitespace and indentation in the source code are arbitrary and can be tabs or spaces or both.
- You can also add *comments* to the source code.
- One moudule file can *import* others, and also import *library modules*.
+ A file on disk with the ``.p8`` suffix. It can contain *directives* and *code blocks*.
+ Whitespace and indentation in the source code are arbitrary and can be mixed tabs or spaces.
+ A module file can *import* other modules, including *library modules*.
Comments
- Everything after a semicolon ``;`` is a comment and is ignored by the compiler.
- If the whole line is just a comment, it will be copied into the resulting assembly source code.
- This makes it easier to understand and relate the generated code. Examples::
-
- A = 42 ; set the initial value to 42
- ; next is the code that...
+ Everything after a semicolon ``;`` is a comment and is ignored by the compiler.
+ If the whole line is just a comment, this line will be copied into the resulting assembly source code for reference.
Directive
- These are special instructions for the compiler, to change how it processes the code
- and what kind of program it creates. A directive is on its own line in the file, and
- starts with ``%``, optionally followed by some arguments.
+ These are special instructions for the compiler, to change how it processes the code
+ and what kind of program it creates. A directive is on its own line in the file, and
+ starts with ``%``, optionally followed by some arguments.
Code block
- A block of actual program code. It defines a *scope* (also known as 'namespace') and
- can contain Prog8 *code*, *variable declarations* and *subroutines*.
- More details about this below: :ref:`blocks`.
+ A block of actual program code. It has a starting address in memory,
+ and defines a *scope* (also known as 'namespace').
+ It contains variables and subroutines.
+ More details about this below: :ref:`blocks`.
Variable declarations
- The data that the code works on is stored in variables ('named values that can change').
- The compiler allocates the required memory for them.
- There is *no dynamic memory allocation*. The storage size of all variables
- is fixed and is determined at compile time.
- Variable declarations tend to appear at the top of the code block that uses them.
- They define the name and type of the variable, and its initial value.
- Prog8 supports a small list of data types, including special 'memory mapped' types
- that don't allocate storage but instead point to a fixed location in the address space.
+ The data that the code works on is stored in variables ('named values that can change').
+ The compiler allocates the required memory for them.
+ There is *no dynamic memory allocation*. The storage size of all variables
+ is fixed and is determined at compile time.
+ Variable declarations tend to appear at the top of the code block that uses them.
+ They define the name and type of the variable, and its initial value.
+ Prog8 supports a small list of data types, including special 'memory mapped' types
+ that don't allocate storage but instead point to a fixed location in the address space.
Code
- These are the instructions that make up the program's logic. There are different kinds of instructions
- ('statements' is a better name):
+ These are the instructions that make up the program's logic.
+ Code can only occur inside a subroutine.
+ There are different kinds of instructions ('statements' is a better name) such as:
- - value assignment
- - looping (for, while, repeat, unconditional jumps)
- - conditional execution (if - then - else, when, and conditional jumps)
- - subroutine calls
- - label definition
+ - value assignment
+ - looping (for, while, repeat, unconditional jumps)
+ - conditional execution (if - then - else, when, and conditional jumps)
+ - subroutine calls
+ - label definition
Subroutine
Defines a piece of code that can be called by its name from different locations in your code.
It accepts parameters and can return a value (optional).
It can define its own variables, and it is even possible to define subroutines nested inside other subroutines.
Their contents is scoped accordingly.
+ Nested subroutines can access the variables from outer scopes.
+ This removes the need and overhead to pass everything via parameters.
Label
This is a named position in your code where you can jump to from another place.
@@ -90,16 +89,20 @@ Scope
Blocks, Scopes, and accessing Symbols
-------------------------------------
-**Blocks** are the top level separate pieces of code and data of your program. They are combined
-into a single output program. No code or data can occur outside a block. Here's an example::
+**Blocks** are the top level separate pieces of code and data of your program. They have a
+starting address in memory and will be combined together into a single output program.
+They can only contain *directives*, *variable declarations*, *subroutines* and *inline assembly code*.
+Your actual program code can only exist inside these subroutines.
+(except the occasional inline assembly)
- main $c000 {
- ; this is code inside the block...
- }
+Here's an example::
+ main $c000 {
+ ; this is code inside the block...
+ }
The name of a block must be unique in your entire program.
-Also be careful when importing other modules; blocks in your own code cannot have
+Be careful when importing other modules; blocks in your own code cannot have
the same name as a block defined in an imported module or library.
If you omit both the name and address, the entire block is *ignored* by the compiler (and a warning is displayed).
@@ -109,7 +112,7 @@ want to work on later, because the contents of the ignored block are not fully p
The address can be used to place a block at a specific location in memory.
Usually it is omitted, and the compiler will automatically choose the location (usually immediately after
the previous block in memory).
-The address must be >= ``$0200`` (because ``$00``--``$ff`` is the ZP and ``$100``--``$200`` is the cpu stack).
+It must be >= ``$0200`` (because ``$00``--``$ff`` is the ZP and ``$100``--``$1ff`` is the cpu stack).
.. _scopes:
@@ -133,14 +136,13 @@ Scopes are created using either of these two statements:
- subroutines (nested named scope)
.. note::
- In contrast to many other programming languages, a new scope is *not* created inside
+ Unlike many other programming languages, a new scope is *not* created inside
for, while and repeat statements, nor for the if statement and branching conditionals.
- This is a bit restrictive because you have to think harder about what variables you
- want to use inside a subroutine. But it is done precisely for this reason; memory in the
- target system is very limited and it would be a waste to allocate a lot of variables.
-
- Right now the prog8 compiler is not advanced enough to be able to 'share' or 'overlap'
- variables intelligently by itself. So for now, it's something the programmer has to think about.
+ This can be a bit restrictive because as a programmer you have to think harder about what variables you
+ want to use inside a subroutine. But it is done precisely for this reason: memory in prog8's
+ target systems is usually very limited and it would be a waste to allocate a lot of variables.
+ The prog8 compiler is not yet advanced enough to be able to share or overlap
+ variables intelligently. So for now that is something the programmer has to think about.
Program Start and Entry Point
@@ -159,12 +161,12 @@ taking no parameters and having no return value.
As any subroutine, it has to end with a ``return`` statement (or a ``goto`` call)::
- main {
- sub start () {
- ; program entrypoint code here
- return
- }
- }
+ main {
+ sub start () {
+ ; program entrypoint code here
+ return
+ }
+ }
The ``main`` module is always relocated to the start of your programs
@@ -175,7 +177,6 @@ calls with the SYS statement.
-
Variables and values
--------------------
diff --git a/docs/source/syntaxreference.rst b/docs/source/syntaxreference.rst
index 25136fc3d..4f4e67db4 100644
--- a/docs/source/syntaxreference.rst
+++ b/docs/source/syntaxreference.rst
@@ -172,13 +172,13 @@ Code blocks
-----------
A named block of actual program code. Itefines a *scope* (also known as 'namespace') and
-can contain Prog8 *code*, *directives*, *variable declarations* and *subroutines*::
+can only contain *directives*, *variable declarations*, *subroutines* or *inline assembly*::
[] {
-
+
}
The must be a valid identifier.
@@ -191,7 +191,6 @@ Also read :ref:`blocks`. Here is an example of a code block, to be loaded at ``
}
-
Labels
------
diff --git a/docs/source/todo.rst b/docs/source/todo.rst
index 60da8d815..3fab45f78 100644
--- a/docs/source/todo.rst
+++ b/docs/source/todo.rst
@@ -11,7 +11,7 @@ Memory Block Operations integrated in language?
array/string memory block operations?
- vector inc/dec/add/sub/mul/div...? (on array or string):
- arrayvar++ / arrayvar-- / arrayvar += 2 / arrayvar -= 2 / arrayvar *= 3 / arrayvar /= 3
+ ``arrayvar++ / arrayvar-- / arrayvar += 2 / arrayvar -= 2 / arrayvar *= 3 / arrayvar /= 3``
- array operations
copy (from another array with the same length), shift-N(left,right), rotate-N(left,right)