File Rules

When creating a file in CarbonScript using the .car file extention, you can add rules to the top of the file Using the RULE command. These dictate certain enviornments and how the file will perform

hide-errors

using RULE hide-errors hiding any errors that emerge in the file.

show-ec

using RULE show-ec shows the error codes in the file.

show-tk

using RULE show-tk shows the tokens in the file.

force-run

using RULE force-run forces the file to run.

force-dontrun

using RULE force-dontrun forces the file to not run.

Standard Outputs

CarbonScript follows Standard I/O protocols to input and output to the console. Use stdout to output to the console.

stdout "Hello World"

Data Types

As of v03.1/25, CarbonScript has 7 Datatypes,

Intigers

Intigers are whole natural numbers, positive or negative including 0. Intigers do not contain fractions or decimals
Intigers are known as int, define them by using this keyword.

set x = 10;int

Strings

Strings are words/charachers, sequence of characthers.
Strings are known as str, define them by using this keyword.

set x = "Hello World";str

Floats

Floats are numbers that can have decimal points.
Floats are known as flt, define them by using this keyword.

set x = 10.5;flt

Arrays

Arrays are collections of multiple values stored together.
Arrays are defined using the arr keyword, followed by a list of values.

// arrays can be set in 2 ways, defining an array right away, or pushing into it
set x = "Hello","World";arr // anything assigned this way, will be types as a string

// use push to accuratly type the contents of the array
let y;arr
push y 1;int "hello";str 3.14;flt

Void

The void type is used for functions that do not return a value.
Functions with the void return type are used when no result is needed from the function.

let x;void // this funtion returns code 2, so it has no value

Booleans

Booleans represent true or false values.
Booleans are known as bool, define them by using this keyword.
Booleans can also be assigned with 1 or 0. 1 = true, 0 = false.

set x == true;bool

Structs

Structs are a collection of multipls datatypes and variables stored inside a bunch.
structs are known as structs, define them by using this keyword.

let profile;struct // assiging the variable profile as a struct
const profile:name = "John Doe";str
const profile:age = 45;int
const profile:graduatued = true;bool

// now we have configered the struct, now we need to call it
stdout profile.name
stdout profile.age
stdout profile.graduated
        

Assigning Variables

Varibles are Assigned with one of 3 assignemnet keywords. set, const and let.

set is used to define mutable variables. You can change the value of a variable once it's assigned.
const is used for immutable variables. Once a value is assigned to a const variable, it cannot be changed.
let is used for temporary mutable variables, typically used in short-term calculations or loops.

const name = "John Doe";str
set age = 25;int
set graduated = false;bool

Standard Inputs

CarbonScript follows Standard I/O protocols to input and output to the console. Use stdin to read a value from the console, and store it in a variable.

stdin name;str "Whats Users Name?"

In the code block above, we ask the user thier name, storing into the variable name, expecting the user to submit a str.

Calling Variables

Variables are called with the prefix ?.

stdout ?name

Math And Logic

All mathematical and logical expressions need to be encased inside of parenthesis.
True and False statements are expressed as boolean values 0 = false,1 = true. Or use the provided variables ?true, ?false to help navigate in a more readable way.

stdout ( 100 + ?x )
// assuming x is already a preset variable

Ceil and Floor

Use the ceil and floor functions to round values up or down.

set x = 3.14;flt
stdout ?x
stdout ceil(?x)
stdout floor(?x)

Conditional Statements

Conditional statements are used to observe according to conditions.

Use if statement to open you conditional analysis
Use ifelse statements as a response to the initial statement
Use else statement to respond if no condition is reached

set x = 10;int
set y = 5;int
if ( ?x > ?y ) stdout x is larger than y
ifelse ( ?x < ?y ) stdout x is smaller than y
else stdout x and y are the same value

Loops

As of v03.1/25, CarbonScript has 2 loops. repeat and do

Repeat Loops

repeat 5 {
// code will loop 5 times
}

Do Loop

do 0 < 5 {
// code will loop 5 times, or unless the first values incrementation is interrupted
}

Arrays

Arrays are used as like stacks (follow a FILO order). items can be pushed into the stack and popped out of the stack.

Pushing Into The Array

// assuming x is an array
push a 1 2 3

Popping Out of The Array

// assuming x is the same array as last example
pop x
stdout ?pop
// output of 3

Indexing The Array

