v1.17.0-rc.0

This release includes type inference of patterns to provide warnings for an initial set of constructs (binaries, maps, and atoms). It also includes a new Duration data type to interact with Calendar types and support for Erlang/OTP 27.

Warnings from gradual set-theoretic types

This release introduces gradual set-theoretic types to infer types from patterns and guards and use them to type check programs, enabling the Elixir compiler to find faults and bugs in codebases without requiring changes to existing software. The underlying principles, theory, and roadmap of our work have been outlined in "The Design Principles of the Elixir Type System" by Giuseppe Castagna, Guillaume Duboc, José Valim.

At the moment, Elixir developers will interact with set-theoretic types only through warnings found by the type system. The current implementation models all data types in the language:

• binary(), integer(), float(), pid(), port(), reference() - these types are indivisible. This means both 1 and 13 get the same integer() type.

• atom() - it represents all atoms and it is divisible. For instance, the atom :foo and :hello_world are also valid (distinct) types.

• map() and structs - maps can be "closed" or "open". Closed maps only allow the specified allows keys, such as %{key: atom(), value: integer()}. Open maps support any other keys in addition to the ones listed and their definition starts with ..., such as %{..., key: atom(), value: integer()}. Structs are closed maps with the __struct__ key.

• tuple(), list(), and function() - currently they are modelled as indivisible types. The next Elixir versions will also introduce fine-grained support to them.

We focused on atoms and maps on this initial release as they are respectively the simplest and the most complex types representations, so we can stress the performance of the type system and quality of error messages. Modelling these types will also provide the most immediate benefits to Elixir developers. Assuming there is a variable named user, holding a %User{} struct with an address field, Elixir v1.17 will emit the following warnings at compile-time:

• Pattern matching against a map or a struct that does not have the given key, such as %{adress: ...} = user (notice address vs adress)

• Accessing a key on a map or a struct that does not have the given key, such as user.adress

• Updating a struct or a map that does not define the given key, such as %{user | adress: ...}

• Invoking a function on non-modules, such as user.address()

• Capturing a function on non-modules, such as &user.address/0

• Performing structural comparisons with structs, such as my_date < ~D[2010-04-17]

• Performing structural comparisons between non-overlapping types, such as integer >= string

• Building and pattern matching on binaries without the relevant specifiers, such as <<string>> (this warns because by default it expects an integer)

• Attempting to rescue an undefined exception or an exception that is not a struct

• Accessing a field that is not defined in a rescued exception

These new warnings help Elixir developers find bugs earlier and give more confidence when refactoring code, especially around maps and structs. While some of these warnings were emitted in the past, they were discovered using syntax analysis. The new warnings are more reliable, precise, and with better error messages. Keep in mind that not all maps have statically known keys, and the Elixir typechecker only infers types from patterns at the moment.

Future Elixir versions will infer and type check more constructs, bringing Elixir developers more warnings and quality of life improvements without changes to code. For more details, see our new reference document on gradual set-theoretic types.

The type system was made possible thanks to a partnership between CNRS and Remote. The development work is currently sponsored by Fresha, Starfish*, and Dashbit.

Erlang/OTP support

This release adds support for Erlang/OTP 27 and drops support for Erlang/OTP 24. We recommend Elixir developers to migrate to Erlang/OTP 26 or later, especially on Windows. Support for WERL (a graphical user interface for the Erlang terminal on Windows) will be removed in Elixir v1.18.

Adding Duration and shift/2 functions

Elixir introduces the Duration data type and APIs to shift dates, times, and date times by a given duration, considering different calendars and time zones.

iex> Date.shift(~D[2016-01-31], month: 2)
~D[2016-03-31]

Note the operation is called shift (instead of add) since working with durations does not obey properties such as associativity. For instance, adding one month and then one month does not give the same result as adding two months:

iex> ~D[2016-01-31] |> Date.shift(month: 1) |> Date.shift(month: 1)
~D[2016-03-29]

