mirror of
https://github.com/roc-lang/roc.git
synced 2024-11-05 01:58:58 +03:00
Merge pull request #6002 from roc-lang/docs-install-updates
Update /docs and /install on WIP website
This commit is contained in:
Richard Feldman
GitHub
commit
6ccee5360a
@ -25,7 +25,7 @@ view =
|
||||
Indent,
|
||||
Desc [Ident "Path.fromStr", Str "\"url.txt\""] "<p>This converts the string <code>\"url.txt\"</code> into a <code>Path</code> by passing it to <code>Path.fromStr</code>.</p><p>Function arguments are separated with whitespace. Parentheses are only needed in <a href=\"/tutorial#calling-functions\">nested function calls</a>.</p>",
|
||||
Newline,
|
||||
Desc [Kw "|>", Ident "storeEmail"] "<p>The <a href=\"/tutorial#the-pipe-operator\">pipe operator</a> (<code>|></code>) is syntax sugar for passing the previous value to the next function in the “pipeline.”</p><p>This line takes the value that <code>Path.fromStr \"url.txt\"</code> returns and passes it to <code>storeEmail</code>.</p><p>The next <code>|></code> continues the pipeline.</p>",
|
||||
Desc [Kw "|>", Ident "storeEmail"] "<p>The <a href=\"/tutorial#the-pipe-operator\">pipe operator</a> (<code>|></code>) is syntax sugar for passing the previous value to the next function in the \"pipeline.\"</p><p>This line takes the value that <code>Path.fromStr \"url.txt\"</code> returns and passes it to <code>storeEmail</code>.</p><p>The next <code>|></code> continues the pipeline.</p>",
|
||||
Newline,
|
||||
Desc [Kw "|>", Ident "Task.onErr", Ident "handleErr"] "<p>If the task returned by the previous step in the pipeline fails, pass its error to <code>handleErr</code>.</p><p>The pipeline essentially does this:</p><pre><code>a = Path.fromStr \"url.txt\"\nb = storeEmail a\n\nTask.onErr b handleErr</code></pre><p>It creates a <code>Path</code> from a string, stores an email based on that path, and then does error handling.</p>",
|
||||
Outdent,
|
||||
@ -34,24 +34,24 @@ view =
|
||||
Indent,
|
||||
Desc [Ident "url", Kw "<-", Ident "File.readUtf8", Ident "path", Kw "|>", Ident "Task.await"] "<p>This reads the contents of the file (as a <a href=\"https://en.wikipedia.org/wiki/UTF-8\">UTF-8</a> string) into <code>url</code>.</p><p>The <code><-</code> does <a href=\"/tutorial#backpassing\">backpassing</a>, which is syntax sugar for defining a function. This line desugars to:</p><pre><code>Task.await\n (File.readUtf8 path)\n \\url -></code></pre><p>The lines after this one form the body of the <code>\\url -></code> <a href=\"https://en.wikipedia.org/wiki/Callback_(computer_programming)\">callback</a>, which runs if the file read succeeds.</p>",
|
||||
Newline,
|
||||
Desc [Ident "user", Kw "<-", Ident "Http.get", Ident "url", Ident "Json.codec", Kw "|>", Ident "Task.await"] "<p>This fetches the contents of the URL and decodes them as <a href=\"https://www.json.org\">JSON</a>.</p><p>If the shape of the JSON isn’t compatible with the type of <code>user</code> (based on type inference), this will give a decoding error immediately.</p><p>As with all the other lines ending in <code>|> Task.await</code>, if there’s an error, nothing else in <code>storeEmail</code> will be run, and <code>handleErr</code> will end up handling the error.</p>",
|
||||
Desc [Ident "user", Kw "<-", Ident "Http.get", Ident "url", Ident "Json.codec", Kw "|>", Ident "Task.await"] "<p>This fetches the contents of the URL and decodes them as <a href=\"https://www.json.org\">JSON</a>.</p><p>If the shape of the JSON isn't compatible with the type of <code>user</code> (based on type inference), this will give a decoding error immediately.</p><p>As with all the other lines ending in <code>|> Task.await</code>, if there's an error, nothing else in <code>storeEmail</code> will be run, and <code>handleErr</code> will end up handling the error.</p>",
|
||||
Newline,
|
||||
Desc [Ident "dest", Kw "=", Ident "Path.fromStr", StrInterpolation "\"" "user.name" ".txt\""] "<p>The <code>\\(user.name)</code> in this string literal will be replaced with the value in <code>name</code>. This is <a href=\"/tutorial#string-interpolation\">string interpolation</a>.</p><p>Note that this line doesn't end with <code>|> Task.await</code>. Earlier lines needed that because they were I/O <a href=\"/tutorial#tasks\">tasks</a>, but this is a plain old <a href=\"/tutorial#defs\">definition</a>, so there's no task to await.</p>",
|
||||
Newline,
|
||||
Desc [Literal "_", Kw "<-", Ident "File.writeUtf8", Ident "dest", Ident "user.email", Kw "|>", Ident "Task.await"] "<p>This writes <code>user.email</code> to the file, encoded as <a href=\"https://en.wikipedia.org/wiki/UTF-8\">UTF-8</a>.</p><p>We won’t be using the output of <code>writeUtf8</code>, so we name it <code>_</code>. The special name <code>_</code> is for when you don’t want to use something.</p><p>You can name as many things as you like <code>_</code>, but you can never reference anything named <code>_</code>. So it’s only useful for when you don’t want to choose a name.</p>",
|
||||
Desc [Literal "_", Kw "<-", Ident "File.writeUtf8", Ident "dest", Ident "user.email", Kw "|>", Ident "Task.await"] "<p>This writes <code>user.email</code> to the file, encoded as <a href=\"https://en.wikipedia.org/wiki/UTF-8\">UTF-8</a>.</p><p>We won't be using the output of <code>writeUtf8</code>, so we name it <code>_</code>. The special name <code>_</code> is for when you don't want to use something.</p><p>You can name as many things as you like <code>_</code>, but you can never reference anything named <code>_</code>. So it's only useful for when you don't want to choose a name.</p>",
|
||||
Newline,
|
||||
Desc [Ident "Stdout.line", StrInterpolation "\"Wrote email to " "Path.display dest" "\""] "<p>This prints what we did to <a href=\"https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)\">stdout</a>.</p><p>Note that this line doesn't end with <code>|> Task.await</code>. That’s because, although <code>Stdout.line</code> returns a <a href=\"/tutorial#tasks\">task</a>, we don’t need to await it because nothing happens after it.</p>",
|
||||
Desc [Ident "Stdout.line", StrInterpolation "\"Wrote email to " "Path.display dest" "\""] "<p>This prints what we did to <a href=\"https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)\">stdout</a>.</p><p>Note that this line doesn't end with <code>|> Task.await</code>. That's because, although <code>Stdout.line</code> returns a <a href=\"/tutorial#tasks\">task</a>, we don't need to await it because nothing happens after it.</p>",
|
||||
Outdent,
|
||||
Newline,
|
||||
Desc [Ident "handleErr", Kw "=", Lambda ["err"]] "<p>Like <code>storeEmail</code>, <code>handleErr</code> is also a function.</p><p>Although type annotations are optional everywhere in Roc—because the language has 100% type inference—you could add type annotations to <code>main</code>, <code>storeEmail</code>, and <code>handleErr</code> if you wanted to.</p>",
|
||||
Indent,
|
||||
Desc [Kw "when", Ident "err", Kw "is"] "<p>This will run one of the following lines depending on what value the <code>err</code> argument has.</p><p>Each line does a <a href=\"/tutorial#tags-with-payloads\">pattern match</a> on the shape of the error to decide whether to run, or to move on and try the next line's pattern.</p><p>Roc will do compile-time <a href=\"/tutorial#exhaustiveness\">exhaustiveness checking</a> and tell you if you forgot to handle any error cases here that could have occurred, based on the tasks that were run in <code>storeEmail</code>.</p>",
|
||||
Indent,
|
||||
Desc [Literal "HttpErr", Ident "url", Kw "_", Kw "->", Ident "Stderr.line", StrInterpolation "\"Error fetching URL " "url" "\""] "<p>This line will run if the <code>Http.get</code> request from earlier encountered an HTTP error.</p><p>It handles the error by printing an error message to <a href=\"https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)\">stderr</a>.</p><p>The <code>_</code> is where more information about the error is stored in the <code>HttpErr</code>. If we wanted to print more detail about what the error was, we’d name that something other than <code>_</code> and actually use it.</p>",
|
||||
Desc [Literal "HttpErr", Ident "url", Kw "_", Kw "->", Ident "Stderr.line", StrInterpolation "\"Error fetching URL " "url" "\""] "<p>This line will run if the <code>Http.get</code> request from earlier encountered an HTTP error.</p><p>It handles the error by printing an error message to <a href=\"https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)\">stderr</a>.</p><p>The <code>_</code> is where more information about the error is stored in the <code>HttpErr</code>. If we wanted to print more detail about what the error was, we'd name that something other than <code>_</code> and actually use it.</p>",
|
||||
Newline,
|
||||
Desc [Literal "FileReadErr", Ident "path", Kw "_", Kw "->", Ident "Stderr.line", StrInterpolation "\"Error reading from " "Path.display path" "\""] "<p>This line will run if the <code>File.readUtf8</code> from earlier encountered a file I/O error.</p><p>It handles the error by printing an error message to <a href=\"https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)\">stderr</a>.</p><p>The <code>_</code> is where more information about the error is stored in the <code>FileReadErr</code>. If we wanted to print more detail about what the error was, we’d name that something other than <code>_</code> and actually use it.</p>",
|
||||
Desc [Literal "FileReadErr", Ident "path", Kw "_", Kw "->", Ident "Stderr.line", StrInterpolation "\"Error reading from " "Path.display path" "\""] "<p>This line will run if the <code>File.readUtf8</code> from earlier encountered a file I/O error.</p><p>It handles the error by printing an error message to <a href=\"https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)\">stderr</a>.</p><p>The <code>_</code> is where more information about the error is stored in the <code>FileReadErr</code>. If we wanted to print more detail about what the error was, we'd name that something other than <code>_</code> and actually use it.</p>",
|
||||
Newline,
|
||||
Desc [Literal "FileWriteErr", Ident "path", Kw "_", Kw "->", Ident "Stderr.line", StrInterpolation "\"Error writing to " "Path.display path" "\""] "<p>This line will run if the <code>File.writeUtf8</code> from earlier encountered a file I/O error.</p><p>It handles the error by printing an error message to <a href=\"https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)\">stderr</a>.</p><p>The <code>_</code> is where more information about the error is stored in the <code>FileWriteErr</code>. If we wanted to print more detail about what the error was, we’d name that something other than <code>_</code> and actually use it.</p>",
|
||||
Desc [Literal "FileWriteErr", Ident "path", Kw "_", Kw "->", Ident "Stderr.line", StrInterpolation "\"Error writing to " "Path.display path" "\""] "<p>This line will run if the <code>File.writeUtf8</code> from earlier encountered a file I/O error.</p><p>It handles the error by printing an error message to <a href=\"https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)\">stderr</a>.</p><p>The <code>_</code> is where more information about the error is stored in the <code>FileWriteErr</code>. If we wanted to print more detail about what the error was, we'd name that something other than <code>_</code> and actually use it.</p>",
|
||||
]
|
||||
|
||||
div [role "presentation"] [
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
We love it when new people stop by and introduce themselves in [`#introductions`](https://roc.zulipchat.com/#narrow/stream/387892-introductions) so others can welcome you to the community!
|
||||
|
||||
The Roc Online Meetup meets about once per month. The organizer posts a [when2meet](https://when2meet.com) for the next month's meetup in [`#gatherings` on Zulip](https://roc.zulipchat.com/#narrow/stream/303057-gatherings), so we can find the best time that works for everyone
|
||||
who's interested in attending. The organizer then posts a finalized time and a link to where people can join. They usually last between 1-2 hours, and consist of some casual show-and-tell presentations followed by conversation. They’re fun!
|
||||
who's interested in attending. The organizer then posts a finalized time and a link to where people can join. They usually last between 1-2 hours, and consist of some casual show-and-tell presentations followed by conversation. They're fun!
|
||||
|
||||
We have not had a Roc conference yet, although there have been a few Roc talks given at conferences,
|
||||
and a few times when Roc community members have met up in person.
|
||||
@ -35,4 +35,4 @@ A written proposal isn't always necessary (for example, it may be deemed a simpl
|
||||
|
||||
There's no guarantee that a proposal will be accepted, and even if it is, there's no guarantee that something won't come up during implementation that changes the tradeoffs and means it doesn't end up making it into the language after all. But if it is accepted (again, doesn't have to be by the [BDFN](/bdfn) - although the BDFN does have final say if there's a disagreement at some point), that means a [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) should be reviewed, and the general understanding is that the PR will be accepted unless some problem is discovered during implementation that wasn't anticipated at the proposal stage.
|
||||
|
||||
This is the process we’re using for now, but of course it may change in the future!
|
||||
This is the process we're using for now, but of course it may change in the future!
|
||||
|
||||
@ -1,17 +1,13 @@
|
||||
# Documentation
|
||||
|
||||
Builtin Package - [docs](https://www.roc-lang.org/builtins)
|
||||
- [Builtins](https://www.roc-lang.org/builtins) - docs for modules built into the language—`Str`, `Num`, etc.
|
||||
- basic-webserver - a platform for making Web servers ([source code](https://github.com/roc-lang/basic-webserver))
|
||||
- [basic-cli](https://www.roc-lang.org/packages/basic-cli) - a platform for making command-line interfaces ([source code](https://github.com/roc-lang/basic-cli))
|
||||
|
||||
Basic-CLI Platform - [repo](https://github.com/roc-lang/basic-cli) - [docs](https://www.roc-lang.org/packages/basic-cli)
|
||||
|
||||
## Guides
|
||||
|
||||
[Frequently Asked Questions](https://github.com/roc-lang/roc/blob/main/FAQ.md)
|
||||
|
||||
[Roc for Elm Programmers](https://github.com/roc-lang/roc/blob/main/roc-for-elm-programmers.md)
|
||||
|
||||
## Language Reference
|
||||
|
||||
<!-- TODO Develop a Short language reference, move stuff out of tutorial e.g. de-sugaring table, keywords -->
|
||||
In the future, a language reference will be on this page too.
|
||||
|
||||
## [Guides](#guides) {#guides}
|
||||
|
||||
- [FAQ (Frequently Asked Questions)](https://github.com/roc-lang/roc/blob/main/FAQ.md)
|
||||
- [Roc for Elm Programmers](https://github.com/roc-lang/roc/blob/main/roc-for-elm-programmers.md)
|
||||
- [Tutorial](/tutorial)
|
||||
|
||||
@ -2,12 +2,12 @@
|
||||
|
||||
We are a small group trying to do big things, and we are grateful for every donation! Right now we are trying to raise $4,000 USD/month in donations to fund one longtime Roc contributor to continue his work on Roc full-time.
|
||||
|
||||
You can donate to Roc’s development using:
|
||||
You can donate to Roc's development using:
|
||||
- [GitHub Sponsors](https://github.com/sponsors/roc-lang)
|
||||
- [Liberapay](https://liberapay.com/roc_lang)
|
||||
|
||||
All donations go through the [Roc Programming Language Foundation](https://foundation.roc-lang.org/), a registered [US 501(c)(3) nonprofit organization](https://en.wikipedia.org/wiki/501(c)(3)_organization), which means these donations are tax-exempt in the US.
|
||||
|
||||
It also means that the foundation’s tax filings are a [matter of public record](https://en.wikipedia.org/wiki/501(c)(3)_organization#Transparency), so you have real transparency into how your donations are advancing Roc!
|
||||
It also means that the foundation's tax filings are a [matter of public record](https://en.wikipedia.org/wiki/501(c)(3)_organization#Transparency), so you have real transparency into how your donations are advancing Roc!
|
||||
|
||||
If you would like your organization to become an official sponsor of Roc's development, please [DM Richard Feldman on Zulip](https://roc.zulipchat.com/#narrow/pm-with/281383-user281383). We’d love to talk to you!
|
||||
If you would like your organization to become an official sponsor of Roc's development, please [DM Richard Feldman on Zulip](https://roc.zulipchat.com/#narrow/pm-with/281383-user281383). We'd love to talk to you!
|
||||
|
||||
@ -4,7 +4,7 @@ Roc code is designed to build fast and run fast...but what does "fast" mean here
|
||||
|
||||
## [Fast programs](#fast-programs) {#fast-programs}
|
||||
|
||||
What "fast" means in embedded systems is different from what it means in games, which in turn is different from what it means on the Web. To better understand Roc’s performance capabilities, let's look at the upper bound of how fast optimized Roc programs are capable of running, and the lower bound of what types of languages Roc should generally outperform.
|
||||
What "fast" means in embedded systems is different from what it means in games, which in turn is different from what it means on the Web. To better understand Roc's performance capabilities, let's look at the upper bound of how fast optimized Roc programs are capable of running, and the lower bound of what types of languages Roc should generally outperform.
|
||||
|
||||
### [Limiting factors: memory management and async I/O](#limiting-factors) {#limiting-factors}
|
||||
|
||||
@ -22,21 +22,21 @@ When [benchmarking compiled Roc programs](https://www.youtube.com/watch?v=vzfy4E
|
||||
|
||||
### [Domain-specific memory management](#domain-specific-memory-management) {#domain-specific-memory-management}
|
||||
|
||||
Roc’s “platforms and applications” design means its automatic memory management can take advantage of domain-specific properties to improve performance.
|
||||
Roc's "platforms and applications" design means its automatic memory management can take advantage of domain-specific properties to improve performance.
|
||||
|
||||
For example, if you build an application on the [`basic-cli` platform](https://github.com/roc-lang/basic-cli) compared to the [`basic-webserver` platform](https://github.com/roc-lang/basic-webserver), each of those platforms may use a different memory management strategy under the hood that’s tailored to their respective use cases. Your application's performance can benefit from this, even though building on either of those platforms feels like using ordinary automatic memory management.
|
||||
For example, if you build an application on the [`basic-cli` platform](https://github.com/roc-lang/basic-cli) compared to the [`basic-webserver` platform](https://github.com/roc-lang/basic-webserver), each of those platforms may use a different memory management strategy under the hood that's tailored to their respective use cases. Your application's performance can benefit from this, even though building on either of those platforms feels like using ordinary automatic memory management.
|
||||
|
||||
This is because Roc _platforms_ get to determine how memory gets allocated and deallocated in applications built on them. ([`basic-cli`](https://github.com/roc-lang/basic-cli) and [`basic-webserver`](https://github.com/roc-lang/basic-webserver) are examples of platforms, but anyone can build their own platform.) Here are some examples of how platforms can use this to improve application performance:
|
||||
|
||||
- A platform for noninteractive command-line scripts can skip deallocations altogether, since any allocated memory will be cheaply reclaimed by the operating system anyway once the script exits. (This strategy is domain-specific; it would not work well for a long-running, interactive program!)
|
||||
- A platform for Web servers can put all allocations for each request into a particular [region of memory](https://en.wikipedia.org/wiki/Region-based_memory_management) (this is known as “arena allocation” or ”bump allocation”) and then deallocate the entire region in one cheap operation after the response has been sent. This would essentially drop memory reclamation times to zero. (This strategy relies on Web servers’ request/response architecture, and wouldn't make sense in other use cases. [`nea`](https://github.com/tweedegolf/nea) is a platform in early development that is working towards implementing this.)
|
||||
- A platform for Web servers can put all allocations for each request into a particular [region of memory](https://en.wikipedia.org/wiki/Region-based_memory_management) (this is known as "arena allocation" or "bump allocation") and then deallocate the entire region in one cheap operation after the response has been sent. This would essentially drop memory reclamation times to zero. (This strategy relies on Web servers' request/response architecture, and wouldn't make sense in other use cases. [`nea`](https://github.com/tweedegolf/nea) is a platform in early development that is working towards implementing this.)
|
||||
- A platform for applications that have very long-lived state could implement [meshing compaction](https://youtu.be/c1UBJbfR-H0?si=D9Gp0cdpjZ_Is5v8) to decrease memory fragmentation. (Compaction would probably be a net negative for performance in the previous two examples.)
|
||||
|
||||
[This talk](https://www.youtube.com/watch?v=cpQwtwVKAfU&t=75s) has more information about platforms and applications, including demos and examples of other benefits they unlock besides performance.
|
||||
|
||||
### [Current progress](#current-progress) {#current-progress}
|
||||
|
||||
Roc's “platforms and applications” design already works, including the domain-specific memory management. Most of Roc’s data structures are already close to their theoretical limit in terms of performance, at least without changing their behavior or introducing memory unsafety. [This talk](https://vimeo.com/653510682) explains how they’re implemented under the hood.
|
||||
Roc's "platforms and applications" design already works, including the domain-specific memory management. Most of Roc's data structures are already close to their theoretical limit in terms of performance, at least without changing their behavior or introducing memory unsafety. [This talk](https://vimeo.com/653510682) explains how they're implemented under the hood.
|
||||
|
||||
That said, [the current implementation](https://ayazhafiz.com/articles/23/a-lambda-calculus-with-coroutines-and-heapless-closures) of [defunctionalization](https://blog.sigplan.org/2019/12/30/defunctionalization-everybody-does-it-nobody-talks-about-it/) (based on [this paper](https://dl.acm.org/doi/pdf/10.1145/3591260))—which unlocks stack-allocated closures, among other optimizations—has [significant known gaps](https://github.com/roc-lang/roc/issues/5969), and has a ways to go before it works across the board. (If you're interested in getting involved in that implementation, [we'd love to hear from you](https://roc.zulipchat.com)!)
|
||||
|
||||
|
||||
@ -50,7 +50,7 @@ When dealing with [serialized data](https://en.wikipedia.org/wiki/Serialization)
|
||||
|
||||
A technique used in some popular languages today is to decode without validation. For example, some languages parse [JSON](https://www.json.org) using a function whose return type is unchecked at compile time (commonly called an `any` type). This technique has a low up-front cost, because it does not require specifying the expected shape of the JSON data.
|
||||
|
||||
Unfortunately, if there’s any mismatch between the way that returned value ends up being used and the runtime shape of the JSON, it can result in errors that are time-consuming to debug because they are distant from (and may appear unrelated to) the JSON decoding where the problem originated. Since Roc has a [sound type system](https://en.wikipedia.org/wiki/Type_safety), it does not have an `any` type, and cannot support this technique.
|
||||
Unfortunately, if there's any mismatch between the way that returned value ends up being used and the runtime shape of the JSON, it can result in errors that are time-consuming to debug because they are distant from (and may appear unrelated to) the JSON decoding where the problem originated. Since Roc has a [sound type system](https://en.wikipedia.org/wiki/Type_safety), it does not have an `any` type, and cannot support this technique.
|
||||
|
||||
Another technique is to validate the serialized data against a schema specified at compile time, and give an error during decoding if the data doesn't match this schema. Serialization formats like [protocol buffers](https://protobuf.dev/) require this approach, but some languages encourage (or require) doing it for _all_ serialized data formats, which prevents decoding errors from propagating throughout the program and causing distant errors. Roc supports and encourages using this technique.
|
||||
|
||||
|
||||
@ -23,9 +23,9 @@ Roc has ways of detecting uniqueness at compile time, so this optimization will
|
||||
|
||||
## [Everything is immutable (semantically)](#everything-is-immutable) {#everything-is-immutable}
|
||||
|
||||
Since mutation is only ever done when it wouldn’t change the behavior of the program, all Roc values are semantically immutable—even though they can still benefit from the performance of in-place mutation.
|
||||
Since mutation is only ever done when it wouldn't change the behavior of the program, all Roc values are semantically immutable—even though they can still benefit from the performance of in-place mutation.
|
||||
|
||||
In many languages, this is reversed; everything is mutable by default, and it's up to the programmer to “defensively” clone to avoid undesirable modification. Roc's approach means that cloning happens automatically, which can be less error-prone than defensive cloning (which might be forgotten), but <span class="nowrap">which—to be fair—can</span> also increase unintentional cloning. It's a different default with different tradeoffs.
|
||||
In many languages, this is reversed; everything is mutable by default, and it's up to the programmer to "defensively" clone to avoid undesirable modification. Roc's approach means that cloning happens automatically, which can be less error-prone than defensive cloning (which might be forgotten), but <span class="nowrap">which—to be fair—can</span> also increase unintentional cloning. It's a different default with different tradeoffs.
|
||||
|
||||
A reliability benefit of semantic immutability everywhere is that it rules out [data races](https://en.wikipedia.org/wiki/Race_condition#Data_race). These concurrency bugs can be difficult to reproduce and time-consuming to debug, and they are only possible through direct mutation. Roc's semantic immutability rules out this category of bugs.
|
||||
|
||||
|
||||
@ -21,7 +21,7 @@
|
||||
<div role="presentation" class="home-goals-column">
|
||||
<a href="/wip/friendly" class="home-goals-content">
|
||||
<h3 class="home-goals-title">Friendly</h3>
|
||||
<p class="home-goals-description">Roc’s syntax, semantics, and included toolset all prioritize user-friendliness.</p>
|
||||
<p class="home-goals-description">Roc's syntax, semantics, and included toolset all prioritize user-friendliness.</p>
|
||||
<p class="home-goals-learn-more">What does <i>friendly</i> mean here?</p>
|
||||
</a>
|
||||
</div>
|
||||
@ -29,7 +29,7 @@
|
||||
<a href="/wip/functional" class="home-goals-content">
|
||||
<h3 class="home-goals-title">Functional</h3>
|
||||
<p class="home-goals-description">
|
||||
Roc has a small number of simple language primitives. It’s a single-paradigm <span class="nowrap">functional language.</span></p>
|
||||
Roc has a small number of simple language primitives. It's a single-paradigm <span class="nowrap">functional language.</span></p>
|
||||
<p class="home-goals-learn-more">What does <i>functional</i> mean here?</p>
|
||||
</a>
|
||||
</div>
|
||||
@ -62,9 +62,9 @@
|
||||
|
||||
## [Examples](#examples) {#examples}
|
||||
|
||||
Roc is a young language. It doesn’t even have a numbered release yet, just nightly builds!
|
||||
Roc is a young language. It doesn't even have a numbered release yet, just nightly builds!
|
||||
|
||||
However, it can already be used for several things if you’re up for being an early adopter—<br>
|
||||
However, it can already be used for several things if you're up for being an early adopter—<br>
|
||||
with all the bugs and missing features which come with that territory.
|
||||
|
||||
Here are some examples of how it can be used today.
|
||||
@ -76,7 +76,7 @@ Here are some examples of how it can be used today.
|
||||
Stdout<span class="punctuation section">.</span>line <span class="literal">"Hello!"</span></samp></pre>
|
||||
<p>You can use Roc to create scripts and command-line interfaces (CLIs). The compiler produces binary executables, so Roc programs can run on devices that don't have Roc itself installed.</p>
|
||||
<p>As an example, the HTML for this website is generated using a simple Roc script. You can see <a href="https://github.com/roc-lang/roc/blob/main/www/wip_new_website/main.roc">the code for it</a> in the main Roc code repository.</p>
|
||||
<p>If you’re looking for a starting point for building a command-line program in Roc, <a href="https://github.com/roc-lang/basic-cli">basic-cli</a> is a popular platform to check out.</p>
|
||||
<p>If you're looking for a starting point for building a command-line program in Roc, <a href="https://github.com/roc-lang/basic-cli">basic-cli</a> is a popular platform to check out.</p>
|
||||
</div>
|
||||
<div role="presentation" class="home-examples-column">
|
||||
<h3 class="home-examples-title">Web Servers</h3>
|
||||
@ -93,7 +93,7 @@ Here are some examples of how it can be used today.
|
||||
log(<span class="string">`Roc says </span><span class="kw">${</span>fn()<span class="kw">}</span><span class="string">`</span>)<span class="kw">;</span></samp></pre>
|
||||
<p>You can call Roc functions from other languages. There are several <a href="https://github.com/roc-lang/roc/tree/main/examples">basic examples</a> of how to call Roc functions from Python, Node.js, Swift, WebAssembly, and JVM languages.</p>
|
||||
<p>Any language that supports C interop can call Roc functions, using similar techniques to the ones found in these examples.</p>
|
||||
<p>Most of those are minimal proofs of concept, but <a href="https://github.com/vendrinc/roc-esbuild">roc-esbuild</a> is a work in progress that’s used at <a href="https://www.vendr.com/careers">Vendr</a> to call Roc functions from Node.js.</p>
|
||||
<p>Most of those are minimal proofs of concept, but <a href="https://github.com/vendrinc/roc-esbuild">roc-esbuild</a> is a work in progress that's used at <a href="https://www.vendr.com/careers">Vendr</a> to call Roc functions from Node.js.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@ -104,7 +104,7 @@ You can find more use cases and examples on the [examples page](/wip/examples)!
|
||||
|
||||
## [Code Sample with Explanations](#code-sample) {#code-sample}
|
||||
|
||||
Here’s a code sample that shows a few different aspects of Roc:
|
||||
Here's a code sample that shows a few different aspects of Roc:
|
||||
* File I/O and HTTP requests
|
||||
* Pattern matching for error handling
|
||||
* JSON deserialization via type inference
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Install Roc
|
||||
# Install
|
||||
|
||||
Roc is a very young language with many incomplete features and known bugs. It doesn't even have a numbered release yet, but it does have [nightly builds](https://github.com/roc-lang/roc/releases) that you can download if you’d like to try it out without [building from source](https://github.com/roc-lang/roc/blob/main/BUILDING_FROM_SOURCE.md)!
|
||||
Roc is a very young language with many incomplete features and known bugs. It doesn't even have a numbered release yet, but it does have [nightly builds](https://github.com/roc-lang/roc/releases) that you can download if you'd like to try it out without [building from source](https://github.com/roc-lang/roc/blob/main/BUILDING_FROM_SOURCE.md)!
|
||||
|
||||
There are currently a few known OS-specific issues:
|
||||
* **macOS:** There are no known compatibility issues, but the compiler doesn't run as fast as it does on Linux or Windows, because we don't (yet) do our own linking like we do on those targets. (Linking works similarly on Linux and Windows, but the way macOS does it is both different and significantly more complicated.)
|
||||
|
||||
@ -31,7 +31,7 @@ Let's start by getting acquainted with Roc's [_Read-Eval-Print-Loop_](https://en
|
||||
|
||||
If Roc is [installed](/wip/install.html), you should see this:
|
||||
|
||||
<pre><samp>The rockin’ roc repl</samp></pre>
|
||||
<pre><samp>The rockin' roc repl</samp></pre>
|
||||
|
||||
So far, so good!
|
||||
|
||||
|
||||
@ -44,7 +44,7 @@ const repl = {
|
||||
},
|
||||
{
|
||||
match: (input) => input.match(/^["][^\\]+\\\(name\)/i),
|
||||
show: `<p>Nicely done! This is an example of <a href=\"/tutorial#string-interpolation\">string interpolation</a>, which replaces part of a string with whatever you put inside the parentheses after a <code>\\</code>.</p><p>Now that you’ve written a few <a href=\"/tutorial#naming-things\">expressions</a>, you can either continue exploring in this REPL, or move on to the <a href=\"/tutorial\">tutorial</a> to learn how to make full programs.<p><p><span class='welcome-to-roc'>Welcome to Roc!</span> <a href='/tutorial' class='btn-small'>${tutorialButtonSvg} Start Tutorial</a></p>`,
|
||||
show: `<p>Nicely done! This is an example of <a href=\"/tutorial#string-interpolation\">string interpolation</a>, which replaces part of a string with whatever you put inside the parentheses after a <code>\\</code>.</p><p>Now that you've written a few <a href=\"/tutorial#naming-things\">expressions</a>, you can either continue exploring in this REPL, or move on to the <a href=\"/tutorial\">tutorial</a> to learn how to make full programs.<p><p><span class='welcome-to-roc'>Welcome to Roc!</span> <a href='/tutorial' class='btn-small'>${tutorialButtonSvg} Start Tutorial</a></p>`,
|
||||
},
|
||||
],
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user