From 41b553737aef6e0588aa35408a5a36d2be5def5f Mon Sep 17 00:00:00 2001 From: Nilay Majorwar Date: Fri, 18 Feb 2022 20:50:53 +0530 Subject: [PATCH] Add developer notes to the language README files --- languages/befunge93/README.md | 31 +++++++++++++++++++++++++---- languages/brainfuck/README.md | 25 ++++++++++++++++------- languages/chef/README.md | 27 +++++++++++++++++++++---- languages/deadfish/README.md | 11 +++++----- languages/shakespeare/README.md | 26 +++++++++++++++++++++--- scripts/new-lang-template/README.md | 17 +++++++++++++++- 6 files changed, 112 insertions(+), 25 deletions(-) diff --git a/languages/befunge93/README.md b/languages/befunge93/README.md index a0a1ef1..fb22d0f 100644 --- a/languages/befunge93/README.md +++ b/languages/befunge93/README.md @@ -1,10 +1,33 @@ # Befunge-93 -## References +Befunge-93 is a two-dimensional esolang created by Chris Pressey, with the goal of being as difficult to compile +as possible. The program is a finite 2D grid of operations, and execution can proceed in any of the four main +directions. This makes watching the execution of a Befunge-93 program particularly satisfying. -- Esolangs wiki: https://esolangs.org/wiki/Befunge +Memory in Befunge-93 is a stack of integers. In addition, Befunge-93 programs can be self-modifying - there are +operations that allow accessing and editing the content of the source code at runtime. This means you can also store +runtime data in the source code itself, if space permits. + +The [esolang wiki page](https://esolangs.org/wiki/Befunge) contains the complete language-specification, along with +some interesting sample programs. + +## Notes for the user + +- The program grid is padded with space to size 80x25 before execution. +- Interactive input is not supported in Esolang Park, so currently division-by-zero throws a runtime error. +- `g` and `p` calls that access coordinates outside of the 80x25 grid result in a runtime error. +- Due to being two-dimensional, the breakpoint functionality is rather uncomfortable to use in Befunge-93. ## Implementation details -- Interactive input is not supported yet, so currently division-by-zero throws a runtime error. -- `g` and `p` calls that access coordinates outside of the 80x25 grid result in a runtime error. +- To avoid long no-op stretches, the engine keeps track of the bounds of the user's source code. If the pointer reaches + the end of the _set_ portion of a horizontal line, it immediately loops over to the opposite end of the line. The same + happens in vertical lines. Try executing `>>>>` to visualise this. + + Note that this does not happen in string mode. In string mode the pointer loops over the full grid, pushing ` ` (space) + characters onto the stack. + +## Possible improvements + +- There seems to be some minor issue in the initial grid padding. Some lines get padded to 81 characters instead + of 80. This is only cosmetic though - the program executes correctly. diff --git a/languages/brainfuck/README.md b/languages/brainfuck/README.md index 0c99eb8..e48f682 100644 --- a/languages/brainfuck/README.md +++ b/languages/brainfuck/README.md @@ -1,12 +1,23 @@ # Brainfuck -## References +Brainfuck is perhaps the most popular esoteric programming language, created by Urban Müller in 1993. +It is Turing-complete and has 8 instructions which operate on a linear array of cells storing integer values. +The [esolangs wiki page](https://esolangs.org/wiki/Brainfuck) contains the language specification and some +sample programs. -- Esolangs wiki: https://esolangs.org/wiki/Brainfuck +Note that brainfuck has minor variants which primarily differ in the workings of the cell array. You may find +many brainfuck programs which don't work correctly on Esolang Park. -## Implementation details +## Notes for the user -- The tape is semi-unbounded (0, 1, 2 ...) -- Cell size is 8 bits, and allows values in the range `[-128, 127]`. -- Value `10` is designated for newlines. -- The value `0` is returned on reaching `EOF`. +- The cell array is semi-infinite. There is no cell to the left of the initial cell, and trying to go left + anyway will result in a runtime error. The right side of the cell array is unbounded. +- Cell size is 8 bits, and allows values in the range `[-128, 127]`. Values loop over to the other side on reaching the bounds. +- The usual ASCII value `10` is designated for newlines. +- The value `0` is returned in input (`,`) operations on reaching `EOF`. + +## Possible improvements + +- The renderer currently uses Blueprint's `Card` component. This leads to performance issues when the stack grows large. + Usage of this component should be replaced by a simple custom component to drastically improve performance. Look at the + `SimpleTag` component used in the Shakespeare renderer for an example. diff --git a/languages/chef/README.md b/languages/chef/README.md index d6d7de4..c64305a 100644 --- a/languages/chef/README.md +++ b/languages/chef/README.md @@ -1,10 +1,11 @@ # Chef -## References +Chef is a stack-based Turing-complete esolang created by David Morgan-Mar in 2002, in which programs read +like cooking recipes. An important guideline while writing Chef programs/recipes is for the recipe to be easy +to prepare and delicious. The complete language specification is available on the +[official Chef homepage](https://www.dangermouse.net/esoteric/chef.html). -- David Morgan-Mar's Chef page: https://www.dangermouse.net/esoteric/chef.html - -## Implementation details +## Notes for the user - Ingredient names are case-sensitive and must contain only letters and spaces. @@ -33,3 +34,21 @@ Shake the mixture until blend. ``` + +## Implementation details + +- The parser is hand-built and uses regular expressions for basically everything. +- The engine is split in two classes: `Kitchen` handles kitchen-related operations while the main class + handles control-flow operations and manages the call-stack. + +## Possible improvements + +- Allow case-insensitive usage of auxiliary recipe names. + +- Chef syntax is flat and simple, easily representable by regular expressions. This means that syntax highlighting for + Chef can easily be made perfect by slightly modifying and reusing parser regexes for the Monarch tokenizer. Currently + the method part of syntax highlighting just highlights the known keywords. + +- We need to find a sensible solution for the verb tense issue mentioned above. Currently, any Chef program involving loops + requires modifications to be run in Esolang Park. Importing a very lightweight English verb-dictionary and only allowing + verbs from this dictionary is a possible way to resolve this. diff --git a/languages/deadfish/README.md b/languages/deadfish/README.md index b1815a2..ea3079a 100644 --- a/languages/deadfish/README.md +++ b/languages/deadfish/README.md @@ -1,9 +1,8 @@ # Deadfish -## References +Deadfish is a dead-simple esolang created by Jonathan Todd Skinner. Four straightforward commands, no conditionals, +no loops. It was the second language to be added to Esolang Park simply because I was feeling a bit lazy. The +[esolangs wiki page](https://esolangs.org/wiki/Deadfish) is the only resource used for this implementation. -- Esolangs wiki: https://esolangs.org/wiki/Deadfish - -## Implementation details - -- The value is unbounded, but is reset to `0` whenever it equals `-1` or `256`. +In all honesty, Esolang Park does not do Deadfish justice. Deadfish is designed for writing highly interactive +programs, but due to the lack of support for interactive input a lot of Deadfish's power is taken away. diff --git a/languages/shakespeare/README.md b/languages/shakespeare/README.md index b644adb..632f0b8 100644 --- a/languages/shakespeare/README.md +++ b/languages/shakespeare/README.md @@ -1,13 +1,33 @@ # Shakespeare -## References +Shakespeare is a programming language that reads like a Shakespearean play, usually involving characters +appreciating and (rather roughly) criticizing other characters. It was created by Karl Wiberg and Jon Åslund +as part of a university course assignment in 2001. -- Official documentation and implementation: http://shakespearelang.sourceforge.net +The original resource page is [hosted on Sourceforge](http://shakespearelang.sourceforge.net). It contains the +[language specification PDF](http://shakespearelang.sourceforge.net/report/shakespeare.pdf) and a Shakespeare-to-C +transpiler written with Flex and Bison in C, along with links to some other related resources. -## Implementation details +The specification and the transpiler source code are the only references used while implementing the Shakespeare +language for Esolang Park. + +## Notes for the user - It is not necessary for questions to immediately be followed by conditionals. Conditionals must immediately follow a question though - a runtime error is thrown otherwise. - Empty acts and scenes are invalid. An act must contain at least one scene, and a scene must contain at least one dialogue set or entry-exit clause. + +## Implementation details + +- The parser is implemented with [Chevrotain](https://chevrotain.io). +- The engine is quite small in size, and is a single file (`runtime.ts`). +- The renderer uses a custom component instead of Blueprint's `Tag` component for much better performance. + +## Possible improvements + +- Currently, the check that conditionals must be preceded immediately by a question is done at runtime. It is a static + check and should be done while parsing the program instead. + +- Syntax highlighting doesn't work for multi-word keywords that break into two lines (`... summer's \n day ...`). diff --git a/scripts/new-lang-template/README.md b/scripts/new-lang-template/README.md index 5642d94..4cb120b 100644 --- a/scripts/new-lang-template/README.md +++ b/scripts/new-lang-template/README.md @@ -1,5 +1,20 @@ # $LANG_NAME -## References +Add a short summary about the language, including link(s) to the language specification and sample programs. + +## Notes for the user + +- Add details and quirks (if any) about the Esolang Park implementation of this esolang. +- These are details that the user may want to know while executing or debugging programs on the editor. ## Implementation details + +- Add notes that a contributor may want to read while looking at the source code of the language provider. +- This includes any third-party libraries you've used, something you've done for performance, or just the + main decisions you took while implementing the language provider. +- If the source code is simple enough, you can simply omit this section. + +## Possible improvements + +- Add any bugs or suboptimalities in the language provider that a contributor can work on. +- (this section doesn't mean you can add a half-baked interpreter and leave, though.)