Still, durations are essential for building intervals, recurring events, and modelling scheduling complexities found in the world around us. For DateTimes, Elixir will correctly deal with time zone changes (such as Daylight Saving Time), but provisions are also available in case you want to surface conflicts (for example, you shifted to a wall clock that does not exist, because the clock has been moved forward by one hour). See DateTime.shift/2 for examples.

Finally, a new Kernel.to_timeout/1 function has been added, which helps developers normalize durations and integers to a timeout used by Process APIs. For example, to send a message after one hour, one can now write:

Process.send_after(pid, :wake_up, to_timeout(hour: 1))

1. Enhancements

Elixir

• [Access] Add Access.find/1 that mirrors Enum.find/2
• [Code] Support cursor inside fn/rescue/catch/else/after inside Code.Fragment.container_cursor_to_quoted/2
• [Date] Add Date.shift/2 to shift dates with duration and calendar-specific semantics
• [Date] Allow Date to accept years outside of -9999..9999 range
• [DateTime] Add DateTime.shift/2 to shift datetimes with duration and calendar-specific semantics
• [Duration] Add a new Duration data type
• [GenServer] Add c:GenServer.format_status/1 callback
• [Kernel] Add Kernel.get_in/1 with safe nil-handling for access and structs
• [Kernel] Add Kernel.is_non_struct_map/1 guard
• [Kernel] Add Kernel.to_timeout/1
• [Kernel] Emit warnings for undefined functions from modules defined within the same context as the caller code
• [Kernel] Support integers in uppercase sigils
• [Macro] Add Macro.Env.define_alias/4, Macro.Env.define_import/4, Macro.Env.define_require/4, Macro.Env.expand_alias/4, Macro.Env.expand_import/5, and Macro.Env.expand_require/6 to aid the implementation of language servers and embedded languages
• [NaiveDateTime] Add NaiveDateTime.shift/2 to shift naive datetimes with duration and calendar-specific semantics
• [Process] Add Process.set_label/1
• [String] Add String.byte_slice/3 to slice a string to a maximum number of bytes while keeping it UTF-8 encoded
• [System] Support use_stdio: false in System.cmd/3 and System.shell/2
• [Time] Add Time.shift/2 to shift times with duration and calendar-specific semantics

ExUnit

• [ExUnit] Propagate the test process itself as a caller in start_supervised
• [ExUnit] Include max cases in ExUnit reports

IEx

• [IEx.Helpers] Warns if recompile was called and the current working directory changed
• [IEx.Helpers] Add c/0 as an alias to continue/0
• [IEx.Pry] Add IEx.Pry.annotate_quoted/3 to annotate a quoted expression with pry breakpoints

Logger

• [Logger] Format :gen_statem reports using Elixir data structures
• [Logger] Include process label in logger events

Mix

• [mix deps] Add :depth option to Mix.SCM.Git, thus supporting shallow clones of Git dependencies
• [mix deps] Warn if :optional is used in combination with :in_umbrella
• [mix deps.get] Do not add optional dependency requirements if its parent dep was skipped
• [mix deps.tree] Add --umbrella-only to mix deps.tree
• [mix test] Add mix test --breakpoints that sets up a breakpoint before each test that will run
• [mix test] Add mix test --repeat-until-failure to rerun tests until a failure occurs
• [mix test] Add mix test --slowest-modules to print slowest modules based on all of the tests they hold

2. Bug fixes

Elixir

• [bin/elixir.bat] Improve handling of quotes and exclamation marks in flags
• [Code] Address a bug where AST nodes for (a -> b) were not wrapped as part of the literal encoder
• [Kernel] Resolve inconsistencies of how .. and ... are handled at the AST level
• [Kernel] Fix parsing precedence of ambiguous operators followed by containers
• [Kernel] Do not expand code in quote bind_quoted: ... twice
• [Kernel] Respect :line property when :file is given as option to quote
• [Kernel] Do not crash on Macro.escape/2 when passing a quote triplet without valid meta
• [Module] Return default value in Module.get_attribute/3 for persisted attributes which have not yet been written to

IEx

• [IEx.Helpers] Update the history size whenever history is pruned

Mix

• [mix deps] Fix error message for diverged SCM definition in sibling

