Create LICENSE and README.md

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Dmitry Shesterkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

NOTES.md

@@ -0,0 +1,39 @@
+# Useful Links
+
+## BASIC Games:
+https://www.roug.org/retrocomputing/languages/basic/morebasicgames
+
+http://www.vintage-basic.net/games.html
+
+http://atariarchives.org
+
+## BASIC docs
+
+### Applesoft BASIC
+http://web.archive.org/web/20210803052054/http://mirrors.apple2.org.za/Apple%20II%20Documentation%20Project/Software/Languages/Applesoft%20BASIC/Manuals/Applesoft%20II%20BASIC%20Programming%20Reference%20Manual.pdf  See grammar on page 30
+
+http://web.archive.org/web/20211121010308/https://apple2online.com/wp-content/uploads/Blue-Book.pdf
+
+http://www.bitsavers.org/pdf/phaseOneSystems/oasis/BASIC_Language_Reference_Manual_Mar80.pdf
+
+https://web.archive.org/web/20070809010851/http://www.apple2.org/faq/FAQ.applesoft.html
+
+### Atari Basic
+https://archive.org/embed/atari-basic-reference-manual
+
+### Microsoft BASIC
+http://web.archive.org/web/20210812071026/https://madexp.com/wp-content/uploads/2018/02/Microsoft_Basic_8086Xenix_Reference.pdf
+
+## Emulators
+
+### Applesoft BASIC in Javascript by Joshua Bell
+https://www.calormen.com/jsbasic/
+
+### Microsoft QBASIC - IBM PC emulator
+https://www.pcjs.org/software/pcx86/lang/microsoft/basic/qbasic/1.10/
+
+### Simple Web Basic by Yohanes Nugroho
+https://yohan.es/swbasic/
+
+## "Crafting Interpreters" by Robert Nystrom
+https://craftinginterpreters.com/

README.md

@@ -0,0 +1,40 @@
+# BASIC-boost.spirit
+
+BASIC programming language interpreter based on `Boost.Spirit X3`
+
+## About The Project
+
+The project was born as a result of a time-limited engineering challenge of implementing a BASIC interpreter that is good enough for running 2 text-based games:
+
+* [**WUMPUS 2**](https://www.atariarchives.org/morebasicgames/showpage.php?page=181) by Gregory Yob from ["More BASIC Computer Games"](https://www.atariarchives.org/morebasicgames/index.php) by David H. Ahl, published 1979 ([listing](https://www.roug.org/retrocomputing/languages/basic/morebasicgames/wumpus2.bas))
+* [**THE ANCIENT CHATEAU**](https://www.atariarchives.org/adventure/chapter21.php) from ["Creating Adventure Games On Your Computer"](https://www.atariarchives.org/adventure/index.php) by Tim Hartnell, published 1983 ([listing](https://www.atariarchives.org/adventure/chapter22.php))
+
+## Features
+
+* Fully functional, but limited to only essential (used in samples) commands.
+* Parsing based on `Boost.Spirit X3`. The whole language [grammar](grammar.cpp) takes less than 250 lines.
+* Comprehensive unit test suite: [`unit_tests.bas`](programs/unit_tests.bas) (based on the test suite of [Applesoft BASIC in Javascript](https://www.calormen.com/jsbasic/) by Joshua Bell) + separate [`tests.cpp`](tests.cpp)
+* Input automation: User input is being logged and can be reused through `.input` files
+* Walkthrough `.input` files for both `wumpus2.bas` and `chateau.bas`
+* Interactive mode
+* Additional programs included
+
+## Executables
+
+Download [Windows executable archive](https://github.com/black-square/BASIC-boost.spirit/releases/latest/download/BASIC-boost.spirit.zip), unarchive, and execute `run.bat` to run most programs at once using the input automation.
+
+## BASIC Program Examples
+
+Maze generation, Prime numbers, etc.
+See a [separate page](programs/README.md) for more info
+
+## Design
+
+The goal was to write an interpreter with a minimum amount of code yet capable of running the sample programs as is and without cheating. It means that many classical concepts of compiler construction theory were omitted for the sake of simplicity. Here are some key decisions and related consequences:
+* Preparse step ([`bool Preparse()`](basic_int.cpp)), which copies the whole program into memory. Doing so, it indexes lines for fast `GOTO` and separately stores `DATA` section. Also, it combines multiline statement sequences together.
+* No tokenization / lexical analysis step. The parser works with characters directly. It increases parser complexity and likely slows it down. Additionally, some "nospace inputs" aren't supported, e.g., in `IFK9>T9THENT9=K9` the substring `T9THENT9` will be recognized as an identifier instead of 2 identifiers and the `then` keyword. (It could be supported using lookahead syntax in `identifier_def` rule). The "right" approach could leverage **`Boost.Spirit.Lex`** or old trusty [**Flex**](https://en.wikipedia.org/wiki/Flex_(lexical_analyser_generator)) to generate the lexical analyzer.
+* Absence of Abstract Syntax Tree (AST) and bytecode generations as well as no separate execution step. I.e. parsing and execution happen simultaneously without intermediate representation. That's the biggest hack. The obvious issue is that each iteration of the loop involves parsing which isn't optimal. Also, there is some increased complexity of the grammar to support proper backtracking. The hardest thing though was the `ESLE` part of the condition statement. To solve that [`class SkipStatementRuntime`](runtime.h) was created and [`bool ParseSequence()`](parse_utils.hpp) complexity came from that. The "right" approach could involve the generation of AST, bytecode with following separate execution, or even generation of LLVM IR and making the real compiler.
+
+## Useful Links
+
+See a [separate page](NOTES.md) for more info

programs/README.md

@@ -0,0 +1,64 @@
+# BASIC programs
+
+## prime_sieve.bas 
+
+Source: https://www.calormen.com/jsbasic/
+
+## prime_factors.bas 
+Source: https://www.calormen.com/jsbasic/
+
+## bmi_index.bas 
+Source: https://www.calormen.com/jsbasic/
+
+## chateau.bas
+Description: https://www.atariarchives.org/adventure/chapter21.php
+
+Source: https://www.atariarchives.org/adventure/chapter22.php
+
+### chateau1.input 
+Walkthrough WIN: 
+
+```
+    CONGRATULATIONS! You have completed
+           THE ADVENTURE
+
+
+    YOU KILLED 2 MONSTERS
+    AND
+    YOU FOUND $1039 WORTH
+            OF TREASURE
+
+    Your score for this Adventure is 21141
+```
+
+### chateau2.input 
+Walkthrough LOSS:
+
+```
+    YOU KILLED 2 MONSTERS
+    AND
+    YOU FOUND $334 WORTH
+            OF TREASURE
+
+    Your score for this Adventure is 3411
+```
+
+## amazing.bas
+Description: https://www.atariarchives.org/basicgames/showpage.php?page=3
+
+Source: http://www.vintage-basic.net/games.html
+
+## unit_tests.bas
+
+Based on the test suite from https://www.calormen.com/jsbasic/
+
+## wumpus2.bas 
+
+Description: https://www.atariarchives.org/morebasicgames/showpage.php?page=181
+
+Source: https://www.roug.org/retrocomputing/languages/basic/morebasicgames
+
+See also Wumpus1 description: https://www.atariarchives.org/morebasicgames/showpage.php?page=178
+
+
+