docs

examples

Roc syntax to use this platform:

app [main!] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.20.0/X73hGh05nNTkDHU06FHC0YfFaQB1pimX7gncRcao5mU.tar.br" }

🆕 Additions

• File.exists! and Path.exists! #380 #381
• File.rename! and Path.rename! #377 #379
• File.time_accessed!, File.time_modified!, File.time_created! #350
• File.size_in_bytes #347
• File.is_readable, File.is_executable, File.is_writable #349
• Sqlite.map_value_result #346
• Stdout.write_bytes and Stderr.write_bytes #329
• More and better examples #355 #356 #358 #369 #372 #391 #322 #323 #327
• Docs website for main branch #339

💥 Breaking Changes

• Cmd API overhaul (see upgrade guide below) #397
• No more guaranteed support for ubuntu-20.04 (End of Life) #328
• Changed Env.VarNotFound to Env.VarNotFound(Str) #398
• Renamed UnhandledRows error in Sqlite to RowsReturnedUseQueryInstead

✨ Improvements

• Massively increased test coverage #354 #359 #361 #363 #364 #368 #370 #371 #373
• Tests on more systems #332 #333 #335 #405
• HTTP Request body body does not need to be UTF-8 #343
• Url.path supports URIs in query parameters #344
• Imrpoved docs comments #320

🐛 Fixes

• Url.append fix #363

Other Notable Changes

• Update rust dependencies #365
• CI check to make sure all exposed functions are tested #351

Full Changelog: 0.19.0...0.20.0

Contributors ❤️

In alphabetical order:

• @albx79
• @Anton-4
• @dezren39
• @kili-ilo
• @niclas-ahden

Cmd Upgrade Guide

Cmd.status! was commonly used when you just wanted to execute a Cmd without needing to process the output.
We now have the better named Cmd.exec_cmd! for this purpose.
The type of Cmd.status! also delivered the impression that it it could return non-zero exit codes like Ok(1), when this was not actually the case. I've regularly seen code where people checked if the exit code returned by status was 0, if you did, you can get rid if that now :) . If you actually want to take action based on the specific non-zero exit code (which is rarely needed), you can now use Cmd.exec_exit_code.

For all exec... functions, we now use Result in a more logical way, if the command had a 0 exit code, it will return with Ok(...). If not, you will get a specific error that will show useful info on Inspect.to_str. Perfect for error handling in hobby programs.

If you previously used Cmd.output!, you should most likely replace that with Cmd.exec_output!. Note the different output type, it should help simplify output and error handling.

docs

examples

Roc syntax to use this platform:

app [main!] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.19.0/Hj-J_zxz7V9YurCSTFcFdu6cQJie4guzsPMUi5kBYUk.tar.br" }

Breaking changes

• Several Roc changes (see Roc migration guide) #305 #310 #312 #314
• Http.send now returns a Result #309
• Docs site moved to https://roc-lang.github.io #306 #307

New features

• Sqlite support #299

Other notable changes

• rust_host_bin: pass -Wl,-headerpad,0x1000 to reserve space for the surgical linker #313
• Make path_from_roc_path pub for Windows by #318

Contributors ❤️

In alphabetical order:

• @bhansconnect
• @imclerran
• @kubkon
• @kukimik
• @lukewilliamboswell
• @smores56

Full Changelog: 0.18.0...0.19.0

docs

examples

Roc syntax to use this platform:

app [main!] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.18.0/0APbwVN1_p1mJ96tXjaoiUCr8NBGamr8G8Ac_DrXR-o.tar.br" }

Breaking changes

• Rename all functions to snake_case #288
• Upgrade to purity inference #257
• Add new custom type Arg, update API to main! : List Arg => Result {} [Exit I32 Str]_ #293

New functions

• Port updates from basic-webserver & basic-ssg

Notable Internal changes

• Add roc_expect_failed #271
• Cleanup and refactoring #283 #287 #280 #288 #290 #294

Full Changelog: 0.17.0...0.18.0

Migration guide

