flix / book

The Flix Programming Book

Flix is a statically typed functional, imperative, and logic programming language.

We refer you to the official Flix website (flix.dev) for more information about Flix.

Example

Building

See docs/BUILD.md.

License

Flix is available under the Apache 2.0 license.

Sponsors

We kindly thank EJ Technologies for providing us with JProfiler and JetBrains for providing us with IntelliJ IDEA.

book's Issues

`mod` and `rem`

/*
https://doc.flix.dev/precedence.html states that 'mod' and 'rem' have a certain operator precedence (multiplicative).
I read the website as 'rem' and 'mod' meaning remainder and modulo.
It appears that 'mod' has been changed to mean module while modulo and remainder have been moved to Int32.mod and Int32.rem.
*/

Iterator is not like in the book

This page mentions Iterator type with 2 type parameters when it really has 3 now.
https://doc.flix.dev/foreach.html

How to call C functions in Flix?

Hi Flix team,
Seems like a nice language to try. Thanks for making this nice language. But how do I call C functions in Flix ? I mean I am interested to do some win32 api programming.

Issues with current version

• Error message in effects section is marked as a flix code block. Should not have that language
• String interpolation in fixpoint section contains escape backslash
• Law singletonMeansOne has a param in type class section
• Not all code blocks are marked with flix

Should we have Java syntax highlighted the one place it is used?

Update Appendix: Operator Precedence

(ticket for much later-- in the summer)

File.readLine should be Files.readLine

Hi,

I am going through the book examples and got stuck on the second one in next-steps section, where File.readLines() supposed to be Files.readLines() instead (seems like it was renamed on the latest recent release(?)).

book/src/next-steps.md

Line 17 in 9745337

match File.readLines(file) {

Same likely applies to https://github.com/flix/book/blob/9745337eb9809b4d5ae124c44bf5e98925e16b79/src/redundancy.md

Add CI support for `mdbook build`

Cleanup code indentation

E.g.

Java interop example does not work

I wanted to learn how to use Java code from Flix.

Unfortunately, the docs examples do not appear to work anymore?

import java_new java.io.File(String): ##java.io.File \ IO as newFile;
import java.io.File.exists(): Bool \ IO as fileExists;

def main2(): Unit \ IO =
    let f = newFile("HelloWorld.txt");
    println(fileExists(f))

I see the following compiler error:

-- Parse Error (Import) -------------------------------------------------- /Users/renato/programming/experiments/flix/myproject/src/Interop.flix

>> Expected <java name>, <name> or <Name> before 'java_new'.

1 | import java_new java.io.File(String): ##java.io.File \ IO as newFile;
           ^^^^^^^^
           Here
Hint: 'java_new' is a keyword.
-- Parse Error (OtherDecl) -------------------------------------------------- /Users/renato/programming/experiments/flix/myproject/src/Interop.flix

>> Expected <declaration> before <name>.

1 | import java_new java.io.File(String): ##java.io.File \ IO as newFile;
                    ^^^^
                    Here

Include singleton enum on Tips and Tricks page

Chapter 4 - mod should be `Int32.mod`

Hi,
Flix seems awesome, I'm going trough book right now and I think in chapter "Functions" in this code snippet:

book/src/functions.md

Lines 105 to 108 in e79cbf8

	List.range(1, 100) |>
	List.filter(x -> x mod 2 == 0) |>
	List.map(x -> x * x) |>
	println;

there should be `Int32.mod` instead of mod? At least I had to change it that way to run main function.

Document how to use external JARs

Update Appendix: Legal Identifiers

(ticket for much later-- in the summer)

Add a "Beginners Guide" to answer common problems

Feature Request: Add support for versioned docs

It would be nice to tie the docs version with the compiler release.

At the time of writing the latest compiler release is v0.41.0, but the online docs already refer to changes that have been merged in master but not released yet, such as Traits.

It took me a while to understand why the compiler was complaining, since I assumed that the examples in the doc would work with the latest available release.

Probably it's not super-priority in this stage of the project since the API is expected to change rapidly, but in the (near?) future consider adding a dropdown menu in the docs to select a target compiler version.

Update code examples that use regions and IO

Once flix/flix#7114 is merged in, we need to scan through the book for examples that use both regions and IO and update them if necessary.

Document `install` command

Add a section on basics

let-bindings
how to run the program
if-then-else
how to exit the program
statement expressions are separated by semicolons

Book Structure `SUMMARY.md`

Proposal:

• The Flix Programming Language
• Introduction

---

• Getting Started
  • Installation
  • Hello, World!
• Data Types
• Functions
• Lists
• Records
• References
• Arrays
• Namespaces
• Concurrency with Channels and Processes
• Polymorphic Effects
• Fixpoints
• Type Classes
• Interoperability
• Build and Package Management
• The Flix Standard Library
• Everyday Programming
  • Printing to Standard Out
  • String Interpolation
  • Pipelines
  • Anonymous and Named Holes
  • Type Ascriptions

---

• Advanced Features
  • Type Casts
  • Effect Casts

Use book on `doc.flix.dev`

Configure GitHub link

Add a section on imperative features

Could explain / document how mutability in Flix works. The reference section could be a subsection of this along with examples of mutable data structures (and for loops!).
Thoughts on this?

Ensure no content has been lost

Do a quick compare of the book and doc.flix.dev to ensure we have not lost any content.

Document nix as an installation option?

Flix is in nixpkgs, so I suggest adding nix as an installation option to the getting started page. Something like:

## Using nix

Flix can also be installed using the nix package manager. To install for the currently running shell run:

`nix-shell -p flix`

Or alternatively to install globally:

`nix-env -i flix`

Then run `flix run` in your project directory.

I can add a PR if you wish that this be added.

The keyword `trait` is not highlighted

Do we need to rebuild highlight.js or something?

Map literals with duplicated keys?

A bit of a nitpick, not really sure if this is a book issue or language issue:

In https://doc.flix.dev/primitive-types.html, the Map Literals section seems to imply map literals are syntactic sugar for inserting from right to left, but Map#{1 => "Hello", 1 => "Lol"} actually evaluates to Map#{1 => Lol}.

Python does the same thing, but I am wondering if we should change Map.insert(1, "Hello", Map.insert(2, "World", Map.empty())) to Map.insert(2, "World", Map.insert(1, "Hello", Map.empty())), which seems to be closer to what's happening in terms of ordering?

Describe record patterns

Common Problems

What are some common problems we could describe here?

https://doc.flix.dev/common-problems.html

Bug: docs refer to outdated keyword: namespace

Rename Record Field to Record Label

See flix/flix#6399

Java interop chapter examples are incorrect?

E.g., the example from https://doc.flix.dev/creating-objects.html

import new java.io.File(String): ##java.io.File \ IO as newFile;
newFile("HelloWorld.txt")

does not build with 0.41 as is:

-- Parse Error -------------------------------------------------- /Users/wzy/Projects/chess/traps.flix

>> Parse Error: Invalid input 'j', expected ';', Use, Import or Decls (line 3, column 12):
import new java.io.File(String): ##java.io.File \ IO as newFile;
           ^

Syntactic Context: OtherDecl.

Wrapping it in def main(): Unit \ IO = ... works, but it is not super obvious.

`for` undocumented?

I see in some library code out there for (v <- expr) yield expr works, but the book only mentions foreach, forM, and forA. What is for? Is it forM or not quite?