This guide provides a step-by-step walkthrough for migrating code from 0.3.5-alpha to 0.4.0-alpha. The current version introduces several breaking changes. This document outlines the modifications, explains how to adapt your code to maintain the same behavior, and highlights updated features. In this guide we will cover two main categories of changes:

1. Language Features: Changes and updates to the core language syntax and semantics.
2. Standard Library Updates: Modifications to existing standard library functions and their usage.

Follow along to ensure a smooth transition to the new version. Let’s get started!

Besides of the changes listed below, there are also some breaking changes in the CLI interface. Please refer to the usage section for more details.

The command can potentially fail. In the previous version the unsafe keyword was used to indicate that this command's failure should be ignored. In this release we renamed this keyword to trust, to better convey intent.

// Before
unsafe $ ls -a $

// After
trust $ ls -a $

To align with standards and improve readability, the loop keyword used for iterator loops has been replaced with for. This change ensures linguistic consistency and adopts a convention widely recognized across many programming languages.

// Before
loop number in 0..=5 {
    echo number
}

// After
for number in 0..=5 {
    echo number
}

We've introduced new builtins len, exit and lines, replacing their equivalents in the standard library.

To emphasize that len supports multiple data types, such as text and arrays, it has been moved to a builtin.

// Before
import { len } from "std/text"
echo len("Hello there!")
echo len([1, 2, 3])

// After
echo len("Hello there!")
echo len([1, 2, 3])

Exit is used so often that we decided to move it as a separate builtin as well. It's implemented as a builtin statement which means that we can remove the parentheses.

// Before
import { exit } from "std/env"
exit(1)

// After
exit 1

Lines was not only moved into a builtin but also it was changed in functionality. Before it accepted a Text value which was then split by newline characters. In this version the newly added builtin accepts a path to file for which it returns each line.

// Before
import { lines } from "std/text"
import { file_read } from "std/fs"
lines(file_read("/path/to/file"))

// After
lines("/path/to/file")

This builtin is specifically optimized for direct use as an iterator in a for loop. When used this way, it does not load the entire file into memory but processes it line by line, ensuring efficient resource usage.

For scenarios where lines was used on a Text value originating from sources other than a file, it is recommended to use the new standard library function split_lines instead.

// Before
import { lines } from "std/text"
lines(long_text)

// After
import { split_lines } from "std/text"
split_lines(long_text)

In order to keep a consistent standard library function naming, most of the functions have been renamed with one exception.

This function has been removed in favor of file_chmod. The same effect can be achieved when used with +x flag.

// Before
import { make_executable } from "std/fs"
make_executable("script.ab")

// After
import { file_chmod } from "std/fs"
file_chmod("script.ab", "+x")

Below is a table of all the functions that have been renamed. Their functionality and definitions remain unchanged.