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.

Nov 7 2022: Replaced single quote (') with comma (,)

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 comma, 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 , commas). 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):


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 comma (,)

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


   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