roc-lang/examples

All kinds of Roc examples

examples's Issues

example suggestion: several `Task.loop` examples

Task.loop can be intimidating, so we should have good examples for it with some explanation.
Inspiration:
https://roc.zulipchat.com/#narrow/stream/231634-beginners/topic/read.20.20file/near/392471155
https://github.com/search?q=repo%3Aroc-lang%2Froc%20%22loop%22%20path%3A*.roc&type=code
https://github.com/search?q=repo%3Aroc-lang%2Fbasic-cli%20loop%20path%3A*.roc&type=code

Example suggestion: How to create number with type Dec, f32, u64,...

This came up on zulip yesterday.

"how to create stand alone Dec number":

2.1dec

I think we should do separate examples for every type. For code snippets we want to give the user what they need and nothing more.

example suggestion: (exact) calculations with money; using Dec

We probably also want to add a warning here that we don't yet recommend using roc for production systems that handle real money 😄

example suggestion: how to publish/release a platform

Add benefits of using `Task` to TaskUsage example

See this message for inspiration.

add test for `roc run main.roc -- examples build`

update examples to basic-cli 0.3.2

set up link checker once we set up website

fix pattern matching test failure

This fails with the latest roc nightly, not sure why though

❯ ./roc_nightly/roc test ./examples/PatternMatching/PatternMatching.roc
── EXPECT FAILED ────────────── ./examples/PatternMatching/PatternMatching.roc ─

This expectation failed:

55│>  # Pattern match on a list with these exact elements: Foo, Bar, and then Baz
56│>  expect
57│>      patternMatch = \input ->
58│>          when input is
59│>              [Foo, Bar, Baz] -> Bingo
60│>              _ -> Other
61│>
62│>      (patternMatch [Foo, Bar, Baz] == Bingo)
63│>      && (patternMatch [Foo, Bar] != Bingo)
64│>      && (patternMatch [Foo, Bar, Baz, Barry] != Bingo)



1 failed and 6 passed in 197 ms.

Add copy button for code examples like we have on https://www.roc-lang.org/tutorial

PatternMatching

Line 65 under the TODO works, so it can be re-enabled, #25 was merged:

# TODO: reenable line below when roc-lang/examples/issues/25 is fixed
# && (patternMatch [Foo, Bar, Baz, Barry] != Bingo)           

Example Suggestion: demonstrate Opaque types with e.g. `Email`

See https://www.roc-lang.org/tutorial#opaque-types for inspiration

Example suggestion: how to do debug printing with roc (showing `dbg`)

see https://www.roc-lang.org/tutorial#debugging for inspiration

Add clearly visible "feedback" and "contribute" links to every example page

example suggestion: string interpolation

for example, roc code that prints a string like this: "this is a number: (Num.toStr someNumber)"

Also mention these constraints:

• it has to be one line
• no interpolations inside other interpolations

example suggestion: reading and writing to sqlite database

roc-pg is likely useful when looking at this issue.

use consitent naming, kebab-case for roc filenames and app names

Perhaps we should keep the folder names CamelCase to make it easy to distinguish when we are using folders?

lots of examples use Stdout.line for errors, we should be using Stderr.line instead

Example suggestion: import file as str

imports [
    "some-file" as someStr : Str,
    "some-file" as someBytes : List U8,
]

Because I want examples to be what users are looking to achieve and nothing more I think "importing as Str" and "importing as List U8" should be two different examples. But they should link to each other, for example: "Importing a list of bytes may be bettere suited for your case. Read about it here"

Example suggestion: record builder syntax `: <-`

We already have this record builder example: https://github.com/roc-lang/basic-cli/blob/main/examples/record-builder.roc
I suppose it's ok to duplicate it in this repo.

re-enable commented out type annotations in `examples/TaskUsage/main.roc`

I believe this is blocked on roc-lang/roc#5660

Example suggestion: Task.await vs Task.attempt vs Task.map

Knowing when to use which is important in Roc!

example suggestion: how to publish/release a package

fix json-basic example

This no longer works with the latest roc nightly, I think the json package json: "https://github.com/lukewilliamboswell/roc-package-explorations/releases/download/0.0.1/cdKMia6cwdRG6Gb0SfXP8cgGF7yTz-i959FV6ZfuS0E.tar.br" needs to be updated.

> ./roc_nightly/roc run ./examples/json-basic/main.roc
Downloading https://github.com/roc-lang/basic-cli/releases/download/0.3.2/tE4xS_zLdmmxmHwHih9kHWQ7fsXtJr7W7h3425-eZFk.tar.br
    into /home/runner/.cache/roc/packages

