gleam-lang / website Goto Github PK
View Code? Open in Web Editor NEW🏡 Gleam's website and guide
Home Page: https://gleam.run
License: Apache License 2.0
🏡 Gleam's website and guide
Home Page: https://gleam.run
License: Apache License 2.0
At the moment, the website says:
so all Gleam programs are as blazingly fast as their Erlang counterpart.
This reads to me as a rather misleading claim. On the first reading of that whole paragraph, l thought “this is all completely wrong”, on a second, more careful reading, I though “OK, technically this is all correct, but you need to have a deep knowledge of beam to understand what’s claimed exactly”.
The problem here is that, when people speak about unqualified performance, they usually have in mind CPU efficiency. Erlang is generally as blazingly fast as Python, which is to say, not really fast at all.
While Erlang wouldn’t be the speed champ at Fibonacci calculations or 3D rendering, it does have two performance super-powers:
So, I suggest to more clearly express what gleam performance is and is not about, such that one can’t misunderstand the claim even if one doesn’t have pre-existing Erlang knowledge. So, something along the lines of:
While Erlang’s virtual machine, BEAM, isn’t particularly efficient for CPU-bound computations, it excels for building highly concurrent, low-latency network applications and web servers, as exemplified by …..
I found out that BitString
just works without importing so I was looking for resources as to what types or functions should work out of the box and I couldn't find any documentation. I only found the source code
Including deploying to Heroku at the end
I'm not sure whether I'm the only one who had issues with this (see: gleam-lang/gleam#1817), but it might be worth adding a notice in the Windows installation instructions.
I am not sure if it's an actual hassle, so feel free to close this.
I saw that after merging PRs with small tweaks to the documents src, @lpil has to push a follow-up commit with regenerated website changes.
Maybe GitHub Actions could be used to automatically re-generate the website when there were changes? A common pattern I saw is: the main repo branch holds just the page source, and a gh-pages branch holds just the output.
Case expressions - Destructuring in the example:
Pattern matching also works in let
bindings, though patterns that do not
match all instances of that type may result in a runtime error.
let [a] = [1] // a is 1
let [b] = [1, 2] // Runtime error! The pattern has 1 element but the value has 2
I think the comment should be // Compile-time error! The pattern has 1 element but the value has 2
In the style of https://gleam.run/cheatsheets/gleam-for-elixir-users/
In https://github.com/gleam-lang/website/blob/master/src/getting-started/creating-a-project.md
We create a project that has hello_world()
Then there is no instruction on how to run that.
Doing rebar3 shell
just throws me into a repl with no indication of what to do.
Would be great if the steps to run hello_world()
would be there.
Thanks
Sebastian
As the title, there is an "Editor plugins" link in the table of contents but it doesn't link anywhere. I would offer a fix but I'm not sure if the content exists somewhere to be linked to or if it is best removed for the moment.
Python 3.10 was still in alpha when the case
section on the Gleam for Python users cheatsheet was last updated. However, 3.10 was released ~7mo ago, so that section is not completely up-to-date.
Referencing features already in stable versions as not yet released can confuse readers. I'm willing to update the section if needed!
options:
Elm has some guidelines on library design that are very useful and informative: https://package.elm-lang.org/help/design-guidelines
It would be great to have something similar for Gleam on the website.
We should also include step by step information on how to publish packages and documentation, along with conventions for git tags etc.
At https://gleam.run/writing-gleam/command-line-reference/, e.g. publish is h3
, deps-list is h2
.
The reference is also missing (maybe not all are relevant):
check
clean
help
update
In the style of https://gleam.run/cheatsheets/gleam-for-elixir-users/
Page is https://gleam.run/ , browser is Firefox for Android. There are just too many sponsors! 😄
This issue describes a problem I ran into while attempting to install Erlang on Ubuntu (on WSL): elixir-lang/elixir-lang.github.com#1575
Specifically, Erlang's PPA (their hosted source for Debian/Ubuntu packages) appears to be broken, at least for Ubuntu 22.04 (Jammy).
Since Gleam's installation instructions recommend using the PPA, it might be preferable to recommend a different approach. Unfortunately, I'm not sure what the most straightforward/correct path would actually be, though I did add a comment on the Elixir issue thread describing my installation approach (downloading the .deb
file directly and installing with apt
).
opening this discussion
some guys documenting the move lang in multiple langs using mdbook choose this as solution
https://github.com/funkill/mdbook-i18n
original thread: rust-lang/mdBook#5
other options?
On the gleam for elixir users page under Operators, the escape characters are shown, so ||
displays as \|\|
. On the Erlang cheat sheet the issue isn't present, however the | character looks huge, unlike the rest of them.
In this section (https://gleam.run/tour/functions.html#pipe-operator), the doc refers to the pipe operator as being the same as in "Elixir of F#".
This is misleading!
While in Elixir the pipe acts as the first parameter of the piped-into function, in F# it's the other way around, and it is the last parameter.
This needs to be clarified explicitly.
We can't assume it is Elixir-like, i.e. first, since Gleam is its own language.
As in the issue name, the whole 3rd section in the book is blank. However, the details are present on the documentation site itself.
For example:
Chapter 13 (Custom types) has a brief section on destructuring in pattern matching to extract values from a record, but does not tell you that you can use the spread syntax ..
to ignore fields you don't care about! It would be great to expand that section to include this info so newcomers don't run into Incorrect arity
errors if they omit fields in their pattern matching.
I just added some information for the new clause guards and ran make build
and it updated the entire book, I'm guessing because I've got a different version of mdbook (v0.3.7). Is there a specific version I should use?
https://gleam.run/book/tour/custom-types.html#erlang-interop
(... or Elixir or TypeScript)
The use of highlight.js has some issues:
My suggestion is to render syntax highlighting at build time and include the syntax highlighting CSS into the base style sheet. This would mean the syntax highlighting step would be executed once and it would be static. Built static, this eliminates the need for JavaScript for the basic documentation, does not require consenting to third-party CDN and security risks involved with it, saves people's CPUs+batteries+data plans, and would increase render performance.
I noticed this in the cli reference when I visited on my phone (here emulated in Chrome):
The culprit in this case seems to be the following <code>
block:
This behavior is caused by white-space: nowrap;
. A fix would be to use a block-element like <pre>
or style the wrapping differently (e.g. white-space: normal
or white-space: pre-line
) on this one.
Additionally, we could consider a block element with overflow-x: auto
. This presents a scrollable code-block on screens that lack horizontal space.
This page is missing the new commands: https://gleam.run/writing-gleam/command-line-reference/
I went over the gleam book / language tour, and started a little project.
This issue bit me for some good 30 minutes.
Can we improve the documentation? Maybe a mention to this on https://gleam.run/book/tour/ints-and-floats.html?
Helpful error messages would be great, but even a helpful note on the language tour would have saved me here.
now it should be
https://github.com/gleam-lang/vscode-gleam
When copying first snippet from https://gleam.run/book/tour/constants.html , I got:
$ gleam build
error: Syntax error
┌─ /home/michal/projects/gleam-realworld-example-app/src/conduit.gleam:15:23
│
15 │ pub const start_year: = 2101
│ ^ Unexpected token
Expected one of "fn(", "tuple", r#"[A-Z][0-9A-Za-z]*"#, r#"[a-z][0-9a-z_]*"#, r#"_([a-z][0-9a-z_]*)?"#
(gleam 0.12.0-rc3)
Maybe it's better to add a demo repo link. When I try this code at first time, I don't know what dependencies should be added.
like this:
Here are my demos:
https://github.com/zhenfeng-zhu/basic_web_server
https://github.com/zhenfeng-zhu/multi_threaded_helloworld
https://github.com/zhenfeng-zhu/helloworld
https://gleam.run/book/tour/constants.html
When a constant is referenced the value is inlined by the compiler
This is true for Erlang, but not for JavaScript, and it would probably make more sense to update this documentation than the change the JavaScript generation, because there are actually a lot of reasons why JavaScript constant inlining would be bad.
We've been talking a lot about the website the last few days, and I have some thoughts that I want to collect into this issue for initial discussion, rather than just jumping straight in and creating a dozen different ones.
Things to mention on the front page:
Things to use to build it:
When learning Gleam I was quite confused about how to make a Struct / Record
I couldn't find this at a glance in the website. Only after reading the changelog I understood that a record is just a Custom Type with one variant.
Would you include a chapter about Records
just after Custom types
?
It will just explain this, give an example and show how to access fields.
I could make a PR if so.
👋 Hello!
I've been interested in Gleam for a while and would like to keep myself in the loop around new releases. My normal way to do that would be by subsribing to the RSS feed for news.
However, there is no RSS feed there 😢 Would you be happy to have one? I think there is a plugin for GitHub pages that generates one... I'd be happy to PR if this seems like a good idea.
A list of features with code snippets on the website would be very handy. Here's a draft for the content:
The power of typed functional programming with the performance and reliability of the Erlang VM, all wrapped up in a familiar modern syntax.
import gleam/io
pub fn main() {
io.println("Hello, world!")
}
No nulls, no exceptions, clear error messages, and a practical type system. Whether you're writing new code or maintaining old code Gleam is designed to make your job as fun and stress-free as possible.
error: Unknown record field
┌─ ./src/app.gleam:8:16
│
8 │ user.alias
│ ^^^^^^^^^^ Did you mean `name`?
The value being accessed has this type:
User
It has these fields:
.name
With Gleam's custom types, generics, and pattern matching features it can implement your business logic precisely and clearly. We think it should always be clear to the reader what code is doing.
pub type Pet {
Cat
Dog
Other(name: String)
}
pub fn greet(pet) {
case pet {
Dog -> "Who's a good boy?"
Cat -> "What a little sweetie!"
Other(name) -> "Hello, " <> name
}
}
Gleam comes with compiler, build tool, formatter, editor integrations, and package manager all built in, so creating a gleam project is just running gleam new
.
Part of the wider BEAM ecosystem, Gleam programs can use the thousands of packages published Hex packages whether they are written in Gleam, Erlang, or Elixir
~/app $ gleam add gleam_json
Resolving versions
Downloading packages
Downloaded 2 packages in 0.01s
Added gleam_json v0.5.0
~/app $ gleam test
Compiling thoas
Compiling gleam_json
Compiling app
Compiled in 1.67s
Running app_test.main
.
1 tests, 0 failures
Running on the battle-tested Erlang virtual machine that powers planet scale systems such as WhatsApp and Ericcson, Gleam is ready for workloads of any size.
Thanks to a multi-core actor based concurrency system that can run millions of concurrent tasks, fast immutable data structures, and a concurrent garbage collector that never stops the world, your service can scale and stay lighting fast with ease.
pub fn main() {
// Run a million of threads, no problem
list.range(0, 1_000_000)
|> list.map(spawn_task)
|> list.each(task.await_forever)
}
fn spawn_task(i) {
task.async(fn() {
let n = int.to_string(i)
io.println("Hello from " <> n)
})
}
As well as running on the Erlang VM Gleam code can also compile to JavaScript. Reuse your existing backend code in the browser, on mobile devices, or anywhere else JavaScript can run.
pub fn main() {
try el = document.query_selector("button")
element.add_event_listener(el, fn() {
io.println("Button clicked!")
})
}
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.