jsFunge IDE

How to Use This IDE

This IDE has several features which may not be obvious at a first glance.

---

Toolbar

Program Options

•   Switch to edit mode and clear the grid
•   Open a dialog where you can select
         an example to load
•   Open a dialog where you can copy a URL
         that will let you share or save your program
•   Open a dialog where you can change
         the dimensions of the grid

---

•   Switch to Edit Mode
•   Switch to Run Mode
•   Turn on Syntax Coloring
•   Turn on Flow Visualization

Edit Mode Options

•   Open the Clipboard dialog
•   Select the direction the cursor will
                          move when typing on the grid.
• Code  Switch to Code Typing mode
• String  Switch to String Typing mode
• Insert  Toggle Insert Typing mode

Run Mode Options

•   Start the program running
•   Pause a running program
•   Halt and reset a running or paused program
•   Advance the program a single step
•   Toggle Cursor Tracing Mode
• Speed Slider  Set the speed the program runs
                           Faster speeds won't show every step

Windows and Dialogues

•   Show the Grid/Text window if it is hidden
              In Edit Mode, toggle between text/grid mode
• Show the dialog to annotate cells.
•   Show the Stack window if it is hidden
•   Show the Terminal window if it is hidden
•   Show the Input Box window if it is hidden

---

•   Show this window if it is hidden
•   Show the About window if it is hidden
•   Show the Settings window if it is hidden

---

Global Features

Windows

Windows and Dialogs can be dragged around by their title bars and hidden by choosing the X in the corner. They can always be shown again from the toolbar.

Certain windows (Stack, Grid, and Terminal) can be resized as you prefer by dragging their lower right corners. The Grid window cannot be larger than just enough to contain the grid.

Cursor Position

In the bottom left corner of the page, a small box always shows the current coordinates of the cursor and the current numerical value of the cell it is in. Although the cursor cannot be moved by clicking in a running program, clicking a cell will still update the contents of this box.

Syntax Coloring and Flow Visualization

Add context-aware colors to the grid to help you visualize. May slightly lag input when updating.

Grid Size

You can use the Grid Size Dialog to resize the grid in any mode. You can give the grid any number of rows or columns. Resizing the grid will never destroy any part of the program currently on the grid without confirming with you first.

Input Box

Open the Input Box Window and type anything you want into the box if you would rather feed a fixed input to your program when it runs than provide interactive input through the terminal. As with most Befunge implementations, if your program tries to read more input than this box contains, it will receive a -1 as EOF instead. Clear the box to return to interactive input mode.

Import Program

From this dialog, you can load the programs that are saved in your browser cache. Importing a program will overwrite the contents of the grid and possibly try to resize it as well. Save your work before doing this! You can also individually delete the programs on this list from your cache if you do not need them.

There are a number of example programs already pre-loaded into your cache. Take a look at these examples to get a better idea of how the language works.

You can also open a plaintext program saved on your filesystem using the button so labeled.

Export URL

You can share the URL from the export URL box to allow anyone to see or edit your program. The link will also preserve your current grid size settings.

If you select Save to Address Bar, your browser will be redirected to the link, thereby saving it in your browser history. (This will destroy any breakpoints you had set.)

If you select Save to My Browser, the program will be permanently saved in the cache of this browser on this device and will appear as a loadable option in the import dialog.

If you select Save Plaintext to My Computer, a file will be downloaded to your computer containing a plaintext version of the program. It will also contain any annotations. You will need to delete these manually to run the program in another interpreter, but the file will open just fine in jsFunge.

Annotations

Use the annotations dialog to add comments to your code. The annotation will be attached to whichever cell is selected when the button is pressed. The cell will be marked with a small green box in the corner and the annotation will appear in the title text (that appears when you hover over a cell) and, if the cell is selected, in the box in the bottom left corner. If you export an annotated program to a URL, the annotations will be exported with it. To remove an annotation from a cell, simply attach a blank (empty) annotation to it.

Settings

Global options are set in this window.

The Befunge-97 instructions checkbox toggles the availability of the hex number instructions a through f and the single character mode instruction ' (single quote)

