This section is intended for developers that will be working on the BoGL stack. Regardless of whether you are working on the language, the server, or the website, it is helpful to have a development environment setup that allows running them all together.
The following software & tools are required to develop with BoGL.
Most unix flavor systems should work nicely with these tools and instructions. A Windows system will also work as well, but it's advisable to have a terminal emulator of some sort to work with.
Installing BoGL (language & server)
BoGL can be installed via git.
git clone https://github.com/The-Code-In-Sheep-s-Clothing/bogl.git cd bogl stack build
Once BoGL has been successfully built, you can choose to work with either the command line (
stack ghci Bogl-Lang:exe:bogl) or the server (
stack ghci Bogl-Lang:exe:boglserver). The difference between the two is the forward facing interface, with the first (bogl) providing a standalone command line that works on a given file and the second (boglserver) having only a REST interface. If you want to run BoGL expressions in the command line you want to use the first option,
stack ghci Bogl-Lang:exe:bogl. For details on this, please read the section For the Command Line below.
You can also run
stack ghci by itself and you'll be prompted to enter
2 to select between either the command line or server variants. It's worth noting that most language features can be observed using either variant, so it's up to your development preference.
Installing the BoGL Website
The BoGL editor can also be installed via git.
git clone https://github.com/The-Code-In-Sheep-s-Clothing/bogl-editor.git cd bogl-editor # make sure your 'node' version is recent, version 14 or so should be good. npm install
Verifying & Running
To verify that changes you've made don't break anything, and that the server and the editor work as expected, you can run them as follows.
For the server
stack ghci Bogl-Lang:exe:boglserver # start the server on port 5174 > startServer 5174
You can also run
stack build and
stack install to make the executable
boglserver accessible from the terminal. In that case, you can then run
boglserver 5174 instead.
For the editor.
This will open up a new tab in your browser that will show the editor. If your BoGL server is running locally on the same network, you'll be able to write programs and evaluate expressions just like you would normally.
For the Command Line
If you want to test things with the BoGL command line you can start a simple repl as follows.
stack ghci Bogl-Lang:exe:bogl > repl
main will check to see if there are any command-line arguments present. In the case where there aren't any arguments present, the repl will be started without loading a file, essentially the same as running
Both these options start a repl without loading a file. If you want to start a repl in the context of BoGL program you can use this instead.
> load "MyProgram.bgl"
As a side-note, in ghci the delete key can add characters instead of removing the last character while typing expressions in. The standalone binary does not have this problem. To rectify this you can install
bogl as a local executable by running
stack build and
stack install to setup
bogl (this installs the same executable from before as well). This executable expects an optional BoGL file as its sole argument, like
bogl "MyProgram.bgl", and will start a REPL to evaluate expressions within the context of that program. Typing
:q will close the REPL.
# starts a repl w/out a file bogl # loads a file and starts a repl bogl "MyProgram.bgl"
While the repl is running expressions can be entered and evaluated; much the same as is done on the website. In the case you loaded a file (and you want to reload the file to factor in new changes) you can enter
:r to reload the file's contents.
If you are making changes to any part of the BoGL stack you will want to consider the following points.
When working on any part of the language (addition or a bug-fix).
- Start with one or more failing tests that should pass when your change is complete.
- Make the desired changes while observing the tests.
- When all tests pass via
stack test, verify that the you haven't introduced any other logical issues.
- Start up the web editor, and verify that your changes work as expected from there as well.
- this can reveal subtle issues that only arise from the server-client setup
When working on the editor it's similar to the later part of the normal testing step. Testing is slightly more difficult to setup on the editor given that it has to work with
React, but when possible add tests in the appropriate YourFile.test.tsx testing file (unless it exists already) to verify your functionality before you add it in. These tests are written using Jasmine, so it may help to double check their documentation. You can always check these tests via
npm run test.
As a final note, whenever you making changes to any part of the API, or to how the editor talks to the server, you should always verify that your changes do not break the server-client structure. There are no complete tests to verify that the server and client boot and run together as expected, so you will need to test these aspects manually by running them through the web editor itself. On the brightside, you shouldn't have to check too many programs if you know what you're looking for in advance.