Syntax Documentation

import fmt
 
fn main() {
	fmt.printf('hello world')
}

import fmt
 
var globalv = 1
 
type globalt = int
 
fn main() {
	var localv = 2
	type local t = int
 
	if true {
	}
 
	for true {
	}
}
 
if true { // x: Declaring an if statement in the global scope is not allowed
}

var foo = 1 // v: Declares variable foo and assigns a value; foo's type is automatically inferred as int
 
var foo = 1 // x: Redeclaring a variable in the same scope is not allowed
 
if (true) {
var foo = 2 // v: Redeclaration is allowed in a different scope
}

int foo = 1 // v
float bar = 2.2 // v
string car = 'hello world' // v: Strings are enclosed in single quotes
 
foo = 2 // v: Variables can be reassigned
 
foo = 'hello world' // x: foo is defined as type int; assigning a string is not allowed
 
i8 f2 = 12 // v: Literals can be automatically converted based on the type
i16 f3 // x: Variable declaration must include an assignment

string bar = '' // v: Use this method to declare an empty string
 
[int] baz = [] // v: Declare an empty vec
 
{float} s = {} // v: Declare an empty set
 
{string:float} m = {} // v: Declare an empty map
 
(int,bool,bool) t = (1, true, false) // v: Define a tuple. Access elements using t[0], t[1], t[2]
 
var (t1, t2, t3) = (1, true, 'hello') // Tuple destructuring declaration
 
var baz = [] // x: Cannot infer the element type of the vec
 
bar = null // x: Assigning null to any composite or simple type is not allowed

// Method 1
string? s = null
s = 'i am string'
 
// Method 2
nullable<string> s2 = null
s2 = 'hello world'

if condition {
    // Code to execute when condition is true
} else {
    // Code to execute when condition is false
}

int foo = 23
 
if foo > 100 {
    print('foo > 100')
 
} else if foo > 20 {
    print('foo > 20')
 
} else {
    print('else handle')
}

// This is a single-line comment
var str = `hello world` // This is also a single-line comment

/*
This is a multi-line comment
It can span multiple lines
*/
var str = `hello world`

int i = 42.5 as int  // float to integer
[u8] bytes = "hello" as [u8]  // string to byte array
anyptr ptr = &i as anyptr  // rawptr<int> to anyptr

type my_int = int
type nullable<T> = T|null

fn string.find_char(u8 char, int after):int {
    int len = self.len()
    for int k = after; k < len; k += 1 {
        if self[k] == char {
            return k
        }
    }
    return -1
}

type square = struct {
    int length
    int width
}
 
fn square.area():int {
    return self.length * self.width
}

fn function_name(parameter_list):return_type {
    // Function body
}

fn sum(int a, int b):int {
    return a + b
}

// Assigning an anonymous function to a variable
var f = fn(int a, int b):int {
    return a + b
}
 
// Calling the anonymous function
var result = f(1, 2)

fn sum(...[int] numbers):int {
    var result = 0
    for v in numbers {
        result += v
    }
    return result
}
 
// Calling
println(sum(1, 2, 3, 4, 5))

fn printf(string fmt, ...[any] args) {
    var str = sprintf(fmt, ...args)
    print(str)
}

fn divide(int a, int b):(int, int) {
    return (a / b, a % b) // Returns the quotient and remainder
}
 
// Receiving return values using tuple destructuring
var (quotient, remainder) = divide(10, 3)

// Defining a function type variable
fn(int,int):int calculator = fn(int a, int b):int {
     return a + b 
}
 
// Function type as a parameter
fn apply(fn(int,int):int f, int x, int y):int {
    return f(x, y)
}

// Struct declaration
type person = struct {
    string name
    int age
    bool active
}
 
// Struct initialization; p is initialized on the stack
var p = person{
    name = "Alice",
    age = 25
}
 
// Using new initializes on the heap and obtains a struct pointer
ptr<person> p2 = new person(name = "Bob", age = 30)
p2.name = "Tom" // Automatic dereference

type person_t = struct{
    string name = "unnamed"
    bool active = true
}
 
// Initialization with default values
var p = person_t{} // p.name="unnamed", p.active=true

