search

crystal-lang / crystal-book

Crystal reference with language specification, manuals and learning materials
https://crystal-lang.org/reference
Other
392 stars 244 forks source link

Listing all preview feature flags #543

Open HertzDevil opened 3 years ago

HertzDevil commented 3 years ago

From https://github.com/crystal-lang/crystal/pull/11145#pullrequestreview-740232558, there should be a place where every compile-time flag for breaking feature previews is listed. This list should be public and contained in the language reference itself. For example:

Specification - Compile-time flags

To define a flag, simply use the --define or -D option, like so:

crystal some_program.cr -Dflag

A flag that starts with preview_ enables a preview compiler feature (link).

Specification - Preview compiler features

A preview compiler feature changes the behaviour of the compiler in a way that may prevent existing code from working. In other to maintain compatibility, these features are enabled by compile-time flags (link), and will be enforced in Crystal 2.0 or turned into warnings some time before a 2.0 release. All preview feature flags must start with preview_. The currently supported preview compiler features are:

* preview_multi_assign (link): Enables stricter checks on one-to-many multiple assignments.

Preview compiler features are experimental and subject to incompatible changes even between minor releases.

Specification - Preview compiler features - Multiple assignment

(the full specification of changes applied by preview_multi_assign, as well as any migration paths applicable)

Specification - Assignment - Multiple assignment

If the right-hand side contains just one expression, the type is indexed for each variable on the left-hand side like so:

# ...

If the preview_multi_assign flag (link) is enabled, the number of elements in that expression must match the number of assignment targets.

straight-shoota commented 3 years ago

There should probably be notes which version introduced a preview flag, if and when it was accepted to be final and if and when its absence leads to deprecation warnings.