$kemlang-py
docs

Reference

Error reference

kemlang-py reports three categories of errors: lexer errors, parse errors, and runtime errors. Each one tells you exactly where the problem is and what went wrong.

Anatomy of an error message

LexerError: unexpected character '?' at line 3, column 8
ParseError: expected '}' after block body at line 7, column 0
RuntimeError: undefined variable 'xyz' at line 5, column 10

Every error includes a type, a human-readable message, and a line:column position pointing to the exact character that caused the problem.

LexerError

Lexer errors happen before parsing even begins. The lexer turns your raw source text into tokens; if it encounters a character or sequence it doesn't understand, it stops with a LexerError.

Unexpected character

LexerError
LexerError: unexpected character '?' at line 2, column 12
jsk
kem bhai
  bhai bol x?2
aavjo bhai
›Remove the unsupported character. kemlang-py only recognises letters, digits, spaces, standard operators (+ - * / % == != < > <= >=), quotes, braces, and parentheses.

Unterminated string

LexerError
LexerError: unterminated string literal starting at line 2, column 10
jsk
kem bhai
  bhai bol "hello
aavjo bhai
›Every string must have a matching closing double-quote on the same line. Multi-line strings are not supported.

Invalid number literal

LexerError
LexerError: invalid number literal '3.14.15' at line 3, column 6
›Numbers may have at most one decimal point. 3.14 is valid; 3.14.15 is not.

ParseError

Parse errors mean the token stream is syntactically invalid - the structure of your program doesn't match the grammar. The parser tells you what it expected and what it found instead.

Missing program header

ParseError
ParseError: expected 'kem bhai' to start program at line 1, column 0
›Every kemlang-py program must begin with kem bhai on its own line.
jsk
kem bhai
  bhai bol "now it works"
aavjo bhai

Missing program footer

ParseError
ParseError: expected 'aavjo bhai' to end program, got EOF at line 5, column 0
›Every kemlang-py program must end with aavjo bhai. If you see this error, you probably forgot it or have an unclosed block above.

Missing block body brace

ParseError
ParseError: expected '{' after condition at line 3, column 14
jsk
kem bhai
  aa x che 5
  jo x > 0
    bhai bol "positive"
aavjo bhai
›The body of a jo or farvu block must be wrapped in curly braces.
jsk
kem bhai
  aa x che 5
  jo x > 0 {
    bhai bol "positive"
  }
aavjo bhai

Expected expression

ParseError
ParseError: expected expression at line 2, column 12
jsk
kem bhai
  aa x che
aavjo bhai
›The che keyword must be followed by a value or expression. You cannot declare a variable without initialising it.

Missing jya sudhi condition

ParseError
ParseError: expected 'jya sudhi' after loop body at line 5, column 0
jsk
kem bhai
  farvu {
    bhai bol "hi"
  }
aavjo bhai
›A farvu loop always needs a jya sudhi condition at the end. Use bhai chhe for an infinite loop that you exit with tame jao.
jsk
kem bhai
  farvu {
    bhai bol "hi"
  } jya sudhi bhai chhe
aavjo bhai

RuntimeError

Runtime errors occur while the program is executing - the syntax is valid but something goes wrong at evaluation time. These are the errors you'll encounter most often.

Undefined variable

RuntimeError
RuntimeError: undefined variable 'score' at line 4, column 10
jsk
kem bhai
  bhai bol score
aavjo bhai
›Declare the variable with aa name che value before using it.
›Check spelling - kemlang-py identifiers are case-sensitive.
›Make sure the variable is not declared inside a block that has already exited.

Type mismatch

RuntimeError
RuntimeError: cannot subtract STRING from INTEGER at line 3, column 12
jsk
kem bhai
  aa x che 10 - "five"
aavjo bhai
›Arithmetic operators (- * / %) only work on numbers. Use + for string concatenation - it auto-converts the other operand.

Division by zero

RuntimeError
RuntimeError: division by zero at line 3, column 14
jsk
kem bhai
  aa x che 10 / 0
aavjo bhai
›Guard the division with a jo check before dividing.
jsk
kem bhai
  aa divisor che 0
  jo divisor != 0 {
    bhai bol 10 / divisor
  } nahi to {
    bhai bol "cannot divide by zero"
  }
aavjo bhai

Invalid operand for unary minus

RuntimeError
RuntimeError: unary minus requires a number at line 2, column 12
›The unary minus (-x) only works on integers and floats, not strings or booleans.

Input conversion failure

RuntimeError
RuntimeError: cannot convert input 'hello' to INTEGER at line 3, column 14
jsk
kem bhai
  aa n che bapu tame bolo
  bhai bol n * 2
aavjo bhai
›bapu tame bolo reads input as a string. If you need a number, kemlang-py attempts implicit conversion when the value is used in arithmetic - if the user types something non-numeric, you get this error. Currently there is no built-in parseInt; validate input with a condition and re-prompt if needed.

Error exit codes

When a program exits due to an error, the kem process sets an appropriate exit code:

codewhenmeaning
0alwaysProgram ran and exited cleanly
1lexer errorsSource could not be tokenized
1parse errorsToken stream is syntactically invalid
1runtime errorsProgram raised an error during execution
2usage errorsWrong CLI command or missing argument

Debugging tips

  • ›

    Use --trace

    kem run file.jsk --trace prints the token stream and AST before running. If the token stream looks wrong, the bug is in the lexer. If the AST looks wrong, the bug is in the parser. If both look right, it's a runtime issue.

  • ›

    Use kem tokens

    kem tokens file.jsk shows exactly how the lexer sees your code - useful for diagnosing unexpected character errors.

  • ›

    Use kem ast

    kem ast file.jsk pretty-prints the AST - useful for checking whether your conditionals and loops parsed as you intended.

  • ›

    Check line:column

    Every error includes a position. Open your file and go to that exact line and column. The error character is usually right there.

  • ›

    REPL for quick tests

    Paste a suspect expression into kem repl to evaluate it interactively without running the whole file.

← CLI referenceRoadmap