type rect = struct {
    int width
    int height
}
 
// Adding an extension function to the rect type
fn rect.area():int {
    return self.width * self.height // Use self to access struct fields
}
 
fn main() {
    var r = rect{width = 10, height = 5}
    println(r.area()) // Output: 50
 
    ptr<rect> rp = new rect(width = 20, height = 10)
    println(rp.area()) // Output: 200
}

// Nested struct
type outer = struct {
    int x
    rect r = rect{} // Nested struct with default initialization
}
 
// Struct composition
type animal = struct {
    string name
}
 
type dog = struct {
    animal base // Compose the animal struct
    string breed
}
 
 
type dog = struct {
    struct {
        string name
    } base // x Do not use anonymous structs; although declaration is possible, initialization and assignment are not, and it's only for memory structure conversion.
    string breed
}

// String declaration - supports single quotes, double quotes, or backticks
string s1 = 'hello world'
string s2 = "hello world"
string s3 = `hello world`
 
// String concatenation
string s4 = s1 + ' one piece'
 
// String comparison
bool b1 = 'hello' == 'hello' // true
bool b2 = 'a' < 'b'         // true
 
// Get string length
int len = s1.len()
 
// Index access and modification
s1[0] = 72 // Modify the first character to 'H' (ASCII code 72)
 
// String to byte array conversion
[u8] bytes = s1 as [u8]
string s5 = bytes as string
 
// String traversal
for v in s1 {
    // The type of v is u8, representing the ASCII code value
    println(v)
}

// Declaration and initialization
[int] list = [1, 2, 3]           // Syntax 1: Declare using [T]
vec<int> list2 = [1, 2, 3]       // Syntax 2: Declare using vec<T>
var list3 = vec_new<int>(0, 10)  // Create an empty vec, the first parameter is the initial default type
var list7 = vec_new<string>("hello", 10) // Initialize a string array with "hello" as the default value
var list5 = [0;10]               // Equivalent to vec_new and automatically infers the type based on the default parameter
var list6 = vec_cap<int>(10)     // Specify capacity, len = 0
[int] list4 = []                 // Automatically infers the empty vec type
 
// Basic operations
list[0] = 10                     // Modify element
var first = list[0]              // Get element
list.push(4)                     // Add element
var len = list.len()             // Get array length
var cap = list.cap()             // Get array capacity
 
// Slicing and concatenation
var slice = list.slice(1, 3)     // Get a slice from index 1 to 3 (exclusive)
list = list.concat([4, 5, 6])    // Concatenate two arrays
list.append([4, 5, 6])           // Append to the list array
 
// Traversal
for v in list {
    println(v)
}

// Declaration and initialization
var m3 = {'a': 1, 'b': 2}           // Type inference
{string:int} m1 = {'a': 1, 'b': 2}  // Declare using {T:T}
map<string,int> m2 = {'a': 1, 'b': 2} // Declare using map<T,T>
 
// Basic operations
m1['c'] = 3                      // Insert/update element
var v = m1['a']                  // Get element value
m1.del('b')                      // Delete element
var exists = m1.contains('a')    // Check if key exists
var size = m1.len()              // Get the number of elements
 
// Traversal
for k in m1 {                    // Iterate through keys only
    println(k)
}
 
for k, v in m1 {                 // Iterate through both keys and values
    println(k, v)
}
 
// Empty map declaration examples
{string:int} empty = {}
var empty = map_new<string,int>()

// Declaration and initialization
{int} s1 = {-32, -64, 13}   // Declare using {T}
set<int> s3 = {1, 2, 3}     // Declare using set<T>
 
// Basic operations
s1.add(111)                 // Add element
s1.del(13)                  // Delete element
var exists = s1.contains(13) // Check if element exists
 
var found = {1, 2, 3}.contains(2) // Supports method chaining
 
// Traversal
for v in s1 {
    println(v)
}
 
// Empty set declaration
{int} empty = {}
var empty = set_new<int>()

var tup = (1, 1.1, true) // v Declare and assign; multiple elements are separated by commas
 
var tup = (1) // x A tuple must contain at least two elements
 
var foo = tup[0] // v Literal 0 represents the first element in the tuple, and so on
 
