KnockScript Documentation

A programming language based on knock-knock jokes. Every statement follows the classic "Knock knock" → "Who's there?" → Command → "Command who?" pattern.

Get Started Try Console

Getting Started

Welcome to KnockScript! This guide will help you get up and running with the most lame programming language.

Installation

Terminal 
git clone https://github.com/darthvader58/knockscript.git
cd knockscript
bundle install
Prerequisites: Ruby 3.2.0 or higher

Quick Start

Run a Program

Terminal 
ruby knockscript.rb examples/hello_world.ks

Web Interface

Terminal 
ruby web/app.rb
# Visit http://localhost:4567

Language Syntax

KnockScript follows a unique syntax pattern based on knock-knock jokes. Every statement begins with the classic setup and punchline structure.

Hello World

Your first KnockScript program:

hello_world.ks 
Knock knock
Who's there?
Print
Print who? "Hello, World!"

Variables

Declare and assign values to variables:

variables.ks 
Knock knock
Who's there?
Set
Set who? x to 42

Arithmetic Operations

Perform mathematical calculations:

arithmetic.ks 
Knock knock
Who's there?
Set
Set who? x to 10

Knock knock
Who's there?
Set
Set who? y to 5

Knock knock
Who's there?
Set
Set who? sum to x plus y

Knock knock
Who's there?
Set
Set who? product to x times y

Knock knock
Who's there?
Set
Set who? quotient to x divided by y
Operators: plus, minus, times, divided by

Conditionals (If/Else)

Control flow with conditional statements:

conditionals.ks 
Knock knock
Who's there?
If
If who? x greater than 10
    Knock knock
    Who's there?
    Print
    Print who? "x is big"
Otherwise
    Knock knock
    Who's there?
    Print
    Print who? "x is small"
Done
Comparison Operators: greater than, less than, equal to, not equal to

Loops

While Loops

while_loop.ks 
Knock knock
Who's there?
Set
Set who? counter to 1

Knock knock
Who's there?
While
While who? counter less than 6
    Knock knock
    Who's there?
    Print
    Print who? counter
    
    Knock knock
    Who's there?
    Set
    Set who? counter to counter plus 1
Done

For Loops

for_loop.ks 
Knock knock
Who's there?
For
For who? i from 1 to 5
    Knock knock
    Who's there?
    Print
    Print who? i
Done

Classes & Object-Oriented Programming

Defining a Class

class_definition.ks 
Knock knock
Who's there?
Class
Class who? Person with name and age

Creating Methods

method_definition.ks 
Knock knock
Who's there?
Method
Method who? greet for Person
    Knock knock
    Who's there?
    Print
    Print who? "Hello, my name is "
    
    Knock knock
    Who's there?
    Print
    Print who? name
Done

Creating Instances

instantiation.ks 
Knock knock
Who's there?
Set
Set who? alice to new Person with name "Alice" and age 30

Calling Methods

method_call.ks 
Knock knock
Who's there?
Call
Call who? greet on alice

Setting Attributes

set_attribute.ks 
Knock knock
Who's there?
Set
Set who? age of alice to 31

Arrays

Creating Arrays

arrays.ks 
Knock knock
Who's there?
Set
Set who? numbers to list with 1, 2, 3, 4, 5

Array Operations

array_operations.ks 
Knock knock
Who's there?
Push
Push who? 6 to numbers

Knock knock
Who's there?
Pop
Pop who? from numbers

Features

Variables & Arithmetic

Full support for variables and mathematical operations

Control Flow

If/else statements, while loops, and for loops

Object-Oriented

Classes, methods, and attributes for structured programming

Arrays

Basic data structures with push and pop operations

Web Interface

Browser-based code editor and runner

CLI Support

Run KnockScript files from the command line

Project Structure

knockscript/
├── knockscript.rb      # Main CLI entry point
├── lexer.rb           # Tokenizes KnockScript source code
├── parser.rb          # Parses tokens into Abstract Syntax Tree
├── interpreter.rb     # Executes the AST
├── ast_nodes.rb       # AST node definitions
├── token.rb           # Token class definition
├── environment.rb     # Variable scope management
├── examples/          # Example KnockScript programs
│   ├── hello_world.ks
│   └── classes.ks
├── web/               # Web interface
│   ├── app.rb         # Sinatra web server
│   └── public/        # Static web assets
├── config.ru          # Rack configuration
└── Dockerfile         # Container configuration

Core Components

  • Lexer: Converts source code into tokens
  • Parser: Builds an Abstract Syntax Tree from tokens
  • Interpreter: Executes the AST and manages program state
  • Web Interface: Browser-based code editor and runner

Contributing

We welcome contributions to KnockScript! Whether it's bug fixes, new features, documentation improvements, or examples, your help is appreciated.

How to Contribute

  1. Fork the repository on GitHub
  2. Clone your fork locally
  3. Create a feature branch
  4. Make your changes following the code style guidelines
  5. Test thoroughly
  6. Submit a pull request
Full Guidelines: See CONTRIBUTING.md for detailed contribution guidelines

Types of Contributions

  • Bug Fixes: Fix issues in the lexer, parser, or interpreter
  • New Features: Add language constructs or improve existing ones
  • Documentation: Improve code comments, examples, or this guide
  • Web Interface: Enhance the online editor and user experience
  • Examples: Create new example programs showcasing language features
  • Testing: Add unit tests or integration tests

API Reference

Commands

Command Syntax Description
Set Set who? variable to value Assign a value to a variable
Print Print who? expression Output a value to the console
If If who? condition ... Done Conditional execution
While While who? condition ... Done Repeat while condition is true
For For who? var from start to end ... Done Loop with range
Class Class who? Name with attr1 and attr2 Define a class
Method Method who? name for Class ... Done Define a method
Call Call who? method on object Call a method
Push Push who? value to array Add to array
Pop Pop who? from array Remove from array

Keywords

to
from
with
and
or
not
plus
minus
times
divided by
greater than
less than
equal to
new
list
Otherwise
Done