The Non-blocking interactive keyboard I/O checkbox toggles a mode in which the key code of any non-special key pressed while a program is running is appended to the input buffer and the ~ command never blocks for input (instead pushing -1 if the buffer is empty). This makes realtime interactive programs possible. Note that in this mode, ~ will be reading key codes, not characters typed, and it will only ever read the last 4 keys pressed, so if you do not poll it fast enough, you may miss some keystrokes.

The Skip non-commands while running checkbox will make a running program leap from one command to the next, skipping over whitespace and anything not in the Befunge instruction set. This makes execution faster but cursor movement somewhat harder to follow.

The Reflow color map when a p could change flow checkbox will cause a reflow of syntax coloring and flow visualization on every alteration of the grid by a running program by the p command that could potentially alter the future behavior of the program. Useful for programs that edit themselves to alter their own control flow. This option can slightly reduce the running speed of such a program.

The Reflow color map every cycle while running (very slow) checkbox forces a reflow of syntax coloring and flow visualization on every major cycle of a running program. This can make clear which parts of a program are purely for initialization (as they become unreachable after they are executed). However, this option significantly lowers the speed of a running program.

The Suppress errors checkbox prevents non-fatal errors from being logged to the terminal.

---

Edit Mode Features

While typing on the grid, the cursor will always move in the direction selected on the toolbar, wrapping around the edges of the grid as needed. Typing Backspace will move the cursor in the opposite direction before clearing the cell. Certain other keys have variant behavior depending on the Typing Mode.

Code Typing Mode

Select Code Typing Mode by choosing Code on the toolbar.

In Code Typing Mode, typing any of the characters <,>,^, or v will change the typing direction and then move in that direction. Typing " will toggle on String Typing Mode.

String Typing Mode

Select String Typing Mode by choosing String on the toolbar.

In String Typing Mode, the cursor will continue in the current direction regardless of what is typed. Typing " will toggle on Code Typing Mode.

Insert Typing Mode

Select Insert Typing Mode by choosing Insert on the toolbar or by pressing the Insert key.

When Insert Typing Mode is off, typing on a cell replaces its contents. Hitting Delete behaves the same as hitting Space.

When Insert Typing Mode is on, typing on a cell shifts everything in the current row or column in the current typing direction, placing the typed character in the newly vacated cell. But the grid has a fixed size, so a character must be overwritten somewhere in that row or column. In this mode, the last space character in that direction is overwritten. If there are no space characters in the current typing direction, attempting to type in Insert Typing Mode will fail to avoid accidentally destroying parts of your program. However, you can still accidentally destroy significant whitespace using this mode. Be careful!

In Insert Typing Mode, pressing Delete will not move the cursor, but instead will shift the entire row/column in the current direction backwards towards the cursor. Pressing Backspace will both move the cursor backward and shift the row/column backwards towards it, overwriting the previous character.

Always check the current typing direction before typing in Insert Typing Mode!

Keyboard Shortcuts

A number of quick keyboard shortcuts are available while editing the grid.

• Home  Move cursor to the first column of the current row
• End  Move cursor to the last column of the current row
• Page Up  Move cursor to the first row of the current column
• Page Down  Move cursor to the last row of the current column
• Insert  Toggle Insert Typing Mode
• Shift+[Any Cursor Key] Set the current typing direction
• Alt+Shift+R  Switch to Run Mode and start the program running
• Alt+Shift+S  Open the Export URL dialog

Text Editing Window

Select the Text Window () option from the toolbar to transform the grid into a simple textbox containing your program.

In the plaintext editing window, you can select all the text in the program, copy it, and paste it elsewhere for safe-keeping or to try out another interpreter. You can also replace the program by pasting in programs from other sources. Any changes made to the text here will be loaded into the grid when you switch back to the Grid Editing Window. Using any of the grid-specific features (like the Export URL and Grid Size dialogs) will automatically switch back to the Grid Editing Window for you.

If the contents of the textbox (not counting trailing whitespace) will not fit in the grid at its current dimensions, switching back to the Grid Editing Window will give you the option to resize the grid to fit it.