// x Expression access is not allowed for tuple elements; only integer literals are allowed
var foo = tup[1 + 1]
 
tup[0] = 2 // v Modify the value of an element in the tuple

var list = [1, 2, 3]
 
// 1. Variable creation
// v Multiple variables can be created consecutively with automatic type inference using var
var (foo, bar, car) = (1, 2, true)
 
// x Type declaration is prohibited; only automatic type inference via var is allowed
// (custom_type, int, bool) (foo, bar, car) = (1, 2, true)
 
var (foo, (bar, car)) = (1, (2, true)) // v Nested creation of multiple variables
var (list[0], list[1]) = (2, 4) // x Expressions are not allowed on the left side when creating variables
 
 
// 2. Variable assignment
(foo, bar) = (bar, foo) // v Modify the values of variables foo and bar, allowing for quick swapping
(foo, (bar, car)) = (2, (4, false)) // v Nested modification of variable values
(foo, bar, car) = (2, (4, false)) // x Type mismatch between left and right values
 
// v Left-value expressions like ident/ident[T]/ident.T are allowed in tuple assignment
(list[0], list[2]) = (1, 2)
(1 + 1, 2 + 2) = (1, 2) // x 1+1 is a right-value expression

[u8;3] array = [1, 2, 3] // Declare an array of length 12 with elements of type u8
array[0] = 12
array[1] = 24
var a = array[7]

type t1 = struct {
    [u8;12] array
}
 
var size = @sizeof(t1) // 12 * 1 = 12 bytes
 
type t2 = struct {
    [u8] list
}
 
var size = @sizeof(t2) // list is a pointer, size = 8 bytes

// x Incorrect usage: can't use throw stmt in a fn without an errable! declaration. example: fn rem(...):void!
fn rem(int dividend, int divisor):int {
    ...
}
 
// v Correct usage: the function must declare that it can contain an error using !
fn rem(int dividend, int divisor):int! {
    if divisor == 0 {
        throw errorf('divisor cannot zero')
    }
    return dividend % divisor
}

// Functions with error(!) declaration can be intercepted using catch, where e implements the throwable interface
//type throwable = interface{
//    fn msg():string
//}
//type errort:throwable = struct{
// ...
//}
 
var result = rem(10, 0) catch e {
    println(e.msg())
    break 1 // break can assign a default value to result
}

try {
    var a = 1
    var b = a + 1
    rem(10, 0)
    var c = a + b
} catch e { // e implements throwable
    println('catch err:', e.msg())
}

fn bar():void! {
    throw errorf('error in bar')
}
 
fn foo():void! {
    bar()
}
 
fn main():void! {
    foo()
}

coroutine 'main' uncaught error: 'error in bar' at nature-test/main.n:2:22
stack backtrace:
0:	main.bar
		at nature-test/main.n:2:22
1:	main.foo
		at nature-test/main.n:6:11
2:	main.main
		at nature-test/main.n:10:11

var list = [1, 2, 3]
var a = list[4]

coroutine 'main' panic: 'index out of vec [4] with length 3' at nature-test/main.n:3:18

// Panic catching is the same as error catching
var a = list[4] catch e {
    println(e.msg())
}
 
// The panic function can be used to manually throw a panic
panic('failed')

// Declare union types using the | operator
type nullable<T> = T|null // Nullable type
type number = int|float   // Numeric type

int? foo = null      // Equivalent to nullable<int> foo = null
string? bar = "hello" // Equivalent to nullable<string> bar = "hello"

int? foo = 42
int val = foo as int // Assert the union type to a specific type

int? foo = 42
bool is_int = foo is int   // true
bool is_null = foo is null // false
 
// Used in conditional statements; if the specific type of foo can be determined by logical judgment,
// foo will be automatically asserted in the if body: foo = foo as int
if foo is int {
    println("foo is an integer", foo)
}

int? foo = null
int result = match foo {
    is int -> foo     // auto: foo = foo as int
    is null -> -1    // auto: foo = foo as null
}

any foo = 1
int? bar = null
foo = bar // v
bar = foo // x The range of bar is smaller than foo

type measurable = interface{
    fn area():int
    fn perimeter():int
}
 
