🏡 Gleam's website and guide
Home Page: https://gleam.run
License: Apache License 2.0
Install github-pages (requires Ruby)
gem install github-pages
gem install webrick # For Ruby3.xand run make serve in root directory.
👋 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.
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.
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.
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.
Including deploying to Heroku at the end
On this page https://gleam.run/getting-started/installing/#gitpod-online-gleam-development-environment
Clicking "Gitpod" opens gitpod but the gitpod does not initialize:
{
sudo -E /app/bob build
}; exit
79a75819-3250-40ae-9f97-59a6ec751fe5:/workspace$ {
> sudo -E /app/bob build
> }; exit
{"file":"builder.go:226","func":"StartBuildkit","level":"debug","message":"buildkitd started","serviceContext":{"service":"bob","version":""},"severity":"DEBUG","stderr":"/tmp/buildkitd_stderr323233791","stdout":"/tmp/buildkitd_stdout1426380294","time":"2023-03-10T05:04:59.137305281Z"}
{"attempt":0,"file":"builder.go:262","func":"connectToBuildkitd","level":"debug","message":"attempting to connect to buildkitd","serviceContext":{"service":"bob","version":""},"severity":"DEBUG","time":"2023-03-10T05:04:59.137483521Z"}
{"attempt":1,"file":"builder.go:262","func":"connectToBuildkitd","level":"debug","message":"attempting to connect to buildkitd","serviceContext":{"service":"bob","version":""},"severity":"DEBUG","time":"2023-03-10T05:05:00.139048904Z"}
{"file":"export.go:69","func":"Info","level":"info","message":"building base image","serviceContext":{"service":"bob","version":""},"severity":"INFO","time":"2023-03-10T05:05:00.153997241Z"}
{"file":"export.go:69","func":"Info","level":"info","message":"waiting for build context","serviceContext":{"service":"bob","version":""},"severity":"INFO","time":"2023-03-10T05:05:00.154073931Z"}
#1 [internal] load build definition from .gitpod.Dockerfile
#1 transferring dockerfile:
#1 transferring dockerfile: 387B done
#1 DONE 0.2s
#2 [internal] load .dockerignore
#2 transferring context: 2B done
#2 DONE 0.2s
#3 [internal] load metadata for ghcr.io/gleam-lang/gleam-compiler-ci-test/gleam:107.0.0-elixir
#3 ERROR: failed to authorize: failed to fetch anonymous token: unexpected status: 403 Forbidden
------
> [internal] load metadata for ghcr.io/gleam-lang/gleam-compiler-ci-test/gleam:107.0.0-elixir:
------
.gitpod.Dockerfile:1
--------------------
1 | >>> FROM ghcr.io/gleam-lang/gleam-compiler-ci-test/gleam:107.0.0-elixir
2 |
3 | USER root
--------------------
error: failed to solve: ghcr.io/gleam-lang/gleam-compiler-ci-test/gleam:107.0.0-elixir: failed to authorize: failed to fetch anonymous token: unexpected status: 403 Forbidden
{"@type":"type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent","command":"build","error":"exit status 1","file":"build.go:44","func":"func1","level":"error","message":"build failed","serviceContext":{"service":"bob","version":""},"severity":"ERROR","time":"2023-03-10T05:05:00.758092058Z"}
exit
headless task failed: exit status 1
The links at the bottom of the page cause it to have bigger width. Screenshot:
Encountered on Samsung Internet on Android
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.
https://gleam.run/book/tour/custom-types.html#erlang-interop
(... or Elixir or TypeScript)
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.
Installation page on mobile is broken like screenshot show:
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
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:
This page is missing the new commands: https://gleam.run/writing-gleam/command-line-reference/
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?
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!
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 …..
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):
checkcleanhelpupdateOn this page: https://gleam.run/getting-started/installing/#installing-gleam
There is a link to AUR page: https://aur.archlinux.org/gleam.git
However the page on AUR does not exists.
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.
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
Some chapters in the book about types have obvious counterparts in the stdlib. It would be nice to provide a link for diving deeper into how the stdlib can be utilised when working with these types.
For example the chapter on Result already have a paragraph mentioning the stdlib so it would be easy to add something like this:
The standard library gleam/result module contains helpful functions for
working with theResulttype, make good use of them!Stdlib references
The exact format can be discussed but if would be nice if it was somewhat consistent through the book.
Some other chapters that could get a link to stdlib are:
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 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:
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.
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
now it should be
https://github.com/gleam-lang/vscode-gleam
Page is https://gleam.run/ , browser is Firefox for Android. There are just too many sponsors! 😄
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.
Elixir:
Erlang:
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)
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!")
})
}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.
options:
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.
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.
React
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
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
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.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.