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);
}
```

## Documentation

More documentation is available at [Documentation](docs/Documentation.md).

## Building
First, install the required packages. (ninja is required only for the quick build, you can use other build systems (like GNU Make) for the manual build)

Debian/Ubuntu:
`# apt install 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 cmake ninja llvm-libs`

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`).

Then, you can either use the quick-build script or do a manual build.

Quick build: `./build.sh`

Manual build first-time setup: 
```
mkdir build
cd build
cmake ..
```

Then, every time you want to build:
```
cd build
cmake --build .
```

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

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 # compiles a file with output filename
$ build/sapphirec main.sp -o main --msystem darwin # compiles a file for macOS
```