Downloading https://github.com/lukewilliamboswell/roc-package-explorations/releases/download/0.0.1/cdKMia6cwdRG6Gb0SfXP8cgGF7yTz-i959FV6ZfuS0E.tar.br
    into /home/runner/.cache/roc/packages
 ── INCOMPLETE ABILITY IMPLEMENTATION ─ ...SfXP8cgGF7yTz-i959FV6ZfuS0E/Core.roc ─

This type does not fully implement the EncoderFormatting ability:

41│>           EncoderFormatting {
42│>               u8: encodeU8,
43│>               u16: encodeU16,
44│>               u32: encodeU32,
45│>               u64: encodeU64,
46│>               u128: encodeU128,
47│>               i8: encodeI8,
48│>               i16: encodeI16,
49│>               i32: encodeI32,
50│>               i64: encodeI64,
51│>               i128: encodeI128,
52│>               f32: encodeF32,
53│>               f64: encodeF64,
54│>               dec: encodeDec,
55│>               bool: encodeBool,
56│>               string: encodeString,
57│>               list: encodeList,
58│>               record: encodeRecord,
59│>               tag: encodeTag,
60│>           },

The following necessary members are missing implementations:

    tuple


── INCOMPLETE ABILITY IMPLEMENTATION ─ ...SfXP8cgGF7yTz-i959FV6ZfuS0E/Core.roc ─

This type does not fully implement the DecoderFormatting ability:

61│>           DecoderFormatting {
62│>               u8: decodeU8,
63│>               u16: decodeU16,
64│>               u32: decodeU32,
65│>               u64: decodeU64,
66│>               u128: decodeU128,
67│>               i8: decodeI8,
68│>               i16: decodeI16,
69│>               i32: decodeI32,
70│>               i64: decodeI64,
71│>               i128: decodeI128,
72│>               f32: decodeF32,
73│>               f64: decodeF64,
74│>               dec: decodeDec,
75│>               bool: decodeBool,
76│>               string: decodeString,
77│>               list: decodeList,
78│>               record: decodeRecord,
79│>           },

The following necessary members are missing implementations:

    tuple

───────────────────────────────────────────���────────────────────────────────────

2 errors and 0 warnings found in 3057 ms.

Example suggestion: command line args

add ci script that checks if every example has a corresponding test

Example suggestion: tuples in roc

Tuples are not mentioned in the tutorial so it would be nice to have a basic example demonstrating how they are commonly used.

example suggestion: error handling with both `Task` and `Result`. `Task.fromResult`

See here for inspiration.

Example suggestion: records with optional fields (= `?`)

Deconstructing records with optional fields can be shown here as well:

clamp = \x, config ->
    { min ? x, max ? x } = config
    min + max

bring back json folder after roc-json 0.3.0 is released

revert 607dd76 and 8f828f6

Example suggestion: error handling

Many people will be unfamiliar with Roc error handling so I think we need a good example for it, some suggestions:

• handling a single Result
• handling a single Task
• chaining Results with a pipeline
• chaining Tasks with a pipeline
• how to mix Task and Result

make top-left examples decoration take you back to the main examples site

ld: warning when running example

% roc test examples/PatternMatching/PatternMatching.roc 
ld: warning: -undefined dynamic_lookup may not work with chained fixups

0 failed and 7 passed in 572 ms.

Example suggestion: how to compare floats the right way

https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/

example suggestion: write `Str` to file

See writeUtf8

example suggestion: read file into `Str`

See readUtf8.

This example should also mention this example as a better alternative in certain situations.

Example suggestion: pattern matching with `Dict`

See conversation here

Example suggestion: `Task {} []` vs `Task {} *`

https://roc.zulipchat.com/#narrow/stream/231634-beginners/topic/Task.20return.20types/near/365002936

Example suggestion: How to use the glue command with an example project

Example suggestion: demonstrate converting all kinds of types to a `Str`

example suggestion: avoiding `{} <-` `|> await` boilerplate

We should make an example for this once we figure it out ourselves :p

Example of a problematic case:

{} <- log "Extracting current rust version from rust-toolchain.toml..." |> await
{ stable: currentStable, nightly: currentNightly } <- getCurrentVersionsFromToml |> await
{} <- log "Found versions:\n\t- stable: \(versionToStr currentStable)\n\t- nightly with date: \(dateToStr currentNightly)" |> await
# TODO Task.map to avoid repeated `{} <-`?
{} <- log "Searching for nightly matching stable-\(newRustVersion)..." |> await

newNightly <-
    findMatchingNigthly (versionFromStr newRustVersion) currentNightly
    |> await

{} <- log "New nightly: nightly-\(dateToStr newNightly)" |> await

TODO can we avoid boiler plate of `{} <-` and `await` here?
{} <-
    Path.fromStr "rust-toolchain.toml"
    |> updateToml newRustVersion
    |> await

