Apple-2-SW/prog8
1
0
Fork 0
mirror of https://github.com/irmen/prog8.git synced 2024-07-06 13:29:00 +00:00
Code Issues Projects Releases Wiki Activity

doc updates

Browse Source
This commit is contained in:
Irmen de Jong 2020-03-14 15:19:03 +01:00
parent 91d9559f79
commit 4fd14f1366
4 changed files with 71 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
docs/source/index.rst
View File

@ -143,6 +143,7 @@ Design principles and features
still able to directly use memory addresses, CPU registers and ROM subroutines, 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 and inline assembly to have full control when every cycle or byte matters
- Arbitrary number of subroutine parameters (constrained only by available memory) - 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 - Complex nested expressions are possible
- Values are typed. Types supported include signed and unsigned bytes and words, arrays, strings and floats. - 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. - 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 - 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 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. 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: .. _requirements:
@ -167,26 +168,25 @@ Required tools
-------------- --------------
`64tass <https://sourceforge.net/projects/tass64/>`_ - cross assembler. Install this on your shell path. `64tass <https://sourceforge.net/projects/tass64/>`_ - cross assembler. Install this on your shell path.
A recent .exe version of this tool for Windows can be obtained from my `clone <https://github.com/irmen/64tass/releases>`_ of this project. It's very easy to compile yourself.
For other platforms it is very easy to compile it yourself (make ; make install). A recent precompiled .exe for Windows can be obtained from my `clone <https://github.com/irmen/64tass/releases>`_ of this project.
A **Java runtime (jre or jdk), version 8 or newer** is required to run the packaged compiler. 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 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 <https://adoptopenjdk.net/>`_ for Fnd for Windows it's possible to get that as well. Check out `AdoptOpenJDK <https://adoptopenjdk.net/>`_ .
downloads.
Finally: a **C-64 emulator** (or a real C-64 ofcourse) to run the programs on. The compiler assumes the presence Finally: a **C-64 emulator** (or a real C-64 ofcourse) can be nice to test and run your programs on.
of the `Vice emulator <http://vice-emu.sourceforge.net/>`_. The compiler assumes the presence of the `Vice emulator <http://vice-emu.sourceforge.net/>`_.
.. important:: .. important::
**Building the compiler itself:** (*Only needed if you have not downloaded a pre-built 'fat-jar'*) **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. (Re)building the compiler itself requires a recent Kotlin SDK.
The compiler is developed using the `IntelliJ IDEA <https://www.jetbrains.com/idea/>`_ The compiler is developed using `IntelliJ IDEA <https://www.jetbrains.com/idea/>`_ ,
IDE from Jetbrains, with the Kotlin plugin (free community edition of this IDE is available). but only a Kotlin SDK installation should work as well, because the gradle tool is
But a bare Kotlin SDK installation should work just as well. 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:: .. toctree::

107
docs/source/programming.rst
View File