// Interface supports generic declaration
type measurable<T> = interface{
    fn area():T
    fn perimeter():T
}

type measurable<T> = interface{
    fn perimeter():T
    fn area():T
}
 
// type implements interface
type rectangle: measurable<i64> = struct{
    i64 width
    i64 height
}
 
fn rectangle.area():i64 {
    return self.width * self.height
}
 
fn rectangle.perimeter():i64 {
    return 2 * (self.width + self.height)
}

fn print_shape(measurable<i64> s) {
    println(s.area(), s.perimeter())
}
 
fn main() {
    // Pass by value
    var r = rectangle{width=3, height=4}
    print_shape(r)
 
    // Pass by pointer reference
    var r1 = new rectangle(width=15, height=18)
    print_shape(r1)
}

type measurable<T> = interface{
    fn perimeter():T
    fn area():T
}
 
type updatable = interface{
    fn update(i64)
}
 
type rectangle: measurable<i64>,updatable = struct{
    i64 width
    i64 height
}
fn rectangle.area():i64 {
    return self.width * self.height
}
fn rectangle.perimeter():i64 {
    return 2 * (self.width + self.height)
}
fn rectangle.update(i64 i) {
   self.width = i
   self.height = i
}

fn use_com(combination c):int {
    if c is square {
        // auto as: square c = c as square, c is interface
        c.unique()
        return 1
    }
    if c is ptr<square> {
        // auto as: ptr<square> c = c as ptr<square>
        c.unique()
        return 2
    }
    return 0
}
 
// match is is also supported
 
fn use_com(combination c):int {
    return match c {
        is square -> 10
        is ptr<square> -> 20
        _ -> 0
    }
}

fn use(testable? test) {
    if (test is testable) { // test = test as testable
        println('testable value is', test.nice())
    } else {
        println('test not testable')
    }
}

match subject {
    pattern1 -> expression1
    pattern2 -> expression2
    ...
    _ -> default_expression // Default branch
}

var a = 12
match a {
    1 -> println('one')
    12 -> println('twelve') // Match successful
    20 -> println('twenty')
    _ -> println('other')
}

match 'hello world' {
    'hello' -> println('greeting')
    'hello world' -> println('full greeting') // Match successful
    _ -> println('other')
}

match {
    12 > 0 && 0 > 0 -> println('case 1')
    (13|(1|2)) == 15 -> println('case 2') // Match successful
    (1|2) > 3 -> println('case 3')
    _ -> println('default')
}

any value = 2.33
var result = match value {
    is int -> 0.0
    is float -> value // value is automatically asserted to float type: var value = value as float
    _ -> 0.0
}

string result = match {
    12 > 13 -> {
        var msg = 'case 1'
        break msg
    }
    12 > 11 -> {
        var msg = 'case 2'
        break msg // Match successful, returns 'case 2'
    }
    _ -> 'default'
}

// Single type parameter
type box<T> = struct {
    T value
}
 
// Multiple type parameters
type pair<T, U> = struct {
    T first
    U second
}
 
type result<T> = T|error   // Generic union type
 
type list<T> = [T]         // Generic array type

type wrapper<T> = struct {
    box<T> inner    // Nested use of generic type
}
 
// Using nested generics
var w = wrapper<int>{
    inner = box<int>{value = 42}
}

// Generic function declaration
fn sum<T>(T a, T b):T {
    return a + b
}
 
// Generic function call
var result = sum<int>(1, 2)     // Explicitly specify type
var result2 = sum(1.1, 2.2)     // Type auto-inference
 
 
// Type parameter defined extension function
type box<T> = struct {
    T value
}
 
fn box<T>.get():T {
    return self.value
}

// union constraint
type test_union = int|bool|float
 
fn test<T:test_union>(T param) {
    println(param)
}
 
// Simplified union constraint
fn test<T:int|bool|float>(T param) {
    println(param)
}
 
// interface constraint
type test_interface = interface{}
type test_interface2 = interface{}
 
fn test<T:test_interface&test_interface2>(T param) {
    println(param)
}

// Define a generic struct
type pair<T, U> = struct {
    T first
    U second
}
 
// Define a generic method
fn pair<T, U>.swap():(U, T) {
    return (self.second, self.first)
}
 
