Syntax Widget: Content Overview

[ryyppy]

Last update: June 14th, 2024

We've got the Syntax Lookup Widget skeleton (#114 ) in place now, so we need content writers to cover quick glance overviews over each topic.

This issue is here to collect a list of language constructs we should definitely cover. Feel free to propose more topics if something is missing. I will continuously update this issue for completeness reasons.

How to work on this?

• Check the list below (we regularly update it as soon as features get added) and pick some features you want to document
• Check out the misc_data/syntax directory for structure and inspiration
• Open a PR in draft mode (target master) as soon as possible, so other contributors see what's currently being worked on

Content Overview

Decorators:

• @val
• @module
• @obj
• @scope
• @get
• @get_index
• @set
• @set_index
• @uncurry
• @send
• @string
• @int
• @unwrap
• @new
• @deriving
• @as
• @variadic
• @inline
• @meth
• @return
• @unboxed
• @this
• @@warning
• @send.pipe (deprecated)
• @genType
• @react.component
• @deprecated
• @ignore
• @tag

Operators:

• ->
• |>
• ++
• +, +.
• -, -.
• /, /.
• *, *.
• mod
• := (ref value assignment)
• :> (type coercion)
• || boolean OR
• && boolean AND
• ! boolean NOT

Language Constructs:

• _ (placeholder, all scenarios like pipe, ignore value)
• type
• let (let binding)
• let \"\" (let binding with invalid identifier name) (Apparently not part of the language, although I strongly disagree not including it, because it's user-facing... see Document %external(\"SomeValue") #351)
• if / else
• external
• () => {} (function)
• (.) => {} (curried function)
• open (also open!)
• include (+ include module type of ...)
• module
• [ #value ] (polyvar definition)
• switch (pattern matching: exceptions, values, variants, when clause..)
• 'a (generic placeholder)
• +'a (placeholder for covariance)
• (Item: Comparable) => {} (module functor)
• <MyComponent> (JSX)
• "" (string)
• j`` (implicit string interpolation) (deprecated)
• `` (explicit string interpolation)
• ' ' (single quote = char)
• for loop
• while loop
• ~ labelled arguments
• | or patterns
• ?: ternary
• ... (spread, all scenarios like array, list, record, polymorphic variant)

Type Specifics:

• {.} (empty object type)
• { "key": "value" } (Object type)
• {..} (including type obj<'a> = {.. "a": string } as 'a) aka Open object type
• ref (mutable type)
• exception (exn)
• module type
• module type of (see playground link)

Builtin Functions:

• ignore

Extension Points:

• %%raw
• %raw
• %identity
• %debugger
• %re

Build System Specials:

• __POS_OF__(string)
• __LINE__
• __LOC__
• __FILE__
• __LOC_OF__
• __MODULE__
• __LINE_OF__

[ryyppy]

Lots of things already shipped thanks to @kevanstannard's help!

We already got some Operators / Decorators documented, so I think it's already useful enough to merge it into master.

In case you want to open a new PR to add more content, please use master as your target branch in the future.

[illusionalsagacity]

@ryyppy for the := operator, is there a formal name for it? I have referred to it as the ref assignment operator in a branch, will publish a draft PR shortly

[ryyppy]

@illusionalsagacity something like ref value assignment sounds good to me.

[ryyppy]

Short note: I reorganized / refined the item list for language constructs and introduced some Type Specifics category, just to separate the value / type space syntax little bit more

[fhammerschmidt]

I found a decorator not on your list: @deprecated.

[kellydanma]

👋 Recently discovered this project and looking forward to learning and using rescript!
I didn't find PRs for the following language constructs, could I work on them:

• "" (string); see [Syntax lookup] Add doc for string literal syntax #352
• j`` (implicit string interpolation)
• `` (explicit string interpolation)
• ' ' (single quote = char)

[ryyppy]

@kellydanma sure, go ahead. Just keep an eye out for any existing PRs when submitting new content 👍

[Minnozz]

I think {..} is missing from the list

[Minnozz]

Changes that can be applied to the OP:

• @@warning is done
• @deprecated is done
• @send.pipe is actually called @bs.send.pipe in the syntax widget; it is done
• open is done
• include is done
• module is done
• #value is done
• switch is done
• 'a is done, but +'a is not
• "" is done
• '' is done
• {..} can be added

Tip: you can use the following GitHub syntax to create a task list with clickable checkboxes:

- [ ] Not done
- [x] Done

[ryyppy]

updated

[Minnozz]

%re() (RegExp literal) is missing from the list

[frou]

I'd like to humbly suggest that such documentation shouldn't use a font with "programming ligatures". They're something that some people choose to use in their own customised editors, but it's not appropriate for documentation, which should always show the concrete syntax of the language.

[Kingdutch]

Even though it may not be complete, can we make the syntax widget more discoverable with a link from the API docs or the header itself?

I only recently found out this exists (and I've been doing ReScript for a while now) but even the current version can safe me a ton of time (e.g. to remember how to use %re or to find decorators without first finding the decorator overview page). This is an amazing tool for anyone using ReScript and should be front and center.

[fhammerschmidt]

The list is not up to date anymore.

The following are merged but not checked:

• ignore
• `` (explicit string interpolation)
• 'a (but '+a needs a separate entry then)

The following can be added to the widget as well:

• async/await
• try/catch (maybe as part of exception, but it is a different syntactical element IMO)
• { ?key: value } optional record fields
• 'a. unit => 'a explicitly polymorphic types
• //, /* */, /** */, /*** */ single-line, multi-line, doc and module-level doc comments

[fhammerschmidt]

Update: I would remove j`` from the list, since it's deprecated