3. Soft deprecations (no warnings emitted)

Elixir

• [GenServer] Deprecate c:GenServer.format_status/2 callback to align with Erlang/OTP 25+

4. Hard deprecations

...

v1.16.3

1. Bug fixes

Elixir

• [bin/elixir] Properly handle the --dbg flag in Elixir's CLI
• [Code.Formatter] Add brackets around keyword lists when formatting the left-hand side of when
• [Kernel] Only infer size in pinned variable in binary strings when needed
• [System] Add a note that arguments are unsafe when invoking .bat/.com scripts on Windows via System.cmd/3
• [Port] Add a note that arguments are unsafe when invoking .bat/.com scripts on Windows
• [URI] Ensure :undefined fields are properly converted to nil when invoking Erlang's API

Logger

• [Logger] Ensure translators are persisted across logger restarts

Mix

• [mix compile] Ensure compile paths are accessible during compilation

v1.15.8

1. Bug fixes

Elixir

• [bin/elixir] Properly handle the --dbg flag in Elixir's CLI
• [System] Add a note that arguments are unsafe when invoking .bat/.com scripts on Windows via System.cmd/3
• [Port] Add a note that arguments are unsafe when invoking .bat/.com scripts on Windows
• [URI] Ensure :undefined fields are properly converted to nil when invoking Erlang's API

Logger

• [Logger] Ensure translators are persisted across logger restarts

Mix

• [mix compile] Ensure compile paths are accessible during compilation

v1.16.2

1. Enhancements

Elixir

• [Code] Emit :defmodule tracing event on module definition

Mix

• [Mix] Add Mix.install_project_dir/0
• [Mix] Add environment variable for reusing Mix.install/2 installation
• [Mix.SCM] Add Mix.SCM.delete/1

2. Bug fixes

Elixir

• [Code] Fix charlist formatting issue when a single-quoted charlist escapes a double-quote character
• [Path] Fix regression on how Path.relative_to/2 dealt with "." as input

IEx

• [IEx.Helpers] Discard mermaid fenced blocks from ansi docs

ExUnit

• [ExUnit] Properly compared pinned values when building diffs

v1.16.1

1. Bug fixes

Elixir

• [Code] Fix Code.quoted_to_algebra/2 for operator with :do key as operand
• [Kernel.ParallelCompiler] Do not crash parallel compiler when it receives diagnostics from additional code evaluation
• [Kernel.ParallelCompiler] Always log errors at the end of compilation
• [String] Fix String.capitalize/1 with a single codepoint

IEx

• [IEx] Fix autocompletion of function signatures on Erlang/OTP 26
• [IEx] Do not assume $HOME is set

Mix

• [mix deps.compile] Handle compilation of rebar3 dependencies when rebar3 is on a path with spaces on Unix
• [mix test] Properly resolve relative paths when running tests from individual files
• [mix test] Properly resolve Windows paths when running tests from individual files

v1.16.0

Official announcement: https://elixir-lang.org/blog/2023/12/22/elixir-v1-16-0-released/

1. Enhancements

EEx

• [EEx] Include relative file information in diagnostics

Elixir

• [Code] Add :emit_warnings for Code.string_to_quoted/2
• [Code] Automatically include columns in parsing options
• [Code] Introduce MismatchedDelimiterError for handling mismatched delimiter exceptions
• [Code.Fragment] Handle anonymous calls in fragments
• [Code.Formatter] Trim trailing whitespace on heredocs with \r\n
• [File] Add :offset option to File.stream!/2
• [Kernel] Auto infer size of matched variable in bitstrings
• [Kernel] Preserve column information when translating typespecs
• [Kernel] Suggest module names based on suffix and casing errors when the module does not exist in UndefinedFunctionError
• [Kernel.ParallelCompiler] Introduce Kernel.ParallelCompiler.pmap/2 to compile multiple additional entries in parallel
• [Kernel.SpecialForms] Warn if True/False/Nil are used as aliases and there is no such alias
• [Macro] Add Macro.compile_apply/4
• [Module] Add support for @nifs annotation from Erlang/OTP 25
• [Module] Add support for missing @dialyzer configuration
• [String] Update to Unicode 15.1.0
• [String] Add String.replace_invalid/2
• [Task] Add :limit option to Task.yield_many/2