@ -12,57 +12,56 @@ Elements of a program
--------------------- ---------------------
Program Program
Consists of one or more *modules*. Consists of one or more *modules*.
Module Module
A file on disk with the ``.p8`` suffix. It contains *directives* and *code blocks*. 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 tabs or spaces or both. Whitespace and indentation in the source code are arbitrary and can be mixed tabs or spaces.
You can also add *comments* to the source code. A module file can *import* other modules, including *library modules*.
One moudule file can *import* others, and also import *library modules*.
Comments Comments
Everything after a semicolon ``;`` is a comment and is ignored by the compiler. 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. If the whole line is just a comment, this line will be copied into the resulting assembly source code for reference.
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...
Directive Directive
These are special instructions for the compiler, to change how it processes the code 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 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. starts with ``%``, optionally followed by some arguments.
Code block Code block
A block of actual program code. It defines a *scope* (also known as 'namespace') and A block of actual program code. It has a starting address in memory,
can contain Prog8 *code*, *variable declarations* and *subroutines*. and defines a *scope* (also known as 'namespace').
More details about this below: :ref:`blocks`. It contains variables and subroutines.
More details about this below: :ref:`blocks`.
Variable declarations Variable declarations
The data that the code works on is stored in variables ('named values that can change'). The data that the code works on is stored in variables ('named values that can change').
The compiler allocates the required memory for them. The compiler allocates the required memory for them.
There is *no dynamic memory allocation*. The storage size of all variables There is *no dynamic memory allocation*. The storage size of all variables
is fixed and is determined at compile time. is fixed and is determined at compile time.
Variable declarations tend to appear at the top of the code block that uses them. 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. 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 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. that don't allocate storage but instead point to a fixed location in the address space.
Code Code
These are the instructions that make up the program's logic. There are different kinds of instructions These are the instructions that make up the program's logic.
('statements' is a better name): Code can only occur inside a subroutine.
There are different kinds of instructions ('statements' is a better name) such as:
- value assignment - value assignment
- looping (for, while, repeat, unconditional jumps) - looping (for, while, repeat, unconditional jumps)
- conditional execution (if - then - else, when, and conditional jumps) - conditional execution (if - then - else, when, and conditional jumps)
- subroutine calls - subroutine calls
- label definition - label definition
Subroutine Subroutine
Defines a piece of code that can be called by its name from different locations in your code. 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 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. It can define its own variables, and it is even possible to define subroutines nested inside other subroutines.
Their contents is scoped accordingly. 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 Label
This is a named position in your code where you can jump to from another place. 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, Scopes, and accessing Symbols
------------------------------------- -------------------------------------
**Blocks** are the top level separate pieces of code and data of your program. They are combined **Blocks** are the top level separate pieces of code and data of your program. They have a
into a single output program. No code or data can occur outside a block. Here's an example:: 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 { Here's an example::
; this is code inside the block...
}
main $c000 {
; this is code inside the block...
}
The name of a block must be unique in your entire program. 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. 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). 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. 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 Usually it is omitted, and the compiler will automatically choose the location (usually immediately after
the previous block in memory). 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: .. _scopes:
@ -133,14 +136,13 @@ Scopes are created using either of these two statements:
- subroutines (nested named scope) - subroutines (nested named scope)
.. note:: .. 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. 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 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 the want to use inside a subroutine. But it is done precisely for this reason: memory in prog8's
target system is very limited and it would be a waste to allocate a lot of variables. 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
Right now the prog8 compiler is not advanced enough to be able to 'share' or 'overlap' variables intelligently. So for now that is something the programmer has to think about.
variables intelligently by itself. So for now, it's something the programmer has to think about.
Program Start and Entry Point 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):: As any subroutine, it has to end with a ``return`` statement (or a ``goto`` call)::
main { main {
sub start () { sub start () {
; program entrypoint code here ; program entrypoint code here
return return
} }
} }
The ``main`` module is always relocated to the start of your programs The ``main`` module is always relocated to the start of your programs
@ -175,7 +177,6 @@ calls with the SYS statement.
Variables and values Variables and values
-------------------- --------------------

5
docs/source/syntaxreference.rst
View File

@ -172,13 +172,13 @@ Code blocks
----------- -----------
A named block of actual program code. Itefines a *scope* (also known as 'namespace') and 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*::
<blockname> [<address>] { <blockname> [<address>] {
<directives> <directives>
<variables> <variables>
<statements>
<subroutines> <subroutines>
<inline asm>
} }
The <blockname> must be a valid identifier. The <blockname> 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 Labels
------ ------

2
docs/source/todo.rst
View File

@ -11,7 +11,7 @@ Memory Block Operations integrated in language?
array/string memory block operations? array/string memory block operations?
- vector inc/dec/add/sub/mul/div...? (on array or string): - 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 - array operations
copy (from another array with the same length), shift-N(left,right), rotate-N(left,right) copy (from another array with the same length), shift-N(left,right), rotate-N(left,right)