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.


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