Logger

• [Logger] Add Logger.levels/0

Mix

• [mix] Add MIX_PROFILE to profile a list of comma separated tasks
• [mix archive.install] Support --sparse option
• [mix compile.app] Warn if both :applications and :extra_applications are used
• [mix compile.elixir] Pass original exception down to diagnostic :details when possible
• [mix compile.elixir] Optimize scenario where there are thousands of files in lib/ and one of them is changed
• [mix deps.clean] Emit a warning instead of crashing when a dependency cannot be removed
• [mix escript.install] Support --sparse option
• [mix release] Include include/ directory in releases
• [mix test] Allow testing multiple file:line at once, such as mix test test/foo_test.exs:13 test/bar_test.exs:27

2. Bug fixes

Elixir

• [Code] Keep quotes for atom keys in formatter
• [Code.Fragment] Fix crash in Code.Fragment.surround_context/2 when matching on ->
• [IO] Raise when using IO.binwrite/2 on terminated device (mirroring IO.write/2)
• [Kernel] Do not expand aliases recursively (the alias stored in Macro.Env is already expanded)
• [Kernel] Ensure dbg module is a compile-time dependency
• [Kernel] Warn when a private function or macro uses unquote/1 and the function/macro itself is unused
• [Kernel] Re-enabled compiler optimizations for top level functions in scripts (disabled in v1.14.0 but shouldn't impact most programs)
• [Kernel] Do not define an alias for nested modules starting with Elixir. in their definition
• [Kernel.ParallelCompiler] Consider a module has been defined in @after_compile callbacks to avoid deadlocks
• [Macro] Address exception on Macro.to_string/1 for certain ASTs
• [Path] Lazily evaluate File.cwd!/0 in Path.expand/1 and Path.absname/1
• [Path] Ensure Path.relative_to/2 returns a relative path when the given argument does not share a common prefix with cwd

ExUnit

• [ExUnit] Raise on incorrectly dedented doctests

IEx

• [IEx.Pry] Fix prying functions with only literals in their body

Mix

• [mix archive.install] Restore code paths after mix archive.install
• [mix compile] Ensure files with duplicate modules are recompiled whenever any of the files change
• [mix compile] Update Mix compiler diagnostics documentation and typespecs to match the Elixir compiler behaviour where both lines and columns start from one (before it inaccurately said that columns started from zero)
• [mix escript.install] Restore code paths after mix escript.install

3. Soft deprecations (no warnings emitted)

Elixir

• [File] Deprecate File.stream!(file, options, line_or_bytes) in favor of keeping the options as last argument, as in File.stream!(file, line_or_bytes, options)
• [Kernel.ParallelCompiler] Deprecate Kernel.ParallelCompiler.async/1 in favor of Kernel.ParallelCompiler.pmap/2
• [Path] Deprecate Path.safe_relative_to/2 in favor of Path.safe_relative/2

Mix

• [mix compile] Returning a four-element tuple as a position in Mix.Task.Compiler.Diagnostic

4. Hard deprecations

Elixir

• [Date] Deprecate inferring a range with negative step, call Date.range/3 with a negative step instead
• [Enum] Deprecate passing a range with negative step on Enum.slice/2, give first..last//1 instead
• [Kernel] ~R/.../ is deprecated in favor of ~r/.../. This is because ~R/.../ still allowed escape codes, which did not fit the definition of uppercase sigils
• [String] Deprecate passing a range with negative step on String.slice/2, give first..last//1 instead

ExUnit

• [ExUnit.Formatter] Deprecate format_time/2, use format_times/1 instead

Mix

• [mix compile.leex] Require :leex to be added as a compiler to run the leex compiler
• [mix compile.yecc] Require :yecc to be added as a compiler to run the yecc compiler

v1.16.0-rc.1

1. Enhancements

Elixir

• [Code] Add :emit_warnings for Code.string_to_quoted/2
• [File] Add :offset option to File.stream!/2
• [Kernel] Auto infer size of matched variable in bitstrings
• [Kernel] Preserve column information when translating typespecs
• [String] Add String.replace_invalid/2

Logger

• [Logger] Add Logger.levels/0

Mix

• [mix archive.install] Support --sparse option
• [mix compile.app] Warn if both :applications and :extra_applications are used
• [mix compile.elixir] Pass original exception down to diagnostic :details when possible
• [mix deps.clean] Emit a warning instead of crashing when a dependency cannot be removed
• [mix escript.install] Support --sparse option
• [mix release] Include include/ directory in releases

2. Bug fixes

Elixir

• [Code] Keep quotes for atom keys in formatter
• [Macro] Address exception on Macro.to_string/1 for certain ASTs
• [Module] Make sure file and position information is included in several module warnings (regression)
• [Path] Lazily evaluate File.cwd!/0 in Path.expand/1 and Path.absname/1

IEx

• [IEx.Pry] Fix prying functions with only literals in their body

Mix

• [mix archive.install] Restore code paths after archive.install
• [mix escript.install] Restore code paths after escript.install

v1.16.0-rc.0

Code snippets in diagnostics

Elixir v1.15 introduced a new compiler diagnostic format and the ability to print multiple error diagnostics per compilation (in addition to multiple warnings).

With Elixir v1.16, we also include code snippets in exceptions and diagnostics raised by the compiler. For example, a syntax error now includes a pointer to where the error happened:

** (SyntaxError) invalid syntax found on lib/my_app.ex:1:17:
    error: syntax error before: '*'
    │
  1 │ [1, 2, 3, 4, 5, *]
    │                 ^
    │
    └─ lib/my_app.ex:1:17

For mismatched delimiters, it now shows both delimiters:

** (MismatchedDelimiterError) mismatched delimiter found on lib/my_app.ex:1:18:
    error: unexpected token: )
    │
  1 │ [1, 2, 3, 4, 5, 6)
    │ │                └ mismatched closing delimiter (expected "]")
    │ └ unclosed delimiter
    │
    └─ lib/my_app.ex:1:18

