sapphire/README.md

# Sapphire
A modern, fast and reliable programming language. (WIP)

**WARNING**: Most features in this README (especially the About section) are planned for the future and not yet implemented.

## About
Sapphire is a relatively high-level programming language, yet low-level when it needs to be. The language supports low-level memory manipulation using pointers, but pointer arithmetic is only allowed in unsafe contexts, for greater memory safety. Dynamic memory allocation is also a thing, though it is recommended not to use it directly, but instead make great use of [smart pointers](https://en.wikipedia.org/wiki/Smart_pointer).

Sapphire is a [compiled](https://en.wikipedia.org/wiki/Compiled_language) programming language, with static typing, although [type inference](https://en.wikipedia.org/wiki/Type_inference) is also supported. It also has a high-level standard library, which supports console/file I/O, operating system functions, advanced math operations, string manipulation, and many more.

## Basic usage
"Hello world" in Sapphire:

```
const io from @'core/io';

let @main in {
	io.outln('Hello, World!');
}
```

or alternatively:

```
const { outln } from @'core/io';

let @main in {
	outln('Hello, World!');
}
```

## Examples
FizzBuzz:
```
const io from @'core/io';
const { toString } from @'core/type_utils';

let @fizzBuzz(i32 i) in {
	String result = '';
	if(i % 3 == 0)
	{
		if(i % 5 == 0)
		{
			result = 'FizzBuzz';
		} else {
			result = 'Fizz';
		}
	} else {
		if(i % 5 == 0)
		{
			result = 'Buzz';
		} else {
			result = toString(i);
		}
	}
	io.outln(result);
}

let @main in {
	for(i32 i = 1; i <= 100; i++)
	{
		fizzBuzz(i);
	}
}
```
Quine:
```
const io from @'core/io';
String fmt = 'const io from @%ccore/io%c;%cString fmt = %c%s%c;%clet @main in {%c%cio.outf(fmt,39,39,10,39,fmt,39,10,10,9,10,10);%c}%c';
let @main in {
	io.outf(fmt,39,39,10,39,fmt,39,10,10,9,10,10);
}
```

## Examples that actually work right now
Exit with exit code 0 (success):
```
let @main in {
	0
}
```
Exit with non-zero exit code (failure):
```
let @main in {
	1 // or any other number
}
```
Exit with calculated exit code (yes, this language is a glorified calculator right now):
```
let @main in {
	3 + 5 * 6 // It doesn't even support parentheses, what a failure
} // the exit code is actually computed at compile time by LLVM (optimizations!!)
```

## Documentation

More documentation is available at [Documentation](docs/Documentation.md), whenever this file gets created.

## Building

First, install the required packages. (ninja is optional, you can use any build system you want)

Debian/Ubuntu:
`# apt install zlib1g-dev build-essential cmake ninja-build llvm-dev`

CentOS/Fedora/RHEL: `# dnf install gcc gcc-c++ zlib-devel libffi-devel cmake ninja-build llvm-devel`

Arch: `# pacman -S gcc cmake ninja llvm-libs llvm`

For Ninja users:
On platforms that install ninja to `/usr/bin/ninja` instead of `/usr/bin/ninja-build`, CMake may fail.
In that case, symlink ninja-build to ninja (`ln -s /usr/bin/ninja /usr/bin/ninja-build`).

First-time setup:
```
./sapphire.sh generate <build system, such as Ninja or Unix Makefiles (you can view all possible options with `cmake --help`)> <build type: Debug or Release (or MinSizeRel/RelWithDebInfo)>
```

To change build type/build system, just run `./sapphire.sh clean` followed by the generate command above.

Building:
```
./sapphire.sh build
```

Installing (probably will have to be run as administrator/root):
```
./sapphire.sh install <destination, default depends on platform, on Linux it's often /usr/local>
```
This will install the compiler at `<destination>/bin/sapphirec`.

## Running
The compiler is built at `build/sapphirec`.

For now, it can only generate object files/LLVM IR, so you'll have to link manually.

A few example commands:
```
$ build/sapphirec --version # prints the compiler version
$ build/sapphirec --help # shows usage
$ build/sapphirec main.sp # compiles a file
$ build/sapphirec main.sp -o main.o # compiles a file with output filename
$ build/sapphirec main.sp -o main.o --msystem darwin # compiles a file for macOS
$ build/sapphirec main.sp -o main.o && gcc main.o -o main && ./main # compiles, links and runs
$ build/sapphirec main.sp -o main.ll --emit-llvm # display the generated cross-platform LLVM intermediate representation
```