gleam-lang / language-tour Goto Github PK

Proposal

When walking through the language tutorial, it would be nice to have a quick method to comment / uncomment code block for testing purposes.

From a quick scan through the code, I don't think this is currently implemented in the online editor yet. Would it be possible / make sense to insert // when user presses cmd + / for Mac and ctrl + / for Windows?

👁️ The current syntax highlighting theme in the code editor makes the text difficult to read on dark mode. I wanted to improve it, but we didn't have a candidate for the new theme.

Today I felt bored/curious, and things happened. I wrote a lil python script to collect colors from the biggest standardized colorscheme resource I know and draw some candidates. The script just takes as weighted list of colors and scores how close the colors in the theme are to the input colors. (also, it converts the colors HSLuv before scoring to keep results relevant to humans)

🎛️ I ran this with various weights/colors from our branding and here are my notes for the top results:

• base16-material-palenight happens to exactly use the "Underwater Blue" color as the background, so it's pretty much a drop-in replacement for the current dark code theme. Also, it could be adapted to use the Faff Pink and Unnamed Blue colors as it has very similar colors there.

• If we perhaps wanted to redesign the page a little bit and use a floating box for the code, like on the website instead of plain divider lines, base16-chalk is using the same Blacker color. It also features #f5f5f5 as the light mode background, which is the same background color for code on the docs sites
  

• base16-railscats has the most compatible grays

• base16-snazzy and base16-rebecca often appeared in the top results

• (honorable mention), base16-mellow-purple was the closest to Faff Pink 😉

👉 Let me know if it's any useful and what the next steps would be. I'm happy to share the script too but I doubt you'd find it as interesting as I did 😆

I cloned and built this repo, and was expecting to view the tour by opening public/index.html from the filesystem. However this does not work because all references are absolute instead of relative. E.g.

Is this by design, or can they be changed to relative references?

I noticed that syntax highlighting stops working on multiline strings:

It would be good for understanding how Gleam compiles code to be able to see then generated JS in the tour. In a similar way to how the ReScript and Melange playgrounds let you edit the code and then see the compiled result live.

Saying io.debug(<<3:unit(2)>>) leads to the error:

rror: Invalid bit array segment
   ┌─ /src/main.gleam:10:16
   │
10 │   io.debug(<<3:unit(2)>>)
   │                ^^^^^^^ This needs an explicit size

Hint: If you specify unit() you must also specify size().
See: https://gleam.run/book/tour/bit-arrays.html

But https://tour.gleam.run/data-types/bit-arrays/ doesn't say how to specify the size as well and every guess I have made for how to do that hasn't worked.

The code editor is completely blocked by the output pane on some pages, completely hiding the most important part of the lesson. This happens on pages with a long text and multiple output lines, like /basics/floats/.

While the files in src/content/ have en.htmls which can be translated to other languages. How should the hard coded lines in tour.gleam be translated?

Also some of the code examples contain code comments which should be translated as well. I think we can just rename the code.gleams to en.gleams and then any code which contains comments can be copied for the target language.

Brought up in https://gleam.run/news/v0.32-polishing-syntax-for-stability/ .

MSE has this "feature" that emulates Android's "elastic scrolling". It doesn't work with arrow-keys, only touch-screens and touch-pads (maybe even scroll-wheels?). This allows users to do silly stuff, like this:

This could (untested) be resolved by

/*
`class` doesn't matter,
all `<nav>`s should have this rule.
*/
nav {
  position: fixed;
  z-index: 8; /* is this high enough? */
}

Versions tested:

• Microsoft Edge 122
• Windows 11

Scroll down to see

• Result is built in verus Option and Dict are not
• the option and dict examples in the do not import the type but it is required if people reference it in their signatures and newbies stumble, the exercism has it https://exercism.org/tracks/gleam/concepts (buts the Dict concept could use a type example over there)
• if the tour grts to have a prelude chapter, maybe the exercism concepts can have almost the same?

For longer examples or when user pastes their own code and get and error or warning it would be helpful to be able to use the line number provided by the compiler.

For example from the first example on https://tour.gleam.run/basics/hello-world/:

