Repository files navigation

• Author: Richard James Howe
• Email:howe.r.j.89@gmail.com
• Repo:https://github.com/howerj/subleq-nodejs
• License: MIT / Public Domain

This is a virtual machine that implements an 8 to 32 bitSUBLEQOne Instruction Set Computer (OISC). The default cell size is 16-bit. Images can be aslarge as you like, but be aware the machine cell width restricts how much theOISC can address. It's just for fun.

If you feel like supporting the project you can buy a book fromAmazon, availableherethat describes how the project works and how to port a Forth toa new platform.

Similar projects, same author:

• https://github.com/howerj/subleq, virtual machine written in C withself-hosted eForth system for SUBLEQ.
• https://github.com/howerj/subleq-js, a JavaScript version of theSUBLEQ machine, different to this one, that runs onhttps://howerj.github.io/subleq.htm.

This example program takes a string containing a SUBLEQ programand loads it into the SUBLEQ VM, it then executes it.

constsubleq=require("@howerj/subleq")consthello=`12 12 3 36 37 6 37 12 9 37 37 12 0 -1 15 38 36 1812 12 21 53 37 24 37 12 27 37 37 30 36 12 -1 37 37 0 39 0 -1 72 101 108108 111 44 32 87 111 114 108 100 33 10 53`;varcpu=newsubleq({putch:function(ch){process.stdout.write(String.fromCharCode(ch));},});cpu.loadFromString(hello,true);

This example runs the default eForth image and allows the user tointeractively program in a REPL.

constsubleq=require('@howerj/subleq');varcpu=newsubleq({putch:function(ch){process.stdout.write(String.fromCharCode(ch));},getch:function(){letbuffer=Buffer.alloc(1)if(require("fs").readSync(0,buffer,0,1)!=1)return-1;returnbuffer.toString('utf8').charCodeAt(0);}});cpu.load(cpu.eforth());cpu.eval(".( EFORTH READY ) cr");cpu.run()

All options width sensible default values are shown here:

constsubleq=require('@howerj/subleq');varcpu=newsubleq({putch:function(ch){process.stdout.write(String.fromCharCode(ch));},// Example putch, writes to stdoutgetch:function(){// Example getch, reads from stdinletbuffer=Buffer.alloc(1)if(require("fs").readSync(0,buffer,0,1)!=1)return-1;returnbuffer.toString('utf8').charCodeAt(0);},debug:false,// If true debugging information is logged to the consolewidth:16,// SUBLEQ machine width, 8-32 bit inclusivetimeout_ms:0,// If non zero setTimeout will be called when cycles run out or input returns an error});

Load signed values from an arrayarr into the memory of the SUBLEQ CPU,enough memory will be allocated to hold all of the values inarr, howeveryour program might require additional memory, which can be optionallyspecified with thelength parameter. Optionally the function can be toldto callrun() after loading. This function will either returnnull orthe result ofrun().

Load from a string instead of an array, most SUBLEQ programs found on theinternet consist of ASCII text containing a list of space delimitedsigned decimal values, this function can split a string containing thatformat into an array and thenload() it. Much likeload(),run()can be called if therun parameter is true. The function will returnnull or the result ofrun().

This function returns an array containing a completeForthimage, which when used in conjunction withload() will run a theprogramming language, care must be taken to hook up the appropriateputch andgetch functions. The eForth image will only work on the16-bit version of the SUBLEQ VM!

This getter/setter combo allow the setting of theputch functionused by the SUBLEQ machine for output. The function should behavelike theCfunction"putchar",the function should accept a single value in the range 0 to 127which should represent a singleASCIIcharacter to be output. You may return negative on failure, but it willnot be used by the SUBLEQ VM (output is assumed to succeed).

The defaultputch callback will swallow characters, doing nothingwith them.

This getter/setter combo allow the setting of thegetch functionused by the SUBLEQ machine for input. The function should behavelike theCfunction"getchar",the function should return a negative integer on failure, and on successshould return a number representing theASCII character value tobe input.

The defaultgetch callback will return -1, indicating failureto get input.

Run the currently loaded program, this will be run for the numberof cycles given to the program (or if the cycles is set to zero,which it is by default, it will continue to run until some otherhalt conditions are met).

The function currently always returnsnull.

Single step execution of the SUBLEQ machine with the previously loadedprogram.step() returns the same result asrun().

Prevent the machine from running.

Continue astop()'ped machine.

Reset execution so the Virtual Machine as it was when executionstarted (eg. The program counter is zero).

Evaluate a string,s, that is set the input to the virtual machine tothe string and continuerun() the VM until the input is consumedby the previously loaded program.append is appended to the inputstrings. The program might chose to do nothing with the string.