fn main() {
    // Create a generic instance
    var p = pair<int, string>{
        first = 42,
        second = "hello"
    }
 
    // Call the generic method
    var (s, i) = p.swap()
}

var fut = go sum(1, 2) // Create a shared coroutine

var fut = @async(sum(1, 2), co.SAME) // SAME indicates that the new coroutine shares a processor with the current coroutine

fn sum(int a, int b):int {
    co.sleep(1000) // Simulate a time-consuming operation, sleep unit is ms
    return a + b
}
 
fn main() {
    var fut = go sum(1, 2)
    var result = fut.await() // Wait for the coroutine to complete and get the result
    println(result) // Output: 3
}

import co.mutex as m
 
// Create a mutex
var mu = m.mutex_t{}
 
// Lock
mu.lock()
 
// Critical section code
// ...
 
// Unlock
mu.unlock()

fn div(int a, int b):int! {
    if b == 0 {
        throw errorf("division by zero")
    }
    return a / b
}
 
fn main() {
    var fut = go div(10, 0)
    var result = fut.await() catch e {
        println("error:", e.msg())
        break 0 // Provide a default value
    }
}

// Create an unbuffered channel
var ch = chan_new<int>()        // Create a channel for passing int type data
var ch_str = chan_new<string>() // Create a channel for passing string type data
 
// Create a buffered channel
var ch_buf = chan_new<int>(5)   // Create a channel with a buffer size of 5
 
// Send data
ch.send(42)         // Send data to the channel
ch_str.send("hello")
 
// Receive data
var value = ch.recv()     // Receive data from the channel
var msg = ch_str.recv()

ch.close()                      // Close the channel
bool closed = ch.is_closed()    // Check if the channel is closed
var ok = ch.is_successful()    // Check if the most recent read or write operation was successful after the channel is closed

select {
    ch1.on_recv() -> msg {
        // Process data received from ch1
    }
    ch2.on_send(value) -> {
        // Processing after successful send on ch2
    }
    _ -> {
        // Default branch, executed when no channel is ready for operation
    }
}

// Producer
go (fn(chan<int> ch):void! {
    ch.send(42)
})(ch)
 
// Consumer
var value = ch.recv()

var limiter = chan_new<u8>(10) // Allow a maximum of 10 concurrent tasks
for u8 i = 0; i < 100; i+=1 {
    limiter.send(i)           // Acquire a token
    go (fn():void! {
        // Process task
        limiter.recv()           // Release the token
    })()
}

var ch = chan_new<string>()
var timeout = chan_new<bool>()
 
select {
    ch.on_recv() -> msg {
        println("received:", msg)
    }
    timeout.on_recv() -> {
        println("operation timeout")
    }
}

var size = @sizeof(i8) // sizeof reads the stack memory occupied by the type
 
type double = f64
var hash = @reflect_hash(double) // Reads the unique reflection identifier of the type
 
@async(delay_sum(1, 2), 0) // Create a coroutine
 
// Use unsafe_load to avoid heap allocation for package structs
@unsafe_load(package).set_age(25)
 
var a = @default // Assign the initial default value to a heap variable, commonly used for default value assignment in generics

#linkid print_message
fn log(string message):void {
    // Function implementation
}

#local
fn internal_helper():void {
    // Function implementation
}

nullable<int> foo = null
foo = 42 // Can be assigned an int type
 
// Shorthand syntax
int? bar = null
bar = 42

 
type throwable = interface{
    fn msg():string
}
 
type errort:throwable = struct{
    string message
    bool is_panic
}
 
fn errort.msg():string {
    return self.message
}
 
fn errorf(string format, ...[any] args):ptr<errort> {
    var msg = fmt.sprintf(format, ...args)
    return new errort(message = msg)
}

print("Hello", 42, true)  // Output: Hello42true

println("Hello", 42)  // Output: Hello 42\n

panic("something went wrong")  // Program terminates and outputs an error message

assert(1 + 1 == 2)  // Executes normally
assert(1 > 2)        // Triggers panic

// main.n
import fmt
 
fn main() {
    fmt.printf("Hello, World!")
}

// user.n
type user = struct {
    int id
    string username
}
 