import gleam/io

pub fn main() {
  io.println(4)
}

error: Type mismatch
  ┌─ /src/main.gleam:4:14
  │
4 │   io.println(4)
  │              ^

Expected type:

    String

Found type:

    Int

It’s difficult navigating some of the tour pages on mobile. Looks like maybe a CSS overflow issue, but I can’t debug at the moment because I’m on mobile :)

Low priority but when I’m back home I’ll investigate unless someone else wants to take a look.

In chapter 0 lesson 5, "basics/floats":

Unlike many languages Gleam does not have a NaN or Infinity float value.

But Gleam does seem to have an Infinity (and also -Infinity) and NaN float value:

  let inf = 3.0e500
  io.debug(inf) // prints "Infinity"
  io.debug(0.0 -. inf) // prints "-Infinity"
  
  let nan = inf /. inf
  io.debug(nan) // prints "NaN"
  
  io.debug(float.compare(nan, 3.0)) // all comparisons with NaN prints "Gt"?

I don't know enough Gleam to know what the lesson should say instead - but I think this misleading comment should be removed in any case.

This is my first evening with Gleam. Sorry if this is already known - I tried searching and couldn't find any previous discussions about this at least. :)

Make it so folks can nicely print the everything page nicely.

Context: gleam-lang/gleam#2622 (reply in thread)

Hi,

Currently the description in the Guards lesson of the tour says the following:

Only a limited set of operators can be used in guards, and functions cannot be called at all.

Source: https://tour.gleam.run/flow-control/guards/

Could (should) we list the supported operators or link to an external resource where there's an up-to-date list of them?

Cheers!

The page says "any number of other arguments passed to the inner function", but function captures are used for "creating anonymous functions that take one argument". It took me a bit of time to realize the "any number" meant you could provide any number of other arguments passed statically to the inner function.

As I'm still learning the language I'm not sure if the term "statically" is correct, but the lack of specificity at least threw me initially.

Hello! The language tour is lovely :). Possibly a small thing, one pattern I was not made familiar with trough the tour was this:
type Name(val) { Name(val) }

Might be nice to have it in there for completeness (assuming it was not on purpose). It would also explain the Result module part with Ok(1) Error(1) a lot more.
And .. now that I go over it, I notice functions must start with a lowercase and types with an uppercase, how lovely! I also didn't read about that, might also be nice to be explicit about aswel :) (assuming I didn't miss it in the text).

Hi,

I've noticed one thing in the Variable patterns lesson, the description mentions variables and how they can be used in bodies of matching clauses, the example doesn't contain such a clause though.

I suppose that the example could be updated to match the description or vice versa.

https://tour.gleam.run/flow-control/variable-patterns/

Thanks!

We can use the colours from the generated HTML docs' dark mode

Hi,

The Record accessors lesson contains the following paragraph.

The accessor syntax can only be used for fields that are in the same position and have the same type for all variants of the custom type.

Should we perhaps also mention that the name of the fields has to match as well across all of the variants for this to work? It's not just the position and type that have to match.

This one is a bit weird and I wasn't sure of I should even open an issue for it, therefore feel free to close it if you think that I'm overthinking 😅

Thanks 😄

Hey all, congrats on the launch!

Watching Theo's video getting through the language tour, I wonder whether the section on ints should specify what using JS 64bit floats for ints means.