Note that if your program is annotated, the annotations will also appear here below a line of semicolons. You can edit all annotations here easily. You could add new annotations here if you wanted, though it is not particularly convenient to do so.

Clipboard

Use the clipboard window () to manipulate subgrids. This is a very complicated and powerful feature. Here is how you use it:

First, ensure that the cursor is in the location you want to the top left corner of the selection to be. Then click the Set top left corner of selection to cursor location button. Then, ensure the cursor is in the location you want the bottom right corner of the selection to be and click the Set bottom right corner of selection to cursor location button. This will both enable the fine selection adjustment controls and reveal the selection transformation controls while the unselected regions are grayed out in the Grid window.

Note that because the Befunge playfield is a torus, the bottom right corner of the selection can be above and/or to the left of the top left corner!

Tip: Clicking on the top left corner grid cell, dragging to the bottom right corner cell, and releasing will skip these two steps and open the window with all features already enabled. Likewise, holding the ctrl key when clicking or long-pressing a grid cell will set the clicked cell to the lower right corner and the cursor location as the top left corner.

The fine selection adjustment controls will allow you to independently move the bounds of the selection bounding box in either direction so that your selection contains exactly the intended cells. Use the displayed row and column counts if you need to ensure the selection is square.

The selection transformation controls provide a number of ways to manipulate the selection:

In the middle is a textbox containing a textual representation of the current selection. Edits to this textbox will be mirrored to the grid and vice versa. Because the contents of the box will always be cropped to the selection size, you never need to worry about accidentally overwriting unselected parts of the grid. You can paste text representations of programs that contain annotations and the annotations corresponding to cells in the cropped selection will be added as well.

The long skinny buttons with arrows translate the selection one cell in the indicated direction by swapping it with the section of the next row or column in that direction. This may cause the surrounding grid to be rearranged in unexpected but entirely intended ways.

The square buttons around the textbox will apply the seven non-identity transformations of the dihedral group of the square. Transformations that would swap the dimensions of the selection (transposes and 90 degree rotations) are only allowed for square selections. Because certain operations in Befunge-93 lack these symmetries, some of these transformations can change the semantics of the transformed subprogram. You will be warned when a transformation is likely to alter semantics.

The Export selection to new tab button will open a new tab and load a new instance of the app containing only the selected subprogram.

The Copy selection to clipboard button will put a trimmed version of the selection including annotations into your clipboard. This is a much more convenient text representation of the selection than the one you would get by selecting and copying the text in the selection textbox.

Run Mode Features

In Run Mode, you cannot edit the contents of the grid nor can you set the location of the cursor. However, there are some things you can do here that you cannot do in Edit Mode.

Breakpoints

Set a breakpoint by double-clicking or long-pressing on a cell. The cell will turn crimson when it is a breakpoint. Breakpoints persist even if you switch to Edit Mode and back, though they will not be visible in Edit Mode. There is no problem with toggling a breakpoint while a program is running.

When the cursor of a running program reaches a breakpoint cell, the program will pause automatically.

Cursor Tracing Mode

Turn Cursor Tracing Mode on by clicking the icon on the toolbar. In this mode, while a program is running, the cursor will recolor each cell it touches in a progression of hues. This will allow you to see the execution paths of a program even when the speed is set too high to watch each move the cursor makes. These colors will persist until you next start the program again, even if you turn Cursor Trace Mode off and on again or switch to edit mode and back again (even though either of these actions will temporarily hide the colors).

Note that Cursor Tracing Mode and Flow Visualization mode cannot both be used at the same time for reasons that should be obvious, although one can switch between the two modes freely. What's the difference between them? Flow Visualization shows all the possible paths the IP could follow and colors the entire path between consecutive branches the same color, while Cursor Tracing shows only the path the IP actually followed colored with a smooth gradient to make direction of motion clearer.

Keyboard Shortcuts

A number of keyboard shortcuts are available in Run Mode.

• Alt+Shift+E  Halt and reset the program and switch to Edit Mode
• Alt+Shift+S  Open the Export URL dialog
• Alt+Shift+C  Immediately halt and reset the program

All of these shortcuts will work even while the program is waiting for interactive input in the terminal.