About ReadableScript
Suggested file extension: *.rjs
Summary: ReadableScript is a dialect of JavaScript optimized for its ability to be read out loud by a person.
Project status
May 16 2022: ReadableScript is in DRAFT status and is not yet production-ready.
Copyright and license
This document, and all code contained herein are hereby released into the public domain by the author, without any guarantee or implied fitness for any particular purpose. You are free to copy, sell, use this code in commercial or personal projects. You are not required to include any notice in your projects as this code is in the public domain.
Synopsis
Have you ever tried to read code out loud to someone? Depending on the programming language, this isn't the simplest of tasks. Reading a for loop, in JavaScript `for (const o of x) { }` could be read as "for left parenthesis const o of x right parenthesis left curly brace right curly brace". That's a lot to express verbally. This led me to wonder, is it possible to make a programming language that uses no or very few syntax symbols?
Yes - I discovered, one can substitute the complex symbols commonly found in programming languages with a set of keywords. This makes the language easier to express to another person over an audio connection, such as a telephone call, internet meeting, or in person. The two symbols I chose to preserve, to aid readability are:
# the hash sign, to add a comment: code following a hash sign will have no effect
' the single quote mark, representing a block when used at the start of a line, or a line separator otherwise
The language
The language is most similar to assembly in syntax, with one command per line of code (although ' multiple ' lines ' can ' be ' simulated ' with ' single ' quotes). We can express a programming grammar using uppercase letters, and [ and ] to desginate optionality. The statement format is then (any number of arguments is possible, for brevity I only show 3):
KEYWORD [ARGUMENT [ARGUMENT [ARGUMENT]]]
Spaces beyond a single space between keywords and arguments are optional, and have no effect.
The machine
The machine runs your code, and it is responsible for defining the keywords that it understands.
Core concepts:
a "focus" - the machine has an implicit focused value at all times, this can be any JavaScript
value or function
blocks - code can be attached to a statement by starting the next line with a single quote (')
Currently, the `main` machine defines 23 keywords:
' # add and at call divide eq false log mod multiply name
or out plain push repeat run set subtract true with
ID NAME ARGUMENTS DESCRIPTION
0 ' any a nested block, to be used by the line immediately preceding the block
1 # any a comment, meaning the line has no effect
2 add number adds argument 0 to focus
3 and none combines all sub block 'out' values with logical boolean and
4 at text sets focus to value at the address provided by arguments
5 call any runs a focused function, passing along pushed values
(see 'push' keyword) and additional arguments
6 divide number divides focus by argument 0
7 eq number compare focus to argument 0
8 false number run the attached code block if focus is false
9 log any logs focus to console
10 mod number modulo focus by argument 0
11 multiply number multiplies focus by argument 0
12 name text sets address provided by arguments to focus
13 or none combines all sub block 'out' values with logical boolean or
14 out none sends focus out to parent command
15 plain any start with a simple value, such as a number or text
16 push none pushes focus onto call argument stack
17 repeat text text `repeat FROM TO`, `FROM` is the source variable name, either an array
or a number to iterate, `TO` is the destination variable name
18 run text run code at the address given by arguments
19 set text any set variable value
20 subtract number subtracts argument 0 from focus
21 true any run the attached code block if focus is true
22 with any prefix arguments for each line of code starting with a ' directly below
Sample ReadableScript code
Sample code output