{} <-
    Path.fromStr "examples/platform-switching/rust-platform/rust-toolchain.toml"
    |> updateToml newRustVersion
    |> await

{} <-
    Path.fromStr "Earthfile"
    |> updateEarthFile newRustVersion
    |> await

example suggestion: how to do a for loop in roc

The example could show an imperative c-style for loop and the equivalent in Roc.

remove readargs from Arithmetic example

In line with the goal "The code snippet of the example should concisely provide the code that the user is looking for.", readargs should not be demonstrated in the Arithmetic example. We should just use fixed values instead of cli args.

We should have another example to demonstrate command line args: #39

Example suggestion: backpassing

Inspiration https://www.roc-lang.org/tutorial#tasks

We should include several examples of how the desugaring works.

add CI tests for ubuntu 22.04, macos 11/12/13

fix examples build script (main.roc) segmentation fault

Run ./roc_nightly/roc run main.roc -- examples build
🔨 Rebuilding platform...
Processing 47 input files...
/home/runner/work/examples/examples/examples/CommandLineArgs/README.md -> /home/runner/work/examples/examples/build/CommandLineArgs/README.html
/home/runner/work/examples/examples/examples/TowersOfHanoi/README.md -> /home/runner/work/examples/examples/build/TowersOfHanoi/README.html
/home/runner/work/examples/examples/examples/GraphTraversal/README.md -> /home/runner/work/examples/examples/build/GraphTraversal/README.html
/home/runner/work/examples/examples/examples/PatternMatching/README.md -> /home/runner/work/examples/examples/build/PatternMatching/README.html
/home/runner/work/examples/examples/examples/Arithmetic/README.md -> /home/runner/work/examples/examples/build/Arithmetic/README.html
/home/runner/work/examples/examples/examples/HelloWorld/README.md -> /home/runner/work/examples/examples/build/HelloWorld/README.html
/home/runner/work/examples/examples/examples/RandomNumbers/README.md -> /home/runner/work/examples/examples/build/RandomNumbers/README.html
/home/runner/work/examples/examples/examples/TaskUsage/README.md -> /home/runner/work/examples/examples/build/TaskUsage/README.html
/home/runner/work/examples/examples/examples/index.md -> /home/runner/work/examples/examples/build/index.html
/home/runner/work/examples/examples/examples/LeastSquares/README.md -> /home/runner/work/examples/examples/build/LeastSquares/README.html
/home/runner/work/examples/examples/examples/Tuples/README.md -> /home/runner/work/examples/examples/build/Tuples/README.html
/home/runner/work/examples/examples/examples/IngestFiles/README.md -> /home/runner/work/examples/examples/build/IngestFiles/README.html
/home/runner/work/examples/examples/examples/Parser/README.md -> /home/runner/work/examples/examples/build/Parser/README.html
/home/runner/work/examples/examples/examples/FizzBuzz/README.md -> /home/runner/work/examples/examples/build/FizzBuzz/README.html
/home/runner/work/examples/examples/examples/Json/README.md -> /home/runner/work/examples/examples/build/Json/README.html
Processed 47 files with 15 successes and 0 errors
/home/runner/work/_temp/ea8097f9-5ff1-4662-9f07-4ff810955e2d.sh: line 1:  2975 Segmentation fault      (core dumped) ./roc_nightly/roc run main.roc -- examples build

Example Suggestion: Safe Arithmetic

Just going through the examples, thank you so much for the effort you are making here.

I am reading through the Arithmetic example and I think there's the obvious edge case about dividing by zero.

According to roc's current div documentation:

Division by zero is undefined in mathematics. As such, you should make sure never to pass zero as the denomaintor to this function! Calling div on a Dec denominator of zero will cause a panic.

Possible solutions:

1. Adjust the example text to state that if the second argument is 0, we can skip the integer quotient operation;

2. Adjust the example text to state that zero is not a valid input for the second argument, and add an explicit check on the readArgs function for this case

3. Adjust the example text to state that an input of 0 on the second argument is allowed to crash with a Floating point exception

My preference would be between solution 1 or 2, or a smarter one :)

Let me know your thoughts and once again, thank you for this amazing effort!

Example suggestion: deconstructing a record

{ min, max } = config

Typo in PatternMatch example

Tag should say EndswithFoo

# Pattern match on a list that ends with a Foo tag
expect 
    patternMatch = \input ->
        when input is 
            [.., Foo] -> StartsWithFoo
            _ -> Other
    
    patternMatch [Baz, Bar, Foo] == StartsWithFoo &&
    patternMatch [Foo, Bar, Baz] != StartsWithFoo 

Update title, this is currently displayed as "title" in the browser