// assuming x is the same array as last example
stdout x[1]
// output of 2

Array Length

// assuming x is the same array as last example
stdout ?length x
// output of 3

Creating Functions

Functions follow a similiar approach to C, where you need to define in the header, what type of value will be returned, void if none.

 func;{return_type} {function_name} {variables;type} {
// function code 
return statement if needed
}

Example Function

// creating a simple function that add's two numbers
func;int addition $x;int $y;int {
  return ( $x + $y ) 
}

Calling Functions

calling a functions requires the prefix @ followed by the function name, before function arguement (if required).
If a function returns a value, the value will have to be stored in a variable.

Calling The Example Function Defined Earlier

set result = @addition 10 20
stdout ?result
// output of 30

Carbon Numbers

Carbon Numbers are essentially just decimal numbers of ascii values, padded so they are all divisible by 3. Containing 4 digits at the end symbolizing the values lenght.

They are used to represent universal understanding of chars and strings in CarbonScript.

Use the keyword cnum() to convert a string into a CarbonNumber
Use the keyword ascii() to convert a CarbonNumber into a string

set x = "CarbonScript";str
set c = cnum(?x)// The cnum = 670971140981111100830991141051121160012
set s = ascii(?c)// The string = CarbonScript

Command Line Arguments

Arguments are stored in an array called ?args. The first index of the array is always the file name being ran. If there are less than 10 arguements provided, the remaining arguemments will be filled with the carbon number for "void" (1181111051000004) Read About Carbon Numbers

A base template to follow for command line args being used inside a program

if ( ?args[1] != cnum("void") ) set runIterations = ?args[1]
else set runIterations = 10;int
@generateFibonacci ?runIterations

This is checking the second index of the args array; if the value is not equal to the carbon number value of void, it will we the iterations to how many are provided. If not then it will set the default to the value of 10

Interacting With Files

You can interact with other files and intergrate it with your carbon script code

Assiging files

To interact with a file, you need to make sure it is defined

To define a file you need to use the keyword fset followed by the file path

fset /path/to/file  // now we have defined the file path and can interact with the file

Writing files

To write to a file, we have to make sure a file is defined

To write to a file we have to use the keyword fwrite "{content}"; when the line is finished, there is a newline escape code so next line typed will be placed on a newline

fwrite "Hello World!" // we write "Hello World!" to the file path we defined earlier

Reading Files

reading a file, will be stored inside a struct, alongside with other types in the struct. All the content from reading the file is stored inside an array; and content can be accessed from indexing the array content

To read a file, we use the keyword fread; the contents are stored inside a struct with the name of the file, without the extention (notes.txt -> notes)

fread // reading notes.txt 
stdout ?notes.contents // prints the array of the contents
stdout ?notes.len // prints the length of contents
stdout ?notes.type // prints the file type

Clearing A File

You can Clear a file using fclear; it will clear the file assigned previously

fclear// this will clear the file

Understanding The Error Diagnosis

CarbonScript has an intuitive and helpful error diagnosis system, similiar to other diagnosis tools. Heres how to understand it

Suppose we run a file with a faulty function header; where we have not defined the type of the variables we are passing through. We would get an output like this...

function:type error: no function intake type specified for $a
main.car:1:3
 |
1| func;int addNums $a $b;int {
 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ unexpected type interaction.
error: aborting due to status code 3

Understanding The Error Diagnosis

The first line will always show us the error we have recieved; what we have done wrong, and what function gave it to us. In this case we got an error from function and it gave us a type error, it also provides us with textual hints on what we did wrong.

The second line provides us with some information we need to decipher a little bit. The text before the first colon will be our filename/path. the second will always be a number, this is the line number where your error occured, the third is the error code we were given. Every code has its own meaning; in this case, we got error code 3 which means there was a type error this means, there was a faulty interaction between the function and the variable type. read more about Error Codes here.

Then we get some a text editor based design of the faulty code. we get to the see line, the code, and a caret pointing to the place where the error occured alongside what we did wrong. while we cannot see a color here; each error code has its own color to make ease of understanding!

Finally the last line tells us the runtime was aborted, with the error code that was returned.

Error Codes

CarbonScript handles internal and external errors using error codes; following its own error code system. Follow these codes to make your CarbonScripting experience seamless

What's New

Version Release v03.1/25. March 11th, 2025

✅   Added Command Line Args
✅   Added CarbonNumbers