Kedu! Welcome to NaijaScript

NaijaScript na language wey you fit use learn coding, automate things, and catch fun. This book go teach you everything wey you need to know, from how we think am to how you go take use am.

You wan experiment quick? Try the online playground.

How to Use This Book

We don arrange this book so e go carry you from the idea to the action. Na so the sections take arrange:

Introduction: Na here you dey so! This place go give you the full gist about the book and help you get the tools wey you need.
Our Mind (Design Philosophy): Learn the "why" behind NaijaScript. If you wan understand the vision, make you start from here.
Language Manual (LRM): The official grammar book for NaijaScript. E go explain the syntax, data types, and how to control your code.
Interpreter (naija): The practical guide on how to use the naija command to run your scripts.
Toolchain Manager (naijaup): Learn how to manage your NaijaScript installation, change versions, and keep everything fresh.

Oya, Make We Start

To start to dey use NaijaScript, you need to install the interpreter first.

First, Install naijaup (the Toolchain Manager)

For Linux/macOS:

curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/xosnrdev/naijascript/master/scripts/install.sh | sh

For Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/xosnrdev/naijascript/master/scripts/install.ps1 | iex"

After you don install am, make sure say $HOME/.local/bin (for Linux/macOS) or %USERPROFILE%\.naijascript\bin (for Windows) dey your PATH. If e no work, restart your terminal.

Then, Install and Set Up naija (the Interpreter)
- To install the latest version:
```
naijaup install latest
```
- To make the version you just installed the default one:
```
naijaup default latest
```

Now, you don ready to explore the rest of the book and start to dey write your own NaijaScript programs. Oya, let's go!

NaijaScript Design Philosophy

NaijaScript is designed to make programming more accessible and relatable for Nigerians and Pidgin English speakers. The language and its interpreter are intentionally simple, prioritizing learnability, expressiveness, and cultural relevance.

Our design philosophy is guided by these core principles:

Pikin-Friendly (Approachability): The primary goal is to lower the barrier to entry for programming. By using Nigerian Pidgin English, we connect with a vast audience in a language they understand intuitively. This is informed by research on the sociolinguistic status of Pidgin in Nigeria, which highlights its role as a lingua franca and its deep cultural roots.
Sharp-Sharp (Simplicity and Readability): The syntax is clean and maps directly to common Pidgin phrases. We avoid complex symbols and abstract jargon, focusing on a small, orthogonal set of features that can be combined powerfully. The language should be easy to read and write, allowing new programmers to build confidence quickly.
Learn as You Go (Experimentation and Iteration): The project is open to breaking changes and rapid development. We believe in learning by doing and evolving the language based on community feedback and practical experience.

2. Interpreter Architecture

NaijaScript uses a tree-walk interpreter architecture. This choice is deliberate and central to our design philosophy.

Why Tree-Walk? Tree-walk interpreters are straightforward to implement, debug, and extend. This makes them ideal for an educational and experimental language, as they allow us to focus on language features rather than complex compilation techniques. This approach is heavily inspired by the book Crafting Interpreters by Bob Nystrom.

Key components of the architecture include:

Recursive Evaluation: Each node in the Abstract Syntax Tree (AST) is evaluated recursively. This model is easy to reason about and aligns with the simple, procedural nature of the language.
Localized Error Reporting: All errors are surfaced in Pidgin English, with clear, contextual line and column information. This is inspired by the excellent diagnostics in the Rust compiler and is crucial for a positive learning experience.
Planned Extensibility: The AST and interpreter are designed to be easily extended with new value types (like booleans or lists) and control flow constructs, following best practices from scripting language research.

3. Language Design Rationale

Why Pidgin English? Pidgin is the most widely spoken language in Nigeria, acting as a bridge across diverse ethnic groups. Using it as the foundation for a programming language makes coding less intimidating and more inclusive.
Dynamic Typing: NaijaScript uses dynamic typing, meaning you don't have to declare the type of a variable. This is common in scripting languages and allows for a more flexible and less verbose coding style, which is beneficial for beginners.
Block Scoping: Any variable declared inside a start ... end block is only visible within that block and its nested children. This matches the behavior of modern programming languages and helps prevent accidental variable shadowing or leakage. Block scoping is enforced both at the semantic analysis and runtime levels, ensuring soundness and predictability.

4. Further Reading

NaijaScript Language Reference Manual (LRM)

1. Introduction

Welcome to the official Language Reference Manual for NaijaScript. This document na the authoritative source for everything about the NaijaScript language. E go explain the full syntax, how variables and types dey work, and wetin each command dey do when you run your code.

NaijaScript dey designed to make programming feel natural and accessible for Pidgin English speakers. Our goal na to create a language wey dey simple to learn, expressive, and culturally relevant.

2. Lexical Structure

This section dey describe how NaijaScript code dey break down into individual tokens.

2.1. Identifiers

Identifiers na the names you give to your variables. Dem fit contain letters (a-z, A-Z), numbers (0-9), and underscore (_), but dem must to start with a letter or underscore.