• ! is now part of the function name of effectful functions (= all platform functions), it is no longer syntax sugar for Task.await. Change:

  • app [main] { to app [main!] {
  • main = to main! = \_args ->

• All basic-cli functions have changed to snake_case naming.

• Task is no longer needed, you can switch to using Result, => is used in the type of a function if it is effectful. Change:

  • Task.ok to Ok
  • Task.err to Err
  • Task to Result
  • Task.loop to a recursive function
  • You may need to add Ok {} as the last line in the main function
  • Example with => :

  rocVersionCheck : Task {} _
  rocVersionCheck =

  To:

  rocVersionCheck! : {} => Result {} _
  rocVersionCheck! = \{} ->

• We recommend the use of the try keyword:

  • replace Stdout.line! "hello" with try Stdout.line! "hello"
  • use it instead of Task.await

• HTTP changes:

  • in headers: key to name
  • url to uri
  • mimeType is gone
  • timeout to timeout_ms

Feel free to suggest additions to the migration guide!

Examples of upgrades

⚠️ This release requires a version of Roc released on November 29 2024 or later.

docs

examples

Roc syntax to use this platform:

app [main] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.17.0/lZFLstMUCUvd5bjnnpYromZJXkQUrdhbva4xdBInicE.tar.br" }

Breaking changes

• Reordered the arguments of File.write, File.writeBytes, File.writeUtf8, Path.write, Path.writeBytes and Path.writeUtf8. #267
• Increased buffer size of Stdin.bytes to 16,384 bytes. #268
• macos-12 testing deprecation #263
• Roc Str.split and List.split updates #272

Full Changelog: 0.16.0...0.17.0

docs -> see doc.tar.gz in assets down below

examples

Roc syntax to use this platform:

app [main] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.16.0/O00IPk-Krg_diNS2dVWlI0ZQP794Vctxzv0ha96mK0E.tar.br" }

Breaking changes

None

New functions

• Added support for reading the system or application Locale #258
• Added Stdin.readtoEnd #259

New Contributors

• @aisk made their first contribution in #247
• @stuarth made their first contribution in #253
• @nathanKramer made their first contribution in #254

Full Changelog: 0.15.0...0.16.0

⚠️ This release requires a version of Roc released on August 31 2024 or later.

docs -> see doc.tar.gz in assets down below

examples

Roc syntax to use this platform:

app [main] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.15.0/SlwdbJ-3GR7uBWQo6zlmYWNYOxnvo8r6YABXD-45UOw.tar.br" }

Breaking changes

• Use builtin Task #217

Upgrade Notes

Task is now builtin in Roc, to upgrade to this release you probably just need to remove Task imports like this one:

import pf.Task exposing [Task]

You may also need to change someTime = Utc.now! to someTime = Utc.now! {}

Full Changelog: 0.14.0...0.15.0

⚠️ This release requires a version of Roc released between August 23 and August 30 2024.

docs -> see doc.tar.gz in assets down below

examples

Roc syntax to use this platform:

app [main] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.14.0/dC5ceT962N_4jmoyoffVdphJ_4GlW3YMhAPyGPr-nU0.tar.br" }

What's Changed

• Make Tcp use a heap like File #237

• Replace deprecated backpassing, use new ? syntax #244

• fix docs examples for File.readBytes and File.readUtf8 #238

• support cargo debug build in build.roc #239

Full Changelog: 0.13.0...0.14.0

⚠️ This release requires a version of Roc released on August 23 2024 or later.

docs -> see doc.tar.gz in assets down below

examples

Roc syntax to use this platform:

app [main] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.13.0/nW9yMRtZuCYf1Oa9vbE5XoirMwzLbtoSgv7NGhUlqYA.tar.br" }

What's Changed

• basic-cli now handles building itself using a build.roc file #194
• Automatic file closing, better file reading #230
• Update Arg module to new record builder syntax #227

Full Changelog: 0.12.0...0.13.0

⚠️ This release requires a version of Roc released on June 10 2024 or later.

docs -> see doc.tar.gz in assets down below

examples

Roc syntax to use this platform:

app [main] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.12.0/Lb8EgiejTUzbggO2HVVuPJFkwvvsfW6LojkLR20kTVE.tar.br" }

What's Changed

Breaking Changes

• Complete overhaul of Arg (example) #204
• Added Env.platform #211
• Added File.readLine for buffered reading (example) #206
• Removed support for macos 11 #213
• rename Task.seq to Task.sequence #219
• Added body to HTTP BadStatus #209

Other

• Upgraded Rust to 1.79 #216

Full Changelog: 0.11.0...0.12.0

What's Changed

• Don't print a blank line if Exit is given "" by @rtfeldman in #197
• test on macos too by @Anton-4 in #198
• Upgrade to new module syntax by @agu-z in #200
• Have File and Dir functions accept Str instead of Path by @rtfeldman in #199
• Change the args example to use Weaver by @smores56 in #202
• Add Http.get, rename HttpError to HttpErr by @rtfeldman in #201

New Contributors

• @smores56 made their first contribution in #202

Full Changelog: 0.10.0...0.11.0