Coming from Elm world I take it to mean "ints are 53bit" (or 52? can't remember), but I can imagine folks misunderstanding it to be the full 64 bits (as in, MAX_INT = 2^64 - 1 or some such)

Having min/max integers shown in the int lesson would help prevent confusion IMHO.

Context: gleam-lang/gleam#2622 (comment)

This line

Intermittently, upon clicking 'next', I don't get any results in the output window.

Clicking 'back' & 'next' it then loads and shows the output as expected.

Alternatively, refreshing the page will also show the output, as expected.

I tested with incognito windows, and the problem still occurs.

I cannot look for any console or network errors, as, for some reason I haven't figured out yet, it never shows any output when I open the dev tools.

The problem was confirmed by another user on the Gleam discord, who also reported seeing the following error message in their browser console:

tour.gleam.run/:1 Unchecked runtime.lastError: The message port closed before a response was received.

The table of contents footer appears on mobile as a large block at the bottom of the page. This button is seemingly unclickable.

Phone: iPhone 12

I'm jotting this down as I will fix it but am not at my PC

As per @lpil on the YouTube stream Gleam v1.2.0 is out now!!! at 27:13 the warning box has some min-height issue where it's causing the output box to show a scroll bar instead of filling the space.

Also, the editor and output on mobile seem to be collapsed and unusable.

Without testing it looks like the change was made here: fix hidden code editor

The current language tour doesn't communicate that you can't use functions in a guard clause:
https://gleam.run/book/tour/case-expressions.html#checking-equality-and-ordering-in-pattern

I think there's an implicit "only" here, that should be made explicit:

The guard expression can check for equality or ordering for Int and Float.

I have decided to embark on the translation of the Language Tour in french but I have faced some choices that might be better discussed at large.

• Neutrality of language: do we keep the translation neutral in a technical way or inclusive using inclusive writing in french
• Use of you. In french there are 2 yous, the polite one (vous) and the informal one (toi)

This PR introduced some extra colours. We need to bring it back into being consistent with the core branding so that it does not define any new colours.

We could promote some colours into core if useful, but we should look to remove extra colours generally as new ones keep getting added.

Hi,

I've noticed that https://tour.gleam.run/basics/ints/ and https://tour.gleam.run/basics/floats/ don't contain examples of inequality check operators (!=).

I suggest that we add this since these two lessons are the first to introduce the operator syntax.

Languages sometimes use different syntax for these, i.e. ~= in Lua, which is another reason why this would be helpful.

Thanks! 😃

import gleam/io

pub type DateTime

@external(erlang, "calendar", "local_time")
pub fn now() -> DateTime

pub fn main() {
  io.debug(now())
}

Error: panic expression evaluated

I think this may be a compiler bug from target tracking not being quite right.

Two examples, I'm told first one should result in a run-time crash:

import gleam/io

pub fn main() {
  let assert <<"\n":utf8, tail>> = <<"\ngoodbye":utf8>>
  io.debug(tail)
}

and this one I would expect to print the bytes of goodbye:

import gleam/io

pub fn main() {
  let assert <<"\n":utf8, tail:bytes>> = <<"\ngoodbye":utf8>>
  io.debug(tail)
}

edit: or maybe actually both should be compiler errors about the utf8 option on js target

I would like to be able to write tours for other things, explained in Gleam.
For example things I would personally like to write are.

• An OTP tour
• Implementing typechecking in Gleam
• Implementing an interpreter in Gleam

It would be great if there was a way to something like the following

// my_tour.gleam
import gleam/tour

pub fn main() {
  tour.build("/build", pages())
}

fn pages() {
  [
    tour.Page(
      title: "Getting started with OTP",
      content: "First we need to introduce processes"
      code: "
        import gleam/otp

        // ..."
    )
  ]
}

I'm happy to help contribute to such a thing. But I think it needs a bit of design work to work out what the interface is and what should be exposed.

Although the fn keyword was introduced in the previous section, using "function" to name variables and parameters may produce more misunderstandings than benefits.

fn twice(argument: Int, function: fn(Int) -> Int) -> Int {
  function(function(argument))
}

Hi,

I've noticed that errors (io.println_error) don't appear in the output in the lesson with the title Use sugar - https://tour.gleam.run/advanced-features/use-sugar/.

If I replace println_error with println then the message appears.

🖖

It would be cool if we could add a search bar to the language tour (and potentially the rest of the website) to quickly look things up since the language tour currently serves as a de facto reference to the core language.

This is a more generic response to #57 .

https://tour.gleam.run/data-types/bit-arrays/ lists various options, but they don't specify things like which ones require an argument (like size), ones that require more than just themselves (e.g. unit), how to change int to not be "a default size of 8 bits", etc.

The list is also missing:

• utf8_codepoint
• utf16_codepoint
• utf32_codepoint
• signed
• unsigned
  based on the error message.