Example: myVar, age, totalAmount, my_var, _hiddenValue

2.2. Keywords

Keywords na special words wey get meaning for NaijaScript. You no fit use them as variable names.

make: Declare a new variable.
get: Assign a value to a variable.
if to say: Conditional if statement.
if not so: Conditional else statement.
jasi: Loop construct.
start: Beginning of a code block.
end: End of a code block.
do: Define a function.
return: Return a value from a function.
add, minus, times, divide, mod: Arithmetic operators.
na, pass, small pass: Comparison operators.
and, or, not: Logical operators.

2.3. Literals

Literals na the fixed values wey you dey write directly for your code.

Numbers: NaijaScript dey support floating-point numbers.
- Example: 10, 3.142, 0.5
Strings: Sequence of characters inside double quotes ("...") or single quotes ('...'). Supported escapes: \\, \", \', \n, \t, \r.
- Example: "Hello, World!", 'Naija no dey carry last', 'foo\nbar'
String Interpolation: Strings fit contain variables as placeholders using braces "{variable}" syntax.
- Example: make name get "World" shout("Hello {name}")
Booleans: Truth values wey be true and false.
- true - mean say e correct or e happen.
- false - mean say e no correct or e no happen.

2.4. Operators

Arithmetic: add (+), minus (-), times (*), divide (/), mod (%)
Comparison: na (==), pass (>), small pass (<)
Logical: and (logical AND), or (logical OR), not (logical NOT)
Unary: not (logical negation), minus (arithmetic negation)

Operator Precedence (from highest to lowest):

not, minus (unary operators)
times, divide, mod
add, minus (binary operators)
na, pass, small pass
and
or

2.5. Punctuation

( and ): Used for grouping expressions and in shout, if to say, and jasi statements.

2.6. Whitespace and Comments

Whitespace (like space, tab, or new line) na wetin you fit use to separate code make e clear. NaijaScript no dey worry about how many space or new line you put.

If you wan write comment, just put # for anywhere for the line. Anything wey dey after # till the end of that line na comment, the interpreter no go run am. You fit put comment anywhere for your code, e no go affect how your program work.

3. Grammar and Syntax

NaijaScript syntax dey defined with a formal grammar using Backus-Naur Form (BNF). You fit check the full grammar for this link.

4. Static Semantics

This section dey cover the rules wey dey checked before your code run.

4.1. Type System

NaijaScript get four main data types:

Number: Represents numeric values (e.g., 10, 99.9). All numbers na floating-point numbers.
String: Represents text (e.g., "Naija").
Boolean: Represents truth values wey fit be true or false.
Function: Represents callable code blocks with parameters and return values.

Type inference dey automatic. You no need to declare the type of a variable.

4.2. Name Binding and Scoping

Declaration: You must declare a variable with the make keyword before you use am.
- make myVar get 10
Redeclaration: You no fit declare a variable wey you don already declare for the same block.
Scope: Any variable or function wey you declare inside a start ... end block go only dey visible inside that block and any nested block. This help prevent accidental variable or function shadowing or leakage, and na the same way modern programming languages dey behave. After the block ends, the function or variable no go dey visible outside the block again.

5. Dynamic Semantics

This section dey explain wetin each part of the language dey do when e dey run.

5.1. Statements

make <variable> get <expression>: This one go create a new variable and give am the value of the expression.
<variable> get <expression>: This one go change the value of a variable wey you don already create.
if to say (<condition>) <block>: If the condition na true, the code inside the start...end block go run. The condition fit be simple comparison or complex compound condition using and, or, and not operators.
if to say (<condition>) <block> if not so <block>: If the condition na true, the first block go run. Otherwise, the second block go run.
jasi (<condition>) <block>: The code inside the block go run repeatedly as long as the condition dey true. Like if to say, the condition fit be compound expression with multiple logical operators.
start ... end: You fit use block anywhere as a statement. Any variable you declare inside the block go only dey visible inside that block and any nested block.
do <name>(<parameters>) <block>: Define a function with the given name and parameters. The function body dey inside the block.
return <expression>: Return a value from a function. If no expression provided, function go return 0. Only valid inside function definitions.
<expression>: You fit use any expression as a statement. This dey useful for function calls wey you wan execute for their side effects.

5.2. Expressions

Addition and Concatenation (add): You fit use the add operator to join or add any combination of string, number, or dynamic types. The only thing wey no dey allowed be boolean: if any side be boolean, e go cause semantic error before your code run. For example, you fit do 2 add 3, "foo" add "bar", 2 add "bar", or join dynamic values, but true add 5 or "foo" add false no go work.

Arithmetic Operators (minus, times, divide, mod): These operators fit only work if both sides be number, or dynamic wey go be number at runtime. If you try use string or boolean with any arithmetic operator (even if the other side na dynamic), e go cause semantic error before your code run.

Dynamic Types: If any operand be dynamic, the operation go pass unless one side be boolean (for add) or string/boolean (for arithmetic). The analyzer only block operation if e fit prove say the types no go work.