Errors and warnings diagnostics also include code snippets. When possible, we will show precise spans, such as on undefined variables:

  error: undefined variable "unknown_var"
  │
5 │     a - unknown_var
  │         ^^^^^^^^^^^
  │
  └─ lib/sample.ex:5:9: Sample.foo/1

Otherwise the whole line is underlined:

error: function names should start with lowercase characters or underscore, invalid name CamelCase
  │
3 │   def CamelCase do
  │   ^^^^^^^^^^^^^^^^
  │
  └─ lib/sample.ex:3

A huge thank you to Vinícius Muller for working on the new diagnostics.

Revamped documentation

Elixir's Getting Started guided has been made part of the Elixir repository and incorporated into ExDoc. This was an opportunity to revisit and unify all official guides and references.

We have also incorporated and extended the work on Understanding Code Smells in Elixir Functional Language, by Lucas Vegi and Marco Tulio Valente, from ASERG/DCC/UFMG, into the official document in the form of anti-patterns. The anti-patterns are divided into four categories: code-related, design-related, process-related, and meta-programming. Our goal is to give all developers examples of potential anti-patterns, with context and examples on how to improve their codebases.

Another ExDoc feature we have incorporated in this release is the addition of cheatsheets, starting with a cheatsheet for the Enum module. If you would like to contribute future cheatsheets to Elixir itself, feel free to start a discussion with an issue.

Finally, we have started enriching our documentation with Mermaid.js diagrams. You can find examples in the GenServer and Supervisor docs.

v1.16.0-rc.0 (2023-10-31)

1. Enhancements

EEx

• [EEx] Include relative file information in diagnostics

Elixir

