diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c805d05..827f68a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## Current version +* Preliminary BBC Micro support. + * Added array initialization syntax with `for` (not yet finalized). * Added multiple new text codecs. diff --git a/README.md b/README.md index c9927a8a..81931542 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,8 @@ For binary releases, see: https://github.com/KarolS/millfork/releases (latest: 0 * Atari 8-bit computers + * BBC Micro + * Apple II+/IIe/Enhanced IIe * inline assembly @@ -46,10 +48,10 @@ For binary releases, see: https://github.com/KarolS/millfork/releases (latest: 0 * [Documentation](docs/index.md) -* [Example programs](examples/index.md) +* [Example programs](examples/README.md) ## Planned features -* more targets: BBC Micro/Electron, Oric computers, PC-Engine/Turbografx-16, Atari Lynx +* more targets: Oric computers, PC-Engine/Turbografx-16, Atari Lynx * support for 65816, SuperFamicom/SNES and Apple IIgs diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..a21740b0 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,37 @@ +# Documentation + + **★ WORK IN PROGRESS ★** + + +## Compiler usage + +* [Getting started](api/getting-started.md) + +* [Command-line option reference](api/command-line.md) + +* [Target platform reference](api/target-platforms.md) + +## Language reference + +* [Syntax](lang/syntax.md) + +* [Types](lang/types.md) + +* [Operators reference](lang/operators.md) + +* [Functions](lang/functions.md) + +* [Inline assembly syntax](lang/assembly.md) + +* [Important guidelines regarding reentrancy](lang/reentrancy.md) + + +## Implementation details + +* [Variable storage](abi/variable-storage.md) + +* [Undefined behaviour](abi/undefined-behaviour.md) + +* [Undocumented instruction support](abi/undocumented.md) + +* [Reference for labels in generated assembly code](abi/generated-labels.md) diff --git a/docs/abi/generated-labels.md b/docs/abi/generated-labels.md index 85287bf4..3907ddc0 100644 --- a/docs/abi/generated-labels.md +++ b/docs/abi/generated-labels.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Guide to generated label names Many Millfork constructs generate labels. diff --git a/docs/abi/inlining.md b/docs/abi/inlining.md index 34461df8..403a2ded 100644 --- a/docs/abi/inlining.md +++ b/docs/abi/inlining.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Macros and inlining ## Macros diff --git a/docs/abi/undefined-behaviour.md b/docs/abi/undefined-behaviour.md index 8691dc60..18c678e2 100644 --- a/docs/abi/undefined-behaviour.md +++ b/docs/abi/undefined-behaviour.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Undefined behaviour Since Millfork is only a middle-level programming language and attempts to eschew runtime checks in favour of performance, diff --git a/docs/abi/undocumented.md b/docs/abi/undocumented.md index 8a5c1e6e..4578cf64 100644 --- a/docs/abi/undocumented.md +++ b/docs/abi/undocumented.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Undocumented opcodes Original 6502 processors accidentally supported a bunch of extra undocumented instructions. diff --git a/docs/abi/variable-storage.md b/docs/abi/variable-storage.md index 15017986..f07c128d 100644 --- a/docs/abi/variable-storage.md +++ b/docs/abi/variable-storage.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Variable storage Variables in Millfork can belong to one of the following storage classes: diff --git a/docs/api/command-line.md b/docs/api/command-line.md index c2deb0ac..1c94c2e3 100644 --- a/docs/api/command-line.md +++ b/docs/api/command-line.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Command-line options ## General options diff --git a/docs/api/famicom-programming-guide.md b/docs/api/famicom-programming-guide.md index a422651f..53e1f61b 100644 --- a/docs/api/famicom-programming-guide.md +++ b/docs/api/famicom-programming-guide.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Famicom/NES programming guide ## Program lifecycle diff --git a/docs/api/getting-started.md b/docs/api/getting-started.md index c7e3d820..01ba62f3 100644 --- a/docs/api/getting-started.md +++ b/docs/api/getting-started.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Getting started ## Hello world example diff --git a/docs/api/target-platforms.md b/docs/api/target-platforms.md index 230435ce..562dc505 100644 --- a/docs/api/target-platforms.md +++ b/docs/api/target-platforms.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Target platforms Currently, Millfork supports creating disk- or tape-based programs for Commodore, Apple and Atari 8-bit computers, @@ -167,4 +169,6 @@ Default: `after_code`. * `::` - inclusive range of bytes in a given segment -* `extension` – target file extension, with or without the dot \ No newline at end of file +* `extension` – target file extension, with or without the dot + +* `bbc_inf` – should the `.inf` file with file metadata for BBC Micro be created diff --git a/docs/lang/assembly.md b/docs/lang/assembly.md index 7f7c7cc9..f7b230cc 100644 --- a/docs/lang/assembly.md +++ b/docs/lang/assembly.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Using assembly within Millfork programs There are two ways to include raw assembly code in your Millfork programs: diff --git a/docs/lang/functions.md b/docs/lang/functions.md index afcc8eb7..3eb32d28 100644 --- a/docs/lang/functions.md +++ b/docs/lang/functions.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Function definitions Syntax: diff --git a/docs/lang/interfacing.md b/docs/lang/interfacing.md index a3c686ec..505282f0 100644 --- a/docs/lang/interfacing.md +++ b/docs/lang/interfacing.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Interfacing with external code ## Calling external functions at a static address diff --git a/docs/lang/literals.md b/docs/lang/literals.md index 00a52fa2..63f4bd55 100644 --- a/docs/lang/literals.md +++ b/docs/lang/literals.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Literals and initializers ## Numeric literals @@ -56,11 +58,29 @@ From the type system point of view, they are constants of type byte. ## Array initialisers -An array is initialized with either a string literal, -or a list of byte literals and strings, surrounded by brackets: +An array is initialized with either: + +* a string literal + +* a `file` expression + +* a `for`-style expression + +* a list of byte literals and/or other array initializers, surrounded by brackets: + array a = [1, 2] array b = "----" scr array c = ["hello world!" ascii, 13] + array d = file("d.bin") + array e = file("d.bin", 128, 256) + array f = for x,0,until,8 [x * 3 + 5] // equivalent to [5, 8, 11, 14, 17, 20, 23, 26] -Trailing commas (`[1, 2,]`) are not allowed. \ No newline at end of file +Trailing commas (`[1, 2,]`) are not allowed. + +The parameters for `file` are: file path, optional start offset, optional length +(start offset and length have to be either both present or both absent). + +The `for`-style expression has a variable, a starting index, a direction, a final index, +and a parametrizable array initializer. +The initializer is repeated for every value of the variable in the given range. diff --git a/docs/lang/operators.md b/docs/lang/operators.md index a357e533..12349d16 100644 --- a/docs/lang/operators.md +++ b/docs/lang/operators.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Operators Unlike in high-level languages, operators in Millfork have limited applicability. @@ -198,4 +200,9 @@ Those expressions are of type `byte`. If `a` is any other kind of expression, `a `nonet(byte <<' constant byte)` Other kinds of expressions than the above (even `nonet(byte + byte + byte)`) will not work as expected. +* `hi`, `lo`: most/least significant byte of a word +`hi(word)` + + + diff --git a/docs/lang/reentrancy.md b/docs/lang/reentrancy.md index 76b4758d..9c799ba5 100644 --- a/docs/lang/reentrancy.md +++ b/docs/lang/reentrancy.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Reentrancy A function is called reentrant, diff --git a/docs/lang/syntax.md b/docs/lang/syntax.md index ddea4b80..9f431e4d 100644 --- a/docs/lang/syntax.md +++ b/docs/lang/syntax.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Syntax For information about types, see [Types](./types.md). @@ -86,6 +88,16 @@ if { } ``` +``` +if { + +} else if { + +} else { + +} +``` + ### `return` statement Syntax: diff --git a/docs/lang/types.md b/docs/lang/types.md index fe43e962..154ae2f9 100644 --- a/docs/lang/types.md +++ b/docs/lang/types.md @@ -1,3 +1,5 @@ +[< back to index](../index.md) + # Types Millfork puts extra limitations on which types can be used in which contexts. diff --git a/examples/index.md b/examples/README.md similarity index 95% rename from examples/index.md rename to examples/README.md index 2957b204..6a5d771f 100644 --- a/examples/index.md +++ b/examples/README.md @@ -2,7 +2,7 @@ ## Cross-platform examples -* [Hello world](hello_world/hello_world.mfk) (C64/C16/PET/VIC-20/Atari/Apple II) – simple text output +* [Hello world](hello_world/hello_world.mfk) (C64/C16/PET/VIC-20/Atari/Apple II/BBC Micro) – simple text output ## Commodore 64 examples