Comparison: Expressions with na, pass, and small pass go compare two values and return a boolean result (true or false) for use in conditions.

Logical: Expressions wey use and, or, and not dey join or change boolean values. Dem only work if the values na true or false. If you try use dem with number or string, e go cause a semantic error.

Function Call: You fit call a function by writing its name followed by arguments in parentheses. The function go run and return a value wey you fit use for further expressions.

6. Built-in Functions

NaijaScript provides several built-in functions wey dey globally available:

6.1. Output Functions

shout(expression): Print the value of the expression to the console. This function take any value (number, string, or boolean) and display am. The function return 0 after printing.

Built-in functions dey take precedence over user-defined functions with the same name. You fit call dem anywhere expression dey expected.

7. Implementation-Defined Behavior

Number Precision: All numbers na 64-bit floating-point numbers (IEEE 754 standard).
Error Reporting: When error happen, the interpreter go stop execution and print a message for Pidgin English wey go explain the problem and show the line and column number where the error occur.

Naija - The Interpreter CLI

Na the main command-line tool wey dey run NaijaScript.

How to Use Am

Run naija --help make you see everything wey you fit do.

1. How to Run Your Script File

To run your NaijaScript file (e must end with .ns or .naija):

naija example.ns

2. How to Run Code Straight from Command Line

To run small code sharp sharp:

naija --eval "make x get 5 shout(x add 2)"

3. How to Send Code from Another Place

To run code wey you send from another command or file:

echo "make x get 5 shout(x add 2)" | naija -

Or:

cat your_script.ns | naija -

All the Command-Line Options

--eval <code>, -e <code>: E go run the code wey you give am inside the quote.
<script>: The path to the script file wey you wan run.
-h, --help: E go show you help message.
-V, --version: E go show you the version of naija wey you get.

Wetin Your Script File Need

Your script file must end with .ns or .naija.
If you use - as the script name, naija go read code from standard input.

Examples

Example Script: `sum.ns`

make x get 10
make y get 20
shout(x add y)

Run am like this:

naija sum.ns

Example: Run Small Code

naija --eval "make x get 2 shout(x times 3)"

If Wahala Happen (Troubleshooting)

Script No Wan Run:
- Check say your script file end with .ns or .naija.
Command No Dey:
- Make sure say the naija program dey your PATH. Check the naijaup to learn how to set am up.
- If the wahala still dey, abeg open issue for us for GitHub.
Piping No Dey Work:
- Use naija - to read from standard input.

Naijaup - The Toolchain Manager

Na the official tool wey you go use manage NaijaScript Interpreter.

How to Install Am

For Linux/macOS:

Open your terminal.

Run:

curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/xosnrdev/naijascript/master/scripts/install.sh | sh

For Windows (PowerShell):

Open PowerShell.

Run:

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/xosnrdev/naijascript/master/scripts/install.ps1 | iex"

This command go install naijaup for your computer inside $HOME/.local/bin (for Linux/macOS) or %USERPROFILE%\.naijaup\bin (for Windows).

To install the latest version, run:
```
naijaup install latest
```
To install another version (e.g., 1.2.3), run:
```
naijaup install 1.2.3
```

2. See All the Versions Wey You Don Install

To see all the versions wey you don install, run:
```
naijaup list
```

3. Choose Your Default Version

To choose the version wey you wan dey use everytime, run:

naijaup default <version>
# For example:
naijaup default latest

4. See All the Versions Wey Dey Online

To see all the versions wey you fit download, run:
```
naijaup available
```

5. How to Comot Version

To comot any version, run:
```
naijaup uninstall <version>
```

6. Run Script with the Version Wey You Choose

To run your script with any version wey you like, run:
```
naijaup run <script.ns> [args...]
```

7. How to Update `naijaup`

To update naijaup to the latest version, run:
```
naijaup self update
```

8. How to Comot `naijaup` and Everything

To comot naijaup and all NaijaScript data from your system, run:
```
naijaup self uninstall --yes
```

How E Take Arrange Things

Default Version:
- You fit set your default version with naijaup default <version>.
- We dey save the default inside ~/.naijaup/config.toml.
Project Version:
- If you wan use another version for your project, just put .naijascript-toolchain file inside your project folder.
Symlinks:
- For Linux/macOS, we dey create shortcut to the naija program inside ~/.local/bin/naija.
- For Windows, the shortcut dey inside %USERPROFILE%\.naijaup\bin\naija.exe.
- Make sure say these folders dey your PATH.

If Wahala Happen (Troubleshooting)

Command No Dey:
- Add the folder where you install am to your PATH.
- Restart your terminal after you install am.
- If the wahala still dey, abeg open issue for us for GitHub.
Permission Wahala:
- For Unix, you fit change the permission for the folder where you install am.
Shortcut No Wan Create (for Windows):
- Run your terminal as administrator, or add the folder to your PATH by yourself.
Network Wahala:
- Make sure say you get internet to download from GitHub.
Manual Installation:
- Go the Releases page to download am by yourself.

Keyboard shortcuts

The NaijaScript Interpreter