• [Code] Automatically include columns in parsing options
• [Code] Introduce MismatchedDelimiterError for handling mismatched delimiter exceptions
• [Code.Fragment] Handle anonymous calls in fragments
• [Code.Formatter] Trim trailing whitespace on heredocs with \r\n
• [Kernel] Suggest module names based on suffix and casing errors when the module does not exist in UndefinedFunctionError
• [Kernel.ParallelCompiler] Introduce Kernel.ParallelCompiler.pmap/2 to compile multiple additional entries in parallel
• [Kernel.SpecialForms] Warn if True/False/Nil are used as aliases and there is no such alias
• [Macro] Add Macro.compile_apply/4
• [Module] Add support for @nifs annotation from Erlang/OTP 25
• [Module] Add support for missing @dialyzer configuration
• [String] Update to Unicode 15.1.0
• [Task] Add :limit option to Task.yield_many/2

Mix

• [mix] Add MIX_PROFILE to profile a list of comma separated tasks
• [mix compile.elixir] Optimize scenario where there are thousands of files in lib/ and one of them is changed
• [mix test] Allow testing multiple file:line at once, such as mix test test/foo_test.exs:13 test/bar_test.exs:27

2. Bug fixes

Elixir

• [Code.Fragment] Fix crash in Code.Fragment.surround_context/2 when matching on ->
• [IO] Raise when using IO.binwrite/2 on terminated device (mirroring IO.write/2)
• [Kernel] Do not expand aliases recursively (the alias stored in Macro.Env is already expanded)
• [Kernel] Ensure dbg module is a compile-time dependency
• [Kernel] Warn when a private function or macro uses unquote/1 and the function/macro itself is unused
• [Kernel] Do not define an alias for nested modules starting with Elixir. in their definition
• [Kernel.ParallelCompiler] Consider a module has been defined in @after_compile callbacks to avoid deadlocks
• [Path] Ensure Path.relative_to/2 returns a relative path when the given argument does not share a common prefix with cwd

ExUnit

• [ExUnit] Raise on incorrectly dedented doctests

Mix

• [Mix] Ensure files with duplicate modules are recompiled whenever any of the files change

3. Soft deprecations (no warnings emitted)

Elixir

• [File] Deprecate File.stream!(file, options, line_or_bytes) in favor of keeping the options as last argument, as in File.stream!(file, line_or_bytes, options)
• [Kernel.ParallelCompiler] Deprecate Kernel.ParallelCompiler.async/1 in favor of Kernel.ParallelCompiler.pmap/2
• [Path] Deprecate Path.safe_relative_to/2 in favor of Path.safe_relative/2

4. Hard deprecations

Elixir

• [Date] Deprecate inferring a range with negative step, call Date.range/3 with a negative step instead
• [Enum] Deprecate passing a range with negative step on Enum.slice/2, give first..last//1 instead
• [Kernel] ~R/.../ is deprecated in favor of ~r/.../. This is because ~R/.../ still allowed escape codes, which did not fit the definition of uppercase sigils
• [String] Deprecate passing a range with negative step on String.slice/2, give first..last//1 instead

ExUnit

• [ExUnit.Formatter] Deprecate format_time/2, use format_times/1 instead

Mix

• [mix compile.leex] Require :leex to be added as a compiler to run the leex compiler
• [mix compile.yecc] Require :yecc to be added as a compiler to run the yecc compiler

v1.15.7

1. Enhancements

Elixir

• [Elixir] Allow code evaluation across Elixir versions

2. Bug fixes

EEx

• [EEx] Do not emit duplicate warnings from tokenizer

Mix

• [mix format] Correctly match file to subdirectory in Mix.Tasks.Format.formatter_for_file/2

v1.15.6

This release also includes fixes to the Windows installer.

1. Bug fixes

EEx

• [EEx] Do not crash when printing tokenizer warnings

Elixir

• [Code] Fix formatter for nested * in bitstrings
• [Code] Improve feedback when an invalid block is given Code.quoted_to_algebra/2
• [Kernel] Trace functions before they are inlined

Mix

• [mix compile] Ensure :extra_applications declare in umbrella projects are loaded
• [mix deps.get] Do not check for invalid applications before deps.get
• [mix deps.update] Do not check for invalid applications before deps.update
• [mix format] Load plugins when invoking the formatter from an IDE