Learn rok

A guide for newcomers to rok, from installation through error handling, concurrency, FFI, ROKON, tools, stones, cryptography, and a cookbook. Each chapter has a short explanation and code you can run right away.

Every code block in this guide is compiled and run with the real toolchain when the site is built, and its output is checked against the one shown. Copy any of them and run it with rok run file.rok.

The complete rules are defined in the language reference and the standard library specification; functions and types are listed in the standard library API. Small complete programs are collected in Examples. For quick answers to everyday tasks (reading a file, timing, threads, JSON, HTTP), see How Do I....

1. Getting Started
In this chapter you install the rok toolchain, create and run your first package, and try a single-file script and the REPL. By the end you can run the examples in the rest of the guide yourself.
2. Values and Types
This chapter covers let for declaring variables, basic types such as numbers and strings, and tuples and lists for grouping values. rok is statically typed, but most types are inferred, so you rarely write them out.
3. Functions
This chapter covers declaring and calling functions, default values and named arguments, and closures you can pass around as values. In rok, a function body is also a block expression, so its last expression is the return value.
4. Control Flow
This chapter covers branching (if, match), looping (while, for, loop), and destructuring. The key point is that if, match, and loop in rok are all expressions that produce values.
5. Sum Types and none
When a value is "either this or that", rok joins the types with |, as in A | B. This chapter covers sum types and the tools for working with the most common one, T | none, which means "there may be no value".
6. Structs, Enums, and Traits
Now it's time to define your own types. This chapter covers struct, which groups data; enum, which lists named cases; and trait, which defines behavior shared by several types.
7. Generics
Use generics when you want the same logic to work for many types. rok generics are compiled separately for each concrete type they're called with (monomorphization), so they run as fast as hand-written per-type functions.
8. Collections and Iterators
Most programs collect, traverse, and transform many values. This chapter covers the standard collections (List, Dict, Set, and their relatives), slicing, and the Iterator that ties them together.
9. Strings and f-strings
Strings show up in almost every program. This chapter covers str and StrBuf, the commonly used methods, the different kinds of literals, and the format specifiers of the f-strings you have been using all along.
10. Error Handling
Things that can fail, like a missing file or bad input, are everywhere. rok has a single error model. A function that can throw writes throws in its signature, and the caller marks that call with try. As a result, every point where an error can flow is visible in the code.
11. Modules and Packages
As a program grows, you need to split the code up and use libraries written by other people. In rok, the unit for dividing code is the module, and the unit for building and distributing is the package. A package published to the registry is called a stone.
12. Concurrency
The right way to do several things at once depends on the goal. Threads and par suit computations that use multiple CPUs, while async tasks suit I/O with lots of waiting. This chapter looks at each tool through short examples and also covers channels, Mutex, and Atomic for exchanging data safely.
13. File and Network IO
This chapter covers how a program talks to the world outside it. Files and directories, paths, standard IO, environment variables, child processes, and TCP / UDP sockets all live in rok::std.
14. FFI Basics
This chapter shows how to call functions written in C from rok, and how to hand rok functions to C. Operating systems and countless libraries expose their functionality through the C ABI, so knowing FFI (foreign function interface) lets you use features the standard library does not provide.
15. ROKON
This chapter shows how to read and write configuration files in ROKON (Rok Object Notation), rok's data format. There is no new syntax to learn: a ROKON file uses the same literal syntax you write values with in rok source. The package manifest rok.rokon uses this format too.
16. Tools
This chapter tours the tools you keep at hand while writing code: the formatter, the linter, tests and benchmarks, documentation generation, editor support (LSP), the REPL and Jupyter, and debug options for looking inside the compiler. All of them start from the single rok command.
17. Conditional Compilation
One source tree often has to build in several shapes: per operating system, debug against release, with or without an optional feature. rok decides this at compile time with #[cfg(..)]. Code whose condition is false is removed right after parsing, as if it had never been written, so it costs nothing at run time and may even refer to names that do not exist in that build.
18. Features and Stones
Chapter 11 built a package and added dependencies. This chapter goes further: features, which let the users of a library turn parts of it on and off; the stones the rok project maintains; and publishing your own library to rokstones.io.
19. Cryptography and TLS
rok ships its own cryptography. rok::core::crypto has the algorithms (hashes, HMAC and HKDF, authenticated encryption, key exchange, signatures), rok::std::crypto::random reads the operating system's secure random source, and rok::std::net::tls is a TLS 1.3 client and server built on the two. No OpenSSL or other system library is involved, so the same code behaves the same on every target.
20. How Do I...
Short answers to everyday tasks, each a complete program you can paste into a file and run with rok run file.rok. Each recipe links to the chapter that explains it.

Edit this page on GitHub

#Learn rok

#Contents

Learn rok

Contents