int total_users = 0
 
fn create_user(string name):user {
    total_users += 1
    return user{
        id = total_users,
        username = name
    }
}

// Basic import
import "user.n"
 
// Using an alias
import "user.n" as u
 
fn main() {
    var new_user = user.create_user("alice")
    // Or using the alias
    var another = u.create_user("bob")
}

# Basic information
name = "myproject"        # Project name
version = "1.0.0"         # Version number
authors = ["Alice <a@example.com>"]
description = "Project description"
license = "MIT"
type = "bin"              # bin or lib
entry = "main"            # Entry file for the library (used when type = "lib")
 
# Dependencies, can be specified via git or local path
[dependencies]
rand = { type = "git", version = "v1.0.1", url = "[jihulab.com/nature-lang/rand](https://jihulab.com/nature-lang/rand)" }
local_pkg = { type = "local", version = "v1.0.0", path = "./local" }

$HOME/.nature/package
├── caches
└── sources
    ├── jihulab.com.nature-lang.os@v1.0.1
    │    ├── main.n
    │    └── package.toml
    └── local@v1.0.0
        ├── main.linux_amd64.n
        ├── main.linux.n
        ├── main.n
        └── package.toml
 

import rand                  // Import the main module of the package (equivalent to import rand.main)
import rand.utils.seed       // Import a specific module
import rand.utils.seed as seed // Use an alias

[dependencies]
rand_v1 = { type = "git", version = "v1.0", url = "[jihulab.com/nature-lang/rand](https://jihulab.com/nature-lang/rand)" }
rand_v2 = { type = "git", version = "v2.0", url = "[jihulab.com/nature-lang/rand](https://jihulab.com/nature-lang/rand)" }

import rand_v1
import rand_v2

[links]
libz = {
    linux_amd64 = 'libs/libz_linux_amd64.a',
    darwin_amd64 = 'libs/libz_darwin_amd64.a',
    linux_arm64 = 'libs/libz_linux_arm64.a',
    darwin_arm64 = 'libs/libz_darwin_arm64.a'
}

#linkid gzopen
fn gzopen(anyptr fname, anyptr mode):anyptr
 
#linkid sleep
fn sleep(int second)

// zlib.n
#linkid gzopen
fn gzopen(anyptr fname, anyptr mode):anyptr
 
// main.n
import zlib
 
fn main() {
    var output = "output.gz"
    // Use the string.ref function to get a C-style string, including '\0'
    var gzfile = zlib.gzopen(output.ref(), "wb".ref())
    if gzfile == null {
        throw errof("failed to open gzip file")
    }
    // ... use gzfile
}

// Get the address of a variable
var str = "hello"
anyptr ptr = str.ref()  // Get the string address
 
// Get a rawptr type
rawptr<tm_t> time_ptr = &time_info  // Get the address of a struct
 
// Get an anyptr type
anyptr c_ptr = time_info as anyptr // Any nature type can be converted to anyptr type

type tm_t = struct {
    i32 tm_sec
    i32 tm_min
    i32 tm_hour
    i32 tm_mday
    i32 tm_mon
    i32 tm_year
    i32 tm_wday
    i32 tm_yday
    i32 tm_isdst
    i64 tm_gmtoff
    anyptr tm_zone
}

// ...
#linkid localtime
fn localtime(rawptr<i64> timestamp):rawptr<tm_t>
 
#linkid strlen
fn strlen(anyptr str):uint
 
#linkid fork
fn fork():int
 
// ...

var bar = '' // No semicolon needed at the end of a statement
 
if true {
    var foo = 1 // Use 4 spaces for indentation
}
 
call_test(
    1,
    2, // Multi-line parameters need a comma on the last line
)
 
var v = [
    1,
    2,
    3, // Same as above
]
 
var m = {
    "a": 1,
    "b": 2, // Same as above
}
 
var s = person_t{ // No space between struct alias identifier and '{'
    name: "john",
    age: 18, // Same as above
}
 
// 1. Function definition '{' should be on the same line as the function declaration
// 2. There should be a space between the return parameters and ')'
// 3. There should be a space between each parameter
fn test(int arg1, int arg2):int {
 
}