The fastest way to learn a language is to type at it. KingCobra's REPL is a read-eval-print loop that keeps your definitions, type-checks every line, and never dies on an error. This is a tour of what it does. Every transcript below was run on KingCobra 1.0.0.
Start it
kingcobra repl # start a session
kingcobra # no arguments in a terminal also starts it
kingcobra repl file.kc # run file.kc into the session first, then prompt
kingcobra -i file.kc # same thing
kingcobra --no-typecheck repl # start with the static type checker off
Leave with Ctrl-D, or with exit, quit or :quit. Inside the REPL, :help lists every command.
Tip for Windows: if the banner shows garbled characters in
cmd.exe, runchcp 65001first or use Windows Terminal, which uses UTF-8 by default.
The basics
Type an expression and its value is echoed. Strings are shown quoted, and assignments and null results print nothing:
>>> 1 + 2
3
>>> "hi" + " there"
"hi there"
>>> let xs = [1, "a", 2.5]
>>> xs
[1, "a", 2.5]
>>> _
[1, "a", 2.5]
-
_is the value of the last expression that was echoed. -
The trailing
;is optional for a single statement.count = 5andcount = 5;are the same. Several statements on one line still need separators:let a = 1; let b = 2;. -
Assignment needs a declaration first.
x = 5on a name you never declared is an error, so usevar x = 5and thenx = 6.
Definitions persist
let, var, fn, struct, extern and import all land in one global scope that lives for the whole session. Redefining a name, even a function or a struct, replaces it:
>>> fn sq(n: int) -> int { return n * n; }
>>> sq(12)
144
>>> fn sq(n: int) -> int { return n * n * n; }
>>> sq(3)
27
>>> struct P { x: int, y: int }
>>> let p = P { x: 1, y: 2 }
>>> p
P { x: 1, y: 2 }
Multi-line input
If a (, [, {, string or /* */ comment is still open, the prompt changes to ... and input continues until it balances. It also keeps reading when a statement is obviously unfinished: a try waits for its catch, and an input that ends in an operator (1 +, a &&) waits for its operand.
>>> fn fact(n: int) -> int {
... if (n < 2) { return 1; }
... return n * fact(n - 1);
... }
>>> fact(10)
3628800
>>> try {
... print([1, 2, 3][9]);
... } catch (e) {
... print("caught:", e.message);
... }
caught: index 9 out of bounds (len 3)
Pasting a block? Use :paste, enter the lines, and finish with :end or Ctrl-D. Ctrl-C abandons the input you were typing.
Every line is type-checked
The static type checker runs on each input against everything declared so far in the session. A rejected input leaves no trace:
>>> fn sq(n: int) -> int { return n * n; }
>>> sq("oops")
<repl:2>:1:4: error: 'sq' argument 1: expected int, got string
1 | sq("oops")
| ^
Turn the checker off with :typecheck off (and back on with :typecheck on), or start with --no-typecheck.
Errors never end the session
Parse errors, type errors and runtime errors, including ones raised inside std.* modules, print a normal diagnostic and return you to the prompt. The label <repl:N> numbers your inputs, and you get the source line and a caret, even for a function defined many inputs ago:
>>> [1, 2, 3][10]
<repl:3>:1:8: error: index 10 out of bounds (len 3)
1 | [1,2,3][10]
| ^
>>> let ok = 41 + 1
>>> ok
42
Runaway recursion is reported instead of crashing:
>>> fn r(n: int) -> int { return r(n + 1) + 1; }
>>> r(0)
error: stack overflow (recursion too deep)
>>> 1 + 1
2
Look around: variables, types and signatures
>>> var count = 15
>>> let name = "Ada"
>>> :vars
sq fn (n)
count int 15
name string "Ada"
>>> :type 3.5
float
>>> :type [1, 2]
array
>>> :info sq
fn sq(n: int) -> int
>>> :info P
struct P { x: int, y: int }
>>> import std.json;
>>> :info json
module json: parse try_parse is_valid error parse_file stringify pretty minify ...
:info is the quickest way to see what a module offers, with no documentation lookup, and :del name forgets a variable or function.
Help without leaving
help(...), ?name and :help name show the language's own documentation for builtins, keywords, methods and modules. A /// doc comment typed at the prompt waits for the declaration after it, so your own functions get documented too:
>>> ?len
len(x) -> int — core
Length of a string (in BYTES), array, buffer or object. Arrays also have
the property a.len.
>>> /// Add two numbers.
>>> fn add(a: int, b: int) -> int { return a + b; }
>>> help(add)
fn add(a: int, b: int) -> int
Add two numbers.
defined at <repl:1>:2
History, redo and saving your work
The REPL numbers the inputs that ran. :redo n runs one again, and :save writes the whole session to a file, so something you explored can become a real program:
>>> let a = 10
>>> let b = 20
>>> a * b
200
>>> :history
1 let a = 10
2 let b = 20
3 a * b
>>> :redo 2
let b = 20
>>> :save session.kc
saved 4 input(s) to session.kc
To bring code in, :load file.kc runs a file into the session (main() is not called), :reload runs the last :load again, and :reset throws everything away and starts fresh.
>>> :load lib.kc
>>> greet("REPL")
"Hello, REPL!"
>>> :reset
session reset
Timing and memory
:time runs one input and reports how long it took. :timing on times every input. Your number will differ:
>>> fn fib(n: int) -> int { if (n < 2) { return n; } return fib(n - 1) + fib(n - 2); }
>>> :time fib(25)
75025
(986.7 us)
Memory is explicit in a session, just like in a program. free(x) works on strings, arrays, structs and alloc() blocks, echoing a freed value is a recoverable use-after-free error, and :mem prints the live allocations:
>>> let s = "id-" + 42
>>> free(s)
>>> s
<repl>:1:1: error: use after free (this string was freed)
>>> :vars
s string <freed string>
The preprocessor works here too
>>> #define SQ(x) ((x)*(x))
>>> SQ(7)
49
Macros persist for the session, :macros lists them and #undef removes one.
Display options
Long arrays, structs and objects wrap one element or field per line. Set the width with :set width n (default 80, minimum 20). On a terminal, values are coloured; :color off or the NO_COLOR=1 environment variable turns that off:
>>> let v = [100000, 200000, 300000, 400000]
>>> v
[100000, 200000, 300000, 400000]
>>> :set width 20
width is 20
>>> v
[
100000,
200000,
300000,
400000
]
Line editing, history and Tab completion
If GNU readline is installed (libreadline-dev on Debian and Ubuntu, readline-devel on Fedora), the build detects it and you get arrow keys, Emacs and vi editing, and a history file in ~/.kingcobra_history that keeps the last 1,000 lines. Tab completes keywords, REPL commands, macros, and every name you've defined. After a dot it completes members, so system.<Tab> lists the module's functions and p.<Tab> lists a struct's fields. After :load or :save it completes file names. Without readline the REPL still works with plain line input.
A startup file
On a terminal, the REPL loads ~/.kingcobrarc if it exists, which is a good place for imports and helpers you always want. The environment variable KC_REPL_INIT names a file to load in any mode:
echo 'let motd = "welcome back";' > init.kc
echo 'motd' | KC_REPL_INIT=init.kc kingcobra repl
"welcome back"
A ./.kingcobrarc in the current directory is deliberately not run, so opening a project folder can't execute code on its own.
Use it from scripts
When stdin isn't a terminal, there is no banner and no prompt, but values are still echoed. That makes the REPL handy for one-line checks:
echo '2 * 10 == 20' | kingcobra repl
true
printf 'fn sq(n: int) -> int { return n*n; }\nsq(12)\n' | kingcobra repl
144
The exit status is 1 if any input failed and 0 otherwise.
Three ways I use it
-
Explore a module.
import std.json;then:info jsonshows every function, and?namedocuments one. -
Try before you write. Test an expression, a string method or a regex in the REPL, then
:savethe good lines. -
Poke at your own code.
kingcobra repl myprog.kcloads a file into the session, so you can call its functions with different arguments.
Limits worth knowing
-
Memory grows slowly. Parsed code is never freed, because closures defined in the session point into it, and
:resetdoesn't release it either. That's fine for interactive use, but it's not meant for a REPL embedded in a long-running server. -
A recovered error skips pending
deferstatements. Put any cleanup you need on every path in code that can't raise an error, or free explicitly. -
Ctrl-Cand stack-overflow recovery are POSIX-only. On Windows,Ctrl-Cends the process, and runaway recursion is stopped by the 4,000-call depth limit instead. -
After an interrupt inside heavy native code (for example
std.httporstd.nntraining), treat the session as disposable. - A script can catch a stack overflow with
try; the REPL just returns you to the prompt. -
An
ifwaits for one more line on a terminal, to catch anelse. Press Enter to run it. -
import "file.kc"in the REPL resolves relative to the current directory.
Try it
kingcobra repl
- Repo: https://github.com/DivyanshuSinha136/KingCobra
- Language tutorial: https://github.com/DivyanshuSinha136/KingCobra/tree/main/tutorial
- Full REPL reference:
docs/REPL.md
If a REPL behaviour surprises you, open an issue. A star on the repo helps other people find it.
Top comments (0)