diff --git a/bp/LICENSE b/bp/LICENSE new file mode 100644 index 0000000..d159169 --- /dev/null +++ b/bp/LICENSE @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. diff --git a/bp/README.md b/bp/README.md new file mode 100644 index 0000000..aac2020 --- /dev/null +++ b/bp/README.md @@ -0,0 +1,491 @@ +--- +title: "Turbo-Basic XL and Atari BASIC parser tool" +author: https://github.com/dmsc/tbxl-parser +book: true +classoption: [oneside] +titlepage: true, +titlepage-text-color: "FFFFFF" +titlepage-rule-color: "FFFFFF" +titlepage-rule-height: 0 +titlepage-background: "expr.pdf" +... + +# Turbo-Basic XL and Atari BASIC parser tool + +This program parses and tokenizes a _Turbo-Basic XL_ or _Atari BASIC_ listing in +a flexible format and produces any of three outputs: + +- A tokenized binary file, directly loadable in the original _Turbo-Basic XL_ + (or _Atari BASIC_ if the `-A` option is given) interpreter. This mode also + replaces variables with single letters by default, but with the `-f` option + writes the full variable names and with the `-x` option writes empty variable + names, making the program unable to be listed or edited. + + This is the default operating mode, and also can be forced with the `-b` + command line switch. + +- A minimized listing, replacing variable names with single letters, using + abbreviations, removing spaces and using Atari end of lines. + + This mode is selected with the `-s` command line switch. Adding the `-f` + option keeps the names of variables with 2 or less characters. + +- A pretty printed expanded listing, with one statement per line and + indentation, and standard ASCII line endings. + + Note that this format can be read back again, but some statements are + transformed in the process, this can lead to problems in non-standard + `IF`/`THEN` constructs. + + Currently, `IF`/`THEN` with statements after the `THEN` are converted to + multi-line `IF`/`ENDIF` statements. + + This mode is selected with the `-l` command line switch. + + +## Example Programs + +The following is an example of a simple program in free form: + +```purebasic + ' Example program + + ' One statement per line: + print "Hello All" + print "---------" + print "This is a heart: \00" + + ' Also, multiple statements per line: + for counter = 0 to 10 : ? "Iter: "; counter : next counter + + ' Line numbers +30 + ' And abbreviations: + g. 30 + +``` + +To generate a tokenized BAS file, loadable by _Turbo-Basic XL_, simply type: + + basicParser samples/sample-1.txt + +This will generate a `sample-1.bas` file in the same folder. + +If on the other hand you want a minimized listing file in ATASCII format (suitable +for `ENTER` into _Atari BASIC_, type: + + basicParser -l -A samples/sample-1.txt + +This will generate a `sample-1.lst` file in the same folder. + +There are more sample programs, located in the `samples` folder that illustrate +the free-form input format. + + +## Input listing format + +The parser accepts standard listings for _Atari BASIC_ or _Trubo-Basic XL_ +programs, with Atari or ASCII end of lines. + +All the standard abbreviations available in the original interpreters are also +accepted. + +As with _Turbo-Basic XL_, the input is case insensitive (uppercase, lowercase +and mixed case is supported). + + +### Line numbers + +You can omit line numbers, only lines that are target to `GOTO` / `GOSUB` / +`THEN` needs them. If you use only labels, no line numbers are needed. + +Also, line numbers can appear alone in a line, for better readability. + + +### Comments + +Comments can be started by `'` in addition to the _Turbo-Basic XL_ `.`, `--` +or `rem`. In short listing an tokenized output formats all comments are +removed unless the `-k` option is given. + +All comment types are supported in _Atari BASIC_ mode. + + +### Special characters inside string constants + +Inside strings, special characters can be specified by using a backslash +followed by an hexadecimal number in upper-case, (i.e., `"\00\A0"` produces a +string with a "heart" and an inverse space "♥█"), this allows editing special +characters on any standard editor. + +Note that to force a backslash before a valid hex number, you can use two +backslashes (i.e., ``"123\\456"`` produces ``123\456``). + + +### Extended string constants + +There is support for extended strings, with embedded character names. + +Extended strings start with with `["` and ends with `"]`, and can contain: + +- Special characters with `{name}` or `{count*name}`, with count a decimal + number and name from the list: + `heart`, `rbranch`, `rline`, `tlcorner`, `lbranch`, `blcorner`, `udiag`, + `ddiag`, `rtriangle`, `brblock`, `ltriangle`, `trblock`, `tlblock`, + `tline`, `bline`, `blblock`, `clubs`, `brcorner`, `hline`, `cross`, `ball`, + `bbar`, `lline`, `bbranch`, `tbranch`, `lbar`, `trcorner`, `esc`, `up`, + `down`, `left`, `right`, `diamond`, `spade`, `vline`, `clr`, + `del`, `ins`, `tbar`, `rbar`, `eol`, `bell`. + +- Inverse video characters surrounded by `~`. + +- Multiple lines, you can terminate the string in a different line than the + start. Note that this will embed end-of-line characters in the string, so it + will only work in tokenized output, not short-listing output. + + +### Parameters and local variables for `PROC` + +Arguments follow the `PROC` label after a comma, and local variables follow +after a semicolon: +```purebasic + D = 3 + EXEC Testing, D+5, "Hello" + PRINT D + PROC Testing, A, B$(10); D + D = A + 1 + PRINT D; " and "; B$ + ENDPROC +``` + +As the example shows, string variables must include the dimensioned length, +as the parser adds a `DIM` at the start of the program to initialize. The +dimensioned length must be an integer, a `$define` or a `%` number. + +Also, setting the value of variable "D" inside the procedure does not alter +the value of the variable "D" outside the procedure. + +The parser transform this construct by creating new variables that hold the +parameters and local variables, so the resulting procedures don't support +recursion. + + +### Syntax from _Turbo-Basic XL_ in _Atari BASIC_ + +Some of the extra statements from _Turbo-Basic XL_ are supported even in _Atari +BASIC_ output mode, those are converted to equivalent forms: + +- Multi-line `IF`/`ENDIF` statements are converted to `IF`/`THEN`. + +- The `%0` to `%3` tokens are converted to the numbers 0 to 3. + +- `PUT` without I/O channel is converted to `PUT #16`. This relies on a bug + in _Atari BASIC_ that makes I/O channel 16 equal to 0. + +- String constants are converted to decimal constants. + + +### Parsing directives + +There are parsing *directives* added, that consist on lines starting with a +dollar sign `$`. A list of available directives is documented bellow. + + +## Program Usage + + basicParser [options] [-o output] filenames + +Options: + +- `-n nun` Sets the maximum line length before splitting lines to `num`. + Note that if a single statement is longer than this, the line + is output anyway. + The default is 120 characters (the standard Atari Editor limit) + +- `-l` Output long (readable) listing, suitable for editing, with standard + end of lines and lowercase statements. + +- `-s` Output a short, minimized listing, with ATASCII end of lines. The + default output file name is the same as input with `.lst` extension + added. + +- `-b` Output a binary tokenized file instead of a listing. The default + output file name is the same as input with `.bas` extension added. Note + that this is the default behaviour. + +- `-A` Accept (and produce) standard _Atari BASIC_ language, without the + extended statements and syntax. Note that some of the optimizations are + specific to _Turbo-Basic XL_ and won't run in this mode. + +- `-x` In binary output mode, writes null variable names, making the program + unlistable. This options does nothing on listing output. + +- `-f` In binary output mode, writes the full variable names, this eases + debugging the program. In short listing mode, keeps the names of + variables with less than two characters, renaming all longer or invalid + names. + +- `-k` In binary output mode, keeps comments in the output. Note that only + standard comments are included, not new style (`'`) comments. + +- `-a` In long output, replace Atari characters in comments with + approximating characters. + +- `-v` Shows more parsing information, like name of renamed variables. + (verbose mode) + +- `-q` Don't show any parsing output, only errors. (quiet mode) + +- `-o` Sets the output file name. By default, the output is the name of the + input with `.lst` (listing) or `.bas` (tokenized) extension. If the + given name starts with a dot, use as output file name extension. + +- `-c` Output to standard output instead of a file. + +- `-O` Enables parser optimizations to produce smaller or faster code. Without + and argument enables all optimizations, an argument can be given + similar to the `optimize` directive in the code, see bellow for the + possible options. The option can be specified multiple times, an + example for producing short listings is `-O -O -convert_percent -O + -const_replace` + +- `-h` Shows help and exit. + + +## Parser directives + +Directives add extra features to the parser, much like C and C++. Directives +start with a dollar as the first non blank character on a line, and continue +up to the end of the line. + +Bellow is a description of available directives. + +### `$options` directive. + +The options directive alter the way the parsing is done, accepting a list of +comma separated options, valid for the current file. Valid options: + +- `mode=compatible`: Disable features to be more compatible with the + _Turbo-Basic XL_ parser. +- `mode=extended`: Makes the parser to accept more extended features. +- `mode=default`: Returns the parser to the default mode. +- `optimize` or `+optimize`: Allows the parser to optimize the output to + produce smaller or faster code. +- `-optimize`: Disable the optimizations. +- `optimize=+`*suboption*: Enable the particular optimization option. +- `optimize=-`*suboption*: Disable the particular optimization option. + +The optimization sub-options are: + +- `const_folding`: Replace operations on constants with the result. +- `convert_percent`: Replace small integers with the `%*` equivalent, this is + only available in _Turbo-Basic XL_ mode. +- `commute`: Swap arguments to binary operations to minimize runtime. +- `line_numbers`: Remove all BASIC line numbers that are unused. +- `const_replace`: Replace repeated constant values (numeric or string) with + a variable initialized to the value. The initialization code is added + before any statement in the program, and tries to use the minimum number + of bytes posible. +- `fixed_vars`: This is the complement of the `const_replace` option, tries to + identify variables with a fixed value in the whole program and removes the + variable. Use this optimization when converting original basic listings, as + reversing the constant replacing gives a simpler listing and allows to apply + further optimizations. Note that currently this option can produce bad + results, as it does not follows the program flow and can't detect if a + variable is used before the first assignment, so it is not enabled by + default. You need to check each removed variable, as printed in the output + and in the comments in the resulting program. +- `then_goto`: Searches `IF` statements with `THEN GOTO` and removes the `GOTO` + statement, replacing with the line number alone. + Note: If the line number is not a constant, the resulting program will be + executed and listed correctly by both _Atari BASIC_ and _Turbo-Basic XL_, but + can't be entered because of an original parser limitation. Therefore, this + conversion is only done for constant values when the output is a short listing. + + Example: `IF X THEN GOTO 100` becomes `IF X THEN 100` +- `if_goto`: Performs the same optimization as `then_goto`, but also replaces + instances of multi-line `IF` statements containing a `GOTO` with `THEN` and + the target line number. + + This optimization is not enabled by default because it can produce larger + code by forcing a newline in the file. + + Example: + ``` + IF X + GOTO 100 + ENDIF + ``` + becomes + ``` + IF X THEN 100 + ``` + +Note that options can be changed at any place in the file, this is an example +of changing the parser mode in the middle of the file: + +```purebasic + ' Example program using directives + $ options optimize, mode=default + error1 = 2 + ? error1 : ' This is parsed like Turbo-Basic XL, as ? ERR OR 1 + + $options mode = extended + ? error1 : ' This is parsed as ? error1 + Printa : ' This is a parsing error. +``` + +A good optimization mode for producing short listings is: + +``` + $options +optimize, optimize=-convert_percent-const_replace +``` + +The above line instructs the parser to avoid converting numbers to `%` values +and the replacement of constants, producing a smaller listing. Note that +replacement of constants can be beneficial, so try enabling the optimization +and running with "-v" option to see what variables are good candidates for +replacement. + +### `$define` directive. + +This directive defines new symbols that are replaced at parsing time with the +values, like C macros. + +Replacement names are prefixed by `@` to differentiate from variables, and +as variables, string defines end in `$`, the syntax of the directive is: + + `$define` *defineName* `=` *value* + +Keep in mind that as the value is replaced each time the variable is used, it +is probably best to assign them to a variable instead if the value will be +used multiple times, and you should enable optimizations so that the usage is +simplified at parsing time. + +This is an example usage of the `$define` directive: + +```purebasic + ' Example usage of defines + $options +optimize + $define Message$ = "Hello world!" + $define PCOLR0 = $2C0 + + print @Message$ : ' Replaced by: ? "Hello world!" + print len(@Message$) : ' Replaced by: ? 12 + poke @PCOLR0+2, $1F : ' Replaced by: POKE 706,31 +``` + +### `$incbin` directive. + +This directive allows including data from a binary file to a new string +definition. The content of the file is read at parsing time and the full +content is stored in the define. The syntax of the directive is: + + `$incbin` *defineName$* `, "`*fileName*`"` [ , *offset* [, *length* ] ] + +The optional *offset* parameter specifies a starting offset in bytes for +the included data, and the optional *length* parameter specifies the number +of bytes to read. If *length* is not given, the file read completely. + +This is an example usage of the `$incbin` directive: + +```purebasic + $options +optimize + $incbin asmBin$, "myasm.bin" + + asmRut = adr( @asmBin$ ) : ' Store address in variable to use multiple times. + ? usr(asmRut, 1, 2) : ' Call routine. Should be relocatable and less than 242 bytes. +``` + +### `$incdata` directive. + +This directive allows including data from a binary file to a `DATA` BASIC +statement. The content of the file is read at parsing time and the full content +is stored as is. The syntax of the directive is: + + `$incdata` `"`*fileName*`"` [ , *offset* [, *length* ] ] + +The optional *offset* parameter specifies a starting offset in bytes for the +included data, and the optional *length* parameter specifies the number of +bytes to read. If *length* is not given, the file read completely. + +Note that you can use this directive to store arbitrary bytes inside the +statement, but BASIC parses the actual data at `READ` time. + + +## Limitations and Incompatibilities + +There are some incompatibilities in the way the source is interpreted with the +standard _Turbo-Basic XL_ and _Atari BASIC_ parsers: + +- The ASCII LF character (hexadecimal $10) is interpreted as end of line in + addition to the ATASCI EOL (hexadecimal $9B). This means that in `DATA` + statements and comments the LF character is not accepted. + +- The parsing of special characters inside strings means that a valid hexadecimal + sequence (`\**`, with `*` an hexadecimal number in uppercase) or two backslashes + are interpreted differently. + +- Extra statements after an `IF`/`THEN`/`LineNumber` are converted to a comment, + with the exception of `DATA` statements. + In the original, those statements are never executed, so this is not a problem + with proper code. + +- Any string is accepted as a variable name, even if it is already an statement, + function name or operator. + + The following code is valid: + + ```purebasic + PRINTED = 0 : ' Invalid in Atari BASIC, as starts with "PRINT" + DONE = 3 : ' Invalid in Turbo-Basic XL, as starts with "DO" + ``` + + This relaxed handling of variable naming creates an incompatibility, as the + first example above is parsed differently as the standard _Atari BASIC_, + where it means "`PRINT (ED = 0)`" instead of "`LET PRINTED = 0`". + + Note that currently, even full statements are accepted as variable names, + but avoid using them as they could produce hard to understand errors. + +- In long format listing output, `IF`/`THEN` are converted to `IF`/`ENDIF` + statements. This introduces an incompatibility with the following code: + + ```purebasic + FOR A = 0 TO 2 + ? "A="; A; " - "; + IF A <> 0 + ? "1"; + IF A = 1 THEN ELSE + ? "2"; + ENDIF + ? " -" + NEXT A + ``` + + This code should produce the following at output: + + ``` + A=0 - 2 - + A=1 - 1 - + A=2 - 12 - + ``` + + After conversion, the `ELSE` is associated with the second `IF` instead + of the first, giving the wrong result. + +- Parsing of `TIME$=` statement allows a space between `TIME$` and the equals + sign, but in _Turbo-Basic XL_ this gives an error. + + +## Compilation + +To compile from source, you need `gawk` and `peg`, both are available in any +recent Debian or Ubuntu Linux distro, install with: + + apt-get install gawk peg + +To compile, simply type `make` in the sources folder, a folder `build` will be +created with the executable program inside. + + diff --git a/bp/basicParser b/bp/basicParser new file mode 100755 index 0000000..b96fba6 Binary files /dev/null and b/bp/basicParser differ diff --git a/bp/basicParser-v11-0-g1b18bf3-manual.pdf b/bp/basicParser-v11-0-g1b18bf3-manual.pdf new file mode 100644 index 0000000..6c294d0 Binary files /dev/null and b/bp/basicParser-v11-0-g1b18bf3-manual.pdf differ diff --git a/bp/basicParser.exe b/bp/basicParser.exe new file mode 100755 index 0000000..d6a879a Binary files /dev/null and b/bp/basicParser.exe differ diff --git a/bp/samples/sample-1.bas b/bp/samples/sample-1.bas new file mode 100644 index 0000000..de6bf8e Binary files /dev/null and b/bp/samples/sample-1.bas differ diff --git a/bp/samples/sample-1.txt b/bp/samples/sample-1.txt new file mode 100644 index 0000000..31f0b94 --- /dev/null +++ b/bp/samples/sample-1.txt @@ -0,0 +1,16 @@ + + ' Example program + + ' One statement per line: + print "Hello All" + print "---------" + print "This is a heart: \00" + + ' Also, multiple statements per line: + for counter = 0 to 10 : ? "Iter: "; counter : next counter + + ' Line numbers +30 + ' And abbreviations: + g. 30 + diff --git a/bp/samples/sample-2.txt b/bp/samples/sample-2.txt new file mode 100644 index 0000000..5773356 --- /dev/null +++ b/bp/samples/sample-2.txt @@ -0,0 +1,60 @@ + + ' Example program with procs and labels + dim name$(20), reply$(1) + + ' Ask your name + exec ask_name + ? "Hello "; name$ + + ? "Think a number from 1 to 100, I will try to guess it." + pause 60 + + ? "Ready?" + pause 60 + + low = 1 + high = 100 + + ' Loop guessing numbers until we have no more guesses + while high - low > 0 + + my_guess = low + (high - low + 1) div 2 + exec ask_guess + + if reply = 1 + ? "I'm a genius, this was your number!!!" + low = my_guess + exit + endif + + if reply = 2 + low = my_guess + 1 + else + high = my_guess - 1 + endif + + wend + + ' We should have guessed + ? "So, your number is "; low + + end + + ' A procedure to ask a name +proc ask_name + name$ = "" + repeat + input "What is your name"; name$ + until len(name$) > 1 +endproc + + ' Procedure to guess a number +proc ask_guess + ? + ? "My guess is "; my_guess + repeat + ? "Tell me, your number is" + input "Higher, Lower of Equal"; reply$ + reply = uinstr("EHL", reply$) + until reply > 0 +endproc diff --git a/bp/samples/sample-3.txt b/bp/samples/sample-3.txt new file mode 100644 index 0000000..3f5e514 --- /dev/null +++ b/bp/samples/sample-3.txt @@ -0,0 +1,17 @@ + ' Example of extended strings + + ' Note that this example can not be directly converted to LIST format, + ' as it uses EOL embedded inside strings. + ' Test with "basicParse -b sample-3.txt" + + print ["{clr} + {17*bline} +{rline}~Hello ATARI World~{lline} + {17*tline} +"] + + ' Do some color effects + do + setcolor 2,peek(20),4 + loop + diff --git a/bp/samples/sample-4.pm b/bp/samples/sample-4.pm new file mode 100644 index 0000000..d51f30d Binary files /dev/null and b/bp/samples/sample-4.pm differ diff --git a/bp/samples/sample-4.txt b/bp/samples/sample-4.txt new file mode 100644 index 0000000..3ba6a34 --- /dev/null +++ b/bp/samples/sample-4.txt @@ -0,0 +1,68 @@ + ' Example program for parser directives + + ' Enable all optimizations: + $options +optimize + ' Include graphics from a binary file + $incbin dataPM$, "sample-4.pm" + ' Some defines + $define RAMTOP = $6A + $define SDMCTL = 559 + $define PCOLR0 = 704 + $define HPOSP0 = $D000 + $define GRACTL = $D01D + $define PMBASE = $D407 + + ' Enable P/M + MemTop = peek(@RAMTOP) - 4 + poke @RAMTOP, MemTop + graphics 0 + P0Mem = 256 * MemTop + 512 + + ' Clear P0 memory + poke P0Mem, 0 + move P0Mem, P0Mem+1, 127 + poke @PCOLR0, $1F : ' Set P0 color + poke @SDMCTL, peek(@SDMCTL) ! 8 : ' Enable Player DMA + poke @PMBASE, MemTop : ' Set PMBASE + poke @GRACTL, 2 : ' Turns on Player read from ANTIC + + oldYpos = P0Mem + 1 + Ypos = 50 + Xpos = 100 + dx = 1 + dy = 1 + + ' Loop movement of the player + do + pause 0 + exec MovePM + + Xpos = Xpos + dx + Ypos = Ypos + dy + + if Xpos < 48 + dx = 1 + endif + if Xpos > 200 + dx = -1 + endif + if Ypos < 16 + dy = 1 + endif + if Ypos > 100 + dy = -1 + endif + + loop + end + + ' Move P/M + proc MovePM + ' Set X position + poke @HPOSP0, Xpos + ' Clear old data + move oldYpos - 1, oldYpos, len( @dataPM$ ) + 1 + ' Set new data + move adr( @dataPM$ ), P0Mem + Ypos, len( @dataPM$ ) + oldYpos = P0Mem + Ypos + endproc diff --git a/feudal_tb_pl.bas b/feudal_tb_pl.bas index 4b42f4d..9579c1a 100644 Binary files a/feudal_tb_pl.bas and b/feudal_tb_pl.bas differ diff --git a/feudal_tb_pl.txt b/feudal_tb_pl.txt index 83e2e5b..6b5aba8 100644 --- a/feudal_tb_pl.txt +++ b/feudal_tb_pl.txt @@ -10,7 +10,7 @@ '+ after suicide "how many units of 76' when bad first letter '+loading game does not really work, it starts again' -$options +optimize, optimize=-fixed_vars-const_replace +''$options +optimize, optimize=-fixed_vars-const_replace '$options mode=compatible REM modified 061485 by Bruce Ramsey 411 N 61st, Seattle, WA 98103