Release v1.13.4

Fix #11740.

.cirrus.yml

@@ -12,20 +12,21 @@ test_template: &DEFAULT_TEST_SETTINGS
 test_freebsd_task:
   <<: *DEFAULT_TEST_SETTINGS
 
-  name: FreeBSD 12.2
+  name: FreeBSD 13.0
   alias: FreeBSD Stable
 
   freebsd_instance:
-    image_family: freebsd-12-2
+    image_family: freebsd-13-0
     cpu: 8
     memory: 7424Mi
 
   env:
     CHECK_REPRODUCIBLE: true
     LC_ALL: en_US.UTF-8
+    PATH: $PATH:/usr/local/lib/erlang22/bin
 
   install_script:
-    - pkg install -y erlang git gmake
+    - pkg install -y erlang-runtime22 git gmake
     - rm -rf .git
     - gmake compile
 

.github/ISSUE_TEMPLATE.md

@@ -1,9 +1,9 @@
 ### Precheck
 
-* Do not use the issue tracker for help or support (try Elixir Forum, Stack Overflow, IRC, etc.)
 * For proposing a new feature, please start a discussion on the Elixir Core mailing list: https://groups.google.com/group/elixir-lang-core
 * For bugs, do a quick search and make sure the bug has not yet been reported
 * Please disclose security vulnerabilities privately at elixir-security@googlegroups.com
+* Do not use the issues tracker for guidance, questions or support (try Elixir Forum, Stack Overflow, Slack, etc. instead)
 * Finally, be nice and have fun!
 
 ### Environment
@@ -14,6 +14,7 @@
 ### Current behavior
 
 Include code samples, errors and stacktraces if appropriate.
+If reporting a bug, please include the reproducing steps.
 
 ### Expected behavior
 

.github/workflows/ci.yml

@@ -10,19 +10,18 @@ env:
 
 jobs:
   test_linux:
-    name: Linux, ${{ matrix.otp_release }}, Ubuntu 16.04
-    continue-on-error: ${{ matrix.development }}
+    name: Linux, ${{ matrix.otp_release }}, Ubuntu 18.04
     strategy:
       fail-fast: false
       matrix:
-        otp_release: ['OTP-23.0', 'OTP-22.3', 'OTP-22.0', 'OTP-21.3.8', 'OTP-21.0']
+        otp_release: ['OTP-24.3', 'OTP-24.0', 'OTP-23.3', 'OTP-23.0', 'OTP-22.3', 'OTP-22.0']
         development: [false]
         include:
           - otp_release: master
             development: true
           - otp_release: maint
             development: true
-    runs-on: ubuntu-16.04
+    runs-on: ubuntu-18.04
     steps:
       - uses: actions/checkout@v2
         with:
@@ -30,7 +29,7 @@ jobs:
       - name: Install Erlang/OTP
         run: |
           cd $RUNNER_TEMP
-          wget -O otp.tar.gz https://repo.hex.pm/builds/otp/ubuntu-16.04/${{ matrix.otp_release }}.tar.gz
+          wget -O otp.tar.gz https://repo.hex.pm/builds/otp/ubuntu-18.04/${{ matrix.otp_release }}.tar.gz
           mkdir -p otp
           tar zxf otp.tar.gz -C otp --strip-components=1
           otp/Install -minimal $(pwd)/otp
@@ -47,17 +46,19 @@ jobs:
         run: dialyzer -pa lib/elixir/ebin --build_plt --output_plt elixir.plt --apps lib/elixir/ebin/elixir.beam lib/elixir/ebin/Elixir.Kernel.beam
       - name: Erlang test suite
         run: make test_erlang
+        continue-on-error: ${{ matrix.development }}
       - name: Elixir test suite
         run: make test_elixir
+        continue-on-error: ${{ matrix.development }}
       - name: Check reproducible builds
         run: taskset 1 make check_reproducible
-        if: matrix.otp_release == 'OTP-23.0'
+        if: matrix.otp_release == 'OTP-24.0'
 
   test_windows:
     name: Windows, OTP-${{ matrix.otp_release }}, Windows Server 2019
     strategy:
       matrix:
-        otp_release: ['22.0']
+        otp_release: ['22.3']
     runs-on: windows-2019
     steps:
       - name: Configure Git
@@ -83,11 +84,13 @@ jobs:
       - name: Erlang test suite
         run: make --keep-going test_erlang
       - name: Elixir test suite
-        run: make --keep-going test_elixir
+        run: |
+          del c:/Windows/System32/drivers/etc/hosts
+          make --keep-going test_elixir
 
   check_posix_compliant:
     name: Check POSIX-compliant
-    runs-on: ubuntu-16.04
+    runs-on: ubuntu-18.04
     steps:
       - uses: actions/checkout@v2
         with:

CHANGELOG.md

@@ -1,223 +1,408 @@
-# Changelog for Elixir v1.12
+# Changelog for Elixir v1.13
 
-Elixir v1.12 is out with improvements to scripting, tighter Erlang/OTP 24 integration, stepped ranges, and dozen of new functions across the standard library. Overall this is a small release, which continues our tradition of bringing Elixir developers quality of live improvements every 6 months.
+The focus behind Elixir v1.13 has been on tooling, mainly tooling related to code formatting, code fragments, code reflection, and code recompilation. A lot of this functionality will directly impact developers working on large codebases and provide meaningful quality of life improvements for those working on Elixir tooling and environments, such as IDEs, notebooks, etc.
 
-## Scripting improvements: `Mix.install/2` and `System.trap_signal/3`
+## Semantic recompilation
 
-Elixir v1.12 brings new conveniences for those using Elixir for scripting (via `.exs` files). Elixir has been capable of managing dependencies for a quite long time, but it could only be done within Mix projects. In particular, the Elixir team is wary of global dependencies as any scripts that rely on system packages are brittle and hard to reproduce whenever your system changes.
+Elixir v1.13 comes with many improvements to the compiler, so it recompiles your files less frequently. In particular:
 
-`Mix.install/2` is meant to be a sweetspot between single-file scripts and full-blown Mix projects. With `Mix.install/2`, you can list your dependencies on top of your scripts. When you execute the script for the first time, Elixir will download, compile, and cache your dependencies before running your script. Future invocations of the script will simply read the compiled artefacts from the cache:
+  * The digest of the files are considered in addition to their size. This avoids recompiling many files when switching or rebasing branches.
+
+  * Changing your `mix.exs` will no longer trigger a full recompilation, unless you specifically change the configurations used by the Elixir compiler (`:elixirc_paths` and `:elixirc_options`).
+
+  * Changing compile-time configuration files (`config/config.exs` and any other file imported from it) now only recompiles the project files that depend on the reconfigured applications, instead of a full recompilation. However, if you change the configuration of your application itself, the whole project is still recompiled.
+
+  * Adding, updating or removing a dependency now only recompiles the project files that depend on the modified a dependency.
+
+  * If your project has both Erlang and Elixir files, changing an Erlang file will now recompile only the Elixir files that depend on it.
+
+In a nutshell, Elixir went from triggering full recompilations whenever any of `mix.exs`, `config/config.exs`, `src/*`, and `mix.lock` changed on disk to semantic recompilations. Now it only fully recompiles when:
+
+  * you change the compilation options in `mix.exs`
+  * you change the configuration for the current project in `config/config.exs`
+
+## mix xref
+
+`mix xref` is a tool that analyzes relationships between files. By analyzing the compile-time and runtime dependencies between files, it allows developers to understand what files have to be recompiled whenever a file changes.
+
+Elixir v1.13 comes with many improvements to `mix xref`, such as:
+
+  * `mix xref graph` now supports `--label` to be set to "compile-connected", which returns all compile-time dependencies that lead to additional transitive dependencies.
+
+  * A new `mix xref trace FILE` subcommand receives a file and returns all dependencies in said file, including the line and what caused said dependency (a function/macro call, an alias, a struct, etc).
+
+  * All `mix xref` subcommands support the `--fail-above` flag, which allows you to enforce your project has at most a certain number of compile-time cycles, transitive compile-time dependencies, etc.
+
+  * `mix xref graph` now supports multiple `--sink` and `--source` to be given.
+
+With these improvements, it has become simpler to understand the impact code recompilation has in our codebases and how to limit it.
+
+## Code fragments
+
+The `Code` module got a companion module called `Code.Fragment`, which hosts functions that work on incomplete code, as is often the scenario in editors, interactive shells, etc. The module contains different heuristics to analyze the source code and return context informational.
+
+Thanks to these improvements, `IEx`' autocomplete got several quality of life improvements, such as the autocompletion of sigils, structs, and paths. For example, typing `~<TAB>` now shows:
+
+```iex
+iex(1)> ~
+~C (sigil_C)    ~D (sigil_D)    ~N (sigil_N)    ~R (sigil_R)
+~S (sigil_S)    ~T (sigil_T)    ~U (sigil_U)    ~W (sigil_W)
+~c (sigil_c)    ~r (sigil_r)    ~s (sigil_s)    ~w (sigil_w)
+
+```
+
+Adding the sigil letter and pressing tab then shows the available delimiters:
+
+```iex
+iex(1)> ~r
+"      """    '      '''    (      /      <      [      {      |
+
+```
+
+Similarly, `%<TAB>` now shows only the available structs (exceptions excluded), instead of all modules:
 
 ```elixir
-Mix.install([:jason])
-IO.puts Jason.encode!(%{hello: :world})
+iex(1)> %File.St
+File.Stat      File.Stream
 ```
 
-`Mix.install/2` also performs protocol consolidation, which gives script developers an option to execute their code in the most performant format possible.
+Once you define the struct, you can hit `tab` to show all struct fields available:
 
-**Note:** `Mix.install/2` is currently experimental and it may change in future releases.
-
-Another improvement to scripting is the ability to trap exit signals via `System.trap_signal/3`. All you need is the signal name and a callback that will be invoked when the signal triggers. For example, ExUnit leverages this functionality to print all currently running tests when you abort the test suite via SIGQUIT (`Ctrl+\\ `):
-
-```
-$ mix test
-.......................................................................
-.....................^\
-
-Aborting test suite, the following have not completed:
-
-* test query building [test/ecto/query_test.exs:48]
-* test placeholders in Repo.insert_all [test/ecto/repo_test.exs:502]
-
-Showing results so far...
-
-78 doctests, 1042 tests, 0 failures
+```elixir
+iex(1)> %URI{
+authority:    fragment:     host:         path:         port:
+query:        scheme:       userinfo:
 ```
 
-This is particularly useful when your tests get stuck and you want to know which one is the culprit.
+As you fill a field in, the already filled fields no longer show up:
 
-**Important**: Trapping signals may have strong implications on how a system shuts down and behave in production and therefore it is extremely discouraged for libraries to set their own traps. Instead, they should redirect users to configure them themselves. The only cases where it is acceptable for libraries to set their own traps is when using Elixir in script mode, such as in `.exs` files and via Mix tasks.
-
-## Tighter Erlang/OTP 24 integration
-
-Erlang/OTP 24 ships with JIT compilation support and Elixir developers don't have to do anything to reap its benefits. There are many other features in Erlang/OTP 24 to look forwards to and Elixir v1.12 provides integration with many of them: such as support for 16bit floats in bitstrings as well as performance improvements in the compiler and during code evaluation.
-
-Another excellent feature in Erlang/OTP 24 is the implementation of [EEP 54](http://erlang.org/eeps/eep-0054.html), which provides extended error information for many functions in Erlang's stdlib. Elixir v1.12 fully leverages this feature to improve reporting for errors coming from Erlang. For example, in earlier OTP versions, inserting an invalid argument into a ETS table that no longer exists would simply error with `ArgumentError`:
-
-```
-Interactive Elixir (1.11.0)
-iex(1)> ets = :ets.new(:example, [])
-#Reference<0.3845811859.2669281281.223553>
-iex(2)> :ets.delete(ets)
-true
-iex(3)> :ets.insert(ets, :should_be_a_tuple)
-** (ArgumentError) argument error
-    (stdlib 3.15) :ets.insert(#Reference<0.3845811859.2669281281.223553>, :should_be_a_tuple)
+```elixir
+iex(1)> %URI{path: "/example",
+authority:    fragment:     host:         port:         query:
+scheme:       userinfo:
 ```
 
-However, in Elixir v1.12 with Erlang/OTP 24:
+Along the same lines, `SyntaxError` and `TokenMissingError` were improved to show a code snippet whenever possible:
 
-```
-Interactive Elixir (1.12.0)
-iex(1)> ets = :ets.new(:example, [])
-#Reference<0.105641012.1058144260.76455>
-iex(2)> :ets.delete(ets)
-true
-iex(3)> :ets.insert(ets, :should_be_a_tuple)
-** (ArgumentError) errors were found at the given arguments:
-
-  * 1st argument: the table identifier does not refer to an existing ETS table
-  * 2nd argument: not a tuple
-
-    (stdlib 3.15) :ets.insert(#Reference<0.105641012.1058144260.76455>, :should_be_a_tuple)
+```elixir
+$ elixir -e "hello + * world"
+** (SyntaxError) nofile:1:9: syntax error before: '*'
+    |
+  1 | hello + * world
+    |         ^
 ```
 
-## Stepped ranges
+Finally, new compilation tracers have been added, alongside a handful of functions in `Module` to retrieve module metadata, which can be used to enrich suggestions in programming environments.
 
-Elixir has support for ranges from before its v1.0 release. Ranges support only integers and are inclusive, using the mathematic notation `a..b`. Ranges in Elixir are either increasing `1..10` or decreasing `10..1` and the direction of the range was always inferred from the starting and stop positions. Ranges are always lazy as its values are emitted as they are enumerated rather than being computed upfront.
+## Extended code formatting
 
-Unfortunately, due to this inference, it is not possible to have empty ranges. For example, if you want to create a list of `n` elements, you can express it with a range from `1..n`, as `1..0` is a decreasing range with two elements.
+The `mix format` task has been augmented with the notion of plugins. Plugins can teach the formatter how to format new files and how to format sigils, via the `Mix.Tasks.Format` behaviour.
 
-Elixir v1.12 supports stepped ranges via the `first..last//step` notation. For example: `1..10//2` will emit the numbers `1`, `3`, `5`, `7`, and `9`. You can consider the `//` operator to perform "range division", as it effectively divides and rounds up the number of elements in the range by `step`. Steps can be either positive (increasing ranges) or negative (decreasing ranges). Stepped ranges bring more expressive power to Elixir ranges and they elegantly solve the empty range problem, as they allow the direction of the steps to be explicitly declared instead of inferred.
+For example, imagine that your project uses Markdown in two distinct ways: via a custom `~M` sigil and via files with the `.md` and `.markdown` extensions. A custom plugin would look like this:
 
-As of Elixir v1.12, implicitly decreasing ranges are soft-deprecated and warnings will be emitted in future Elixir versions based on our [deprecation policy](https://hexdocs.pm/elixir/compatibility-and-deprecations.html#deprecations).
+```elixir
+defmodule MixMarkdownFormatter do
+  @behaviour Mix.Tasks.Format
 
-## Additional functions
+  def features(_opts) do
+    [sigils: [:M], extensions: [".md", ".markdown"]]
+  end
 
-Elixir v1.12 has the additional of many functions across the standard library. The `Enum` module received additions such as `Enum.count_until/2`, `Enum.product/1`, `Enum.zip_with/2`, and more. The `Integer` module now includes `Integer.pow/2` and `Integer.extended_gcd/2`. The `Range` module now deals with stepped ranges and includes new convenience functions such as `Range.empty?/1` and `Range.size/1`. Finally, the `Kernel` module got two new functions, `Kernel.then/2` and `Kernel.tap/2`, which are specially useful in `|>` pipelines.
+  def format(contents, opts) do
+    # logic that formats markdown
+  end
+end
+```
 
-## v1.12.0-dev
+Now any application can use your formatter as follows:
+
+```elixir
+# .formatter.exs
+[
+  # Define the desired plugins
+  plugins: [MixMarkdownFormatter],
+  # Remember to update the inputs list to include the new extensions
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}", "posts/*.{md,markdown}"]
+]
+```
+
+Finally, the `Code` module has also been augmented with two functions: `Code.string_to_quoted_with_comments/2` and `Code.quoted_to_algebra/2`. Those functions allow someone to retrieve the Elixir AST with their original source code comments, and then convert this AST to formatted code. In other words, those functions provide a wrapper around the Elixir Code Formatter, supporting developers who wish to create tools that directly manipulate and custom format Elixir source code.
+
+## v1.13.4 (2022-04-07)
+
+This release has been verified to work with Erlang/OTP 25 RC2.
 
 ### 1. Enhancements
 
-#### EEx
-
-  * [EEx.Engine] Add `c:EEx.Engine.handle_text/3` callback that receives text metadata
-  * [EEx.Engine] Emit warnings for unused "do" expression in EEx
-
 #### Elixir
 
-  * [Code] Do not add newlines around interpolation on code formatting. Note this means formatted code that has interpolation after the line length on Elixir v1.12 won't be considered as formatted on earlier Elixir versions
-  * [Calendar] Support basic datetime format in `Calendar.ISO` parsing functions
-  * [Code] Improve evaluation performance on systems running on Erlang/OTP 24+
-  * [Date] Support steps via `Date.range/3`
-  * [DateTime] Add `offset` to `DateTime.to_iso8601/2` (now `to_iso8601/3`)
-  * [Enum] Add `Enum.count_until/2` and `Enum.count_until/3`
-  * [Enum] Add `Enum.product/1`
-  * [Enum] Add `Enum.zip_with/2`, `Enum.zip_with/3`, `Enum.zip_reduce/3`, and `Enum.zip_reduce/4`
-  * [Enum] Add support for functions as the second argument of `Enum.with_index/2`
-  * [Exception] Show `error_info` data for exceptions coming from Erlang
-  * [Float] Add `Float.pow/2`
-  * [Integer] Add `Integer.pow/2` and `Integer.extended_gcd/2`
-  * [List] Add default value for `List.first/1` and `List.last/1`
-  * [Kernel] Add `start..stop//step` as support for stepped ranges
-  * [Kernel] Also warn for literal structs on `min/2` and `max/2`
-  * [Kernel] Add `Kernel.tap/2` and `Kernel.then/2`
-  * [Kernel] Do not add runtime dependencies to remotes in typespecs
-  * [Kernel] When there is an unused variable warning and there is a variable with the same name previously defined, suggest the user may have wanted to use the pin operator
-  * [Kernel] Improve error messages on invalid character right after a number
-  * [Kernel] Show removal and deprecated tips from Erlang/OTP
-  * [Macro] Add export dependencies on `Macro.struct!/2`
-  * [Macro] Support `:newline` to customize newlines escaping in `Macro.unescape_string/2`
-  * [Module] Raise on invalid `@dialyzer` attributes
-  * [Module] Add `Module.get_definition/2` and `Module.delete_definition/2`
-  * [Module] Allow `@on_load` to be a private function
-  * [Module] Validate `@dialyzer` related module attributes
-  * [Range] Add `Range.new/3`, `Range.empty?/1`, and `Range.size/1`
-  * [Regex] Add offset option to `Regex.scan/3` and `Regex.run/3`
-  * [Registry] Support `:compression` on `Registry` tables
-  * [Stream] Add `Stream.zip_with/2` and `Stream.zip_with/3`
-  * [String] Add `:turkic` mode option to String case functions
-  * [System] Add `System.trap_signal/3` and `System.untrap_signal/2`
-  * [Tuple] Add `Tuple.sum/1` and `Tuple.product/1`
-  * [URI] Support RFC3986 compliant encoding and decoding of queries via the `:rfc3986` option
-
-#### ExUnit
-
-  * [ExUnit] Intercept SIGQUIT (via Ctrl+\\) and show a list of all aborted tests as well as intermediate test results
-  * [ExUnit] Interpolate module attributes in match assertions diffs
-  * [ExUnit] Print how much time is spent on `async` vs `sync` tests
-  * [ExUnit] Improve error messages for doctests
-  * [ExUnit] Compile doctests faster (often by two times)
-
-#### IEx
-
-  * [IEx] Make IEx' parser configurable to allow special commands
-  * [IEx] Show function signature when pressing tab after the opening parens of a function
-  * [IEx] If an IEx expression starts with a binary operator, such as `|>`, automatically pipe in the result of the last expression
-
-#### Mix
-
-  * [Mix] Add `Mix.install/2` for dynamically installing a list of dependencies
-  * [Mix] Support `:exit_code` option in `Mix.raise/2`
-  * [Mix] Discard `MIX_ENV` and `MIX_TARGET` values if they are empty strings
-  * [Mix] Print the time taken to execute a task with on `MIX_DEBUG=1`
-  * [mix compile.erlang] Compile multiple files in parallel
-  * [mix escript.build] Deep merge configuration and ensure argv is set when executing `config/runtime.exs`
-  * [mix release] Add `RELEASE_PROG` to releases with the name of the executable starting the release
-  * [mix release] Support `remote.vm.args` to customize how the connecting VM boots
-  * [mix test] Run all available tests if there are no pending `--failed` tests. This provides a better workflow as you no longer need to toggle the `--failed` flag between runs
+  * [Code] Allow iodata to be returned in sigil formatting functions
+  * [Code] Pass opening delimiter information to sigil formatting functions
 
 ### 2. Bug fixes
 
 #### Elixir
 
-  * [CLI] Ensure `-e ""` (with an empty string) parses correctly on Windows
-  * [Inspect] Do not override user supplied `:limit` option for derived implementations
-  * [Kernel] Allow heredoc inside a heredoc interpolation
-  * [Kernel] Preserve CRLF on heredocs
-  * [Kernel] Public functions without documentation now appear as an empty map on `Code.fetch_docs/1`, unless they start with underscore, where they remain as `:none`. This aligns Elixir's implementation with EEP48
-  * [Kernel] Do not crash when complex literals (binaries and maps) are used in guards
-  * [Kernel] Properly parse keywords (such as `end`) followed by the `::` operator
-  * [Macro] `Macro.decompose_call/1` now also consider tuples with more than 2 elements to not be valid calls
-  * [Macro] Fix `Macro.underscore/1` for digit preceded by capitals: "FOO10" now becomes "foo10" instead of "fo_o10"
-  * [OptionParser] Properly parse when numbers follow-up aliases, for example, `-ab3` is now parsed as `-a -b 3`
-  * [Path] Fix `Path.relative_to/2` when referencing self
-  * [Task] Ensure `Task.async_stream/2` with `ordered: false` discard results as they are emitted, instead of needlessly accumulating inside the stream manager
-  * [URI] Do not discard empty paths on `URI.merge/2`
+  * [Kernel] Tweak type unification to fix infinite loop with recursive vars
+  * [Kernel] Add compile-time dependencies on `require`
+  * [Registry] Make `Registry` send work with named triplets
 
-#### ExUnit
-
-  * [ExUnit.Case] Make `@tag tmp_dir` an absolute directory, avoiding inconsistencies if the test changes the current working directory
-  * [ExUnit.Diff] Fix cases where the diffing algorithm would fail to print a pattern correct
-
-#### IEx
-
-  * [IEx] Fix auto-completion inside remote shells
+### 3. Deprecations
 
 #### Mix
 
-  * [mix app.config] Do not emit false positive warnings when configured dependencies that have `runtime: false` set
-  * [mix compile.elixir] Ensure that a manifest is generated even with no source code
-  * [mix compile.elixir] Make sure export dependencies trigger recompilation when the dependency is removed as well as when the whole file is removed
-  * [mix compile.elixir] Do not emit false positive warnings when a path dependency adds a module that is then used by the current application in the same `mix compile` cycle
-  * [mix test] Ensure protocols within the current project are consolidated when `--cover` is given
-  * [mix release] Improve compliance of release scripts with stripped down Linux installations
-  * [mix release] Preserve file mode when copying non-beam ebin files
+  * [mix rebar] Deprecate Rebar 2 as it no longer works on Erlang/OTP 25
+
+## v1.13.3 (2022-02-09)
+
+### 1. Enhancements
+
+#### Mix
+
+  * [mix format] Supply file and line to formatter plugins
+  * [mix format] Support embedded Elixir expressions inside formatter plugins
+
+### 2. Bug fixes
+
+#### Elixir
+
+  * [Code] Fix duplicate bindings causing errors during evaluation
+  * [Kernel] Make sure signatures stored in the Documentation chunk does not contain newlines
+  * [Kernel] Fix infinite loop when compiling guards with recursive map access
+  * [Macro] Fix error on `Macro.to_string/1` when the plain alias `Elixir` is given
+  * [String] Fix error for certain codepoint combinations in `String.split_at/2`
+
+#### Mix
+
+  * [mix compile] Recompile project files when exports from dependencies change
+  * [mix test] Fix total coverage always showing in red even when above the threshold
+
+## v1.13.2 (2022-01-13)
+
+### 1. Enhancements
+
+#### Mix
+
+  * [mix format] Allow plugins to also format `.ex` and `.exs` files
+  * [mix release] Allow bypassing application mode validation in release spec
+  * [mix test] Print a message when the suite fails due to the coverage threshold
+
+### 2. Bug fixes
+
+#### Elixir
+
+  * [Code] Do not emit warnings on `Code.Fragment.container_cursor_to_quoted/2`
+  * [Kernel] Fix a crash when a for-comprehension with `:uniq` was used inside another comprehension with `:uniq`
+  * [Kernel] Ensure `env.context_modules` is properly set inside optimized `defmodule`
+  * [Keyword] Deprecate the recently added `Keyword.map/2` as it is equivalent to `Keyword.new/2`
+  * [Map] Deprecate the recently added `Map.map/2` as it is equivalent to `Map.new/2`
+  * [Protocol] Warn on zero arity callbacks inside protocols
+
+## v1.13.1 (2021-12-14)
+
+### 1. Bug fixes
+
+#### Elixir
+
+  * [Code] Do not show code snippets in `SyntaxError` and `TokenMissingError` if line is empty
+  * [Exception] Do not fail blaming `ArgumentError` for improper lists on `apply/3`
+  * [Macro] Set a max `line_length` for `Macro.to_string/1`
+  * [Macro] Fix formatting of lists on module attributes for `Macro.to_string/1`
+  * [String] Fix incorrect codepoint byte counting in `slice` with negative positions in ranges
+  * [Task] Ensure async streams can be consumed from another process than the one that creates them
+  * [URI] Undeprecate `URI.parse/1` as `URI.new/1` is too strict in many common cases
+  * [URI] Make sure `URI.new/1` returns nil for empty paths
+
+#### IEx
+
+  * [IEx] Make sure the `--version` flag halts IEx
+
+#### Mix
+
+  * [Mix] Make protocol consolidation part of the `Mix.install/2` cache
+
+## v1.13.0 (2021-12-03)
+
+### 1. Enhancements
+
+#### EEx
+
+  * [EEx] Add `:parser_options` to EEx functions
+
+#### Elixir
+
+  * [Calendar] Add `c:Calendar.year_of_era/3` to support calendars where the beginning of a new era does not align with the beginning of a new year
+  * [CLI] Support `--short-version` on the CLI that does not boot the VM
+  * [Code] Add `Code.string_to_quoted_with_comments/2` and `Code.quoted_to_algebra/2`
+  * [Code] Add more `:token_metadata` to aliases and remote calls when parsing strings
+  * [Code] Add `Code.Fragment` module to provide best-effort information from code fragments. The module currently provides an updated `Code.Fragment.cursor_context/2` with operator support and `Code.Fragment.surround_context/2` which looks at a given position in a fragment and find its surrounding delimiters
+  * [Code] Allow custom sigil formatting on `Code.format_string!/2`
+  * [Code] Add `{:on_module, bytecode, :none}` trace to compilation tracers
+  * [Enum] Optimize `Enum.concat/1` for lists of lists
+  * [Enum] Add `Enum.slide/3`
+  * [Exception] Better format Elixir exceptions in Erlang
+  * [Inspect] Allow default inspect fun to be set globally with `Inspect.Opts.default_inspect_fun/1`
+  * [IO] Allow `:eof` to be given as limit to `IO.getn/2`
+  * [Kernel] Support the `:sigils` option in `import Mod, only: :sigils` and allow the sigil modifiers to be also digits
+  * [Kernel] Make `get_in` consistently abort and return `nil` when `nil` values are found (previously Elixir would raise an error in this case). This allows a user to use `get_in` as a safe navigation operator.
+  * [Kernel] Improve compilation times by reducing the amount of copies of the AST across compiler processes
+  * [Kernel] Raise if trying to define a module with a slash in its name
+  * [Kernel] Warn when `?\` is used and there is no need for a escape character
+  * [Kernel] Track structs in typespecs as export deps instead of compile-time deps
+  * [Kernel] Add power operator (`**/2`)
+  * [Keyword] Add `Keyword.validate/2`
+  * [Keyword] Implement `Keyword.filter/2` and `Keyword.map/2`
+  * [List] Add `List.keyfind!/3`
+  * [Macro] Add `Macro.prewalker/1` and `Macro.postwalker/1`
+  * [Macro.Env] Add the following reflection functions: `required?/2`, `lookup_import/2`, `fetch_alias/2`, and `fetch_macro_alias/2`
+  * [Map] Implement `Map.filter/2` and `Map.map/2`
+  * [Module] Support `:nillify_clauses` in `Module.get_definition/3`
+  * [Module] Add `Module.attributes_in/1` and `Module.overridables_in/1`
+  * [OptionParser] Add "did you mean?" suggestions to `OptionParser.ParseError` messages
+  * [Record] Add record reflection via `@__records__`
+  * [Task] Add `Task.completed/1`
+  * [Task] Add `Task.ignore/1` to keep a task running but ignoring all of its results
+  * [Task] Reduce the amount of copying `Task.async*` functions
+  * [URI] Add `URI.new/1` and `URI.new!/1`
+
+#### ExUnit
+
+  * [ExUnit] Show hint if comparing different but equivalent strings
+  * [ExUnit.CaptureIO] Add `with_io/3` to return result with captured io
+  * [ExUnit.CaptureLog] Add `with_log/2` to return result with captured logs
+
+#### IEx
+
+  * [IEx.Autocomplete] Add path autocompletion whenever when the cursor follows `"./` or `"/` or `"DRIVER:` where `DRIVER` is a single letter
+  * [IEx.Autocomplete] Add autocompletion for sigils, struct names, and struct fields
+  * [IEx.Helpers] Allow multiple modules to be given to `r/1`
+
+#### Logger
+
+  * [Logger] Add `Logger.put_application_level/2`
+  * [Logger] Print all log levels in accordance to Erlang/OTP. This also means `[warn]` is now shown as `[warning]`
+
+#### Mix
+
+  * [Mix] Add `MIX_INSTALL_FORCE` environment variable support
+  * [Mix] Support `:config` and `:system_env` in `Mix.install/2`
+  * [Mix] Add `Mix.installed?/0`
+  * [Mix.Shell] Add `:default` option to `Mix.Shell.yes?`
+  * [mix archive.install] Run `loadconfig` before building archive
+  * [mix compile] Move Elixir version check to before deps are compiled, in order to give feedback earlier
+  * [mix compile.elixir] Do not recompile files if their modification time change but their contents are still the same and the .beam files are still on disk
+  * [mix compile.elixir] Do not recompile all Elixir sources when Erlang modules change, only dependent ones
+  * [mix compile.elixir] Do not recompile Elixir files if `mix.exs` changes, instead recompile only files using `Mix.Project` or trigger a recompilation if a compiler option changes
+  * [mix compile.elixir] Only recompile needed files when a dependency is added, updated or removed
+  * [mix compile.elixir] Only recompile needed files when a dependency is configured
+  * [mix deps] Add `:subdir` option to git deps
+  * [mix escript.install] Run `loadconfig` before building escript
+  * [mix format] Support `:plugins` in `mix format` that can hook into custom extensions and sigils
+  * [mix format] Add `Mix.Tasks.Format.formatter_for_file/2`
+  * [mix local.rebar] No longer support `sub_dirs` in Rebar 2 to help migration towards Rebar 3
+  * [mix local.rebar] Support `--if-missing` option when installing Rebar
+  * [mix local.rebar] Set `REBAR_PROFILE=prod` when compiling Rebar dependencies
+  * [mix test] Support `--profile-require=time` to profile the time loading test files themselves
+  * [mix test] Allow filtering modules from coverage using regex
+  * [mix test] Allow the exit status of ExUnit to be configured and set the default to 2
+  * [mix test] Exit with a status of 3 when coverage falls below threshold
+  * [mix test] Write failed manifest when suite fails due to --warnings-as-errors
+  * [mix test] Ignore `MIX_TEST_PARTITION` when partitions set to 1
+  * [mix xref] Support multiple sinks and sources in `mix xref graph`
+  * [mix xref] Add `trace` subcommand to print compilation dependencies between files
+  * [mix xref] Add `--fail-above` option to `mix xref`
+  * [mix xref] Add `--label compile-connected` to `mix xref`
+
+### 2. Bug fixes
+
+#### EEx
+
+  * [EEx] Accept comments in EEx between do and the first clause
+  * [EEx] Accept EEx expressions where `->` is followed by newline
+
+#### Elixir
+
+  * [Application] Allow any expression as first argument of `compile_env`
+  * [Application] Warn if `Application.compile_env` or `Application.compile_env!` are called without a require
+  * [Code] Make sure `:static_atoms_encoder` in `Code.string_to_quoted/2` also applies to quoted keyword keys
+  * [Code] Ensure bindings with no context are returned as atoms instead of `{binding, nil}` in eval operations
+  * [Inspect] Fix a bug when inspecting a non-binary bitstring with colors
+  * [Kernel] Reject bidirectional formatting characters in strings and comments
+  * [Kernel] Support escaping of terminators in uppercase sigils heredocs for consistency
+  * [Kernel] Raise if `__CALLER__` or `__ENV__` or `__STACKTRACE__` are used in match
+  * [Kernel] Improve error message on invalid argument for `byte_size` from binary concat
+  * [Kernel] Raise when aliasing non-Elixir modules without `:as`
+  * [Kernel] Allow `unquote_splicing` inside `%{...}` without parens
+  * [Kernel] Ensure that waiting on a struct expansion inside a typespec is correctly tracked as waiting time in the compiler
+  * [Kernel] Correctly parse the atom `.` as a keyword list key
+  * [Kernel] Do not leak variables from the first generator in `with` and `for` special forms
+  * [Kernel] Fix column number on strings with NFD characters
+  * [Kernel] Fix a bug where a combination of dynamic line in `quote` with `unquote` of remote calls would emit invalid AST metadata
+  * [OptionParser] Validate switch types/modifiers early on to give more precise feedback
+  * [Protocol] Add `defdelegate` to the list of unallowed macros inside protocols as protocols do not allow function definitions
+  * [Protocol] Warn if `@callback`, `@macrocallback` and `@optional_callbacks` are defined inside protocol
+  * [Protocol] Ensure protocol metadata is deterministic on consolidation
+  * [Range] Always show step when range is descending
+  * [String] Update Unicode database to version 14.0
+  * [URI] Only percent decode if followed by hex digits (according to https://url.spec.whatwg.org/#percent-decode)
+  * [Version] Ensure proper precedence of `and`/`or` in version requirements
+
+#### ExUnit
+
+  * [ExUnit] Fix formatter and counters from `ExUnit.run/0` to consider all tests in a module whenever if a module's `setup_all` fails
+  * [ExUnit] Allow doctests newlines to be terminated by CRLF
+
+#### IEx
+
+  * [IEx] Fix the loss of `.iex.exs` context after a pry session
+  * [IEx] Stop evaluator before exiting IEx server to avoid evaluators leaking
+
+#### Logger
+
+  * [Logger] Raise clear error message for invalid `:compile_time_purge_matching` configuration
+  * [Logger] Fix a bug where Logger would not reset its discard counter under some scenarios
+
+#### Mix
+
+  * [mix compile.elixir] Track transitive runtime dependencies coming from local/path dependencies
+  * [mix compile.elixir] Recompile file if `@external_resource` is deleted
+  * [mix compile.elixir] Print number of compiling files on all compiler cycles. This will make the `Compiling N files (.ex)` show up multiple times if necessary
+  * [mix deps] Raise if local dep is unavailable while compiling
+  * [mix deps.unlock] Fix blank output when unlocking a dependency that is not locked
+  * [mix local.install] Do not respect `MIX_DEPS_PATH` for install commands
+  * [mix release] Improve release scripts by making sure shell errors cascade (this is done by avoiding exporting and defining variables in a single step)
+  * [mix release] Do not boot release if `RELEASE_COOKIE` is empty
+  * [mix release] Allow releases running as a daemon to be restarted
+  * [mix release] Raise proper error message when non-serializable values are in configs
+  * [mix test] Fix coverage engine to also tag `case`, `cond`, and `receive` branches where the right side is a literal
 
 ### 3. Soft-deprecations (no warnings emitted)
 
 #### Elixir
 
-  * [Kernel] Using `start..stop` to match on ranges is soft-deprecated and will warn on future Elixir versions. Use `start..stop//step` instead
-  * [Kernel] Using `start..stop` to create decreasing ranges is soft-deprecated and will warn on future versions. Use `start..stop//-1` instead
-
-### 4. Hard-deprecations
-
-#### EEx
-
-  * [EEx.Engine] `use EEx.Engine` is deprecated in favor of explicit delegation
-
-#### Elixir
-
-  * [Kernel] The binary operator `^^^` is deprecated. If you are using `Bitwise.^^^/2`, use `Bitwise.bxor/2` instead
-  * [Kernel] Deprecate `@foo()` in favor of `@foo`
-  * [System] Deprecate `System.stacktrace/0` (it was already deprecated outside of catch/rescue and now it is deprecated everywhere)
+  * [Code] Environment options in `Code.eval_quoted/3` and `Code.eval_string/3`, such as `:aliases` and `:tracers`, have been deprecated in favor of passing an environment
+  * [IO] `:all` on `IO.getn` is deprecated in favor of `:eof`
+  * [URI] `URI.parse/1` is deprecated in favor of `URI.new/1` and `URI.new!/1`
 
 #### Mix
 
-  * [mix compile] The `:xref` compiler is deprecated and it has no effect. Please remove it from your mix.exs file.
+  * [mix format] `Mix.Tasks.Format.formatter_opts_for_file/2` is deprecated in favor of `Mix.Tasks.Format.formatter_for_file/2`
 
-## v1.11
+### 4. Hard-deprecations
 
-The CHANGELOG for v1.11 releases can be found [in the v1.11 branch](https://github.com/elixir-lang/elixir/blob/v1.11/CHANGELOG.md).
+#### Elixir
+
+  * [Code] `Code.cursor_context/2` is deprecated, use `Code.Fragment.cursor_context/2` instead
+  * [Macro] `Macro.to_string/2` is deprecated, use `Macro.to_string/1` instead
+  * [System] `System.get_pid/0` is deprecated, use `System.pid/0` instead
+  * [Version] Using `!` or `!=` in version requirements is deprecated, use `~>` or `>=` instead
+
+#### Mix
+
+  * [mix escript.build] `:strip_beam` option is deprecated in favor of `:strip_beams`
+  * [Mix] `:exit_code` in `Mix.raise/2` has been deprecated in favor of `:exit_status`
+  * [Mix.Config] `Mix.Config` is deprecated in favor of `Config` module
+
+## v1.12
+
+The CHANGELOG for v1.12 releases can be found [in the v1.12 branch](https://github.com/elixir-lang/elixir/blob/v1.12/CHANGELOG.md).

CODE_OF_CONDUCT.md

@@ -13,17 +13,23 @@ The goal of the Code of Conduct is to specify a baseline standard of behavior so
 These are the values Elixir developers should aspire to:
 
   * Be friendly and welcoming
-  * Be patient
+  * Be kind
     * Remember that people have varying communication styles and that not everyone is using their native language. (Meaning and tone can be lost in translation.)
+    * Interpret the arguments of others in good faith, do not seek to disagree.
+    * When we do disagree, try to understand why.
   * Be thoughtful
     * Productive communication requires effort. Think about how your words will be interpreted.
     * Remember that sometimes it is best to refrain entirely from commenting.
   * Be respectful
     * In particular, respect differences of opinion. It is important that we resolve disagreements and differing views constructively.
-  * Avoid destructive behavior
-    * Derailing: stay on topic; if you want to talk about something else, start a new conversation.
-    * Unconstructive criticism: don't merely decry the current state of affairs; offer (or at least solicit) suggestions as to how things may be improved.
-    * Snarking (pithy, unproductive, sniping comments).
+  * Be constructive
+    * Avoid derailing: stay on topic; if you want to talk about something else, start a new conversation.
+    * Avoid unconstructive criticism: don't merely decry the current state of affairs; offer — or at least solicit — suggestions as to how things may be improved.
+    * Avoid harsh words and stern tone: we are all aligned towards the well-being of the community and the progress of the ecosystem. Harsh words exclude, demotivate, and lead to unnecessary conflict.
+    * Avoid snarking (pithy, unproductive, sniping comments).
+    * Avoid microaggressions (brief and commonplace verbal, behavioral and environmental indignities that communicate hostile, derogatory or negative slights and insults towards a project, person or group).
+  * Be responsible
+    * What you say and do matters. Take responsibility for your words and actions, including their consequences, whether intended or otherwise.
 
 The following actions are explicitly forbidden:
 
@@ -41,11 +47,11 @@ Explicit enforcement of the Code of Conduct applies to the official mediums oper
 
 * The [official GitHub projects][1] and code reviews.
 * The official elixir-lang mailing lists.
-* The **[#elixir-lang][2]** IRC channel on [Freenode][3].
+* The **[#elixir][2]** IRC channel on [Libera.Chat][3].
 
 Other Elixir activities (such as conferences, meetups, and unofficial forums) are encouraged to adopt this Code of Conduct. Such groups must provide their own contact information.
 
-Project maintainers may remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct.
+Project maintainers may block, remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by emailing: elixir-lang-conduct@googlegroups.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. **All reports will be kept confidential**.
 
@@ -53,8 +59,8 @@ Instances of abusive, harassing, or otherwise unacceptable behavior may be repor
 
 ## Acknowledgements
 
-This document was based on the Code of Conduct from the Go project with parts derived from Django's Code of Conduct, Rust's Code of Conduct and the Contributor Covenant.
+This document was based on the Code of Conduct from the Go project (dated Sep/2021) and the Contributor Covenant (v1.4).
 
 [1]: https://github.com/elixir-lang/
-[2]: https://webchat.freenode.net/?channels=#elixir-lang
-[3]: https://www.freenode.net
+[2]: https://web.libera.chat/#elixir
+[3]: https://libera.chat/

Makefile

@@ -2,7 +2,7 @@ PREFIX ?= /usr/local
 TEST_FILES ?= "*_test.exs"
 SHARE_PREFIX ?= $(PREFIX)/share
 MAN_PREFIX ?= $(SHARE_PREFIX)/man
-#CANONICAL := vMAJOR.MINOR/
+CANONICAL := 1.13/
 CANONICAL ?= master/
 ELIXIRC := bin/elixirc --ignore-module-conflict $(ELIXIRC_OPTS)
 ERLC := erlc -I lib/elixir/include
@@ -28,9 +28,9 @@ SOURCE_DATE_EPOCH_FILE = $(SOURCE_DATE_EPOCH_PATH)/SOURCE_DATE_EPOCH
 #==> Functions
 
 define CHECK_ERLANG_RELEASE
-	erl -noshell -eval '{V,_} = string:to_integer(erlang:system_info(otp_release)), io:fwrite("~s", [is_integer(V) and (V >= 21)])' -s erlang halt | grep -q '^true'; \
+	erl -noshell -eval '{V,_} = string:to_integer(erlang:system_info(otp_release)), io:fwrite("~s", [is_integer(V) and (V >= 22)])' -s erlang halt | grep -q '^true'; \
 		if [ $$? != 0 ]; then \
-		  echo "At least Erlang/OTP 21.0 is required to build Elixir"; \
+		  echo "At least Erlang/OTP 22.0 is required to build Elixir"; \
 		  exit 1; \
 		fi
 endef
@@ -105,7 +105,6 @@ unicode: $(UNICODE)
 $(UNICODE): lib/elixir/unicode/*
 	@ echo "==> unicode (compile)";
 	$(Q) $(ELIXIRC) lib/elixir/unicode/unicode.ex -o lib/elixir/ebin;
-	$(Q) $(ELIXIRC) lib/elixir/unicode/properties.ex -o lib/elixir/ebin;
 	$(Q) $(ELIXIRC) lib/elixir/unicode/tokenizer.ex -o lib/elixir/ebin;
 
 $(eval $(call APP_TEMPLATE,ex_unit,ExUnit))
@@ -172,6 +171,7 @@ clean_residual_files:
 	rm -rf lib/mix/test/fixtures/git_rebar/
 	rm -rf lib/mix/test/fixtures/git_repo/
 	rm -rf lib/mix/test/fixtures/git_sparse_repo/
+	rm -rf lib/mix/test/fixtures/archive/ebin/
 	rm -f erl_crash.dump
 	$(Q) $(MAKE) clean_man
 
@@ -180,7 +180,7 @@ clean_residual_files:
 LOGO_PATH = $(shell test -f ../docs/logo.png && echo "--logo ../docs/logo.png")
 SOURCE_REF = $(shell tag="$(call GIT_TAG)" revision="$(call GIT_REVISION)"; echo "$${tag:-$$revision}")
 DOCS_FORMAT = html
-COMPILE_DOCS = bin/elixir ../ex_doc/bin/ex_doc "$(1)" "$(VERSION)" "lib/$(2)/ebin" --main "$(3)" --source-url "https://github.com/elixir-lang/elixir" --source-ref "$(call SOURCE_REF)" $(call LOGO_PATH) --output doc/$(2) --canonical "https://hexdocs.pm/$(2)/$(CANONICAL)" --homepage-url "https://elixir-lang.org/docs.html" --formatter "$(DOCS_FORMAT)" $(4)
+COMPILE_DOCS = CANONICAL=$(CANONICAL) bin/elixir ../ex_doc/bin/ex_doc "$(1)" "$(VERSION)" "lib/$(2)/ebin" --main "$(3)" --source-url "https://github.com/elixir-lang/elixir" --source-ref "$(call SOURCE_REF)" $(call LOGO_PATH) --output doc/$(2) --canonical "https://hexdocs.pm/$(2)/$(CANONICAL)" --homepage-url "https://elixir-lang.org/docs.html" --formatter "$(DOCS_FORMAT)" $(4)
 
 docs: compile ../ex_doc/bin/ex_doc docs_elixir docs_eex docs_mix docs_iex docs_ex_unit docs_logger
 
@@ -192,27 +192,27 @@ docs_elixir: compile ../ex_doc/bin/ex_doc
 docs_eex: compile ../ex_doc/bin/ex_doc
 	@ echo "==> ex_doc (eex)"
 	$(Q) rm -rf doc/eex
-	$(call COMPILE_DOCS,EEx,eex,EEx)
+	$(call COMPILE_DOCS,EEx,eex,EEx,--config "lib/mix/docs.exs")
 
 docs_mix: compile ../ex_doc/bin/ex_doc
 	@ echo "==> ex_doc (mix)"
 	$(Q) rm -rf doc/mix
-	$(call COMPILE_DOCS,Mix,mix,Mix)
+	$(call COMPILE_DOCS,Mix,mix,Mix,--config "lib/mix/docs.exs")
 
 docs_iex: compile ../ex_doc/bin/ex_doc
 	@ echo "==> ex_doc (iex)"
 	$(Q) rm -rf doc/iex
-	$(call COMPILE_DOCS,IEx,iex,IEx)
+	$(call COMPILE_DOCS,IEx,iex,IEx,--config "lib/mix/docs.exs")
 
 docs_ex_unit: compile ../ex_doc/bin/ex_doc
 	@ echo "==> ex_doc (ex_unit)"
 	$(Q) rm -rf doc/ex_unit
-	$(call COMPILE_DOCS,ExUnit,ex_unit,ExUnit)
+	$(call COMPILE_DOCS,ExUnit,ex_unit,ExUnit,--config "lib/mix/docs.exs")
 
 docs_logger: compile ../ex_doc/bin/ex_doc
 	@ echo "==> ex_doc (logger)"
 	$(Q) rm -rf doc/logger
-	$(call COMPILE_DOCS,Logger,logger,Logger)
+	$(call COMPILE_DOCS,Logger,logger,Logger,--config "lib/mix/docs.exs")
 
 ../ex_doc/bin/ex_doc:
 	@ echo "ex_doc is not found in ../ex_doc as expected. See README for more information."
@@ -278,7 +278,7 @@ $(TEST_EBIN)/%.beam: $(TEST_ERL)/%.erl
 	$(Q) mkdir -p $(TEST_EBIN)
 	$(Q) $(ERLC) -o $(TEST_EBIN) $<
 
-test_elixir: test_stdlib test_ex_unit test_logger test_mix test_eex test_iex
+test_elixir: test_stdlib test_ex_unit test_logger test_eex test_iex test_mix
 
 test_stdlib: compile
 	@ echo "==> elixir (ex_unit)"

NOTICE

@@ -22,6 +22,7 @@ limitations under the License.
 == All other files
 
 Copyright 2012 Plataformatec
+Copyright 2021 The Elixir Team
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

README.md

@@ -11,11 +11,14 @@ For more about Elixir, installation and documentation,
 ## Policies
 
 New releases are announced in the [announcement mailing list][8].
-You can subscribe by sending an email to elixir-lang-ann+subscribe@googlegroups.com and replying to the confirmation email.
+You can subscribe by sending an email to elixir-lang-ann+subscribe@googlegroups.com
+and replying to the confirmation email.
 
-All security releases [will be tagged with `[security]`][10]. For more information, please read our [Security Policy][9].
+All security releases [will be tagged with `[security]`][10]. For more
+information, please read our [Security Policy][9].
 
-All interactions in our official communication channels follow our [Code of Conduct][1].
+All interactions in our official communication channels follow our
+[Code of Conduct][1].
 
 ## Bug reports
 
@@ -23,13 +26,56 @@ For reporting bugs, [visit our issue tracker][2] and follow the steps
 for reporting a new issue. **Please disclose security vulnerabilities
 privately at elixir-security@googlegroups.com**.
 
+## Issues tracker management
+
+All currently open bugs related to the Elixir repository are listed
+in the issues tracker. The Elixir team uses the issues tracker to focus
+on *actionable items*, including planned enhancements in the short- and
+medium-term. We also do our best to label entries for clarity and to ease
+collaboration.
+
+Our *actionable item policy* has some important consequences, such as:
+
+  * Proposing new features as well as request for support, help, and
+    guidance must be done in their own spaces, detailed next.
+
+  * Issues where we have identified to be outside of Elixir scope,
+    such as a bug upstream, will be closed (and requested to be moved
+    elsewhere if appropriate).
+
+  * We actively close unrelated and non-actionable issues to keep the
+    issues tracker tidy. However, we may get things wrong from time to
+    time, so we are glad to revisit issues and reopen if necessary.
+
+Keep the tone positive and be kind! For more information, see the
+[Code of Conduct][1].
+
+### Proposing new features
+
+For proposing new features, please start a discussion in the
+[Elixir Core mailing list][3]. Keep in mind that it is your responsibility
+to argue and explain why a feature is useful and how it will impact the
+codebase and the community.
+
+Once a proposal is accepted, it will be added to [the issue tracker][2].
+Features and bug fixes that have already been merged and will be included
+in the next release are then "closed" and added to the [changelog][7].
+
+### Discussions, support, and help
+
+For general discussions, support, and help, please use many of the community
+spaces [listed on the sidebar of the Elixir website](https://elixir-lang.org/),
+such as forums, chat platforms, etc, where the wider community will be available
+to help you.
+
 ## Compiling from source
 
 For the many different ways to install Elixir,
 [see our installation instructions on the website](https://elixir-lang.org/install.html).
-To compile from source, you can follow the steps below.
+However, if you want to contribute to Elixir, you will need to compile from source.
 
-First, [install Erlang](https://elixir-lang.org/install.html#installing-erlang). After that, clone this repository to your machine, compile and test it:
+First, [install Erlang](https://elixir-lang.org/install.html#installing-erlang).
+After that, clone this repository to your machine, compile and test it:
 
 ```sh
 git clone https://github.com/elixir-lang/elixir.git
@@ -41,37 +87,13 @@ make clean test
 [this article includes important notes for compiling Elixir from source
 on Windows](https://github.com/elixir-lang/elixir/wiki/Windows).
 
+In case you want to use this Elixir version as your system version,
+you need to add the `bin` directory to [your PATH environment variable](https://elixir-lang.org/install.html#setting-path-environment-variable).
+
 If Elixir fails to build (specifically when pulling in a new version via
 `git`), be sure to remove any previous build artifacts by running
 `make clean`, then `make test`.
 
-If tests pass, you can use Interactive Elixir by running `bin/iex` in your terminal.
-
-However, if tests fail, it is likely that you have an outdated Erlang/OTP version
-(Elixir requires Erlang/OTP 21.0 or later). You can check your Erlang/OTP version
-by calling `erl` in the command line. You will see some information similar to:
-
-    Erlang/OTP 21 [erts-9.0] [smp:2:2] [async-threads:10] [kernel-poll:false]
-
-If you have properly set up your dependencies and tests still fail,
-you may want to open up a bug report, as explained next.
-
-## Proposing new features
-
-For proposing new features, please start a discussion in the
-[Elixir Core mailing list][3]. Keep in mind that it is your responsibility
-to argue and explain why a feature is useful and how it will impact the
-codebase and the community.
-
-Once a proposal is accepted, it will be added to [the issue tracker][2].
-The issue tracker focuses on *actionable items* and it holds a list of
-upcoming enhancements and pending bugs. All entries in the tracker are
-tagged for clarity and to ease collaboration.
-
-Features and bug fixes that have already been merged and will be included
-in the next release are marked as "closed" in the issue tracker and are
-added to the [changelog][7].
-
 ## Contributing
 
 We welcome everyone to contribute to Elixir. To do so, there are a few
@@ -123,7 +145,7 @@ make clean_elixir compile
 
 Similarly, if you can't get Elixir to compile or the tests to pass after
 updating an existing checkout, run `make clean compile`. You can check
-[the official build status on Cirrus CI](https://cirrus-ci.com/github/elixir-lang/elixir).
+[the official build status](https://github.com/elixir-lang/elixir/actions/workflows/ci.yml).
 More tasks can be found by reading the [Makefile](Makefile).
 
 With tests running and passing, you are ready to contribute to Elixir and
@@ -190,13 +212,13 @@ and `mix` under the `doc` directory. If you are planning to contribute documenta
   * [Issue tracker][2]
   * [Changelog][7]
   * [Security Policy][9]
-  * **[#elixir-lang][4]** on [Freenode][5] IRC
+  * **[#elixir][4]** on [Libera.Chat][5] IRC
 
   [1]: CODE_OF_CONDUCT.md
   [2]: https://github.com/elixir-lang/elixir/issues
   [3]: https://groups.google.com/group/elixir-lang-core
-  [4]: https://webchat.freenode.net/?channels=#elixir-lang
-  [5]: https://www.freenode.net
+  [4]: https://web.libera.chat/#elixir
+  [5]: https://libera.chat
   [6]: https://elixir-lang.org/docs.html
   [7]: CHANGELOG.md
   [8]: https://groups.google.com/group/elixir-lang-ann
@@ -205,7 +227,7 @@ and `mix` under the `doc` directory. If you are planning to contribute documenta
 
 ## License
 
-"Elixir" and the Elixir logo are copyright (c) 2012 Plataformatec.
+"Elixir" and the Elixir logo are registered trademarks of The Elixir Team.
 
 Elixir source code is released under Apache License 2.0.
 

RELEASE.md

@@ -4,7 +4,7 @@
 
 1. Ensure you are running on the oldest supported Erlang version
 
-2. Update version in /VERSION
+2. Update version in /VERSION, bin/elixir and bin/elixir.bat
 
 3. Ensure /CHANGELOG.md is updated, versioned and add the current date
 
@@ -32,11 +32,11 @@
 
 2. Update tables in /SECURITY.md and "Compatibility and Deprecations"
 
-3. Commit "Prepare vMAJOR.MINOR for release"
+3. Commit "Branch out vMAJOR.MINOR"
 
 ### Back in master
 
-1. Bump /VERSION file
+1. Bump /VERSION file, bin/elixir and bin/elixir.bat
 
 2. Start new /CHANGELOG.md
 

SECURITY.md

@@ -4,14 +4,13 @@
 
 Elixir applies bug fixes only to the latest minor branch. Security patches are available for the last 5 minor branches:
 
-| Elixir version | Support
-| -------------- | ------------------------------
-| 1.12           | Development
-| 1.11           | Bug fixes and security patches
-| 1.10           | Security patches only
-| 1.9            | Security patches only
-| 1.8            | Security patches only
-| 1.7            | Security patches only
+Elixir version | Support
+:------------- | :-----------------------------
+1.13           | Bug fixes and security patches
+1.12           | Security patches only
+1.11           | Security patches only
+1.10           | Security patches only
+1.9            | Security patches only
 
 ## Announcements
 

VERSION

@@ -1 +1 @@
-1.12.0-dev
+1.13.4

bin/elixir

@@ -1,20 +1,22 @@
 #!/bin/sh
 set -e
 
-if [ $# -eq 0 ] || [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
+ELIXIR_VERSION=1.13.4
+
+if [ $# -eq 0 ] || { [ $# -eq 1 ] && { [ "$1" = "--help" ] || [ "$1" = "-h" ]; }; }; then
   cat <<USAGE >&2
 Usage: $(basename "$0") [options] [.exs file] [data]
 
 ## General options
 
   -e "COMMAND"                 Evaluates the given command (*)
-  -h, --help                   Prints this message and exits
+  -h, --help                   Prints this message (standalone)
   -r "FILE"                    Requires the given files/patterns (*)
-  -S SCRIPT                    Finds and executes the given script in \$PATH
+  -S SCRIPT                    Finds and executes the given script in \$PATH
   -pr "FILE"                   Requires the given files/patterns in parallel (*)
   -pa "PATH"                   Prepends the given path to Erlang code path (*)
   -pz "PATH"                   Appends the given path to Erlang code path (*)
-  -v, --version                Prints Elixir version and exits
+  -v, --version                Prints Erlang/OTP and Elixir versions (standalone)
 
   --app APP                    Starts the given app and its dependencies (*)
   --erl "SWITCHES"             Switches to be passed down to Erlang (*)
@@ -22,6 +24,7 @@ Usage: $(basename "$0") [options] [.exs file] [data]
   --logger-otp-reports BOOL    Enables or disables OTP reporting
   --logger-sasl-reports BOOL   Enables or disables SASL reporting
   --no-halt                    Does not halt the Erlang VM after execution
+  --short-version              Prints Elixir version (standalone)
   --werl                       Uses Erlang's Windows shell GUI (Windows only)
 
 Options given after the .exs file or -- are passed down to the executed code.
@@ -52,6 +55,7 @@ It will attempt to create PIPEDIR and LOGDIR if they don't exist.
 See run_erl to learn more. To reattach, run: to_erl PIPEDIR.
 
 ** Options marked with (*) can be given more than once.
+** Standalone options can't be combined with other options.
 USAGE
   exit 1
 fi
@@ -66,6 +70,11 @@ readlink_f () {
   fi
 }
 
+if [ $# -eq 1 ] && [ "$1" = "--short-version" ]; then
+  echo "$ELIXIR_VERSION"
+  exit 0
+fi
+
 # Stores static Erlang arguments and --erl (which is passed as is)
 ERL=""
 
@@ -210,7 +219,11 @@ if [ "$OS" != "Windows_NT" ] && [ -z "$NO_COLOR" ]; then
   if test -t 1 -a -t 2; then ERL="-elixir ansi_enabled true $ERL"; fi
 fi
 
+# One MAY change ERTS_BIN= but you MUST NOT change
+# ERTS_BIN=$ERTS_BIN as it is handled by Elixir releases.
 ERTS_BIN=
+ERTS_BIN="$ERTS_BIN"
+
 set -- "$ERTS_BIN$ERL_EXEC" -pa "$SCRIPT_PATH"/../lib/*/ebin $ELIXIR_ERL_OPTIONS $ERL "$@"
 
 if [ -n "$RUN_ERL_PIPE" ]; then

bin/elixir.bat

@@ -1,10 +1,14 @@
 @if defined ELIXIR_CLI_ECHO (@echo on) else (@echo off)
+
+set ELIXIR_VERSION=1.13.4
+
 setlocal enabledelayedexpansion
-if    ""%1""==""""       goto documentation
-if /I ""%1""==""--help"" goto documentation
-if /I ""%1""==""-h""     goto documentation
-if /I ""%1""==""/h""     goto documentation
-if    ""%1""==""/?""     goto documentation
+if    ""%1""==""""                if ""%2""=="""" goto documentation
+if /I ""%1""==""--help""          if ""%2""=="""" goto documentation
+if /I ""%1""==""-h""              if ""%2""=="""" goto documentation
+if /I ""%1""==""/h""              if ""%2""=="""" goto documentation
+if    ""%1""==""/?""              if ""%2""=="""" goto documentation
+if /I ""%1""==""--short-version"" if ""%2""=="""" goto shortversion
 goto parseopts
 
 :documentation
@@ -13,13 +17,13 @@ echo.
 echo ## General options
 echo.
 echo   -e "COMMAND"                 Evaluates the given command (*)
-echo   -h, --help                   Prints this message and exits
+echo   -h, --help                   Prints this message (standalone)
 echo   -r "FILE"                    Requires the given files/patterns (*)
 echo   -S SCRIPT                    Finds and executes the given script in $PATH
 echo   -pr "FILE"                   Requires the given files/patterns in parallel (*)
 echo   -pa "PATH"                   Prepends the given path to Erlang code path (*)
 echo   -pz "PATH"                   Appends the given path to Erlang code path (*)
-echo   -v, --version                Prints Elixir version and exits
+echo   -v, --version                Prints Erlang/OTP and Elixir versions (standalone)
 echo.
 echo   --app APP                    Starts the given app and its dependencies (*)
 echo   --erl "SWITCHES"             Switches to be passed down to Erlang (*)
@@ -27,6 +31,7 @@ echo   --eval "COMMAND"             Evaluates the given command, same as -e (*)
 echo   --logger-otp-reports BOOL    Enables or disables OTP reporting
 echo   --logger-sasl-reports BOOL   Enables or disables SASL reporting
 echo   --no-halt                    Does not halt the Erlang VM after execution
+echo   --short-version              Prints Elixir version (standalone)
 echo   --werl                       Uses Erlang's Windows shell GUI (Windows only)
 echo.
 echo Options given after the .exs file or -- are passed down to the executed code.
@@ -54,6 +59,11 @@ echo.
 echo --pipe-to is not supported on Windows. If set, Elixir won't boot.
 echo.
 echo ** Options marked with (*) can be given more than once.
+echo ** Standalone options can't be combined with other options.
+goto end
+
+:shortversion
+echo !ELIXIR_VERSION!
 goto end
 
 :parseopts
@@ -78,6 +88,7 @@ set SCRIPT_PATH=%~dp0
 
 rem Designates the path to the ERTS system
 set ERTS_BIN=
+set ERTS_BIN=!ERTS_BIN!
 
 rem Recursive loop called for each parameter that parses the cmd line parameters
 :startloop
@@ -125,6 +136,7 @@ if ""==!par:-pr=!         (set "parsElixir=!parsElixir! -pr %1" && shift && goto
 if ""==!par:-pa=!         (set "parsElixir=!parsElixir! -pa %1" && shift && goto startloop)
 if ""==!par:-pz=!         (set "parsElixir=!parsElixir! -pz %1" && shift && goto startloop)
 if ""==!par:-v=!          (set "parsElixir=!parsElixir! -v" && goto startloop)
+if ""==!par:--version=!   (set "parsElixir=!parsElixir! --version" && goto startloop)
 if ""==!par:--app=!       (set "parsElixir=!parsElixir! --app %1" && shift && goto startloop)
 if ""==!par:--no-halt=!   (set "parsElixir=!parsElixir! --no-halt" && goto startloop)
 if ""==!par:--remsh=!     (set "parsElixir=!parsElixir! --remsh %1" && shift && goto startloop)
@@ -168,4 +180,4 @@ if defined useWerl (
   "!ERTS_BIN!erl.exe" !ext_libs! !ELIXIR_ERL_OPTIONS! !parsErlang! !beforeExtra! -extra !parsElixir!
 )
 :end
-endlocal
+endlocal

bin/elixirc

@@ -7,14 +7,14 @@ Usage: $(basename "$0") [elixir switches] [compiler switches] [.ex files]
 
   -h, --help                Prints this message and exits
   -o                        The directory to output compiled files
-  -v, --version             Prints Elixir version and exits
+  -v, --version             Prints Elixir version and exits (standalone)
 
   --ignore-module-conflict  Does not emit warnings if a module was previously defined
   --no-debug-info           Does not attach debug info to compiled modules
   --no-docs                 Does not attach documentation to compiled modules
   --profile time            Profile the time to compile modules
   --verbose                 Prints compilation status
-  --warnings-as-errors      Treats warnings as errors and return non-zero exit code
+  --warnings-as-errors      Treats warnings as errors and return non-zero exit status
 
 Options given after -- are passed down to the executed code.
 Options can be passed to the Erlang runtime using \$ELIXIR_ERL_OPTIONS.

bin/elixirc.bat

@@ -16,14 +16,14 @@ echo Usage: %~nx0 [elixir switches] [compiler switches] [.ex files]
 echo.
 echo   -h, --help                Prints this message and exits
 echo   -o                        The directory to output compiled files
-echo   -v, --version             Prints Elixir version and exits
+echo   -v, --version             Prints Elixir version and exits (standalone)
 echo.
 echo   --ignore-module-conflict  Does not emit warnings if a module was previously defined
 echo   --no-debug-info           Does not attach debug info to compiled modules
 echo   --no-docs                 Does not attach documentation to compiled modules
 echo   --profile time            Profile the time to compile modules
 echo   --verbose                 Prints compilation status
-echo   --warnings-as-errors      Treats warnings as errors and returns non-zero exit code
+echo   --warnings-as-errors      Treats warnings as errors and returns non-zero exit status
 echo.
 echo ** Options given after -- are passed down to the executed code
 echo ** Options can be passed to the Erlang runtime using ELIXIR_ERL_OPTIONS

lib/eex/lib/eex.ex

@@ -48,6 +48,10 @@ defmodule EEx do
     * `:trim` - if `true`, trims whitespace left and right of quotation as
       long as at least one newline is present. All subsequent newlines and
       spaces are removed but one newline is retained. Defaults to `false`.
+    * `:parser_options` - (since: 1.13.0) allow customizing the parsed code that is generated.
+      See `Code.string_to_quoted/2` for available options. Note that the options
+      `:file`, `:line` and `:column` are ignored if passed in.
+      Defaults to `Code.get_compiler_option(:parser_options)` (which defaults to `[]` if not set).
 
   ## Engine
 

lib/eex/lib/eex/compiler.ex

@@ -16,6 +16,7 @@ defmodule EEx.Compiler do
     column = 1
     indentation = opts[:indentation] || 0
     trim = opts[:trim] || false
+    parser_options = opts[:parser_options] || Code.get_compiler_option(:parser_options)
     tokenizer_options = %{trim: trim, indentation: indentation}
 
     case EEx.Tokenizer.tokenize(source, line, column, tokenizer_options) do
@@ -27,7 +28,7 @@ defmodule EEx.Compiler do
           quoted: [],
           start_line: nil,
           start_column: nil,
-          parser_options: Code.get_compiler_option(:parser_options)
+          parser_options: parser_options
         }
 
         init = state.engine.init(opts)
@@ -71,10 +72,11 @@ defmodule EEx.Compiler do
       message =
         "the contents of this expression won't be output unless the EEx block starts with \"<%=\""
 
-      :elixir_errors.erl_warn(start_line, state.file, message)
+      :elixir_errors.erl_warn({start_line, start_column}, state.file, message)
     end
 
-    {contents, line, rest} = look_ahead_middle(rest, start_line, chars)
+    {rest, line, contents} =
+      look_ahead_middle(rest, start_line, chars) || {rest, start_line, chars}
 
     {contents, rest} =
       generate_buffer(
@@ -115,7 +117,7 @@ defmodule EEx.Compiler do
       "unexpected beginning of EEx tag \"<%#{modifier}\" on \"<%#{modifier}#{chars}%>\", " <>
         "please remove \"#{modifier}\" accordingly"
 
-    :elixir_errors.erl_warn(line, state.file, message)
+    :elixir_errors.erl_warn({line, column}, state.file, message)
     generate_buffer([{:middle_expr, line, column, '', chars} | t], buffer, scope, state)
     # TODO: Make this an error on Elixir v2.0 since it accidentally worked previously.
     # raise EEx.SyntaxError, message: message, file: state.file, line: line
@@ -153,7 +155,7 @@ defmodule EEx.Compiler do
       "unexpected beginning of EEx tag \"<%#{modifier}\" on end of " <>
         "expression \"<%#{modifier}#{chars}%>\", please remove \"#{modifier}\" accordingly"
 
-    :elixir_errors.erl_warn(line, state.file, message)
+    :elixir_errors.erl_warn({line, column}, state.file, message)
     generate_buffer([{:end_expr, line, column, '', chars} | t], buffer, scope, state)
     # TODO: Make this an error on Elixir v2.0 since it accidentally worked previously.
     # raise EEx.SyntaxError, message: message, file: state.file, line: line, column: column
@@ -193,24 +195,20 @@ defmodule EEx.Compiler do
 
   # Look middle expressions that immediately follow a start_expr
 
-  defp look_ahead_middle(
-         [{:text, _, _, text}, {:middle_expr, line, _, _, chars} | rest] = tokens,
-         start,
-         contents
-       ) do
+  defp look_ahead_middle([{:text, _, _, text} | rest], start, contents) do
     if only_spaces?(text) do
-      {contents ++ text ++ chars, line, rest}
+      look_ahead_middle(rest, start, contents ++ text)
     else
-      {contents, start, tokens}
+      nil
     end
   end
 
   defp look_ahead_middle([{:middle_expr, line, _column, _, chars} | rest], _start, contents) do
-    {contents ++ chars, line, rest}
+    {rest, line, contents ++ chars}
   end
 
-  defp look_ahead_middle(tokens, start, contents) do
-    {contents, start, tokens}
+  defp look_ahead_middle(_tokens, _start, _contents) do
+    nil
   end
 
   defp only_spaces?(chars) do

lib/eex/lib/eex/tokenizer.ex

@@ -71,8 +71,15 @@ defmodule EEx.Tokenizer do
       {:ok, expr, new_line, new_column, rest} ->
         {key, expr} =
           case :elixir_tokenizer.tokenize(expr, 1, file: "eex", check_terminators: false) do
-            {:ok, tokens} -> token_key(tokens, expr)
-            {:error, _, _, _} -> {:expr, expr}
+            {:ok, _line, _column, warnings, tokens} ->
+              Enum.each(Enum.reverse(warnings), fn {location, file, msg} ->
+                :elixir_errors.erl_warn(location, file, msg)
+              end)
+
+              token_key(tokens, expr)
+
+            {:error, _, _, _, _} ->
+              {:expr, expr}
           end
 
         {rest, new_line, new_column, buffer} =
@@ -127,7 +134,7 @@ defmodule EEx.Tokenizer do
 
   # Receives tokens and check if it is a start, middle or an end token.
   defp token_key(tokens, expr) do
-    case {tokens, Enum.reverse(tokens)} do
+    case {tokens, tokens |> Enum.reverse() |> drop_eol()} do
       {[{:end, _} | _], [{:do, _} | _]} ->
         {:middle_expr, expr}
 
@@ -158,6 +165,9 @@ defmodule EEx.Tokenizer do
     end
   end
 
+  defp drop_eol([{:eol, _} | rest]), do: drop_eol(rest)
+  defp drop_eol(rest), do: rest
+
   defp maybe_append_space([?\s]), do: [?\s]
   defp maybe_append_space([h]), do: [h, ?\s]
   defp maybe_append_space([h | t]), do: [h | maybe_append_space(t)]

lib/eex/test/eex/tokenizer_test.exs

@@ -64,7 +64,7 @@ defmodule EEx.TokenizerTest do
              {:ok, [{:text, 1, 1, 'foo <% true %>'}, {:eof, 1, 16}]}
   end
 
-  test "quotation with do/end" do
+  test "quotation with do-end" do
     assert T.tokenize('foo <%% true do %>bar<%% end %>', 1, 1, @opts) ==
              {:ok, [{:text, 1, 1, 'foo <% true do %>bar<% end %>'}, {:eof, 1, 32}]}
   end
@@ -91,7 +91,7 @@ defmodule EEx.TokenizerTest do
     assert T.tokenize('<%%% a <%%= b %> c %>', 1, 1, @opts) == {:ok, exprs}
   end
 
-  test "eex comments" do
+  test "EEx comments" do
     exprs = [
       {:text, 1, 1, 'foo '},
       {:eof, 1, 16}
@@ -100,7 +100,7 @@ defmodule EEx.TokenizerTest do
     assert T.tokenize('foo <%# true %>', 1, 1, @opts) == {:ok, exprs}
   end
 
-  test "eex comments with do/end" do
+  test "EEx comments with do-end" do
     exprs = [
       {:text, 1, 1, 'foo '},
       {:text, 1, 19, 'bar'},
@@ -110,7 +110,29 @@ defmodule EEx.TokenizerTest do
     assert T.tokenize('foo <%# true do %>bar<%# end %>', 1, 1, @opts) == {:ok, exprs}
   end
 
-  test "elixir comments" do
+  test "EEx comments inside do-end" do
+    exprs = [
+      {:start_expr, 1, 1, '', ' if true do '},
+      {:text, 1, 31, 'bar'},
+      {:end_expr, 1, 34, [], ' end '},
+      {:eof, 1, 43}
+    ]
+
+    assert T.tokenize('<% if true do %><%# comment %>bar<% end %>', 1, 1, @opts) == {:ok, exprs}
+
+    exprs = [
+      {:start_expr, 1, 1, [], ' case true do '},
+      {:middle_expr, 1, 33, '', ' true -> '},
+      {:text, 1, 46, 'bar'},
+      {:end_expr, 1, 49, [], ' end '},
+      {:eof, 1, 58}
+    ]
+
+    assert T.tokenize('<% case true do %><%# comment %><% true -> %>bar<% end %>', 1, 1, @opts) ==
+             {:ok, exprs}
+  end
+
+  test "Elixir comments" do
     exprs = [
       {:text, 1, 1, 'foo '},
       {:expr, 1, 5, [], ' true # this is a boolean '},
@@ -120,7 +142,7 @@ defmodule EEx.TokenizerTest do
     assert T.tokenize('foo <% true # this is a boolean %>', 1, 1, @opts) == {:ok, exprs}
   end
 
-  test "elixir comments with do/end" do
+  test "Elixir comments with do-end" do
     exprs = [
       {:start_expr, 1, 1, [], ' if true do # startif '},
       {:text, 1, 27, 'text'},
@@ -160,7 +182,19 @@ defmodule EEx.TokenizerTest do
              {:ok, exprs}
   end
 
-  test "strings with multiple callbacks" do
+  test "strings with fn-end with newline" do
+    exprs = [
+      {:start_expr, 1, 1, '=', ' a fn ->\n'},
+      {:text, 2, 3, 'foo'},
+      {:end_expr, 2, 6, [], ' end '},
+      {:eof, 2, 15}
+    ]
+
+    assert T.tokenize('<%= a fn ->\n%>foo<% end %>', 1, 1, @opts) ==
+             {:ok, exprs}
+  end
+
+  test "strings with multiple fn-end" do
     exprs = [
       {:start_expr, 1, 1, '=', ' a fn -> '},
       {:text, 1, 15, 'foo'},
@@ -174,7 +208,7 @@ defmodule EEx.TokenizerTest do
              {:ok, exprs}
   end
 
-  test "strings with callback followed by do block" do
+  test "strings with fn-end followed by do block" do
     exprs = [
       {:start_expr, 1, 1, '=', ' a fn -> '},
       {:text, 1, 15, 'foo'},

lib/eex/test/eex_test.exs

@@ -198,6 +198,15 @@ defmodule EExTest do
       assert_eval("foo baz", "foo <%= if false do %>bar<% else %>baz<% end %>")
     end
 
+    test "embedded code with comments in do end" do
+      assert_eval("foo bar", "foo <%= case true do %><%# comment %><% true -> %>bar<% end %>")
+
+      assert_eval(
+        "foo\n\nbar\n",
+        "foo\n<%= case true do %>\n<%# comment %>\n<% true -> %>\nbar\n<% end %>"
+      )
+    end
+
     test "embedded code with nested do end" do
       assert_eval("foo bar", "foo <%= if true do %><%= if true do %>bar<% end %><% end %>")
     end
@@ -215,6 +224,11 @@ defmodule EExTest do
         "<%= Enum.map([1, 2, 3], fn x -> %> <%= 100 + x %> <% end) %>"
       )
 
+      assert_eval(
+        " 101  102  103 ",
+        "<%= Enum.map([1, 2, 3], fn x ->\n%> <%= 100 + x %> <% end) %>"
+      )
+
       assert_eval(
         " 101  102  103 ",
         "<%= apply Enum, :map, [[1, 2, 3], fn x -> %> <%= 100 + x %> <% end] %>"
@@ -718,6 +732,16 @@ defmodule EExTest do
     end
   end
 
+  describe "parser options" do
+    test "customizes parsed code" do
+      atoms_encoder = fn "not_jose", _ -> {:ok, :jose} end
+
+      assert_eval("valid", "<%= not_jose %>", [jose: "valid"],
+        parser_options: [static_atoms_encoder: atoms_encoder]
+      )
+    end
+  end
+
   defp assert_eval(expected, actual, binding \\ [], opts \\ []) do
     opts = Keyword.merge([file: __ENV__.file, engine: opts[:engine] || EEx.Engine], opts)
     result = EEx.eval_string(actual, binding, opts)

lib/elixir/docs.exs

@@ -1,6 +1,16 @@
 # Returns config for Elixir docs
+
+canonical = System.fetch_env!("CANONICAL")
+
 [
   extras: Path.wildcard("lib/elixir/pages/*.md") ++ ["CHANGELOG.md"],
+  deps: [
+    eex: "https://hexdocs.pm/eex/#{canonical}",
+    ex_unit: "https://hexdocs.pm/ex_unit/#{canonical}",
+    iex: "https://hexdocs.pm/iex/#{canonical}",
+    logger: "https://hexdocs.pm/logger/#{canonical}",
+    mix: "https://hexdocs.pm/mix/#{canonical}"
+  ],
   groups_for_functions: [
     Guards: &(&1[:guard] == true)
   ],
@@ -86,6 +96,7 @@
     ],
     "Code & Macros": [
       Code,
+      Code.Fragment,
       Kernel.ParallelCompiler,
       Macro,
       Macro.Env

lib/elixir/lib/access.ex

@@ -99,16 +99,15 @@ defmodule Access do
   @type key :: any
   @type value :: any
 
-  @type get_fun(data, current_value) ::
-          (:get, data, (term -> term) ->
-             {current_value, new_data :: container})
+  @type get_fun(data) ::
+          (:get, data, (term -> term) -> new_data :: container)
 
   @type get_and_update_fun(data, current_value) ::
           (:get_and_update, data, (term -> term) ->
              {current_value, new_data :: container} | :pop)
 
   @type access_fun(data, current_value) ::
-          get_fun(data, current_value) | get_and_update_fun(data, current_value)
+          get_fun(data) | get_and_update_fun(data, current_value)
 
   @doc """
   Invoked in order to access the value stored under `key` in the given term `term`.
@@ -446,9 +445,6 @@ defmodule Access do
 
   An error is raised if the accessed structure is not a map or a struct:
 
-      iex> get_in(nil, [Access.key(:foo)])
-      ** (BadMapError) expected a map, got: nil
-
       iex> get_in([], [Access.key(:foo)])
       ** (BadMapError) expected a map, got: []
 

lib/elixir/lib/application.ex

@@ -42,12 +42,16 @@ defmodule Application do
       end
 
   In Mix projects, the environment of the application and its dependencies can
-  be overridden via the `config/config.exs` file. For example, someone using
-  your application can override its `:db_host` environment variable as follows:
+  be overridden via the `config/config.exs` and `config/runtime.exs` files. The
+  former is loaded at build-time, before your code compiles, and the latter at
+  runtime, just before your app starts. For example, someone using your application
+  can override its `:db_host` environment variable as follows:
 
       import Config
       config :my_app, :db_host, "db.local"
 
+  See the "Configuration" section in the `Mix` module for more information.
+
   You can also change the application environment dynamically by using functions
   such as `put_env/3` and `delete_env/2`. However, as a rule of thumb, each application
   is responsible for its own environment. Please do not use the functions in this
@@ -96,6 +100,7 @@ defmodule Application do
   first choice. However, if you really have to read the application environment
   during compilation, we recommend you to use `compile_env/3` instead:
 
+      require Application
       @db_host Application.compile_env(:my_app, :db_host, "db.local")
 
   By using `compile_env/3`, tools like Mix will store the values used during
@@ -385,6 +390,7 @@ defmodule Application do
     :maxT,
     :registered,
     :included_applications,
+    :optional_applications,
     :applications,
     :mod,
     :start_phases
@@ -502,16 +508,27 @@ defmodule Application do
   # compile time instead of compile_env
   @doc since: "1.10.0"
   @spec compile_env(app, key | list, value) :: value
-  defmacro compile_env(app, key_or_path, default \\ nil) when is_atom(app) do
+  defmacro compile_env(app, key_or_path, default \\ nil) do
     if __CALLER__.function do
       raise "Application.compile_env/3 cannot be called inside functions, only in the module body"
     end
 
+    key_or_path = expand_key_or_path(key_or_path, __CALLER__)
+
     quote do
       Application.__compile_env__(unquote(app), unquote(key_or_path), unquote(default), __ENV__)
     end
   end
 
+  defp expand_key_or_path({:__aliases__, _, _} = alias, env),
+    do: Macro.expand(alias, %{env | function: {:__info__, 1}})
+
+  defp expand_key_or_path(list, env) when is_list(list),
+    do: Enum.map(list, &expand_key_or_path(&1, env))
+
+  defp expand_key_or_path(other, _env),
+    do: other
+
   @doc false
   def __compile_env__(app, key_or_path, default, env) do
     case fetch_compile_env(app, key_or_path, env) do
@@ -528,11 +545,13 @@ defmodule Application do
   """
   @doc since: "1.10.0"
   @spec compile_env!(app, key | list) :: value
-  defmacro compile_env!(app, key_or_path) when is_atom(app) do
+  defmacro compile_env!(app, key_or_path) do
     if __CALLER__.function do
       raise "Application.compile_env!/2 cannot be called inside functions, only in the module body"
     end
 
+    key_or_path = expand_key_or_path(key_or_path, __CALLER__)
+
     quote do
       Application.__compile_env__!(unquote(app), unquote(key_or_path), __ENV__)
     end
@@ -611,10 +630,18 @@ defmodule Application do
 
   Our database engine used by `:my_app` needs to know what databases exist, and
   what the database configurations are. The database engine can make a call to
-  `get_env(:my_app, :my_app_databases)` to retrieve the list of databases (specified
-  by module names). Our database engine can then traverse each repository in the
-  list and then call `get_env(:my_app, Databases.RepoOne)` and so forth to retrieve
-  the configuration of each one.
+  `Application.get_env(:my_app, :my_app_databases, [])` to retrieve the list of
+  databases (specified by module names).
+
+  The engine can then traverse each repository in the list and call
+  `Application.get_env(:my_app, Databases.RepoOne)` and so forth to retrieve the
+  configuration of each one. In this case, each configuration will be a keyword
+  list, so you can use the functions in the `Keyword` module or even the `Access`
+  module to traverse it, for example:
+
+      config = Application.get_env(:my_app, Databases.RepoOne)
+      config[:ip]
+
   """
   @spec get_env(app, key, value) :: value
   def get_env(app, key, default \\ nil) when is_atom(app) do
@@ -694,9 +721,6 @@ defmodule Application do
     :application.set_env(app, key, value, opts)
   end
 
-  # TODO: Remove this once we support Erlang/OTP 22+ exclusively.
-  @compile {:no_warn_undefined, {:application, :set_env, 2}}
-
   @doc """
   Puts the environment for multiple apps at the same time.
 
@@ -705,28 +729,14 @@ defmodule Application do
     * have the same application listed more than once
     * have the same key inside the same application listed more than once
 
-  If those conditions are not met, the behaviour is undefined
-  (on Erlang/OTP 21 and earlier) or will raise (on Erlang/OTP 22
-  and later).
+  If those conditions are not met, it will raise.
 
   It receives the same options as `put_env/4`. Returns `:ok`.
   """
   @doc since: "1.9.0"
   @spec put_all_env([{app, [{key, value}]}], timeout: timeout, persistent: boolean) :: :ok
   def put_all_env(config, opts \\ []) when is_list(config) and is_list(opts) do
-    # TODO: Remove function exported? check when we require Erlang/OTP 22+
-    if function_exported?(:application, :set_env, 2) do
-      :application.set_env(config, opts)
-    else
-      for app_keyword <- config,
-          {app, keyword} = app_keyword,
-          key_value <- keyword,
-          {key, value} = key_value do
-        :application.set_env(app, key, value, opts)
-      end
-
-      :ok
-    end
+    :application.set_env(config, opts)
   end
 
   @doc """

lib/elixir/lib/base.ex

@@ -92,6 +92,9 @@ defmodule Base do
 
   """
 
+  @type encode_case :: :upper | :lower
+  @type decode_case :: :upper | :lower | :mixed
+
   b16_alphabet = '0123456789ABCDEF'
   b64_alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
   b64url_alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'
@@ -267,7 +270,7 @@ defmodule Base do
       "666f6f626172"
 
   """
-  @spec encode16(binary, keyword) :: binary
+  @spec encode16(binary, case: encode_case) :: binary
   def encode16(data, opts \\ []) when is_binary(data) do
     case = Keyword.get(opts, :case, :upper)
     do_encode16(case, data)
@@ -300,7 +303,7 @@ defmodule Base do
       {:ok, "foobar"}
 
   """
-  @spec decode16(binary, keyword) :: {:ok, binary} | :error
+  @spec decode16(binary, case: decode_case) :: {:ok, binary} | :error
   def decode16(string, opts \\ []) do
     {:ok, decode16!(string, opts)}
   rescue
@@ -337,7 +340,7 @@ defmodule Base do
       "foobar"
 
   """
-  @spec decode16!(binary, keyword) :: binary
+  @spec decode16!(binary, case: decode_case) :: binary
   def decode16!(string, opts \\ [])
 
   def decode16!(string, opts) when is_binary(string) and rem(byte_size(string), 2) == 0 do
@@ -367,7 +370,7 @@ defmodule Base do
       "Zm9vYg"
 
   """
-  @spec encode64(binary, keyword) :: binary
+  @spec encode64(binary, padding: boolean) :: binary
   def encode64(data, opts \\ []) when is_binary(data) do
     pad? = Keyword.get(opts, :padding, true)
     do_encode64(data, pad?)
@@ -397,7 +400,7 @@ defmodule Base do
       {:ok, "foob"}
 
   """
-  @spec decode64(binary, keyword) :: {:ok, binary} | :error
+  @spec decode64(binary, ignore: :whitespace, padding: boolean) :: {:ok, binary} | :error
   def decode64(string, opts \\ []) when is_binary(string) do
     {:ok, decode64!(string, opts)}
   rescue
@@ -431,7 +434,7 @@ defmodule Base do
       "foob"
 
   """
-  @spec decode64!(binary, keyword) :: binary
+  @spec decode64!(binary, ignore: :whitespace, padding: boolean) :: binary
   def decode64!(string, opts \\ []) when is_binary(string) do
     pad? = Keyword.get(opts, :padding, true)
     string |> remove_ignored(opts[:ignore]) |> do_decode64(pad?)
@@ -453,7 +456,7 @@ defmodule Base do
       "_3_-_A"
 
   """
-  @spec url_encode64(binary, keyword) :: binary
+  @spec url_encode64(binary, padding: boolean) :: binary
   def url_encode64(data, opts \\ []) when is_binary(data) do
     pad? = Keyword.get(opts, :padding, true)
     do_encode64url(data, pad?)
@@ -481,7 +484,7 @@ defmodule Base do
       {:ok, <<255, 127, 254, 252>>}
 
   """
-  @spec url_decode64(binary, keyword) :: {:ok, binary} | :error
+  @spec url_decode64(binary, ignore: :whitespace, padding: boolean) :: {:ok, binary} | :error
   def url_decode64(string, opts \\ []) when is_binary(string) do
     {:ok, url_decode64!(string, opts)}
   rescue
@@ -513,7 +516,7 @@ defmodule Base do
       <<255, 127, 254, 252>>
 
   """
-  @spec url_decode64!(binary, keyword) :: binary
+  @spec url_decode64!(binary, ignore: :whitespace, padding: boolean) :: binary
   def url_decode64!(string, opts \\ []) when is_binary(string) do
     pad? = Keyword.get(opts, :padding, true)
     string |> remove_ignored(opts[:ignore]) |> do_decode64url(pad?)
@@ -551,7 +554,7 @@ defmodule Base do
       "MZXW6YTBOI"
 
   """
-  @spec encode32(binary, keyword) :: binary
+  @spec encode32(binary, case: encode_case, padding: boolean) :: binary
   def encode32(data, opts \\ []) when is_binary(data) do
     case = Keyword.get(opts, :case, :upper)
     pad? = Keyword.get(opts, :padding, true)
@@ -594,7 +597,7 @@ defmodule Base do
       {:ok, "foobar"}
 
   """
-  @spec decode32(binary, keyword) :: {:ok, binary} | :error
+  @spec decode32(binary, case: decode_case, padding: boolean) :: {:ok, binary} | :error
   def decode32(string, opts \\ []) do
     {:ok, decode32!(string, opts)}
   rescue
@@ -640,7 +643,7 @@ defmodule Base do
       "foobar"
 
   """
-  @spec decode32!(binary, keyword) :: binary
+  @spec decode32!(binary, case: decode_case, padding: boolean) :: binary
   def decode32!(string, opts \\ []) when is_binary(string) do
     case = Keyword.get(opts, :case, :upper)
     pad? = Keyword.get(opts, :padding, true)
@@ -680,7 +683,7 @@ defmodule Base do
       "CPNMUOJ1E8"
 
   """
-  @spec hex_encode32(binary, keyword) :: binary
+  @spec hex_encode32(binary, case: encode_case, padding: boolean) :: binary
   def hex_encode32(data, opts \\ []) when is_binary(data) do
     case = Keyword.get(opts, :case, :upper)
     pad? = Keyword.get(opts, :padding, true)
@@ -724,7 +727,7 @@ defmodule Base do
       {:ok, "foobar"}
 
   """
-  @spec hex_decode32(binary, keyword) :: {:ok, binary} | :error
+  @spec hex_decode32(binary, case: decode_case, padding: boolean) :: {:ok, binary} | :error
   def hex_decode32(string, opts \\ []) do
     {:ok, hex_decode32!(string, opts)}
   rescue
@@ -771,7 +774,7 @@ defmodule Base do
       "foobar"
 
   """
-  @spec hex_decode32!(binary, keyword) :: binary
+  @spec hex_decode32!(binary, case: decode_case, padding: boolean) :: binary
   def hex_decode32!(string, opts \\ []) when is_binary(string) do
     case = Keyword.get(opts, :case, :upper)
     pad? = Keyword.get(opts, :padding, true)

lib/elixir/lib/calendar.ex

@@ -189,7 +189,7 @@ defmodule Calendar do
   @doc """
   Calculates the year and era from the given `year`.
   """
-  @callback year_of_era(year) :: {year, era}
+  @callback year_of_era(year, month, day) :: {year, era}
 
   @doc """
   Calculates the day and era from the given `year`, `month`, and `day`.

lib/elixir/lib/calendar/date.ex

@@ -92,7 +92,7 @@ defmodule Date do
   def range(%{calendar: calendar} = first, %{calendar: calendar} = last) do
     {first_days, _} = to_iso_days(first)
     {last_days, _} = to_iso_days(last)
-    # TODO: Deprecate inferring a range with step of -1 on Elixir v1.16
+    # TODO: Deprecate inferring a range with a step of -1 on Elixir v1.16
     step = if first_days <= last_days, do: 1, else: -1
     range(first, first_days, last, last_days, calendar, step)
   end
@@ -102,7 +102,7 @@ defmodule Date do
   end
 
   @doc """
-  Returns a range of dates with step.
+  Returns a range of dates with a step.
 
   ## Examples
 
@@ -133,8 +133,8 @@ defmodule Date do
         step
       ) do
     raise ArgumentError,
-          "both dates must have matching calendar and the step must be an integer " <>
-            "different than zero, got: #{inspect(first)}, #{inspect(last)}, #{step}"
+          "both dates must have matching calendar and the step must be a " <>
+            "non-zero integer, got: #{inspect(first)}, #{inspect(last)}, #{step}"
   end
 
   defp range(first, first_days, last, last_days, calendar, step) do
@@ -943,8 +943,14 @@ defmodule Date do
   @spec year_of_era(Calendar.date()) :: {Calendar.year(), non_neg_integer()}
   def year_of_era(date)
 
-  def year_of_era(%{calendar: calendar, year: year}) do
-    calendar.year_of_era(year)
+  def year_of_era(%{calendar: calendar, year: year, month: month, day: day}) do
+    # TODO: Remove me on 1.17
+    # The behaviour implementation already warns on missing callback.
+    if function_exported?(calendar, :year_of_era, 3) do
+      calendar.year_of_era(year, month, day)
+    else
+      calendar.year_of_era(year)
+    end
   end
 
   @doc """

lib/elixir/lib/calendar/date_range.ex

@@ -23,16 +23,19 @@ defmodule Date.Range do
 
   @typep iso_days() :: Calendar.iso_days()
 
+  @enforce_keys [:first, :last, :first_in_iso_days, :last_in_iso_days, :step]
   defstruct [:first, :last, :first_in_iso_days, :last_in_iso_days, :step]
 
   defimpl Enumerable do
-    def member?(%{first: %{calendar: calendar}} = range, %Date{calendar: calendar} = date) do
-      %{
-        first_in_iso_days: first_days,
-        last_in_iso_days: last_days,
-        step: step
-      } = range
-
+    def member?(
+          %Date.Range{
+            first: %{calendar: calendar},
+            first_in_iso_days: first_days,
+            last_in_iso_days: last_days,
+            step: step
+          } = range,
+          %Date{calendar: calendar} = date
+        ) do
       {days, _} = Date.to_iso_days(date)
 
       cond do
@@ -47,24 +50,43 @@ defmodule Date.Range do
       end
     end
 
-    def member?(_, _) do
+    def member?(%Date.Range{step: _}, _) do
       {:ok, false}
     end
 
+    # TODO: Remove me on v2.0
+    def member?(
+          %{__struct__: Date.Range, first_in_iso_days: first_days, last_in_iso_days: last_days} =
+            date_range,
+          date
+        ) do
+      step = if first_days <= last_days, do: 1, else: -1
+      member?(Map.put(date_range, :step, step), date)
+    end
+
     def count(range) do
       {:ok, size(range)}
     end
 
-    def slice(range) do
-      %{
-        first_in_iso_days: first,
-        first: %{calendar: calendar},
-        step: step
-      } = range
-
+    def slice(
+          %Date.Range{
+            first_in_iso_days: first,
+            first: %{calendar: calendar},
+            step: step
+          } = range
+        ) do
       {:ok, size(range), &slice(first + &1 * step, step, &2, calendar)}
     end
 
+    # TODO: Remove me on v2.0
+    def slice(
+          %{__struct__: Date.Range, first_in_iso_days: first_days, last_in_iso_days: last_days} =
+            date_range
+        ) do
+      step = if first_days <= last_days, do: 1, else: -1
+      slice(Map.put(date_range, :step, step))
+    end
+
     defp slice(current, _step, 1, calendar) do
       [date_from_iso_days(current, calendar)]
     end
@@ -76,17 +98,30 @@ defmodule Date.Range do
       ]
     end
 
-    def reduce(range, acc, fun) do
-      %{
-        first_in_iso_days: first_days,
-        last_in_iso_days: last_days,
-        first: %{calendar: calendar},
-        step: step
-      } = range
-
+    def reduce(
+          %Date.Range{
+            first_in_iso_days: first_days,
+            last_in_iso_days: last_days,
+            first: %{calendar: calendar},
+            step: step
+          },
+          acc,
+          fun
+        ) do
       reduce(first_days, last_days, acc, fun, step, calendar)
     end
 
+    # TODO: Remove me on v2.0
+    def reduce(
+          %{__struct__: Date.Range, first_in_iso_days: first_days, last_in_iso_days: last_days} =
+            date_range,
+          acc,
+          fun
+        ) do
+      step = if first_days <= last_days, do: 1, else: -1
+      reduce(Map.put(date_range, :step, step), acc, fun)
+    end
+
     defp reduce(_first_days, _last_days, {:halt, acc}, _fun, _step, _calendar) do
       {:halted, acc}
     end
@@ -135,6 +170,15 @@ defmodule Date.Range do
     defp size(%Date.Range{first_in_iso_days: first_days, last_in_iso_days: last_days, step: step}),
       do: abs(div(last_days - first_days, step)) + 1
 
+    # TODO: Remove me on v2.0
+    defp size(
+           %{__struct__: Date.Range, first_in_iso_days: first_days, last_in_iso_days: last_days} =
+             date_range
+         ) do
+      step = if first_days <= last_days, do: 1, else: -1
+      size(Map.put(date_range, :step, step))
+    end
+
     defp empty?(%Date.Range{
            first_in_iso_days: first_days,
            last_in_iso_days: last_days,
@@ -151,10 +195,21 @@ defmodule Date.Range do
          when step < 0 and first_days < last_days,
          do: true
 
-    defp empty?(%Date.Range{}), do: false
+    defp empty?(%Date.Range{step: _}), do: false
+
+    # TODO: Remove me on v2.0
+    defp empty?(
+           %{__struct__: Date.Range, first_in_iso_days: first_days, last_in_iso_days: last_days} =
+             date_range
+         ) do
+      step = if first_days <= last_days, do: 1, else: -1
+      empty?(Map.put(date_range, :step, step))
+    end
   end
 
   defimpl Inspect do
+    import Kernel, except: [inspect: 2]
+
     def inspect(%Date.Range{first: first, last: last, step: 1}, _) do
       "#DateRange<" <> inspect(first) <> ", " <> inspect(last) <> ">"
     end
@@ -162,5 +217,11 @@ defmodule Date.Range do
     def inspect(%Date.Range{first: first, last: last, step: step}, _) do
       "#DateRange<" <> inspect(first) <> ", " <> inspect(last) <> ", #{step}>"
     end
+
+    # TODO: Remove me on v2.0
+    def inspect(%{__struct__: Date.Range, first: first, last: last} = date_range, opts) do
+      step = if first <= last, do: 1, else: -1
+      inspect(Map.put(date_range, :step, step), opts)
+    end
   end
 end

lib/elixir/lib/calendar/datetime.ex

@@ -2,11 +2,14 @@ defmodule DateTime do
   @moduledoc """
   A datetime implementation with a time zone.
 
-  This datetime can be seen as an ephemeral snapshot
-  of a datetime at a given time zone. For such purposes,
-  it also includes both UTC and Standard offsets, as
-  well as the zone abbreviation field used exclusively
-  for formatting purposes.
+  This datetime can be seen as a snapshot of a date and time
+  at a given time zone. For such purposes, it also includes both
+  UTC and Standard offsets, as well as the zone abbreviation
+  field used exclusively for formatting purposes. Note future
+  datetimes are not necessarily guaranteed to exist, as time
+  zones may change any time in the future due to geopolitical
+  reasons. See the "Datetimes as snapshots" section for more
+  information.
 
   Remember, comparisons in Elixir using `==/2`, `>/2`, `</2` and friends
   are structural and based on the DateTime struct fields. For proper
@@ -41,6 +44,56 @@ defmodule DateTime do
       Calendar.put_time_zone_database(Tzdata.TimeZoneDatabase)
 
   See the proper names in the library installation instructions.
+
+  ## Datetimes as snapshots
+
+  In the first section, we described datetimes as a "snapshot of
+  a date and time at a given time zone". To understand precisely
+  what we mean, let's see an example.
+
+  Imagine someone in Poland wants to schedule a meeting with someone
+  in Brazil in the next year. The meeting will happen at 2:30 AM
+  in the Polish time zone. At what time will the meeting happen in
+  Brazil?
+
+  You can consult the time zone database today, one year before,
+  using the API in this module and it will give you an answer that
+  is valid right now. However, this answer may not be valid in the
+  future. Why? Because both Brazil and Poland may change their timezone
+  rules, ultimately affecting the result. For example, a country may
+  choose to enter or abandon "Daylight Saving Time", which is a
+  process where we adjust the clock one hour forward or one hour
+  back once per year. Whenener the rules change, the exact instant
+  that 2:30 AM in Polish time will be in Brazil may change.
+
+  In other words, whenever working with future DateTimes, there is
+  no guarantee the results you get will always be correct, until
+  the event actually happens. Therefore, when you ask for a future
+  time, the answers you get are a snapshot that reflects the current
+  state of the time zone rules. For datetimes in the past, this is
+  not a problem, because time zone rules do not change for past
+  events.
+
+  To make matters worse, it may be that the 2:30 AM in Polish time
+  does not actually even exist or it is ambiguous. If a certain
+  time zone observes "Daylight Saving Time", they will move their
+  clock forward once a year. When this happens, there is a whole
+  hour that does not exist. Then, when they move the clock back,
+  there is a certain hour that will happen twice. So if you want
+  to schedule a meeting when this shift back happens, you would
+  need to explicitly say which of the 2:30 AM you precisely mean.
+  Applications that are date and time sensitive, need to take
+  these scenarios into account and correctly communicate them to
+  users.
+
+  The good news is: Elixir contains all of the building blocks
+  necessary to tackle those problems. The default timezone database
+  used by Elixir, `Calendar.UTCOnlyTimeZoneDatabase`, only works
+  with UTC, which does not observe those issues. Once you bring
+  a proper time zone database, the functions in this module will
+  query the database and return the relevant information. For
+  example, look at how `DateTime.new/4` returns different results
+  based on the scenarios described in this section.
   """
 
   @enforce_keys [:year, :month, :day, :hour, :minute, :second] ++
@@ -450,7 +503,7 @@ defmodule DateTime do
         # we get the last microsecond just before.
         before_naive =
           first_period_until_wall
-          |> Map.put(:microsecond, {999_999, 6})
+          |> Map.replace!(:microsecond, {999_999, 6})
           |> NaiveDateTime.add(-1)
 
         after_naive = second_period_from_wall

lib/elixir/lib/calendar/iso.ex

@@ -11,60 +11,40 @@ defmodule Calendar.ISO do
   ## ISO 8601 compliance
 
   The ISO 8601 specification is feature-rich, but allows applications
-  to selectively implement most parts of it. The choices Elixir makes here
+  to selectively implement most parts of it. The choices Elixir makes
   are catalogued below.
 
-  ### Additions
-
-  ISO 8601 does not allow a whitespace instead of `T` as a separator
-  between date and times, both when parsing and formatting.
-  This is a common enough representation, Elixir allows it during parsing.
-
-  The formatting of dates in `NaiveDateTime.to_iso8601/1` and `DateTime.to_iso8601/1`
-  do produce specification-compliant string representations using the `T` separator.
-
-  #### Examples
-
-      iex> Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07.0123456")
-      {:ok, {2015, 1, 23, 23, 50, 7, {12345, 6}}}
-      iex> Calendar.ISO.parse_naive_datetime("2015-01-23T23:50:07.0123456")
-      {:ok, {2015, 1, 23, 23, 50, 7, {12345, 6}}}
-
-      iex> Calendar.ISO.parse_utc_datetime("2015-01-23 23:50:07.0123456Z")
-      {:ok, {2015, 1, 23, 23, 50, 7, {12345, 6}}, 0}
-      iex> Calendar.ISO.parse_utc_datetime("2015-01-23T23:50:07.0123456Z")
-      {:ok, {2015, 1, 23, 23, 50, 7, {12345, 6}}, 0}
-
   ### Features
 
   The standard library supports a minimal set of possible ISO 8601 features.
-  Specifically, the parser only supports calendar dates, and defaults to
-  only parsing extended-formatted date/times.
+  Specifically, the parser only supports calendar dates and does not support
+  ordinal and week formats.
+
+  By default Elixir only parses extended-formatted date/times. You can opt-in
+  to parse basic-formatted date/times.
 
-  You can ask to parse only basic-formatted date/times instead, or both.
   `NaiveDateTime.to_iso8601/2` and `DateTime.to_iso8601/2` allow you to produce
   either basic or extended formatted strings, and `Calendar.strftime/2` allows
   you to format datetimes however else you desire.
 
-  Other optional ISO 8601 features; such as ordinal dates, week dates, and reduced
-  precision (except for milliseconds); are not supported by the parser or formatters.
-
-  No functions exist to parse ISO 8601 durations or time intervals.
+  Elixir does not support reduced accuracy formats (for example, a date without
+  the day component) nor decimal precisions in the lowest component (such as
+  `10:01:25,5`). No functions exist to parse ISO 8601 durations or time intervals.
 
   #### Examples
 
-  Only the extended format is supported in parsing; the basic format is not.
+  Elixir expects the extended format by default when parsing:
 
-      iex> Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07")
+      iex> Calendar.ISO.parse_naive_datetime("2015-01-23T23:50:07")
       {:ok, {2015, 1, 23, 23, 50, 7, {0, 0}}}
-      iex> Calendar.ISO.parse_naive_datetime("20150123 235007")
+      iex> Calendar.ISO.parse_naive_datetime("20150123T235007")
       {:error, :invalid_format}
 
-  Parsing can be restricted to basic or extend formats.
+  Parsing can be restricted to basic if desired:
 
-      iex> Calendar.ISO.parse_naive_datetime("20150123 235007Z", :basic)
+      iex> Calendar.ISO.parse_naive_datetime("20150123T235007Z", :basic)
       {:ok, {2015, 1, 23, 23, 50, 7, {0, 0}}}
-      iex> Calendar.ISO.parse_naive_datetime("20150123 235007Z", :extended)
+      iex> Calendar.ISO.parse_naive_datetime("20150123T235007Z", :extended)
       {:error, :invalid_format}
 
   Only calendar dates are supported in parsing; ordinal and week dates are not.
@@ -78,8 +58,7 @@ defmodule Calendar.ISO do
       iex> Calendar.ISO.parse_date("2015-W016-3")
       {:error, :invalid_format}
 
-  Reduced precision is supported for only milliseconds;
-  years, months, days, hours, minutes, and seconds must be fully specified.
+  Years, months, days, hours, minutes, and seconds must be fully specified:
 
       iex> Calendar.ISO.parse_date("2015-04-15")
       {:ok, {2015, 4, 15}}
@@ -122,6 +101,27 @@ defmodule Calendar.ISO do
       iex> Calendar.ISO.parse_utc_datetime("+2015-01-23 23:50:07Z")
       {:ok, {2015, 1, 23, 23, 50, 7, {0, 0}}, 0}
 
+  ### Additions
+
+  ISO 8601 does not allow a whitespace instead of `T` as a separator
+  between date and times, both when parsing and formatting.
+  This is a common enough representation, Elixir allows it during parsing.
+
+  The formatting of dates in `NaiveDateTime.to_iso8601/1` and `DateTime.to_iso8601/1`
+  do produce specification-compliant string representations using the `T` separator.
+
+  #### Examples
+
+      iex> Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07.0123456")
+      {:ok, {2015, 1, 23, 23, 50, 7, {12345, 6}}}
+      iex> Calendar.ISO.parse_naive_datetime("2015-01-23T23:50:07.0123456")
+      {:ok, {2015, 1, 23, 23, 50, 7, {12345, 6}}}
+
+      iex> Calendar.ISO.parse_utc_datetime("2015-01-23 23:50:07.0123456Z")
+      {:ok, {2015, 1, 23, 23, 50, 7, {12345, 6}}, 0}
+      iex> Calendar.ISO.parse_utc_datetime("2015-01-23T23:50:07.0123456Z")
+      {:ok, {2015, 1, 23, 23, 50, 7, {12345, 6}}, 0}
+
   """
 
   @behaviour Calendar
@@ -131,6 +131,8 @@ defmodule Calendar.ISO do
   unix_end = 315_569_519_999_999_999 - @unix_epoch * 1_000_000
   @unix_range_microseconds unix_start..unix_end
 
+  defguardp is_format(term) when term in [:basic, :extended]
+
   @typedoc """
   "Before the Current Era" or "Before the Common Era" (BCE), for those years less than `1`.
   """
@@ -156,6 +158,8 @@ defmodule Calendar.ISO do
   @type minute :: 0..59
   @type second :: 0..59
   @type weekday :: :monday | :tuesday | :wednesday | :thursday | :friday | :saturday | :sunday
+  @type utc_offset :: integer
+  @type format :: :basic | :extended
 
   @typedoc """
   Microseconds with stored precision.
@@ -262,6 +266,9 @@ defmodule Calendar.ISO do
   """
   @doc since: "1.10.0"
   @impl true
+  @spec parse_time(String.t()) ::
+          {:ok, {hour, minute, second, microsecond}}
+          | {:error, atom}
   def parse_time(string) when is_binary(string),
     do: parse_time(string, :extended)
 
@@ -282,11 +289,15 @@ defmodule Calendar.ISO do
 
   """
   @doc since: "1.12.0"
-  def parse_time("T" <> string, format) when is_binary(string),
-    do: do_parse_time(string, format)
-
-  def parse_time(string, format) when is_binary(string),
-    do: do_parse_time(string, format)
+  @spec parse_time(String.t(), format) ::
+          {:ok, {hour, minute, second, microsecond}}
+          | {:error, atom}
+  def parse_time(string, format) when is_binary(string) and is_format(format) do
+    case string do
+      "T" <> rest -> do_parse_time(rest, format)
+      _ -> do_parse_time(string, format)
+    end
+  end
 
   defp do_parse_time(<<unquote(match_basic_time), rest::binary>>, :basic)
        when unquote(guard_time) do
@@ -336,6 +347,9 @@ defmodule Calendar.ISO do
   """
   @doc since: "1.10.0"
   @impl true
+  @spec parse_date(String.t()) ::
+          {:ok, {year, month, day}}
+          | {:error, atom}
   def parse_date(string) when is_binary(string),
     do: parse_date(string, :extended)
 
@@ -356,13 +370,19 @@ defmodule Calendar.ISO do
 
   """
   @doc since: "1.12.0"
-  def parse_date("-" <> string, format) when is_binary(string),
+  @spec parse_date(String.t(), format) ::
+          {:ok, {year, month, day}}
+          | {:error, atom}
+  def parse_date(string, format) when is_binary(string) and is_format(format),
+    do: parse_date_guarded(string, format)
+
+  defp parse_date_guarded("-" <> string, format),
     do: do_parse_date(string, -1, format)
 
-  def parse_date("+" <> string, format) when is_binary(string),
+  defp parse_date_guarded("+" <> string, format),
     do: do_parse_date(string, 1, format)
 
-  def parse_date(string, format) when is_binary(string),
+  defp parse_date_guarded(string, format),
     do: do_parse_date(string, 1, format)
 
   defp do_parse_date(unquote(match_basic_date), multiplier, :basic) when unquote(guard_date) do
@@ -412,6 +432,9 @@ defmodule Calendar.ISO do
   """
   @doc since: "1.10.0"
   @impl true
+  @spec parse_naive_datetime(String.t()) ::
+          {:ok, {year, month, day, hour, minute, second, microsecond}}
+          | {:error, atom}
   def parse_naive_datetime(string) when is_binary(string),
     do: parse_naive_datetime(string, :extended)
 
@@ -432,13 +455,19 @@ defmodule Calendar.ISO do
 
   """
   @doc since: "1.12.0"
-  def parse_naive_datetime("-" <> string, format) when is_binary(string),
+  @spec parse_naive_datetime(String.t(), format) ::
+          {:ok, {year, month, day, hour, minute, second, microsecond}}
+          | {:error, atom}
+  def parse_naive_datetime(string, format) when is_binary(string) and is_format(format),
+    do: parse_naive_datetime_guarded(string, format)
+
+  defp parse_naive_datetime_guarded("-" <> string, format),
     do: do_parse_naive_datetime(string, -1, format)
 
-  def parse_naive_datetime("+" <> string, format) when is_binary(string),
+  defp parse_naive_datetime_guarded("+" <> string, format),
     do: do_parse_naive_datetime(string, 1, format)
 
-  def parse_naive_datetime(string, format) when is_binary(string),
+  defp parse_naive_datetime_guarded(string, format),
     do: do_parse_naive_datetime(string, 1, format)
 
   defp do_parse_naive_datetime(
@@ -507,6 +536,9 @@ defmodule Calendar.ISO do
   """
   @doc since: "1.10.0"
   @impl true
+  @spec parse_utc_datetime(String.t()) ::
+          {:ok, {year, month, day, hour, minute, second, microsecond}, utc_offset}
+          | {:error, atom}
   def parse_utc_datetime(string) when is_binary(string),
     do: parse_utc_datetime(string, :extended)
 
@@ -527,13 +559,19 @@ defmodule Calendar.ISO do
 
   """
   @doc since: "1.12.0"
-  def parse_utc_datetime("-" <> string, format) when is_binary(string),
+  @spec parse_utc_datetime(String.t(), format) ::
+          {:ok, {year, month, day, hour, minute, second, microsecond}, utc_offset}
+          | {:error, atom}
+  def parse_utc_datetime(string, format) when is_binary(string) and is_format(format),
+    do: parse_utc_datetime_guarded(string, format)
+
+  defp parse_utc_datetime_guarded("-" <> string, format),
     do: do_parse_utc_datetime(string, -1, format)
 
-  def parse_utc_datetime("+" <> string, format) when is_binary(string),
+  defp parse_utc_datetime_guarded("+" <> string, format),
     do: do_parse_utc_datetime(string, 1, format)
 
-  def parse_utc_datetime(string, format) when is_binary(string),
+  defp parse_utc_datetime_guarded(string, format),
     do: do_parse_utc_datetime(string, 1, format)
 
   defp do_parse_utc_datetime(
@@ -985,14 +1023,33 @@ defmodule Calendar.ISO do
   """
   @doc since: "1.8.0"
   @spec year_of_era(year) :: {1..10000, era}
-  @impl true
-  def year_of_era(year) when is_year_CE(year) do
-    {year, 1}
-  end
+  def year_of_era(year) when is_year_CE(year), do: {year, 1}
+  def year_of_era(year) when is_year_BCE(year), do: {abs(year) + 1, 0}
 
-  def year_of_era(year) when is_year_BCE(year) do
-    {abs(year) + 1, 0}
-  end
+  @doc """
+  Calendar callback to compute the year and era from the
+  given `year`, `month` and `day`.
+
+  In the ISO calendar, the new year coincides with the new era,
+  so the `month` and `day` arguments are discarded. If you only
+  have the year available, you can `year_of_era/1` instead.
+
+  ## Examples
+
+      iex> Calendar.ISO.year_of_era(1, 1, 1)
+      {1, 1}
+      iex> Calendar.ISO.year_of_era(2018, 12, 1)
+      {2018, 1}
+      iex> Calendar.ISO.year_of_era(0, 1, 1)
+      {1, 0}
+      iex> Calendar.ISO.year_of_era(-1, 12, 1)
+      {2, 0}
+
+  """
+  @doc since: "1.13.0"
+  @impl true
+  @spec year_of_era(year, month, day) :: {1..10000, era}
+  def year_of_era(year, _month, _day), do: year_of_era(year)
 
   @doc """
   Calculates the day and era from the given `year`, `month`, and `day`.
@@ -1288,9 +1345,7 @@ defmodule Calendar.ISO do
   @doc """
   Determines if the date given is valid according to the proleptic Gregorian calendar.
 
-  Note that while ISO 8601 allows times to specify 24:00:00 as the
-  zero hour of the next day, this notation is not supported by Elixir.
-  Leap seconds are not supported as well by the built-in Calendar.ISO.
+  Leap seconds are not supported by the built-in Calendar.ISO.
 
   ## Examples
 

lib/elixir/lib/code.ex

@@ -30,6 +30,11 @@ defmodule Code do
   file, without tracking. `eval_file/2` should be used when you are interested in
   the result of evaluating the file rather than the modules it defines.
 
+  The functions above work with Elixir source. If you want to work
+  with modules compiled to bytecode, which have the `.beam` extension
+  and are typically found below the _build directory of a Mix project,
+  see the functions in Erlang's [`:code`](`:code`) module.
+
   ## Code loading on the Erlang VM
 
   Erlang has two modes to load code: interactive and embedded.
@@ -38,8 +43,8 @@ defmodule Code do
   are loaded as needed. In embedded mode the opposite happens, as all
   modules need to be loaded upfront or explicitly.
 
-  You can use `ensure_loaded/1` (as well as `ensure_lodead?/1` and
-  `ensure_lodead!/1`) to check if a module is loaded before using it and
+  You can use `ensure_loaded/1` (as well as `ensure_loaded?/1` and
+  `ensure_loaded!/1`) to check if a module is loaded before using it and
   act.
 
   ## `ensure_compiled/1` and `ensure_compiled!/1`
@@ -144,6 +149,12 @@ defmodule Code do
       of keys to traverse in the application environment and `return` is either
       `{:ok, value}` or `:error`.
 
+    * `{:on_module, bytecode, :none}` - (since v1.11.0) traced whenever a module
+      is defined. This is equivalent to the `@after_compile` callback and invoked
+      after any `@after_compile` in the given module. The third element is currently
+      `:none` but it may provide more metadata in the future. It is best to ignore
+      it at the moment.
+
   The `:tracers` compiler option can be combined with the `:parser_options`
   compiler option to enrich the metadata of the traced events above.
 
@@ -206,6 +217,12 @@ defmodule Code do
     required_files()
   end
 
+  @doc false
+  @deprecated "Use Code.Fragment.cursor_context/2 instead"
+  def cursor_context(code, options \\ []) do
+    Code.Fragment.cursor_context(code, options)
+  end
+
   @doc """
   Removes files from the required files list.
 
@@ -326,33 +343,18 @@ defmodule Code do
 
     * `:line` - the line on which the script starts
 
-  Additionally, the following scope values can be configured:
+  Additionally, you may also pass an environment as second argument,
+  so the evaluation happens within that environment. However, if the evaluated
+  code requires or compiles another file, the environment given to this function
+  will not apply to said files.
 
-    * `:aliases` - a list of tuples with the alias and its target
+  Returns a tuple of the form `{value, binding}`, where `value` is the value
+  returned from evaluating `string`. If an error occurs while evaluating
+  `string` an exception will be raised.
 
-    * `:requires` - a list of modules required
-
-    * `:functions` - a list of tuples where the first element is a module
-      and the second a list of imported function names and arity; the list
-      of function names and arity must be sorted
-
-    * `:macros` - a list of tuples where the first element is a module
-      and the second a list of imported macro names and arity; the list
-      of function names and arity must be sorted
-
-  Note that setting any of the values above overrides Elixir's default
-  values. For example, setting `:requires` to `[]` will no longer
-  automatically require the `Kernel` module. In the same way setting
-  `:macros` will no longer auto-import `Kernel` macros like `Kernel.if/2`,
-  `Kernel.SpecialForms.case/2`, and so on.
-
-  Returns a tuple of the form `{value, binding}`,
-  where `value` is the value returned from evaluating `string`.
-  If an error occurs while evaluating `string` an exception will be raised.
-
-  `binding` is a list with all variable bindings
-  after evaluating `string`. The binding keys are usually atoms, but they
-  may be a tuple for variables defined in a different context.
+  `binding` is a list with all variable bindings after evaluating `string`.
+  The binding keys are usually atoms, but they may be a tuple for variables
+  defined in a different context.
 
   ## Examples
 
@@ -389,16 +391,15 @@ defmodule Code do
   def eval_string(string, binding \\ [], opts \\ [])
 
   def eval_string(string, binding, %Macro.Env{} = env) do
-    eval_string_with_error_handling(string, binding, Map.to_list(env))
+    validated_eval_string(string, binding, env)
   end
 
   def eval_string(string, binding, opts) when is_list(opts) do
-    validate_eval_opts(opts)
-    eval_string_with_error_handling(string, binding, opts)
+    validated_eval_string(string, binding, opts)
   end
 
-  defp eval_string_with_error_handling(string, binding, opts) do
-    %{line: line, file: file} = env = :elixir.env_for_eval(opts)
+  defp validated_eval_string(string, binding, opts_or_env) do
+    %{line: line, file: file} = env = :elixir.env_for_eval(opts_or_env)
     forms = :elixir.string_to_quoted!(to_charlist(string), line, 1, file, [])
     {value, binding, _env} = :elixir.eval_forms(forms, binding, env)
     {value, binding}
@@ -430,10 +431,10 @@ defmodule Code do
       and this option augments this list.
 
     * `:force_do_end_blocks` (since v1.9.0) - when `true`, converts all
-      inline usages of `do: ...`,  `else: ...` and friends into `do/end`
+      inline usages of `do: ...`,  `else: ...` and friends into `do`-`end`
       blocks. Defaults to `false`. Note that this option is convergent:
       once you set it to `true`, **all keywords** will be converted.
-      If you set it to `false` later on, `do/end` blocks won't be
+      If you set it to `false` later on, `do`-`end` blocks won't be
       converted back to keywords.
 
   ## Design principles
@@ -552,17 +553,19 @@ defmodule Code do
   gives more options to the formatter.
 
   This may also appear in do/end blocks, where the `do` keyword (or `->`)
-  may go over the line lenth because there is no opportunity for the
+  may go over the line length because there is no opportunity for the
   formatter to introduce a line break in a readable way. For example,
   if you do:
 
       case very_long_expression() do
+      end
 
   And only the `do` keyword is above the line length, Elixir **will not**
   emit this:
 
       case very_long_expression()
       do
+      end
 
   So it prefers to not touch the line at all and leave `do` above the
   line limit.
@@ -585,7 +588,7 @@ defmodule Code do
       line before and after and 2) empty lines are always squeezed
       together into a single empty line
 
-    * The choice between `:do` keyword and `do/end` blocks is left
+    * The choice between `:do` keyword and `do`-`end` blocks is left
       to the user
 
     * Lists, tuples, bitstrings, maps, structs and function calls will be
@@ -634,7 +637,7 @@ defmodule Code do
   Elixir has two syntaxes for function calls. With parens and no parens.
   By default, Elixir will add parens to all calls except for:
 
-    1. calls that have do/end blocks
+    1. calls that have `do`-`end` blocks
     2. local calls without parens where the name and arity of the local
        call is also listed under `:locals_without_parens` (except for
        calls with arity 0, where the compiler always require parens)
@@ -722,8 +725,25 @@ defmodule Code do
   @spec format_string!(binary, keyword) :: iodata
   def format_string!(string, opts \\ []) when is_binary(string) and is_list(opts) do
     line_length = Keyword.get(opts, :line_length, 98)
-    algebra = Code.Formatter.to_algebra!(string, opts)
-    Inspect.Algebra.format(algebra, line_length)
+
+    to_quoted_opts =
+      [
+        unescape: false,
+        warn_on_unnecessary_quotes: false,
+        literal_encoder: &{:ok, {:__block__, &2, [&1]}},
+        token_metadata: true
+      ] ++ opts
+
+    {forms, comments} = string_to_quoted_with_comments!(string, to_quoted_opts)
+
+    to_algebra_opts =
+      [
+        comments: comments
+      ] ++ opts
+
+    doc = Code.Formatter.to_algebra(forms, to_algebra_opts)
+
+    Inspect.Algebra.format(doc, line_length)
   end
 
   @doc """
@@ -748,7 +768,7 @@ defmodule Code do
   Macro arguments are typically transformed by unquoting them into the
   returned quoted expressions (instead of evaluated).
 
-  See `eval_string/3` for a description of `binding` and options.
+  See `eval_string/3` for a description of `binding` and `opts`.
 
   ## Examples
 
@@ -774,64 +794,25 @@ defmodule Code do
   def eval_quoted(quoted, binding \\ [], opts \\ [])
 
   def eval_quoted(quoted, binding, %Macro.Env{} = env) do
-    {value, binding, _env} = :elixir.eval_quoted(quoted, binding, Map.to_list(env))
+    {value, binding, _env} = :elixir.eval_quoted(quoted, binding, :elixir.env_for_eval(env))
     {value, binding}
   end
 
   def eval_quoted(quoted, binding, opts) when is_list(opts) do
-    validate_eval_opts(opts)
-    {value, binding, _env} = :elixir.eval_quoted(quoted, binding, opts)
+    {value, binding, _env} = :elixir.eval_quoted(quoted, binding, :elixir.env_for_eval(opts))
     {value, binding}
   end
 
-  defp validate_eval_opts(opts) do
-    if f = opts[:functions], do: validate_imports(:functions, f)
-    if m = opts[:macros], do: validate_imports(:macros, m)
-    if a = opts[:aliases], do: validate_aliases(:aliases, a)
-    if r = opts[:requires], do: validate_requires(:requires, r)
-  end
-
-  defp validate_requires(kind, requires) do
-    valid = is_list(requires) and Enum.all?(requires, &is_atom(&1))
-
-    unless valid do
-      raise ArgumentError, "expected :#{kind} option given to eval in the format: [module]"
-    end
-  end
-
-  defp validate_aliases(kind, aliases) do
-    valid = is_list(aliases) and Enum.all?(aliases, fn {k, v} -> is_atom(k) and is_atom(v) end)
-
-    unless valid do
-      raise ArgumentError,
-            "expected :#{kind} option given to eval in the format: [{module, module}]"
-    end
-  end
-
-  defp validate_imports(kind, imports) do
-    valid =
-      is_list(imports) and
-        Enum.all?(imports, fn {k, v} ->
-          is_atom(k) and is_list(v) and
-            Enum.all?(v, fn {name, arity} -> is_atom(name) and is_integer(arity) end)
-        end)
-
-    unless valid do
-      raise ArgumentError,
-            "expected :#{kind} option given to eval in the format: [{module, [{name, arity}]}]"
-    end
-  end
-
   @doc ~S"""
   Converts the given string to its quoted form.
 
   Returns `{:ok, quoted_form}` if it succeeds,
-  `{:error, {line, error, token}}` otherwise.
+  `{:error, {meta, message_info, token}}` otherwise.
 
   ## Options
 
     * `:file` - the filename to be reported in case of parsing errors.
-      Defaults to "nofile".
+      Defaults to `"nofile"`.
 
     * `:line` - the starting line of the string being parsed.
       Defaults to 1.
@@ -842,6 +823,13 @@ defmodule Code do
     * `:columns` - when `true`, attach a `:column` key to the quoted
       metadata. Defaults to `false`.
 
+    * `:unescape` (since v1.10.0) - when `false`, preserves escaped sequences.
+      For example, `"null byte\\t\\x00"` will be kept as is instead of being
+      converted to a bitstring literal. Note if you set this option to false, the
+      resulting AST is no longer valid, but it can be useful to analyze/transform
+      source code, typically in in combination with `quoted_to_algebra/2`.
+      Defaults to `true`.
+
     * `:existing_atoms_only` - when `true`, raises an error
       when non-existing atoms are found by the tokenizer.
       Defaults to `false`.
@@ -906,7 +894,7 @@ defmodule Code do
 
   """
   @spec string_to_quoted(List.Chars.t(), keyword) ::
-          {:ok, Macro.t()} | {:error, {location :: keyword, term, term}}
+          {:ok, Macro.t()} | {:error, {location :: keyword, binary | {binary, binary}, binary}}
   def string_to_quoted(string, opts \\ []) when is_list(opts) do
     file = Keyword.get(opts, :file, "nofile")
     line = Keyword.get(opts, :line, 1)
@@ -924,7 +912,7 @@ defmodule Code do
   @doc """
   Converts the given string to its quoted form.
 
-  It returns the ast if it succeeds,
+  It returns the AST if it succeeds,
   raises an exception otherwise. The exception is a `TokenMissingError`
   in case a token is missing (usually because the expression is incomplete),
   `SyntaxError` otherwise.
@@ -940,7 +928,188 @@ defmodule Code do
   end
 
   @doc """
-  Evals the given file.
+  Converts the given string to its quoted form and a list of comments.
+
+  This function is useful when performing textual changes to the source code,
+  while preserving information like comments and literals position.
+
+  Returns `{:ok, quoted_form, comments}` if it succeeds,
+  `{:error, {line, error, token}}` otherwise.
+
+  Comments are maps with the following fields:
+
+    * `:line` - The line number the source code
+
+    * `:text` - The full text of the comment, including the leading `#`
+
+    * `:previous_eol_count` - How many end of lines there are between the comment and the previous AST node or comment
+
+    * `:next_eol_count` - How many end of lines there are between the comment and the next AST node or comment
+
+  Check `string_to_quoted/2` for options information.
+
+  ## Examples
+
+      iex> Code.string_to_quoted_with_comments("\""
+      ...> :foo
+      ...>
+      ...> # Hello, world!
+      ...>
+      ...>
+      ...> # Some more comments!
+      ...> "\"")
+      {:ok, :foo, [
+        %{line: 3, column: 1, previous_eol_count: 2, next_eol_count: 3, text: "\# Hello, world!"},
+        %{line: 6, column: 1, previous_eol_count: 3, next_eol_count: 1, text: "\# Some more comments!"},
+      ]}
+
+      iex> Code.string_to_quoted_with_comments(":foo # :bar")
+      {:ok, :foo, [
+        %{line: 1, column: 6, previous_eol_count: 0, next_eol_count: 0, text: "\# :bar"}
+      ]}
+
+  """
+  @doc since: "1.13.0"
+  @spec string_to_quoted_with_comments(List.Chars.t(), keyword) ::
+          {:ok, Macro.t(), list(map())} | {:error, {location :: keyword, term, term}}
+  def string_to_quoted_with_comments(string, opts \\ []) when is_list(opts) do
+    charlist = to_charlist(string)
+    file = Keyword.get(opts, :file, "nofile")
+    line = Keyword.get(opts, :line, 1)
+    column = Keyword.get(opts, :column, 1)
+
+    Process.put(:code_formatter_comments, [])
+    opts = [preserve_comments: &preserve_comments/5] ++ opts
+
+    with {:ok, tokens} <- :elixir.string_to_tokens(charlist, line, column, file, opts),
+         {:ok, forms} <- :elixir.tokens_to_quoted(tokens, file, opts) do
+      comments = Enum.reverse(Process.get(:code_formatter_comments))
+      {:ok, forms, comments}
+    end
+  after
+    Process.delete(:code_formatter_comments)
+  end
+
+  @doc """
+  Converts the given string to its quoted form and a list of comments.
+
+  Returns the AST and a list of comments if it succeeds, raises an exception
+  otherwise. The exception is a `TokenMissingError` in case a token is missing
+  (usually because the expression is incomplete), `SyntaxError` otherwise.
+
+  Check `string_to_quoted/2` for options information.
+  """
+  @doc since: "1.13.0"
+  @spec string_to_quoted_with_comments!(List.Chars.t(), keyword) :: {Macro.t(), list(map())}
+  def string_to_quoted_with_comments!(string, opts \\ []) do
+    charlist = to_charlist(string)
+
+    case string_to_quoted_with_comments(charlist, opts) do
+      {:ok, forms, comments} ->
+        {forms, comments}
+
+      {:error, {location, error, token}} ->
+        :elixir_errors.parse_error(
+          location,
+          Keyword.get(opts, :file, "nofile"),
+          error,
+          token,
+          {charlist, Keyword.get(opts, :line, 1), Keyword.get(opts, :column, 1)}
+        )
+    end
+  end
+
+  defp preserve_comments(line, column, tokens, comment, rest) do
+    comments = Process.get(:code_formatter_comments)
+
+    comment = %{
+      line: line,
+      column: column,
+      previous_eol_count: previous_eol_count(tokens),
+      next_eol_count: next_eol_count(rest, 0),
+      text: List.to_string(comment)
+    }
+
+    Process.put(:code_formatter_comments, [comment | comments])
+  end
+
+  defp next_eol_count('\s' ++ rest, count), do: next_eol_count(rest, count)
+  defp next_eol_count('\t' ++ rest, count), do: next_eol_count(rest, count)
+  defp next_eol_count('\n' ++ rest, count), do: next_eol_count(rest, count + 1)
+  defp next_eol_count('\r\n' ++ rest, count), do: next_eol_count(rest, count + 1)
+  defp next_eol_count(_, count), do: count
+
+  defp previous_eol_count([{token, {_, _, count}} | _])
+       when token in [:eol, :",", :";"] and count > 0 do
+    count
+  end
+
+  defp previous_eol_count([]), do: 1
+  defp previous_eol_count(_), do: 0
+
+  @doc ~S"""
+  Converts a quoted expression to an algebra document using Elixir's formatter rules.
+
+  The algebra document can be converted into a string by calling:
+
+      doc
+      |> Inspect.Algebra.format(:infinity)
+      |> IO.iodata_to_binary()
+
+  For a high-level function that does the same, see `Macro.to_string/1`.
+
+  ## Formatting considerations
+
+  The Elixir AST does not contain metadata for literals like strings, lists, or
+  tuples with two elements, which means that the produced algebra document will
+  not respect all of the user preferences and comments may be misplaced.
+  To get better results, you can use the `:token_metadata`, `:unescape` and
+  `:literal_encoder` options to `string_to_quoted/2` to provide additional
+  information to the formatter:
+
+      [
+        literal_encoder: &{:ok, {:__block__, &2, [&1]}},
+        token_metadata: true,
+        unescape: false
+      ]
+
+  This will produce an AST that contains information such as `do` blocks start
+  and end lines or sigil delimiters, and by wrapping literals in blocks they can
+  now hold metadata like line number, string delimiter and escaped sequences, or
+  integer formatting (such as `0x2a` instead of `47`). However, **note this AST is
+  not valid**. If you evaluate it, it won't have the same semantics as the regular
+  Elixir AST due to the `:unescape` and `:literal_encoder` options. However,
+  those options are useful if you're doing source code manipulation, where it's
+  important to preserve user choices and comments placing.
+
+  ## Options
+
+    * `:comments` - the list of comments associated with the quoted expression.
+      Defaults to `[]`. It is recommended that both `:token_metadata` and
+      `:literal_encoder` options are given to `string_to_quoted_with_comments/2`
+      in order to get proper placement for comments
+
+    * `:escape` - when `true`, escaped sequences like `\n` will be escaped into
+      `\\n`. If the `:unescape` option was set to `false` when using
+      `string_to_quoted/2`, setting this option to `false` will prevent it from
+      escaping the sequences twice. Defaults to `true`.
+
+    * `:locals_without_parens` - a keyword list of name and arity
+      pairs that should be kept without parens whenever possible.
+      The arity may be the atom `:*`, which implies all arities of
+      that name. The formatter already includes a list of functions
+      and this option augments this list.
+  """
+  @doc since: "1.13.0"
+  @spec quoted_to_algebra(Macro.t(), keyword) :: Inspect.Algebra.t()
+  def quoted_to_algebra(quoted, opts \\ []) do
+    quoted
+    |> Code.Normalizer.normalize(opts)
+    |> Code.Formatter.to_algebra(opts)
+  end
+
+  @doc """
+  Evaluates the given file.
 
   Accepts `relative_to` as an argument to tell where the file is located.
 
@@ -959,9 +1128,14 @@ defmodule Code do
   def load_file(file, relative_to \\ nil) when is_binary(file) do
     file = find_file(file, relative_to)
     :elixir_code_server.call({:acquire, file})
-    loaded = :elixir_compiler.file(file, fn _, _ -> :ok end)
+
+    loaded =
+      Module.ParallelChecker.verify(fn ->
+        :elixir_compiler.file(file, fn _, _ -> :ok end)
+      end)
+
     :elixir_code_server.cast({:required, file})
-    verify_loaded(loaded)
+    loaded
   end
 
   @doc """
@@ -1005,9 +1179,13 @@ defmodule Code do
         nil
 
       :proceed ->
-        loaded = :elixir_compiler.file(file, fn _, _ -> :ok end)
+        loaded =
+          Module.ParallelChecker.verify(fn ->
+            :elixir_compiler.file(file, fn _, _ -> :ok end)
+          end)
+
         :elixir_code_server.cast({:required, file})
-        verify_loaded(loaded)
+        loaded
     end
   end
 
@@ -1033,8 +1211,8 @@ defmodule Code do
   @doc """
   Stores all given compilation options.
 
-  To store individual options, see `put_compiler_option/2`.
-  For a description of all options, see `put_compiler_option/2`.
+  To store individual options and for a description of all
+  options, see `put_compiler_option/2`.
 
   ## Examples
 
@@ -1212,7 +1390,7 @@ defmodule Code do
   @spec compile_string(List.Chars.t(), binary) :: [{module, binary}]
   def compile_string(string, file \\ "nofile") when is_binary(file) do
     loaded = :elixir_compiler.string(to_charlist(string), file, fn _, _ -> :ok end)
-    Enum.map(loaded, fn {module, _map, binary} -> {module, binary} end)
+    Enum.map(loaded, &elem(&1, 0))
   end
 
   @doc """
@@ -1226,7 +1404,7 @@ defmodule Code do
   @spec compile_quoted(Macro.t(), binary) :: [{module, binary}]
   def compile_quoted(quoted, file \\ "nofile") when is_binary(file) do
     loaded = :elixir_compiler.quoted(quoted, file, fn _, _ -> :ok end)
-    Enum.map(loaded, fn {module, _map, binary} -> {module, binary} end)
+    Enum.map(loaded, &elem(&1, 0))
   end
 
   @doc """
@@ -1246,8 +1424,9 @@ defmodule Code do
   @doc since: "1.7.0"
   @spec compile_file(binary, nil | binary) :: [{module, binary}]
   def compile_file(file, relative_to \\ nil) when is_binary(file) do
-    loaded = :elixir_compiler.file(find_file(file, relative_to), fn _, _ -> :ok end)
-    verify_loaded(loaded)
+    Module.ParallelChecker.verify(fn ->
+      :elixir_compiler.file(find_file(file, relative_to), fn _, _ -> :ok end)
+    end)
   end
 
   @doc """
@@ -1297,6 +1476,7 @@ defmodule Code do
   @doc """
   Same as `ensure_loaded/1` but raises if the module cannot be loaded.
   """
+  @doc since: "1.12.0"
   @spec ensure_loaded!(module) :: module
   def ensure_loaded!(module) do
     case ensure_loaded(module) do
@@ -1419,7 +1599,7 @@ defmodule Code do
   file.
 
   It returns the term stored in the documentation chunk in the format defined by
-  [EEP 48](https://erlang.org/eep/eeps/eep-0048.html) or `{:error, reason}` if
+  [EEP 48](https://www.erlang.org/eeps/eep-0048.html) or `{:error, reason}` if
   the chunk is not available.
 
   ## Examples
@@ -1522,7 +1702,7 @@ defmodule Code do
   @doc ~S"""
   Deprecated function to retrieve old documentation format.
 
-  Elixir v1.7 adopts [EEP 48](https://erlang.org/eep/eeps/eep-0048.html)
+  Elixir v1.7 adopts [EEP 48](https://www.erlang.org/eeps/eep-0048.html)
   which is a new documentation format meant to be shared across all
   BEAM languages. The old format, used by `Code.get_docs/2`, is no
   longer available, and therefore this function always returns `nil`.
@@ -1553,10 +1733,4 @@ defmodule Code do
       raise Code.LoadError, file: file
     end
   end
-
-  defp verify_loaded(loaded) do
-    maps_binaries = Enum.map(loaded, fn {_module, map, binary} -> {map, binary} end)
-    Module.ParallelChecker.verify(maps_binaries, [])
-    Enum.map(loaded, fn {module, _map, binary} -> {module, binary} end)
-  end
 end

lib/elixir/lib/code/formatter.ex

@@ -13,7 +13,7 @@ defmodule Code.Formatter do
   @ampersand_prec Code.Identifier.unary_op(:&) |> elem(1)
 
   # Operators that are composed of multiple binary operators
-  @multi_binary_operators [:..//]
+  @multi_binary_operators [:"..//"]
 
   # Operators that do not have space between operands
   @no_space_binary_operators [:.., :"//"]
@@ -142,170 +142,92 @@ defmodule Code.Formatter do
   @do_end_keywords [:rescue, :catch, :else, :after]
 
   @doc """
-  Checks if two strings are equivalent.
+  Converts the quoted expression into an algebra document.
   """
-  def equivalent(string1, string2) when is_binary(string1) and is_binary(string2) do
-    quoted1 = :elixir.string_to_quoted!(to_charlist(string1), 1, 1, "nofile", [])
-    quoted2 = :elixir.string_to_quoted!(to_charlist(string2), 1, 1, "nofile", [])
+  def to_algebra(quoted, opts \\ []) do
+    comments = Keyword.get(opts, :comments, [])
 
-    case not_equivalent(quoted1, quoted2) do
-      {left, right} -> {:error, left, right}
-      nil -> :ok
-    end
-  end
+    state =
+      comments
+      |> Enum.map(&format_comment/1)
+      |> gather_comments()
+      |> state(opts)
 
-  defp not_equivalent({:__block__, _, [left]}, right) do
-    not_equivalent(left, right)
-  end
-
-  defp not_equivalent(left, {:__block__, _, [right]}) do
-    not_equivalent(left, right)
-  end
-
-  defp not_equivalent({:__block__, _, []}, nil) do
-    nil
-  end
-
-  defp not_equivalent(nil, {:__block__, _, []}) do
-    nil
-  end
-
-  defp not_equivalent([left | lefties], [right | righties]) do
-    not_equivalent(left, right) || not_equivalent(lefties, righties)
-  end
-
-  defp not_equivalent({left_name, _, left_args}, {right_name, _, right_args}) do
-    not_equivalent(left_name, right_name) || not_equivalent(left_args, right_args)
-  end
-
-  defp not_equivalent({left1, left2}, {right1, right2}) do
-    not_equivalent(left1, right1) || not_equivalent(left2, right2)
-  end
-
-  defp not_equivalent(side, side) do
-    nil
-  end
-
-  defp not_equivalent(left, right) do
-    {left, right}
+    {doc, _} = block_to_algebra(quoted, @min_line, @max_line, state)
+    doc
   end
 
   @doc """
-  Converts `string` to an algebra document.
-
-  Returns `{:ok, doc}` or `{:error, parser_error}`.
-
-  See `Code.format_string!/2` for the list of options.
+  Lists all default locals without parens.
   """
-  def to_algebra(string, opts \\ []) when is_binary(string) and is_list(opts) do
-    file = Keyword.get(opts, :file, "nofile")
-    line = Keyword.get(opts, :line, 1)
-    charlist = String.to_charlist(string)
-
-    Process.put(:code_formatter_comments, [])
-
-    tokenizer_options = [
-      unescape: false,
-      preserve_comments: &preserve_comments/5,
-      warn_on_unnecessary_quotes: false
-    ]
-
-    parser_options = [
-      literal_encoder: &{:ok, {:__block__, &2, [&1]}},
-      token_metadata: true
-    ]
-
-    with {:ok, tokens} <- :elixir.string_to_tokens(charlist, line, 1, file, tokenizer_options),
-         {:ok, forms} <- :elixir.tokens_to_quoted(tokens, file, parser_options) do
-      state =
-        Process.get(:code_formatter_comments)
-        |> Enum.reverse()
-        |> gather_comments()
-        |> state(opts)
-
-      {doc, _} = block_to_algebra(forms, @min_line, @max_line, state)
-      {:ok, doc}
-    end
-  after
-    Process.delete(:code_formatter_comments)
+  def locals_without_parens do
+    @locals_without_parens
   end
 
   @doc """
-  Converts `string` to an algebra document.
-
-  Raises if the `string` cannot be parsed.
-
-  See `Code.format_string!/2` for the list of options.
+  Checks if a function is a local without parens.
   """
-  def to_algebra!(string, opts \\ []) do
-    case to_algebra(string, opts) do
-      {:ok, doc} ->
-        doc
-
-      {:error, {location, error, token}} ->
-        :elixir_errors.parse_error(location, Keyword.get(opts, :file, "nofile"), error, token)
-    end
+  def local_without_parens?(fun, arity, locals_without_parens) do
+    arity > 0 and
+      Enum.any?(locals_without_parens, fn {key, val} ->
+        key == fun and (val == :* or val == arity)
+      end)
   end
 
   defp state(comments, opts) do
     force_do_end_blocks = Keyword.get(opts, :force_do_end_blocks, false)
+    locals_without_parens = Keyword.get(opts, :locals_without_parens, [])
+    file = Keyword.get(opts, :file, nil)
+    sigils = Keyword.get(opts, :sigils, [])
 
-    locals_without_parens =
-      Keyword.get(opts, :locals_without_parens, []) ++ @locals_without_parens
+    sigils =
+      Map.new(sigils, fn {key, value} ->
+        with true <- is_atom(key) and is_function(value, 2),
+             [char] <- Atom.to_charlist(key),
+             true <- char in ?A..?Z do
+          {char, value}
+        else
+          _ ->
+            raise ArgumentError,
+                  ":sigils must be a keyword list with a single uppercased letter as key and an " <>
+                    "anonymous function expecting two arguments as value, got: #{inspect(sigils)}"
+        end
+      end)
 
     %{
       force_do_end_blocks: force_do_end_blocks,
-      locals_without_parens: locals_without_parens,
+      locals_without_parens: locals_without_parens ++ locals_without_parens(),
       operand_nesting: 2,
-      comments: comments
+      skip_eol: false,
+      comments: comments,
+      sigils: sigils,
+      file: file
     }
   end
 
-  # Code comment handling
-
-  defp preserve_comments(line, _column, tokens, comment, rest) do
-    comments = Process.get(:code_formatter_comments)
-    comment = {line, {previous_eol(tokens), next_eol(rest, 0)}, format_comment(comment, [])}
-    Process.put(:code_formatter_comments, [comment | comments])
+  defp format_comment(%{text: text} = comment) do
+    %{comment | text: format_comment_text(text)}
   end
 
-  defp next_eol('\s' ++ rest, count), do: next_eol(rest, count)
-  defp next_eol('\t' ++ rest, count), do: next_eol(rest, count)
-  defp next_eol('\n' ++ rest, count), do: next_eol(rest, count + 1)
-  defp next_eol('\r\n' ++ rest, count), do: next_eol(rest, count + 1)
-  defp next_eol(_, count), do: count
-
-  defp previous_eol([{token, {_, _, count}} | _])
-       when token in [:eol, :",", :";"] and count > 0 do
-    count
-  end
-
-  defp previous_eol([]), do: 1
-  defp previous_eol(_), do: nil
-
-  defp format_comment('##' ++ rest, acc), do: format_comment([?# | rest], [?# | acc])
-
-  defp format_comment('#!', acc), do: reverse_to_string(acc, '#!')
-  defp format_comment('#! ' ++ _ = rest, acc), do: reverse_to_string(acc, rest)
-  defp format_comment('#!' ++ rest, acc), do: reverse_to_string(acc, [?#, ?!, ?\s, rest])
-
-  defp format_comment('#', acc), do: reverse_to_string(acc, '#')
-  defp format_comment('# ' ++ _ = rest, acc), do: reverse_to_string(acc, rest)
-  defp format_comment('#' ++ rest, acc), do: reverse_to_string(acc, [?#, ?\s, rest])
-
-  defp reverse_to_string(acc, prefix) do
-    acc |> Enum.reverse(prefix) |> List.to_string()
-  end
+  defp format_comment_text("#"), do: "#"
+  defp format_comment_text("#!" <> rest), do: "#!" <> rest
+  defp format_comment_text("##" <> rest), do: "#" <> format_comment_text("#" <> rest)
+  defp format_comment_text("# " <> rest), do: "# " <> rest
+  defp format_comment_text("#" <> rest), do: "# " <> rest
 
   # If there is a no new line before, we can't gather all followup comments.
-  defp gather_comments([{line, {nil, next_eol}, doc} | comments]) do
-    comment = {line, {@newlines, next_eol}, doc}
+  defp gather_comments([%{previous_eol_count: 0} = comment | comments]) do
+    comment = %{comment | previous_eol_count: @newlines}
     [comment | gather_comments(comments)]
   end
 
-  defp gather_comments([{line, {previous_eol, next_eol}, doc} | comments]) do
-    {next_eol, comments, doc} = gather_followup_comments(line + 1, next_eol, comments, doc)
-    comment = {line, {previous_eol, next_eol}, doc}
+  defp gather_comments([comment | comments]) do
+    %{line: line, next_eol_count: next_eol_count, text: doc} = comment
+
+    {next_eol_count, comments, doc} =
+      gather_followup_comments(line + 1, next_eol_count, comments, doc)
+
+    comment = %{comment | next_eol_count: next_eol_count, text: doc}
     [comment | gather_comments(comments)]
   end
 
@@ -313,13 +235,14 @@ defmodule Code.Formatter do
     []
   end
 
-  defp gather_followup_comments(line, _, [{line, {previous_eol, next_eol}, text} | comments], doc)
-       when previous_eol != nil do
-    gather_followup_comments(line + 1, next_eol, comments, line(doc, text))
+  defp gather_followup_comments(line, _, [%{line: line} = comment | comments], doc)
+       when comment.previous_eol_count != 0 do
+    %{next_eol_count: next_eol_count, text: text} = comment
+    gather_followup_comments(line + 1, next_eol_count, comments, line(doc, text))
   end
 
-  defp gather_followup_comments(_line, next_eol, comments, doc) do
-    {next_eol, comments, doc}
+  defp gather_followup_comments(_line, next_eol_count, comments, doc) do
+    {next_eol_count, comments, doc}
   end
 
   # Special AST nodes from compiler feedback
@@ -349,7 +272,7 @@ defmodule Code.Formatter do
         {doc, state} =
           entries
           |> prepend_heredoc_line()
-          |> interpolation_to_algebra(:heredoc, state, @double_heredoc, @double_heredoc)
+          |> interpolation_to_algebra(~s["""], state, @double_heredoc, @double_heredoc)
 
         {force_unfit(doc), state}
 
@@ -371,7 +294,7 @@ defmodule Code.Formatter do
         {doc, state} =
           entries
           |> prepend_heredoc_line()
-          |> list_interpolation_to_algebra(:heredoc, state, @single_heredoc, @single_heredoc)
+          |> list_interpolation_to_algebra(~s['''], state, @single_heredoc, @single_heredoc)
 
         {force_unfit(doc), state}
 
@@ -393,10 +316,17 @@ defmodule Code.Formatter do
   end
 
   # foo[bar]
-  defp quoted_to_algebra({{:., _, [Access, :get]}, meta, [target | args]}, _context, state) do
+  defp quoted_to_algebra({{:., _, [Access, :get]}, meta, [target, arg]}, _context, state) do
     {target_doc, state} = remote_target_to_algebra(target, state)
-    {call_doc, state} = list_to_algebra(meta, args, state)
-    {concat(target_doc, call_doc), state}
+
+    {access_doc, state} =
+      if keyword?(arg) do
+        list_to_algebra(meta, arg, state)
+      else
+        list_to_algebra(meta, [arg], state)
+      end
+
+    {concat(target_doc, access_doc), state}
   end
 
   # %Foo{}
@@ -427,7 +357,7 @@ defmodule Code.Formatter do
   defp quoted_to_algebra({:__block__, meta, [list]}, _context, state) when is_list(list) do
     case meta[:delimiter] do
       ~s['''] ->
-        string = list |> List.to_string() |> escape_heredoc()
+        string = list |> List.to_string() |> escape_heredoc(~s['''])
         {@single_heredoc |> concat(string) |> concat(@single_heredoc) |> force_unfit(), state}
 
       ~s['] ->
@@ -441,7 +371,7 @@ defmodule Code.Formatter do
 
   defp quoted_to_algebra({:__block__, meta, [string]}, _context, state) when is_binary(string) do
     if meta[:delimiter] == ~s["""] do
-      string = escape_heredoc(string)
+      string = escape_heredoc(string, ~s["""])
       {@double_heredoc |> concat(string) |> concat(@double_heredoc) |> force_unfit(), state}
     else
       string = escape_string(string, @double_quote)
@@ -516,12 +446,12 @@ defmodule Code.Formatter do
   end
 
   # 1..2//3
-  defp quoted_to_algebra({:..//, meta, [left, middle, right]}, context, state) do
+  defp quoted_to_algebra({:"..//", meta, [left, middle, right]}, context, state) do
     quoted_to_algebra({:"//", meta, [{:.., meta, [left, middle]}, right]}, context, state)
   end
 
   defp quoted_to_algebra({:fn, meta, [_ | _] = clauses}, _context, state) do
-    anon_fun_to_algebra(clauses, line(meta), closing_line(meta), state, eol?(meta))
+    anon_fun_to_algebra(clauses, line(meta), closing_line(meta), state, eol?(meta, state))
   end
 
   defp quoted_to_algebra({fun, meta, args}, context, state) when is_atom(fun) and is_list(args) do
@@ -553,6 +483,10 @@ defmodule Code.Formatter do
       if keyword_key?(left_arg) do
         {left, state} =
           case left_arg do
+            # TODO: Remove this clause in v1.16 when we no longer quote operator :..//
+            {:__block__, _, [:"..//"]} ->
+              {string(~S{"..//":}), state}
+
             {:__block__, _, [atom]} when is_atom(atom) ->
               key =
                 case Code.Identifier.classify(atom) do
@@ -586,6 +520,11 @@ defmodule Code.Formatter do
     {doc, state}
   end
 
+  # #PID's and #Ref's may appear on regular AST
+  defp quoted_to_algebra(unknown, _context, state) do
+    {inspect(unknown), state}
+  end
+
   ## Blocks
 
   defp block_to_algebra([{:->, _, _} | _] = type_fun, min_line, max_line, state) do
@@ -766,7 +705,7 @@ defmodule Code.Formatter do
           concat(concat(group(left), op_string), group(right))
 
         true ->
-          eol? = eol?(meta)
+          eol? = eol?(meta, state)
 
           next_break_fits? =
             op in @next_break_fits_operators and next_break_fits?(right_arg, state) and not eol?
@@ -908,7 +847,7 @@ defmodule Code.Formatter do
     {docs, comments?, state} =
       quoted_to_algebra_with_comments(operands, acc, min_line, max_line, state, fun)
 
-    if comments? or eol?(meta) do
+    if comments? or eol?(meta, state) do
       {docs |> Enum.reduce(&line(&2, &1)) |> force_unfit(), state}
     else
       {docs |> Enum.reduce(&glue(&2, &1)), state}
@@ -1068,9 +1007,14 @@ defmodule Code.Formatter do
   defp local_to_algebra(fun, meta, args, context, state) when is_atom(fun) do
     skip_parens =
       cond do
-        meta?(meta, :closing) -> :skip_if_only_do_end
-        local_without_parens?(fun, args, state) -> :skip_unless_many_args
-        true -> :skip_if_do_end
+        meta?(meta, :closing) ->
+          :skip_if_only_do_end
+
+        local_without_parens?(fun, length(args), state.locals_without_parens) ->
+          :skip_unless_many_args
+
+        true ->
+          :skip_if_do_end
       end
 
     {{call_doc, state}, wrap_in_parens?} =
@@ -1144,7 +1088,7 @@ defmodule Code.Formatter do
       end
 
     args = if keyword?, do: left ++ right, else: left ++ [right]
-    many_eol? = match?([_, _ | _], args) and eol?(meta)
+    many_eol? = match?([_, _ | _], args) and eol?(meta, state)
     no_generators? = no_generators?(args)
     to_algebra_fun = &quoted_to_algebra(&1, context, &2)
 
@@ -1249,15 +1193,6 @@ defmodule Code.Formatter do
     end
   end
 
-  defp local_without_parens?(fun, args, %{locals_without_parens: locals_without_parens}) do
-    length = length(args)
-
-    length > 0 and
-      Enum.any?(locals_without_parens, fn {key, val} ->
-        key == fun and (val == :* or val == length)
-      end)
-  end
-
   defp no_generators?(args) do
     not Enum.any?(args, &match?({:<-, _, [_, _]}, &1))
   end
@@ -1335,8 +1270,7 @@ defmodule Code.Formatter do
 
   defp list_interpolation_to_algebra([entry | entries], escape, state, acc, last) do
     {{:., _, [Kernel, :to_string]}, _meta, [quoted]} = entry
-    {doc, state} = block_to_algebra(quoted, @max_line, @min_line, state)
-    doc = surround("\#{", doc, "}") |> interpolation_to_string()
+    {doc, state} = interpolation_to_string(quoted, state)
     list_interpolation_to_algebra(entries, escape, state, concat(acc, doc), last)
   end
 
@@ -1352,8 +1286,7 @@ defmodule Code.Formatter do
 
   defp interpolation_to_algebra([entry | entries], escape, state, acc, last) do
     {:"::", _, [{{:., _, [Kernel, :to_string]}, _meta, [quoted]}, {:binary, _, _}]} = entry
-    {doc, state} = block_to_algebra(quoted, @max_line, @min_line, state)
-    doc = surround("\#{", doc, "}") |> interpolation_to_string()
+    {doc, state} = interpolation_to_string(quoted, state)
     interpolation_to_algebra(entries, escape, state, concat(acc, doc), last)
   end
 
@@ -1361,6 +1294,12 @@ defmodule Code.Formatter do
     {concat(acc, last), state}
   end
 
+  defp interpolation_to_string(quoted, %{skip_eol: skip_eol} = state) do
+    {doc, state} = block_to_algebra(quoted, @max_line, @min_line, %{state | skip_eol: true})
+    doc = interpolation_to_string(surround("\#{", doc, "}"))
+    {doc, %{state | skip_eol: skip_eol}}
+  end
+
   defp interpolation_to_string(doc) do
     [head | tail] =
       doc
@@ -1380,13 +1319,37 @@ defmodule Code.Formatter do
          opening_delimiter when not is_nil(opening_delimiter) <- meta[:delimiter] do
       doc = <<?~, name, opening_delimiter::binary>>
 
+      entries =
+        case state.sigils do
+          %{^name => callback} ->
+            metadata = [
+              file: state.file,
+              line: meta[:line],
+              sigil: List.to_atom([name]),
+              modifiers: modifiers,
+              opening_delimiter: opening_delimiter
+            ]
+
+            case callback.(hd(entries), metadata) do
+              iodata when is_binary(iodata) or is_list(iodata) ->
+                [IO.iodata_to_binary(iodata)]
+
+              other ->
+                raise ArgumentError,
+                      "expected sigil callback to return iodata, got: #{inspect(other)}"
+            end
+
+          %{} ->
+            entries
+        end
+
       if opening_delimiter in [@double_heredoc, @single_heredoc] do
         closing_delimiter = concat(opening_delimiter, List.to_string(modifiers))
 
         {doc, state} =
           entries
           |> prepend_heredoc_line()
-          |> interpolation_to_algebra(:heredoc, state, doc, closing_delimiter)
+          |> interpolation_to_algebra(opening_delimiter, state, doc, closing_delimiter)
 
         {force_unfit(doc), state}
       else
@@ -1410,7 +1373,7 @@ defmodule Code.Formatter do
 
   defp bitstring_to_algebra(meta, args, state) do
     last = length(args) - 1
-    join = if eol?(meta), do: :line, else: :flex_break
+    join = if eol?(meta, state), do: :line, else: :flex_break
     to_algebra_fun = &bitstring_segment_to_algebra(&1, &2, last)
 
     {args_doc, join, state} =
@@ -1478,7 +1441,7 @@ defmodule Code.Formatter do
   ## Literals
 
   defp list_to_algebra(meta, args, state) do
-    join = if eol?(meta), do: :line, else: :break
+    join = if eol?(meta, state), do: :line, else: :break
     fun = &quoted_to_algebra(&1, :parens_arg, &2)
 
     {args_doc, _join, state} =
@@ -1488,7 +1451,7 @@ defmodule Code.Formatter do
   end
 
   defp map_to_algebra(meta, name_doc, [{:|, _, [left, right]}], state) do
-    join = if eol?(meta), do: :line, else: :break
+    join = if eol?(meta, state), do: :line, else: :break
     fun = &quoted_to_algebra(&1, :parens_arg, &2)
     {left_doc, state} = fun.(left, state)
 
@@ -1505,7 +1468,7 @@ defmodule Code.Formatter do
   end
 
   defp map_to_algebra(meta, name_doc, args, state) do
-    join = if eol?(meta), do: :line, else: :break
+    join = if eol?(meta, state), do: :line, else: :break
     fun = &quoted_to_algebra(&1, :parens_arg, &2)
 
     {args_doc, _join, state} =
@@ -1516,7 +1479,7 @@ defmodule Code.Formatter do
   end
 
   defp tuple_to_algebra(meta, args, join, state) do
-    join = if eol?(meta), do: :line, else: join
+    join = if eol?(meta, state), do: :line, else: join
     fun = &quoted_to_algebra(&1, :parens_arg, &2)
 
     {args_doc, join, state} =
@@ -1533,6 +1496,11 @@ defmodule Code.Formatter do
     Atom.to_string(atom)
   end
 
+  # TODO: Remove this clause in v1.16 when we no longer quote operator :..//
+  defp atom_to_algebra(:"..//") do
+    string(":\"..//\"")
+  end
+
   defp atom_to_algebra(atom) do
     string = Atom.to_string(atom)
 
@@ -1590,11 +1558,13 @@ defmodule Code.Formatter do
     end
   end
 
-  defp escape_heredoc(string) do
+  defp escape_heredoc(string, escape) do
+    string = String.replace(string, escape, "\\" <> escape)
     heredoc_to_algebra(["" | String.split(string, "\n")])
   end
 
-  defp escape_string(string, :heredoc) do
+  defp escape_string(string, <<_, _, _>> = escape) do
+    string = String.replace(string, escape, "\\" <> escape)
     heredoc_to_algebra(String.split(string, "\n"))
   end
 
@@ -1693,7 +1663,7 @@ defmodule Code.Formatter do
       |> glue(body_doc)
       |> nest(2)
       |> glue("end")
-      |> maybe_force_clauses(clauses)
+      |> maybe_force_clauses(clauses, state)
       |> group()
 
     {doc, state}
@@ -1727,7 +1697,7 @@ defmodule Code.Formatter do
       |> glue(body_doc)
       |> nest(2)
       |> glue("end")
-      |> maybe_force_clauses(clauses)
+      |> maybe_force_clauses(clauses, state)
       |> group()
 
     {doc, state}
@@ -1755,7 +1725,7 @@ defmodule Code.Formatter do
       "(() -> "
       |> concat(nest(body_doc, :cursor))
       |> concat(")")
-      |> maybe_force_clauses(clauses)
+      |> maybe_force_clauses(clauses, state)
       |> group()
 
     {doc, state}
@@ -1776,7 +1746,7 @@ defmodule Code.Formatter do
       |> group()
       |> concat(break() |> concat(body_doc) |> nest(2))
       |> wrap_in_parens()
-      |> maybe_force_clauses(clauses)
+      |> maybe_force_clauses(clauses, state)
       |> group()
 
     {doc, state}
@@ -1795,8 +1765,8 @@ defmodule Code.Formatter do
 
   ## Clauses
 
-  defp maybe_force_clauses(doc, clauses) do
-    if Enum.any?(clauses, fn {:->, meta, _} -> eol?(meta) end) do
+  defp maybe_force_clauses(doc, clauses, state) do
+    if Enum.any?(clauses, fn {:->, meta, _} -> eol?(meta, state) end) do
       force_unfit(doc)
     else
       doc
@@ -1819,7 +1789,7 @@ defmodule Code.Formatter do
         {doc_acc, state_acc}
       end)
 
-    {clauses_doc |> maybe_force_clauses([clause | clauses]) |> group(), state}
+    {clauses_doc |> maybe_force_clauses([clause | clauses], state) |> group(), state}
   end
 
   defp clauses_to_algebra(other, min_line, max_line, state) do
@@ -1899,7 +1869,7 @@ defmodule Code.Formatter do
   defp quoted_to_algebra_with_comments(args, acc, min_line, max_line, state, fun) do
     {pre_comments, state} =
       get_and_update_in(state.comments, fn comments ->
-        Enum.split_while(comments, fn {line, _, _} -> line <= min_line end)
+        Enum.split_while(comments, fn %{line: line} -> line <= min_line end)
       end)
 
     {docs, comments?, state} =
@@ -1915,23 +1885,29 @@ defmodule Code.Formatter do
   end
 
   defp each_quoted_to_algebra_with_comments([arg | args], acc, max_line, state, comments?, fun) do
-    {doc_start, doc_end} = traverse_line(arg, {@max_line, @min_line})
+    case traverse_line(arg, {@max_line, @min_line}) do
+      {@max_line, @min_line} ->
+        {doc_triplet, state} = fun.(arg, args, state)
+        acc = [doc_triplet | acc]
+        each_quoted_to_algebra_with_comments(args, acc, max_line, state, comments?, fun)
 
-    {acc, comments, comments?} =
-      extract_comments_before(doc_start, acc, state.comments, comments?)
+      {doc_start, doc_end} ->
+        {acc, comments, comments?} =
+          extract_comments_before(doc_start, acc, state.comments, comments?)
 
-    {doc_triplet, state} = fun.(arg, args, %{state | comments: comments})
+        {doc_triplet, state} = fun.(arg, args, %{state | comments: comments})
 
-    {acc, comments, comments?} =
-      extract_comments_trailing(doc_start, doc_end, acc, state.comments, comments?)
+        {acc, comments, comments?} =
+          extract_comments_trailing(doc_start, doc_end, acc, state.comments, comments?)
 
-    acc = [adjust_trailing_newlines(doc_triplet, doc_end, comments) | acc]
-    state = %{state | comments: comments}
-    each_quoted_to_algebra_with_comments(args, acc, max_line, state, comments?, fun)
+        acc = [adjust_trailing_newlines(doc_triplet, doc_end, comments) | acc]
+        state = %{state | comments: comments}
+        each_quoted_to_algebra_with_comments(args, acc, max_line, state, comments?, fun)
+    end
   end
 
-  defp extract_comments_before(max, acc, [{line, _, _} = comment | rest], _) when line < max do
-    {_, {previous, next}, doc} = comment
+  defp extract_comments_before(max, acc, [%{line: line} = comment | rest], _) when line < max do
+    %{previous_eol_count: previous, next_eol_count: next, text: doc} = comment
     acc = [{doc, @empty, next} | add_previous_to_acc(acc, previous)]
     extract_comments_before(max, acc, rest, true)
   end
@@ -1946,7 +1922,7 @@ defmodule Code.Formatter do
   defp add_previous_to_acc(acc, _previous),
     do: acc
 
-  defp extract_comments_trailing(min, max, acc, [{line, _, doc_comment} | rest], _)
+  defp extract_comments_trailing(min, max, acc, [%{line: line, text: doc_comment} | rest], _)
        when line >= min and line <= max do
     acc = [{doc_comment, @empty, 1} | acc]
     extract_comments_trailing(min, max, acc, rest, true)
@@ -1958,7 +1934,7 @@ defmodule Code.Formatter do
 
   # If the document is immediately followed by comment which is followed by newlines,
   # its newlines wouldn't have considered the comment, so we need to adjust it.
-  defp adjust_trailing_newlines({doc, next_line, newlines}, doc_end, [{line, _, _} | _])
+  defp adjust_trailing_newlines({doc, next_line, newlines}, doc_end, [%{line: line} | _])
        when newlines > 1 and line == doc_end + 1 do
     {doc, next_line, 1}
   end
@@ -2160,12 +2136,12 @@ defmodule Code.Formatter do
     false
   end
 
-  defp eol_or_comments?(meta, %{comments: comments}) do
-    eol?(meta) or
+  defp eol_or_comments?(meta, %{comments: comments} = state) do
+    eol?(meta, state) or
       (
         min_line = line(meta)
         max_line = closing_line(meta)
-        Enum.any?(comments, fn {line, _, _} -> line > min_line and line < max_line end)
+        Enum.any?(comments, fn %{line: line} -> line > min_line and line < max_line end)
       )
   end
 
@@ -2190,8 +2166,8 @@ defmodule Code.Formatter do
         {{_, arg_meta, _}, _} = hd(arg)
         first_line = line(arg_meta)
 
-        case Enum.drop_while(comments, fn {line, _, _} -> line <= block_line end) do
-          [{line, _, _} | _] when line <= first_line ->
+        case Enum.drop_while(comments, fn %{line: line} -> line <= block_line end) do
+          [%{line: line} | _] when line <= first_line ->
             {false, block}
 
           _ ->
@@ -2209,7 +2185,7 @@ defmodule Code.Formatter do
   end
 
   defp force_args?(args) do
-    match?([_, _ | _], args) and force_args?(args, MapSet.new())
+    match?([_ | _], args) and force_args?(args, %{})
   end
 
   defp force_args?([[arg | _] | args], lines) do
@@ -2219,18 +2195,19 @@ defmodule Code.Formatter do
   defp force_args?([arg | args], lines) do
     line =
       case arg do
-        {{_, meta, _}, _} -> line(meta)
-        {_, meta, _} -> line(meta)
+        {{_, meta, _}, _} -> meta[:line]
+        {_, meta, _} -> meta[:line]
       end
 
-    if MapSet.member?(lines, line) do
-      false
-    else
-      force_args?(args, MapSet.put(lines, line))
+    cond do
+      # Line may be missing from non-formatter AST
+      is_nil(line) -> force_args?(args, lines)
+      Map.has_key?(lines, line) -> false
+      true -> force_args?(args, Map.put(lines, line, true))
     end
   end
 
-  defp force_args?([], _lines), do: true
+  defp force_args?([], lines), do: map_size(lines) >= 2
 
   defp force_keyword(doc, arg) do
     if force_args?(arg), do: force_unfit(doc), else: doc
@@ -2248,9 +2225,8 @@ defmodule Code.Formatter do
   defp keyword_key?(_),
     do: false
 
-  defp eol?(meta) do
-    Keyword.get(meta, :newlines, 0) > 0
-  end
+  defp eol?(_meta, %{skip_eol: true}), do: false
+  defp eol?(meta, _state), do: Keyword.get(meta, :newlines, 0) > 0
 
   defp meta?(meta, key) do
     is_list(meta[key])

lib/elixir/lib/code/fragment.ex

@@ -0,0 +1,841 @@
+defmodule Code.Fragment do
+  @moduledoc """
+  This module provides conveniences for analyzing fragments of
+  textual code and extract available information whenever possible.
+
+  Most of the functions in this module provide a best-effort
+  and may not be accurate under all circumstances. Read each
+  documentation for more information.
+
+  This module should be considered experimental.
+  """
+
+  @type position :: {line :: pos_integer(), column :: pos_integer()}
+
+  @doc """
+  Receives a string and returns the cursor context.
+
+  This function receives a string with an Elixir code fragment,
+  representing a cursor position, and based on the string, it
+  provides contextual information about said position. The
+  return of this function can then be used to provide tips,
+  suggestions, and autocompletion functionality.
+
+  This function provides a best-effort detection and may not be
+  accurate under all circumstances. See the "Limitations"
+  section below.
+
+  Consider adding a catch-all clause when handling the return
+  type of this function as new cursor information may be added
+  in future releases.
+
+  ## Examples
+
+      iex> Code.Fragment.cursor_context("")
+      :expr
+
+      iex> Code.Fragment.cursor_context("hello_wor")
+      {:local_or_var, 'hello_wor'}
+
+  ## Return values
+
+    * `{:alias, charlist}` - the context is an alias, potentially
+      a nested one, such as `Hello.Wor` or `HelloWor`
+
+    * `{:dot, inside_dot, charlist}` - the context is a dot
+      where `inside_dot` is either a `{:var, charlist}`, `{:alias, charlist}`,
+      `{:module_attribute, charlist}`, `{:unquoted_atom, charlist}` or a `dot`
+      itself. If a var is given, this may either be a remote call or a map
+      field access. Examples are `Hello.wor`, `:hello.wor`, `hello.wor`,
+      `Hello.nested.wor`, `hello.nested.wor`, and `@hello.world`
+
+    * `{:dot_arity, inside_dot, charlist}` - the context is a dot arity
+      where `inside_dot` is either a `{:var, charlist}`, `{:alias, charlist}`,
+      `{:module_attribute, charlist}`, `{:unquoted_atom, charlist}` or a `dot`
+      itself. If a var is given, it must be a remote arity. Examples are
+      `Hello.world/`, `:hello.world/`, `hello.world/2`, and `@hello.world/2`
+
+    * `{:dot_call, inside_dot, charlist}` - the context is a dot
+      call. This means parentheses or space have been added after the expression.
+      where `inside_dot` is either a `{:var, charlist}`, `{:alias, charlist}`,
+      `{:module_attribute, charlist}`, `{:unquoted_atom, charlist}` or a `dot`
+      itself. If a var is given, it must be a remote call. Examples are
+      `Hello.world(`, `:hello.world(`, `Hello.world `, `hello.world(`, `hello.world `,
+      and `@hello.world(`
+
+    * `:expr` - may be any expression. Autocompletion may suggest an alias,
+      local or var
+
+    * `{:local_or_var, charlist}` - the context is a variable or a local
+      (import or local) call, such as `hello_wor`
+
+    * `{:local_arity, charlist}` - the context is a local (import or local)
+      arity, such as `hello_world/`
+
+    * `{:local_call, charlist}` - the context is a local (import or local)
+      call, such as `hello_world(` and `hello_world `
+
+    * `{:module_attribute, charlist}` - the context is a module attribute,
+      such as `@hello_wor`
+
+    * `{:operator, charlist}` - the context is an operator, such as `+` or
+      `==`. Note textual operators, such as `when` do not appear as operators
+      but rather as `:local_or_var`. `@` is never an `:operator` and always a
+      `:module_attribute`
+
+    * `{:operator_arity, charlist}` - the context is an operator arity, which
+      is an operator followed by /, such as `+/`, `not/` or `when/`
+
+    * `{:operator_call, charlist}` - the context is an operator call, which is
+      an operator followed by space, such as `left + `, `not ` or `x when `
+
+    * `:none` - no context possible
+
+    * `{:sigil, charlist}` - the context is a sigil. It may be either the beginning
+      of a sigil, such as `~` or `~s`, or an operator starting with `~`, such as
+      `~>` and `~>>`
+
+    * `{:struct, charlist}` - the context is a struct, such as `%`, `%UR` or `%URI`
+
+    * `{:unquoted_atom, charlist}` - the context is an unquoted atom. This
+      can be any atom or an atom representing a module
+
+  ## Limitations
+
+  The current algorithm only considers the last line of the input. This means
+  it will also show suggestions inside strings, heredocs, etc, which is
+  intentional as it helps with doctests, references, and more.
+  """
+  @doc since: "1.13.0"
+  @spec cursor_context(List.Chars.t(), keyword()) ::
+          {:alias, charlist}
+          | {:dot, inside_dot, charlist}
+          | {:dot_arity, inside_dot, charlist}
+          | {:dot_call, inside_dot, charlist}
+          | :expr
+          | {:local_or_var, charlist}
+          | {:local_arity, charlist}
+          | {:local_call, charlist}
+          | {:module_attribute, charlist}
+          | {:operator, charlist}
+          | {:operator_arity, charlist}
+          | {:operator_call, charlist}
+          | :none
+          | {:sigil, charlist}
+          | {:struct, charlist}
+          | {:unquoted_atom, charlist}
+        when inside_dot:
+               {:alias, charlist}
+               | {:dot, inside_dot, charlist}
+               | {:module_attribute, charlist}
+               | {:unquoted_atom, charlist}
+               | {:var, charlist}
+  def cursor_context(fragment, opts \\ [])
+
+  def cursor_context(binary, opts) when is_binary(binary) and is_list(opts) do
+    binary =
+      case :binary.matches(binary, "\n") do
+        [] ->
+          binary
+
+        matches ->
+          {position, _} = List.last(matches)
+          binary_part(binary, position + 1, byte_size(binary) - position - 1)
+      end
+
+    binary
+    |> String.to_charlist()
+    |> :lists.reverse()
+    |> codepoint_cursor_context(opts)
+    |> elem(0)
+  end
+
+  def cursor_context(charlist, opts) when is_list(charlist) and is_list(opts) do
+    charlist =
+      case charlist |> Enum.chunk_by(&(&1 == ?\n)) |> List.last([]) do
+        [?\n | _] -> []
+        rest -> rest
+      end
+
+    charlist
+    |> :lists.reverse()
+    |> codepoint_cursor_context(opts)
+    |> elem(0)
+  end
+
+  def cursor_context(other, opts) when is_list(opts) do
+    cursor_context(to_charlist(other), opts)
+  end
+
+  @operators '\\<>+-*/:=|&~^%!'
+  @starter_punctuation ',([{;'
+  @non_starter_punctuation ')]}"\'.$'
+  @space '\t\s'
+  @trailing_identifier '?!'
+  @tilde_op_prefix '<=~'
+
+  @non_identifier @trailing_identifier ++
+                    @operators ++ @starter_punctuation ++ @non_starter_punctuation ++ @space
+
+  @textual_operators ~w(when not and or in)c
+  @incomplete_operators ~w(^^ ~~ ~)c
+
+  defp codepoint_cursor_context(reverse, _opts) do
+    {stripped, spaces} = strip_spaces(reverse, 0)
+
+    case stripped do
+      # It is empty
+      [] -> {:expr, 0}
+      # Structs
+      [?%, ?:, ?: | _] -> {{:struct, ''}, 1}
+      [?%, ?: | _] -> {{:unquoted_atom, '%'}, 2}
+      [?% | _] -> {{:struct, ''}, 1}
+      # Token/AST only operators
+      [?>, ?= | rest] when rest == [] or hd(rest) != ?: -> {:expr, 0}
+      [?>, ?- | rest] when rest == [] or hd(rest) != ?: -> {:expr, 0}
+      # Two-digit containers
+      [?<, ?< | rest] when rest == [] or hd(rest) != ?< -> {:expr, 0}
+      # Ambiguity around :
+      [?: | rest] when rest == [] or hd(rest) != ?: -> unquoted_atom_or_expr(spaces)
+      # Dots
+      [?.] -> {:none, 0}
+      [?. | rest] when hd(rest) not in '.:' -> dot(rest, spaces + 1, '')
+      # It is a local or remote call with parens
+      [?( | rest] -> call_to_cursor_context(strip_spaces(rest, spaces + 1))
+      # A local arity definition
+      [?/ | rest] -> arity_to_cursor_context(strip_spaces(rest, spaces + 1))
+      # Starting a new expression
+      [h | _] when h in @starter_punctuation -> {:expr, 0}
+      # It is a local or remote call without parens
+      rest when spaces > 0 -> call_to_cursor_context({rest, spaces})
+      # It is an identifier
+      _ -> identifier_to_cursor_context(reverse, 0, false)
+    end
+  end
+
+  defp strip_spaces([h | rest], count) when h in @space, do: strip_spaces(rest, count + 1)
+  defp strip_spaces(rest, count), do: {rest, count}
+
+  defp unquoted_atom_or_expr(0), do: {{:unquoted_atom, ''}, 1}
+  defp unquoted_atom_or_expr(_), do: {:expr, 0}
+
+  defp arity_to_cursor_context({reverse, spaces}) do
+    case identifier_to_cursor_context(reverse, spaces, true) do
+      {{:local_or_var, acc}, count} -> {{:local_arity, acc}, count}
+      {{:dot, base, acc}, count} -> {{:dot_arity, base, acc}, count}
+      {{:operator, acc}, count} -> {{:operator_arity, acc}, count}
+      {_, _} -> {:none, 0}
+    end
+  end
+
+  defp call_to_cursor_context({reverse, spaces}) do
+    case identifier_to_cursor_context(reverse, spaces, true) do
+      {{:local_or_var, acc}, count} -> {{:local_call, acc}, count}
+      {{:dot, base, acc}, count} -> {{:dot_call, base, acc}, count}
+      {{:operator, acc}, count} -> {{:operator_call, acc}, count}
+      {_, _} -> {:none, 0}
+    end
+  end
+
+  defp identifier_to_cursor_context([?., ?., ?: | _], n, _), do: {{:unquoted_atom, '..'}, n + 3}
+  defp identifier_to_cursor_context([?., ?., ?. | _], n, _), do: {{:local_or_var, '...'}, n + 3}
+  defp identifier_to_cursor_context([?., ?: | _], n, _), do: {{:unquoted_atom, '.'}, n + 2}
+  defp identifier_to_cursor_context([?., ?. | _], n, _), do: {{:operator, '..'}, n + 2}
+
+  defp identifier_to_cursor_context(reverse, count, call_op?) do
+    case identifier(reverse, count) do
+      :none ->
+        {:none, 0}
+
+      :operator ->
+        operator(reverse, count, [], call_op?)
+
+      {:module_attribute, acc, count} ->
+        {{:module_attribute, acc}, count}
+
+      {:sigil, acc, count} ->
+        {{:sigil, acc}, count}
+
+      {:unquoted_atom, acc, count} ->
+        {{:unquoted_atom, acc}, count}
+
+      {:alias, rest, acc, count} ->
+        case strip_spaces(rest, count) do
+          {'.' ++ rest, count} when rest == [] or hd(rest) != ?. ->
+            nested_alias(rest, count + 1, acc)
+
+          {'%' ++ _, count} ->
+            {{:struct, acc}, count + 1}
+
+          _ ->
+            {{:alias, acc}, count}
+        end
+
+      {:identifier, _, acc, count} when call_op? and acc in @textual_operators ->
+        {{:operator, acc}, count}
+
+      {:identifier, rest, acc, count} ->
+        case strip_spaces(rest, count) do
+          {'.' ++ rest, count} when rest == [] or hd(rest) != ?. ->
+            dot(rest, count + 1, acc)
+
+          _ ->
+            {{:local_or_var, acc}, count}
+        end
+    end
+  end
+
+  defp identifier([?? | rest], count), do: check_identifier(rest, count + 1, [??])
+  defp identifier([?! | rest], count), do: check_identifier(rest, count + 1, [?!])
+  defp identifier(rest, count), do: check_identifier(rest, count, [])
+
+  defp check_identifier([h | t], count, acc) when h not in @non_identifier,
+    do: rest_identifier(t, count + 1, [h | acc])
+
+  defp check_identifier(_, _, _), do: :operator
+
+  defp rest_identifier([h | rest], count, acc) when h not in @non_identifier do
+    rest_identifier(rest, count + 1, [h | acc])
+  end
+
+  defp rest_identifier(rest, count, [?@ | acc]) do
+    case tokenize_identifier(rest, count, acc) do
+      {:identifier, _rest, acc, count} -> {:module_attribute, acc, count}
+      :none when acc == [] -> {:module_attribute, '', count}
+      _ -> :none
+    end
+  end
+
+  defp rest_identifier([?~ | rest], count, [letter])
+       when (letter in ?A..?Z or letter in ?a..?z) and
+              (rest == [] or hd(rest) not in @tilde_op_prefix) do
+    {:sigil, [letter], count + 1}
+  end
+
+  defp rest_identifier([?: | rest], count, acc) when rest == [] or hd(rest) != ?: do
+    case String.Tokenizer.tokenize(acc) do
+      {_, _, [], _, _, _} -> {:unquoted_atom, acc, count + 1}
+      _ -> :none
+    end
+  end
+
+  defp rest_identifier([?? | _], _count, _acc) do
+    :none
+  end
+
+  defp rest_identifier(rest, count, acc) do
+    tokenize_identifier(rest, count, acc)
+  end
+
+  defp tokenize_identifier(rest, count, acc) do
+    case String.Tokenizer.tokenize(acc) do
+      # Not actually an atom cause rest is not a :
+      {:atom, _, _, _, _, _} ->
+        :none
+
+      # Aliases must be ascii only
+      {:alias, _, _, _, false, _} ->
+        :none
+
+      {kind, _, [], _, _, extra} ->
+        if ?@ in extra do
+          :none
+        else
+          {kind, rest, acc, count}
+        end
+
+      _ ->
+        :none
+    end
+  end
+
+  defp nested_alias(rest, count, acc) do
+    {rest, count} = strip_spaces(rest, count)
+
+    case identifier_to_cursor_context(rest, count, true) do
+      {{:struct, prev}, count} -> {{:struct, prev ++ '.' ++ acc}, count}
+      {{:alias, prev}, count} -> {{:alias, prev ++ '.' ++ acc}, count}
+      _ -> {:none, 0}
+    end
+  end
+
+  defp dot(rest, count, acc) do
+    {rest, count} = strip_spaces(rest, count)
+
+    case identifier_to_cursor_context(rest, count, true) do
+      {{:local_or_var, var}, count} -> {{:dot, {:var, var}, acc}, count}
+      {{:unquoted_atom, _} = prev, count} -> {{:dot, prev, acc}, count}
+      {{:alias, _} = prev, count} -> {{:dot, prev, acc}, count}
+      {{:dot, _, _} = prev, count} -> {{:dot, prev, acc}, count}
+      {{:module_attribute, _} = prev, count} -> {{:dot, prev, acc}, count}
+      {{:struct, acc}, count} -> {{:struct, acc ++ '.'}, count}
+      {_, _} -> {:none, 0}
+    end
+  end
+
+  defp operator([h | rest], count, acc, call_op?) when h in @operators do
+    operator(rest, count + 1, [h | acc], call_op?)
+  end
+
+  defp operator(rest, count, acc, call_op?) when acc in @incomplete_operators do
+    {rest, dot_count} = strip_spaces(rest, count)
+
+    cond do
+      call_op? ->
+        {:none, 0}
+
+      match?([?. | rest] when rest == [] or hd(rest) != ?., rest) ->
+        dot(tl(rest), dot_count + 1, acc)
+
+      acc == '~' ->
+        {{:sigil, ''}, count}
+
+      true ->
+        {{:operator, acc}, count}
+    end
+  end
+
+  # If we are opening a sigil, ignore the operator.
+  defp operator([letter, ?~ | rest], _count, [op], _call_op?)
+       when op in '<|/' and (letter in ?A..?Z or letter in ?a..?z) and
+              (rest == [] or hd(rest) not in @tilde_op_prefix) do
+    {:none, 0}
+  end
+
+  defp operator(rest, count, acc, _call_op?) do
+    case :elixir_tokenizer.tokenize(acc, 1, 1, []) do
+      {:ok, _, _, _, [{:atom, _, _}]} ->
+        {{:unquoted_atom, tl(acc)}, count}
+
+      {:ok, _, _, _, [{_, _, op}]} ->
+        {rest, dot_count} = strip_spaces(rest, count)
+
+        cond do
+          Code.Identifier.unary_op(op) == :error and Code.Identifier.binary_op(op) == :error ->
+            :none
+
+          match?([?. | rest] when rest == [] or hd(rest) != ?., rest) ->
+            dot(tl(rest), dot_count + 1, acc)
+
+          true ->
+            {{:operator, acc}, count}
+        end
+
+      _ ->
+        {:none, 0}
+    end
+  end
+
+  @doc """
+  Receives a string and returns the surround context.
+
+  This function receives a string with an Elixir code fragment
+  and a `position`. It returns a map containing the beginning
+  and ending of the identifier alongside its context, or `:none`
+  if there is nothing with a known context.
+
+  The difference between `cursor_context/2` and `surround_context/3`
+  is that the former assumes the expression in the code fragment
+  is incomplete. For example, `do` in `cursor_context/2` may be
+  a keyword or a variable or a local call, while `surround_context/3`
+  assumes the expression in the code fragment is complete, therefore
+  `do` would always be a keyword.
+
+  The `position` contains both the `line` and `column`, both starting
+  with the index of 1. The column must precede the surrounding expression.
+  For example, the expression `foo`, will return something for the columns
+  1, 2, and 3, but not 4:
+
+      foo
+      ^ column 1
+
+      foo
+       ^ column 2
+
+      foo
+        ^ column 3
+
+      foo
+         ^ column 4
+
+  The returned map contains the column the expression starts and the
+  first column after the expression ends.
+
+  Similar to `cursor_context/2`, this function also provides a best-effort
+  detection and may not be accurate under all circumstances. See the
+  "Return values" and "Limitations" section under `cursor_context/2` for
+  more information.
+
+  ## Examples
+
+      iex> Code.Fragment.surround_context("foo", {1, 1})
+      %{begin: {1, 1}, context: {:local_or_var, 'foo'}, end: {1, 4}}
+
+  ## Differences to `cursor_context/2`
+
+  Because `surround_context/3` deals with complete code, it has some
+  difference to `cursor_context/2`:
+
+    * `dot_call`/`dot_arity` and `operator_call`/`operator_arity`
+      are collapsed into `dot` and `operator` contexts respectively
+      as there aren't any meaningful distinctions between them
+
+    * On the other hand, this function still makes a distinction between
+      `local_call`/`local_arity` and `local_or_var`, since the latter can
+      be a local or variable
+
+    * `@` when not followed by any identifier is returned as `{:operator, '@'}`
+      (in contrast to `{:module_attribute, ''}` in `cursor_context/2`
+
+    * This function never returns empty sigils `{:sigil, ''}` or empty structs
+      `{:struct, ''}` as context
+  """
+  @doc since: "1.13.0"
+  @spec surround_context(List.Chars.t(), position(), keyword()) ::
+          %{begin: position, end: position, context: context} | :none
+        when context:
+               {:alias, charlist}
+               | {:dot, inside_dot, charlist}
+               | {:local_or_var, charlist}
+               | {:local_arity, charlist}
+               | {:local_call, charlist}
+               | {:module_attribute, charlist}
+               | {:operator, charlist}
+               | {:unquoted_atom, charlist},
+             inside_dot:
+               {:alias, charlist}
+               | {:dot, inside_dot, charlist}
+               | {:module_attribute, charlist}
+               | {:unquoted_atom, charlist}
+               | {:var, charlist}
+  def surround_context(fragment, position, options \\ [])
+
+  def surround_context(binary, {line, column}, opts) when is_binary(binary) do
+    binary
+    |> String.split("\n")
+    |> Enum.at(line - 1, '')
+    |> String.to_charlist()
+    |> position_surround_context(line, column, opts)
+  end
+
+  def surround_context(charlist, {line, column}, opts) when is_list(charlist) do
+    charlist
+    |> :string.split('\n', :all)
+    |> Enum.at(line - 1, '')
+    |> position_surround_context(line, column, opts)
+  end
+
+  def surround_context(other, {_, _} = position, opts) do
+    surround_context(to_charlist(other), position, opts)
+  end
+
+  defp position_surround_context(charlist, line, column, opts)
+       when is_integer(line) and line >= 1 and is_integer(column) and column >= 1 do
+    {reversed_pre, post} = string_reverse_at(charlist, column - 1, [])
+    {reversed_pre, post} = adjust_position(reversed_pre, post)
+
+    case take_identifier(post, []) do
+      {_, [], _} ->
+        maybe_operator(reversed_pre, post, line, opts)
+
+      {:identifier, reversed_post, rest} ->
+        {rest, _} = strip_spaces(rest, 0)
+        reversed = reversed_post ++ reversed_pre
+
+        case codepoint_cursor_context(reversed, opts) do
+          {{:struct, acc}, offset} ->
+            build_surround({:struct, acc}, reversed, line, offset)
+
+          {{:alias, acc}, offset} ->
+            build_surround({:alias, acc}, reversed, line, offset)
+
+          {{:dot, _, [_ | _]} = dot, offset} ->
+            build_surround(dot, reversed, line, offset)
+
+          {{:local_or_var, acc}, offset} when hd(rest) == ?( ->
+            build_surround({:local_call, acc}, reversed, line, offset)
+
+          {{:local_or_var, acc}, offset} when hd(rest) == ?/ ->
+            build_surround({:local_arity, acc}, reversed, line, offset)
+
+          {{:local_or_var, acc}, offset} when acc in @textual_operators ->
+            build_surround({:operator, acc}, reversed, line, offset)
+
+          {{:local_or_var, acc}, offset} when acc not in ~w(do end after else catch rescue)c ->
+            build_surround({:local_or_var, acc}, reversed, line, offset)
+
+          {{:module_attribute, ''}, offset} ->
+            build_surround({:operator, '@'}, reversed, line, offset)
+
+          {{:module_attribute, acc}, offset} ->
+            build_surround({:module_attribute, acc}, reversed, line, offset)
+
+          {{:sigil, acc}, offset} ->
+            build_surround({:sigil, acc}, reversed, line, offset)
+
+          {{:unquoted_atom, acc}, offset} ->
+            build_surround({:unquoted_atom, acc}, reversed, line, offset)
+
+          _ ->
+            maybe_operator(reversed_pre, post, line, opts)
+        end
+
+      {:alias, reversed_post, _rest} ->
+        reversed = reversed_post ++ reversed_pre
+
+        case codepoint_cursor_context(reversed, opts) do
+          {{:alias, acc}, offset} ->
+            build_surround({:alias, acc}, reversed, line, offset)
+
+          {{:struct, acc}, offset} ->
+            build_surround({:struct, acc}, reversed, line, offset)
+
+          _ ->
+            :none
+        end
+    end
+  end
+
+  defp maybe_operator(reversed_pre, post, line, opts) do
+    case take_operator(post, []) do
+      {[], _rest} ->
+        :none
+
+      {reversed_post, rest} ->
+        reversed = reversed_post ++ reversed_pre
+
+        case codepoint_cursor_context(reversed, opts) do
+          {{:operator, acc}, offset} when acc not in @incomplete_operators ->
+            build_surround({:operator, acc}, reversed, line, offset)
+
+          {{:sigil, ''}, offset} when hd(rest) in ?A..?Z or hd(rest) in ?a..?z ->
+            build_surround({:sigil, [hd(rest)]}, [hd(rest) | reversed], line, offset + 1)
+
+          {{:dot, _, [_ | _]} = dot, offset} ->
+            build_surround(dot, reversed, line, offset)
+
+          _ ->
+            :none
+        end
+    end
+  end
+
+  defp build_surround(context, reversed, line, offset) do
+    {post, reversed_pre} = enum_reverse_at(reversed, offset, [])
+    pre = :lists.reverse(reversed_pre)
+    pre_length = :string.length(pre) + 1
+
+    %{
+      context: context,
+      begin: {line, pre_length},
+      end: {line, pre_length + :string.length(post)}
+    }
+  end
+
+  defp take_identifier([h | t], acc) when h in @trailing_identifier,
+    do: {:identifier, [h | acc], t}
+
+  defp take_identifier([h | t], acc) when h not in @non_identifier,
+    do: take_identifier(t, [h | acc])
+
+  defp take_identifier(rest, acc) do
+    with {[?. | t], _} <- strip_spaces(rest, 0),
+         {[h | _], _} when h in ?A..?Z <- strip_spaces(t, 0) do
+      take_alias(rest, acc)
+    else
+      _ -> {:identifier, acc, rest}
+    end
+  end
+
+  defp take_alias([h | t], acc) when h not in @non_identifier,
+    do: take_alias(t, [h | acc])
+
+  defp take_alias(rest, acc) do
+    with {[?. | t], acc} <- move_spaces(rest, acc),
+         {[h | t], acc} when h in ?A..?Z <- move_spaces(t, [?. | acc]) do
+      take_alias(t, [h | acc])
+    else
+      _ -> {:alias, acc, rest}
+    end
+  end
+
+  defp take_operator([h | t], acc) when h in @operators, do: take_operator(t, [h | acc])
+  defp take_operator([h | t], acc) when h == ?., do: take_operator(t, [h | acc])
+  defp take_operator(rest, acc), do: {acc, rest}
+
+  # Unquoted atom handling
+  defp adjust_position(reversed_pre, [?: | post])
+       when hd(post) != ?: and (reversed_pre == [] or hd(reversed_pre) != ?:) do
+    {[?: | reversed_pre], post}
+  end
+
+  defp adjust_position(reversed_pre, [?% | post]) do
+    adjust_position([?% | reversed_pre], post)
+  end
+
+  # Dot/struct handling
+  defp adjust_position(reversed_pre, post) do
+    case move_spaces(post, reversed_pre) do
+      # If we are between spaces and a dot, move past the dot
+      {[?. | post], reversed_pre} when hd(post) != ?. and hd(reversed_pre) != ?. ->
+        {post, reversed_pre} = move_spaces(post, [?. | reversed_pre])
+        {reversed_pre, post}
+
+      _ ->
+        case strip_spaces(reversed_pre, 0) do
+          # If there is a dot to our left, make sure to move to the first character
+          {[?. | rest], _} when rest == [] or hd(rest) not in '.:' ->
+            {post, reversed_pre} = move_spaces(post, reversed_pre)
+            {reversed_pre, post}
+
+          # If there is a % to our left, make sure to move to the first character
+          {[?% | _], _} ->
+            case move_spaces(post, reversed_pre) do
+              {[h | _] = post, reversed_pre} when h in ?A..?Z ->
+                {reversed_pre, post}
+
+              _ ->
+                {reversed_pre, post}
+            end
+
+          _ ->
+            {reversed_pre, post}
+        end
+    end
+  end
+
+  defp move_spaces([h | t], acc) when h in @space, do: move_spaces(t, [h | acc])
+  defp move_spaces(t, acc), do: {t, acc}
+
+  defp string_reverse_at(charlist, 0, acc), do: {acc, charlist}
+
+  defp string_reverse_at(charlist, n, acc) do
+    case :unicode_util.gc(charlist) do
+      [gc | cont] when is_integer(gc) -> string_reverse_at(cont, n - 1, [gc | acc])
+      [gc | cont] when is_list(gc) -> string_reverse_at(cont, n - 1, :lists.reverse(gc, acc))
+      [] -> {acc, []}
+    end
+  end
+
+  defp enum_reverse_at([h | t], n, acc) when n > 0, do: enum_reverse_at(t, n - 1, [h | acc])
+  defp enum_reverse_at(rest, _, acc), do: {acc, rest}
+
+  @doc """
+  Receives a code fragment and returns a quoted expression
+  with a cursor at the nearest argument position.
+
+  A container is any Elixir expression starting with `(`,
+  `{`, and `[`. This includes function calls, tuples, lists,
+  maps, and so on. For example, take this code, which would
+  be given as input:
+
+      max(some_value,
+
+  This function will return the AST equivalent to:
+
+      max(some_value, __cursor__())
+
+  In other words, this function is capable of closing any open
+  brackets and insert the cursor position. Any content at the
+  cursor position that is after a comma or an opening bracket
+  is discarded. For example, if this is given as input:
+
+      max(some_value, another_val
+
+  It will return the same AST:
+
+      max(some_value, __cursor__())
+
+  Similarly, if only this is given:
+
+      max(some_va
+
+  Then it returns:
+
+      max(__cursor__())
+
+  Calls without parenthesis are also supported, as we assume the
+  brackets are implicit.
+
+  Operators and anonymous functions are not containers, and therefore
+  will be discarded. The following will all return the same AST:
+
+      max(some_value,
+      max(some_value, fn x -> x end
+      max(some_value, 1 + another_val
+      max(some_value, 1 |> some_fun() |> another_fun
+
+  On the other hand, tuples, lists, maps, etc all retain the
+  cursor position:
+
+      max(some_value, [1, 2,
+
+  Returns the following AST:
+
+      max(some_value, [1, 2, __cursor__()])
+
+  Keyword lists (and do-end blocks) are also retained. The following:
+
+      if(some_value, do:
+      if(some_value, do: :token
+      if(some_value, do: 1 + val
+
+  all return:
+
+      if(some_value, do: __cursor__())
+
+  The AST returned by this function is not safe to evaluate but
+  it can be analyzed and expanded.
+
+  ## Examples
+
+      iex> Code.Fragment.container_cursor_to_quoted("max(some_value, ")
+      {:ok, {:max, [line: 1], [{:some_value, [line: 1], nil}, {:__cursor__, [line: 1], []}]}}
+
+  ## Options
+
+    * `:file` - the filename to be reported in case of parsing errors.
+      Defaults to `"nofile"`.
+
+    * `:line` - the starting line of the string being parsed.
+      Defaults to 1.
+
+    * `:column` - the starting column of the string being parsed.
+      Defaults to 1.
+
+    * `:columns` - when `true`, attach a `:column` key to the quoted
+      metadata. Defaults to `false`.
+
+    * `:token_metadata` - when `true`, includes token-related
+      metadata in the expression AST, such as metadata for `do` and `end`
+      tokens, for closing tokens, end of expressions, as well as delimiters
+      for sigils. See `t:Macro.metadata/0`. Defaults to `false`.
+
+  """
+  @doc since: "1.13.0"
+  @spec container_cursor_to_quoted(List.Chars.t(), keyword()) ::
+          {:ok, Macro.t()} | {:error, {location :: keyword, binary | {binary, binary}, binary}}
+  def container_cursor_to_quoted(fragment, opts \\ []) do
+    file = Keyword.get(opts, :file, "nofile")
+    line = Keyword.get(opts, :line, 1)
+    column = Keyword.get(opts, :column, 1)
+    columns = Keyword.get(opts, :columns, false)
+    token_metadata = Keyword.get(opts, :token_metadata, false)
+
+    fragment = to_charlist(fragment)
+    tokenizer_opts = [file: file, cursor_completion: true, columns: columns]
+
+    case :elixir_tokenizer.tokenize(fragment, line, column, tokenizer_opts) do
+      {:ok, _, _, _warnings, tokens} ->
+        :elixir.tokens_to_quoted(tokens, nil, columns: columns, token_metadata: token_metadata)
+
+      {:error, {line, column, {prefix, suffix}, token}, _rest, _warnings, _so_far} ->
+        location = [line: line, column: column]
+        {:error, {location, {to_string(prefix), to_string(suffix)}, to_string(token)}}
+
+      {:error, {line, column, error, token}, _rest, _warnings, _so_far} ->
+        location = [line: line, column: column]
+        {:error, {location, to_string(error), to_string(token)}}
+    end
+  end
+end

lib/elixir/lib/code/identifier.ex

@@ -48,6 +48,7 @@ defmodule Code.Identifier do
       op in [:++, :--, :.., :<>, :+++, :---] -> {:right, 200}
       op in [:+, :-] -> {:left, 210}
       op in [:*, :/] -> {:left, 220}
+      op in [:**] -> {:left, 230}
       op in [:.] -> {:left, 310}
       true -> :error
     end
@@ -83,7 +84,7 @@ defmodule Code.Identifier do
     charlist = Atom.to_charlist(atom)
 
     cond do
-      atom in [:%, :%{}, :{}, :<<>>, :..., :.., :., :..//, :->] ->
+      atom in [:%, :%{}, :{}, :<<>>, :..., :.., :., :"..//", :->] ->
         :not_callable
 
       atom in [:"::", :"//"] ->
@@ -96,7 +97,7 @@ defmodule Code.Identifier do
         :alias
 
       true ->
-        case :elixir_config.get(:identifier_tokenizer, String.Tokenizer).tokenize(charlist) do
+        case :elixir_config.identifier_tokenizer().tokenize(charlist) do
           {kind, _acc, [], _, _, special} ->
             if kind == :identifier and not :lists.member(?@, special) do
               :callable_local

lib/elixir/lib/code/normalizer.ex

@@ -0,0 +1,585 @@
+defmodule Code.Normalizer do
+  @moduledoc false
+
+  defguard is_literal(x)
+           when is_integer(x) or
+                  is_float(x) or
+                  is_binary(x) or
+                  is_atom(x)
+
+  @doc """
+  Wraps literals in the quoted expression to conform to the AST format expected
+  by the formatter.
+  """
+  def normalize(quoted, opts \\ []) do
+    line = Keyword.get(opts, :line, nil)
+    escape = Keyword.get(opts, :escape, true)
+    locals_without_parens = Keyword.get(opts, :locals_without_parens, [])
+
+    state = %{
+      escape: escape,
+      parent_meta: [line: line],
+      locals_without_parens: locals_without_parens ++ Code.Formatter.locals_without_parens()
+    }
+
+    do_normalize(quoted, state)
+  end
+
+  # Wrapped literals should receive the block meta
+  defp do_normalize({:__block__, meta, [literal]}, state)
+       when not is_tuple(literal) or tuple_size(literal) == 2 do
+    normalize_literal(literal, meta, state)
+  end
+
+  # Only normalize the first argument of an alias if it's not an atom
+  defp do_normalize({:__aliases__, meta, [first | rest]}, state) when not is_atom(first) do
+    meta = patch_meta_line(meta, state.parent_meta)
+    first = do_normalize(first, %{state | parent_meta: meta})
+    {:__aliases__, meta, [first | rest]}
+  end
+
+  defp do_normalize({:__aliases__, _, _} = quoted, _state) do
+    quoted
+  end
+
+  # Skip captured arguments like &1
+  defp do_normalize({:&, meta, [term]}, state) when is_integer(term) do
+    meta = patch_meta_line(meta, state.parent_meta)
+    {:&, meta, [term]}
+  end
+
+  # Ranges
+  defp do_normalize(left..right//step, state) do
+    left = do_normalize(left, state)
+    right = do_normalize(right, state)
+    meta = meta_line(state)
+
+    if step == 1 do
+      {:.., meta, [left, right]}
+    else
+      step = do_normalize(step, state)
+      {:"..//", meta, [left, right, step]}
+    end
+  end
+
+  # Bit containers
+  defp do_normalize({:<<>>, _, args} = quoted, state) when is_list(args) do
+    normalize_bitstring(quoted, state)
+  end
+
+  # Atoms with interpolations
+  defp do_normalize(
+         {{:., dot_meta, [:erlang, :binary_to_atom]}, call_meta,
+          [{:<<>>, _, args} = string, :utf8]},
+         state
+       )
+       when is_list(args) do
+    dot_meta = patch_meta_line(dot_meta, state.parent_meta)
+    call_meta = patch_meta_line(call_meta, dot_meta)
+
+    string =
+      if state.escape do
+        normalize_bitstring(string, state, true)
+      else
+        normalize_bitstring(string, state)
+      end
+
+    {{:., dot_meta, [:erlang, :binary_to_atom]}, call_meta, [string, :utf8]}
+  end
+
+  # Charlists with interpolations
+  defp do_normalize({{:., dot_meta, [List, :to_charlist]}, call_meta, [parts]}, state) do
+    parts =
+      Enum.map(parts, fn
+        {{:., part_dot_meta, [Kernel, :to_string]}, part_call_meta, args} ->
+          args = normalize_args(args, state)
+
+          {{:., part_dot_meta, [Kernel, :to_string]}, part_call_meta, args}
+
+        part ->
+          if state.escape do
+            maybe_escape_literal(part, state)
+          else
+            part
+          end
+      end)
+
+    {{:., dot_meta, [List, :to_charlist]}, call_meta, [parts]}
+  end
+
+  # Don't normalize the `Access` atom in access syntax
+  defp do_normalize({:., meta, [Access, :get]}, state) do
+    meta = patch_meta_line(meta, state.parent_meta)
+    {:., meta, [Access, :get]}
+  end
+
+  # Only normalize the left side of the dot operator
+  # The right hand side is an atom in the AST but it's not an atom literal, so
+  # it should not be wrapped
+  defp do_normalize({:., meta, [left, right]}, state) do
+    meta = patch_meta_line(meta, state.parent_meta)
+
+    left = do_normalize(left, %{state | parent_meta: meta})
+
+    {:., meta, [left, right]}
+  end
+
+  # A list of left to right arrows is not considered as a list literal, so it's not wrapped
+  defp do_normalize([{:->, _, [_ | _]} | _] = quoted, state) do
+    normalize_args(quoted, state)
+  end
+
+  # left -> right
+  defp do_normalize({:->, meta, [left, right]}, state) do
+    meta = patch_meta_line(meta, state.parent_meta)
+
+    left = normalize_args(left, %{state | parent_meta: meta})
+    right = do_normalize(right, %{state | parent_meta: meta})
+    {:->, meta, [left, right]}
+  end
+
+  # Maps
+  defp do_normalize({:%{}, meta, args}, state) when is_list(args) do
+    meta =
+      if meta == [] do
+        line = state.parent_meta[:line]
+        [line: line, closing: [line: line]]
+      else
+        meta
+      end
+
+    state = %{state | parent_meta: meta}
+
+    args =
+      case args do
+        [{:|, pipe_meta, [left, right]}] ->
+          left = do_normalize(left, state)
+          right = normalize_map_args(right, state)
+          [{:|, pipe_meta, [left, right]}]
+
+        [{_, _, _} = call] ->
+          [do_normalize(call, state)]
+
+        args ->
+          normalize_map_args(args, state)
+      end
+
+    {:%{}, meta, args}
+  end
+
+  # Sigils
+  defp do_normalize({sigil, meta, [{:<<>>, _, args} = string, modifiers]} = quoted, state)
+       when is_list(args) and is_atom(sigil) do
+    case Atom.to_string(sigil) do
+      <<"sigil_", _name>> ->
+        meta =
+          meta
+          |> patch_meta_line(state.parent_meta)
+          |> Keyword.put_new(:delimiter, "\"")
+
+        {sigil, meta, [do_normalize(string, %{state | parent_meta: meta}), modifiers]}
+
+      _ ->
+        normalize_call(quoted, state)
+    end
+  end
+
+  # Tuples
+  defp do_normalize({:{}, meta, args} = quoted, state) when is_list(args) do
+    {last_arg, args} = List.pop_at(args, -1)
+
+    if args != [] and match?([_ | _], last_arg) and keyword?(last_arg) do
+      args = normalize_args(args, state)
+      kw_list = normalize_kw_args(last_arg, state, true)
+      {:{}, meta, args ++ kw_list}
+    else
+      normalize_call(quoted, state)
+    end
+  end
+
+  # Module attributes
+  defp do_normalize({:@, meta, [{name, name_meta, [value]}]}, state) do
+    value =
+      cond do
+        keyword?(value) ->
+          normalize_kw_args(value, state, true)
+
+        is_list(value) ->
+          normalize_literal(value, meta, state)
+
+        true ->
+          do_normalize(value, state)
+      end
+
+    {:@, meta, [{name, name_meta, [value]}]}
+  end
+
+  # Regular blocks
+  defp do_normalize({:__block__, meta, args}, state) when is_list(args) do
+    {:__block__, meta, normalize_args(args, state)}
+  end
+
+  # Calls
+  defp do_normalize({_, _, args} = quoted, state) when is_list(args) do
+    normalize_call(quoted, state)
+  end
+
+  # Vars
+  defp do_normalize({_, _, context} = quoted, _state) when is_atom(context) do
+    quoted
+  end
+
+  # Literals
+  defp do_normalize(quoted, state) do
+    normalize_literal(quoted, [], state)
+  end
+
+  # Numbers
+  defp normalize_literal(number, meta, state) when is_number(number) do
+    meta =
+      meta
+      |> Keyword.put_new(:token, inspect(number))
+      |> patch_meta_line(state.parent_meta)
+
+    {:__block__, meta, [number]}
+  end
+
+  # Atom, Strings
+  defp normalize_literal(literal, meta, state) when is_atom(literal) or is_binary(literal) do
+    meta = patch_meta_line(meta, state.parent_meta)
+    literal = maybe_escape_literal(literal, state)
+
+    if is_atom(literal) and Code.Identifier.classify(literal) == :alias and
+         is_nil(meta[:delimiter]) do
+      segments =
+        case Atom.to_string(literal) do
+          "Elixir" ->
+            [:"Elixir"]
+
+          "Elixir." <> segments ->
+            segments
+            |> String.split(".")
+            |> Enum.map(&String.to_atom/1)
+        end
+
+      {:__aliases__, meta, segments}
+    else
+      {:__block__, meta, [literal]}
+    end
+  end
+
+  # 2-tuples
+  defp normalize_literal({left, right}, meta, state) do
+    meta = patch_meta_line(meta, state.parent_meta)
+    state = %{state | parent_meta: meta}
+
+    if match?([_ | _], right) and keyword?(right) do
+      {:__block__, meta, [{do_normalize(left, state), normalize_kw_args(right, state, true)}]}
+    else
+      {:__block__, meta, [{do_normalize(left, state), do_normalize(right, state)}]}
+    end
+  end
+
+  # Lists
+  defp normalize_literal(list, meta, state) when is_list(list) do
+    if list != [] and List.ascii_printable?(list) do
+      # It's a charlist
+      list =
+        if state.escape do
+          {string, _} = Code.Identifier.escape(IO.chardata_to_string(list), -1)
+          IO.iodata_to_binary(string) |> to_charlist()
+        else
+          list
+        end
+
+      meta =
+        meta
+        |> Keyword.put_new(:delimiter, "'")
+        |> patch_meta_line(state.parent_meta)
+
+      {:__block__, meta, [list]}
+    else
+      meta =
+        if line = state.parent_meta[:line] do
+          meta
+          |> Keyword.put_new(:closing, line: line)
+          |> patch_meta_line(state.parent_meta)
+        else
+          meta
+        end
+
+      {:__block__, meta, [normalize_kw_args(list, state, false)]}
+    end
+  end
+
+  # Probably an invalid value, wrap it and send it upstream
+  defp normalize_literal(quoted, meta, _state) do
+    {:__block__, meta, [quoted]}
+  end
+
+  defp normalize_call({form, meta, args}, state) do
+    meta = patch_meta_line(meta, state.parent_meta)
+    arity = length(args)
+
+    # Only normalize the form if it's a qualified call
+    form =
+      if is_atom(form) do
+        form
+      else
+        do_normalize(form, %{state | parent_meta: meta})
+      end
+
+    meta =
+      if is_nil(meta[:no_parens]) and is_nil(meta[:closing]) and is_nil(meta[:do]) and
+           not Code.Formatter.local_without_parens?(form, arity, state.locals_without_parens) do
+        [closing: [line: meta[:line]]] ++ meta
+      else
+        meta
+      end
+
+    cond do
+      Keyword.has_key?(meta, :do) or match?([{{:__block__, _, [:do]}, _} | _], List.last(args)) ->
+        # def foo do :ok end
+        # def foo, do: :ok
+        normalize_kw_blocks(form, meta, args, state)
+
+      match?([{:do, _} | _], List.last(args)) ->
+        # Non normalized kw blocks
+        line = state.parent_meta[:line]
+        meta = meta ++ [do: [line: line], end: [line: line]]
+        normalize_kw_blocks(form, meta, args, state)
+
+      allow_keyword?(form, arity) ->
+        args = normalize_args(args, %{state | parent_meta: state.parent_meta})
+        {last_arg, leading_args} = List.pop_at(args, -1, [])
+
+        last_args =
+          case last_arg do
+            {:__block__, _, [[{{:__block__, key_meta, _}, _} | _]] = last_args} ->
+              if key_meta[:format] == :keyword do
+                last_args
+              else
+                [last_arg]
+              end
+
+            [] ->
+              []
+
+            _ ->
+              [last_arg]
+          end
+
+        {form, meta, leading_args ++ last_args}
+
+      true ->
+        args = normalize_args(args, %{state | parent_meta: state.parent_meta})
+        {form, meta, args}
+    end
+  end
+
+  defp allow_keyword?(:when, 2), do: true
+  defp allow_keyword?(:{}, _), do: false
+  defp allow_keyword?(op, arity), do: not is_atom(op) or not Macro.operator?(op, arity)
+
+  defp normalize_bitstring({:<<>>, meta, parts} = quoted, state, escape_interpolation \\ false) do
+    meta = patch_meta_line(meta, state.parent_meta)
+
+    parts =
+      if interpolated?(quoted) do
+        normalize_interpolation_parts(parts, %{state | parent_meta: meta}, escape_interpolation)
+      else
+        state = %{state | parent_meta: meta}
+
+        Enum.map(parts, fn part ->
+          with {:"::", meta, [left, _]} <- part,
+               true <- meta[:inferred_bitstring_spec] do
+            do_normalize(left, state)
+          else
+            _ -> do_normalize(part, state)
+          end
+        end)
+      end
+
+    {:<<>>, meta, parts}
+  end
+
+  defp normalize_interpolation_parts(parts, state, escape_interpolation) do
+    Enum.map(parts, fn
+      {:"::", interpolation_meta,
+       [
+         {{:., dot_meta, [Kernel, :to_string]}, middle_meta, [middle]},
+         {:binary, binary_meta, context}
+       ]} ->
+        middle = do_normalize(middle, %{state | parent_meta: dot_meta})
+
+        {:"::", interpolation_meta,
+         [
+           {{:., dot_meta, [Kernel, :to_string]}, middle_meta, [middle]},
+           {:binary, binary_meta, context}
+         ]}
+
+      part ->
+        if escape_interpolation do
+          maybe_escape_literal(part, state)
+        else
+          part
+        end
+    end)
+  end
+
+  defp normalize_map_args(args, state) do
+    Enum.map(normalize_kw_args(args, state, false), fn
+      {:__block__, _, [{_, _} = pair]} -> pair
+      pair -> pair
+    end)
+  end
+
+  defp normalize_kw_blocks(form, meta, args, state) do
+    {kw_blocks, leading_args} = List.pop_at(args, -1)
+
+    kw_blocks =
+      Enum.map(kw_blocks, fn {tag, block} ->
+        block = do_normalize(block, %{state | parent_meta: meta})
+
+        block =
+          case block do
+            {_, _, [[{:->, _, _} | _] = block]} -> block
+            block -> block
+          end
+
+        # Only wrap the tag if it isn't already wrapped
+        tag =
+          case tag do
+            {:__block__, _, _} -> tag
+            _ -> {:__block__, [line: meta[:line]], [tag]}
+          end
+
+        {tag, block}
+      end)
+
+    leading_args = normalize_args(leading_args, %{state | parent_meta: meta})
+    {form, meta, leading_args ++ [kw_blocks]}
+  end
+
+  defp normalize_kw_args(elems, state, keyword?)
+
+  defp normalize_kw_args(
+         [{{:__block__, key_meta, [key]}, value} = first | rest] = current,
+         state,
+         keyword?
+       )
+       when is_atom(key) do
+    keyword? = keyword? or keyword?(current)
+
+    first =
+      if key_meta[:format] == :keyword and not keyword? do
+        key_meta = Keyword.delete(key_meta, :format)
+        line = key_meta[:line] || meta_line(state)
+        {:__block__, [line: line], [{{:__block__, key_meta, [key]}, value}]}
+      else
+        first
+      end
+
+    [first | normalize_kw_args(rest, state, keyword?)]
+  end
+
+  defp normalize_kw_args([{left, right} | rest] = current, state, keyword?) do
+    keyword? = keyword? or keyword?(current)
+
+    left =
+      if keyword? do
+        meta = [format: :keyword] ++ meta_line(state)
+        {:__block__, meta, [maybe_escape_literal(left, state)]}
+      else
+        do_normalize(left, state)
+      end
+
+    right = do_normalize(right, state)
+
+    pair =
+      with {:__block__, meta, _} <- left,
+           :keyword <- meta[:format] do
+        {left, right}
+      else
+        _ -> {:__block__, meta_line(state), [{left, right}]}
+      end
+
+    [pair | normalize_kw_args(rest, state, keyword?)]
+  end
+
+  defp normalize_kw_args([first | rest], state, keyword?) do
+    [do_normalize(first, state) | normalize_kw_args(rest, state, keyword?)]
+  end
+
+  defp normalize_kw_args([], _state, _keyword?) do
+    []
+  end
+
+  defp normalize_args(args, state) do
+    Enum.map(args, &do_normalize(&1, state))
+  end
+
+  defp maybe_escape_literal(string, %{escape: true}) when is_binary(string) do
+    {string, _} = Code.Identifier.escape(string, -1)
+    IO.iodata_to_binary(string)
+  end
+
+  defp maybe_escape_literal(atom, %{escape: true} = state) when is_atom(atom) do
+    atom
+    |> Atom.to_string()
+    |> maybe_escape_literal(state)
+    |> String.to_atom()
+  end
+
+  defp maybe_escape_literal(term, _) do
+    term
+  end
+
+  # Check if we have an interpolated string.
+  defp interpolated?({:<<>>, _, [_ | _] = parts}) do
+    Enum.all?(parts, fn
+      {:"::", _, [{{:., _, [Kernel, :to_string]}, _, [_]}, {:binary, _, _}]} -> true
+      binary when is_binary(binary) -> true
+      _ -> false
+    end)
+  end
+
+  defp interpolated?(_) do
+    false
+  end
+
+  defp patch_meta_line(meta, parent_meta) do
+    with nil <- meta[:line],
+         line when is_integer(line) <- parent_meta[:line] do
+      [line: line] ++ meta
+    else
+      _ -> meta
+    end
+  end
+
+  defp meta_line(state) do
+    if line = state.parent_meta[:line] do
+      [line: line]
+    else
+      []
+    end
+  end
+
+  defp keyword?([{{:__block__, key_meta, [key]}, _} | rest]) when is_atom(key) do
+    if key_meta[:format] == :keyword do
+      keyword?(rest)
+    else
+      false
+    end
+  end
+
+  defp keyword?([{key, _value} | rest]) when is_atom(key) do
+    case Atom.to_charlist(key) do
+      'Elixir.' ++ _ -> false
+      _ -> keyword?(rest)
+    end
+  end
+
+  defp keyword?([]), do: true
+  defp keyword?(_other), do: false
+end

lib/elixir/lib/code/typespec.ex

@@ -7,9 +7,9 @@ defmodule Code.Typespec do
   @spec spec_to_quoted(atom, tuple) :: {atom, keyword, [Macro.t()]}
   def spec_to_quoted(name, spec)
 
-  def spec_to_quoted(name, {:type, line, :fun, [{:type, _, :product, args}, result]})
+  def spec_to_quoted(name, {:type, anno, :fun, [{:type, _, :product, args}, result]})
       when is_atom(name) do
-    meta = [line: line]
+    meta = meta(anno)
     body = {name, meta, Enum.map(args, &typespec_to_quoted/1)}
 
     vars =
@@ -27,11 +27,13 @@ defmodule Code.Typespec do
     end
   end
 
-  def spec_to_quoted(name, {:type, line, :fun, []}) when is_atom(name) do
-    {:"::", [line: line], [{name, [line: line], []}, quote(do: term)]}
+  def spec_to_quoted(name, {:type, anno, :fun, []}) when is_atom(name) do
+    meta = meta(anno)
+    {:"::", meta, [{name, meta, []}, quote(do: term)]}
   end
 
-  def spec_to_quoted(name, {:type, line, :bounded_fun, [type, constrs]}) when is_atom(name) do
+  def spec_to_quoted(name, {:type, anno, :bounded_fun, [type, constrs]}) when is_atom(name) do
+    meta = meta(anno)
     {:type, _, :fun, [{:type, _, :product, args}, result]} = type
 
     guards =
@@ -39,7 +41,6 @@ defmodule Code.Typespec do
         {erl_to_ex_var(var), typespec_to_quoted(type)}
       end
 
-    meta = [line: line]
     ignore_vars = Keyword.keys(guards)
 
     vars =
@@ -52,7 +53,7 @@ defmodule Code.Typespec do
     args = for arg <- args, do: typespec_to_quoted(arg)
 
     when_args = [
-      {:"::", meta, [{name, [line: line], args}, typespec_to_quoted(result)]},
+      {:"::", meta, [{name, meta, args}, typespec_to_quoted(result)]},
       guards ++ vars
     ]
 
@@ -188,27 +189,27 @@ defmodule Code.Typespec do
 
   ## To AST conversion
 
-  defp collect_vars({:ann_type, _line, args}) when is_list(args) do
+  defp collect_vars({:ann_type, _anno, args}) when is_list(args) do
     []
   end
 
-  defp collect_vars({:type, _line, _kind, args}) when is_list(args) do
+  defp collect_vars({:type, _anno, _kind, args}) when is_list(args) do
     Enum.flat_map(args, &collect_vars/1)
   end
 
-  defp collect_vars({:remote_type, _line, args}) when is_list(args) do
+  defp collect_vars({:remote_type, _anno, args}) when is_list(args) do
     Enum.flat_map(args, &collect_vars/1)
   end
 
-  defp collect_vars({:typed_record_field, _line, type}) do
+  defp collect_vars({:typed_record_field, _anno, type}) do
     collect_vars(type)
   end
 
-  defp collect_vars({:paren_type, _line, [type]}) do
+  defp collect_vars({:paren_type, _anno, [type]}) do
     collect_vars(type)
   end
 
-  defp collect_vars({:var, _line, var}) do
+  defp collect_vars({:var, _anno, var}) do
     [erl_to_ex_var(var)]
   end
 
@@ -216,48 +217,48 @@ defmodule Code.Typespec do
     []
   end
 
-  defp typespec_to_quoted({:user_type, line, name, args}) do
+  defp typespec_to_quoted({:user_type, anno, name, args}) do
     args = for arg <- args, do: typespec_to_quoted(arg)
-    {name, [line: line], args}
+    {name, meta(anno), args}
   end
 
-  defp typespec_to_quoted({:type, line, :tuple, :any}) do
-    {:tuple, [line: line], []}
+  defp typespec_to_quoted({:type, anno, :tuple, :any}) do
+    {:tuple, meta(anno), []}
   end
 
-  defp typespec_to_quoted({:type, line, :tuple, args}) do
+  defp typespec_to_quoted({:type, anno, :tuple, args}) do
     args = for arg <- args, do: typespec_to_quoted(arg)
-    {:{}, [line: line], args}
+    {:{}, meta(anno), args}
   end
 
-  defp typespec_to_quoted({:type, _line, :list, [{:type, _, :union, unions} = arg]}) do
+  defp typespec_to_quoted({:type, _anno, :list, [{:type, _, :union, unions} = arg]}) do
     case unpack_typespec_kw(unions, []) do
       {:ok, ast} -> ast
       :error -> [typespec_to_quoted(arg)]
     end
   end
 
-  defp typespec_to_quoted({:type, line, :list, []}) do
-    {:list, [line: line], []}
+  defp typespec_to_quoted({:type, anno, :list, []}) do
+    {:list, meta(anno), []}
   end
 
-  defp typespec_to_quoted({:type, _line, :list, [arg]}) do
+  defp typespec_to_quoted({:type, _anno, :list, [arg]}) do
     [typespec_to_quoted(arg)]
   end
 
-  defp typespec_to_quoted({:type, line, :nonempty_list, []}) do
-    [{:..., [line: line], nil}]
+  defp typespec_to_quoted({:type, anno, :nonempty_list, []}) do
+    [{:..., meta(anno), nil}]
   end
 
-  defp typespec_to_quoted({:type, line, :nonempty_list, [arg]}) do
-    [typespec_to_quoted(arg), {:..., [line: line], nil}]
+  defp typespec_to_quoted({:type, anno, :nonempty_list, [arg]}) do
+    [typespec_to_quoted(arg), {:..., meta(anno), nil}]
   end
 
-  defp typespec_to_quoted({:type, line, :map, :any}) do
-    {:map, [line: line], []}
+  defp typespec_to_quoted({:type, anno, :map, :any}) do
+    {:map, meta(anno), []}
   end
 
-  defp typespec_to_quoted({:type, line, :map, fields}) do
+  defp typespec_to_quoted({:type, anno, :map, fields}) do
     fields =
       Enum.map(fields, fn
         {:type, _, :map_field_assoc, :any} ->
@@ -275,16 +276,17 @@ defmodule Code.Typespec do
 
     case List.keytake(fields, :__struct__, 0) do
       {{:__struct__, struct}, fields_pruned} when is_atom(struct) and struct != nil ->
-        map_pruned = {:%{}, [line: line], fields_pruned}
-        {:%, [line: line], [struct, map_pruned]}
+        map_pruned = {:%{}, meta(anno), fields_pruned}
+        {:%, meta(anno), [struct, map_pruned]}
 
       _ ->
-        {:%{}, [line: line], fields}
+        {:%{}, meta(anno), fields}
     end
   end
 
-  defp typespec_to_quoted({:type, line, :binary, [arg1, arg2]}) do
+  defp typespec_to_quoted({:type, anno, :binary, [arg1, arg2]}) do
     [arg1, arg2] = for arg <- [arg1, arg2], do: typespec_to_quoted(arg)
+    line = meta(anno)[:line]
 
     case {typespec_to_quoted(arg1), typespec_to_quoted(arg2)} do
       {arg1, 0} ->
@@ -298,57 +300,57 @@ defmodule Code.Typespec do
     end
   end
 
-  defp typespec_to_quoted({:type, line, :union, args}) do
+  defp typespec_to_quoted({:type, anno, :union, args}) do
     args = for arg <- args, do: typespec_to_quoted(arg)
-    Enum.reduce(Enum.reverse(args), fn arg, expr -> {:|, [line: line], [arg, expr]} end)
+    Enum.reduce(Enum.reverse(args), fn arg, expr -> {:|, meta(anno), [arg, expr]} end)
   end
 
-  defp typespec_to_quoted({:type, line, :fun, [{:type, _, :product, args}, result]}) do
+  defp typespec_to_quoted({:type, anno, :fun, [{:type, _, :product, args}, result]}) do
     args = for arg <- args, do: typespec_to_quoted(arg)
-    [{:->, [line: line], [args, typespec_to_quoted(result)]}]
+    [{:->, meta(anno), [args, typespec_to_quoted(result)]}]
   end
 
-  defp typespec_to_quoted({:type, line, :fun, [args, result]}) do
-    [{:->, [line: line], [[typespec_to_quoted(args)], typespec_to_quoted(result)]}]
+  defp typespec_to_quoted({:type, anno, :fun, [args, result]}) do
+    [{:->, meta(anno), [[typespec_to_quoted(args)], typespec_to_quoted(result)]}]
   end
 
-  defp typespec_to_quoted({:type, line, :fun, []}) do
-    typespec_to_quoted({:type, line, :fun, [{:type, line, :any}, {:type, line, :any, []}]})
+  defp typespec_to_quoted({:type, anno, :fun, []}) do
+    typespec_to_quoted({:type, anno, :fun, [{:type, anno, :any}, {:type, anno, :any, []}]})
   end
 
-  defp typespec_to_quoted({:type, line, :range, [left, right]}) do
-    {:.., [line: line], [typespec_to_quoted(left), typespec_to_quoted(right)]}
+  defp typespec_to_quoted({:type, anno, :range, [left, right]}) do
+    {:.., meta(anno), [typespec_to_quoted(left), typespec_to_quoted(right)]}
   end
 
-  defp typespec_to_quoted({:type, _line, nil, []}) do
+  defp typespec_to_quoted({:type, _anno, nil, []}) do
     []
   end
 
-  defp typespec_to_quoted({:type, line, name, args}) do
+  defp typespec_to_quoted({:type, anno, name, args}) do
     args = for arg <- args, do: typespec_to_quoted(arg)
-    {name, [line: line], args}
+    {name, meta(anno), args}
   end
 
-  defp typespec_to_quoted({:var, line, var}) do
-    {erl_to_ex_var(var), [line: line], nil}
+  defp typespec_to_quoted({:var, anno, var}) do
+    {erl_to_ex_var(var), meta(anno), nil}
   end
 
-  defp typespec_to_quoted({:op, line, op, arg}) do
-    {op, [line: line], [typespec_to_quoted(arg)]}
+  defp typespec_to_quoted({:op, anno, op, arg}) do
+    {op, meta(anno), [typespec_to_quoted(arg)]}
   end
 
-  defp typespec_to_quoted({:remote_type, line, [mod, name, args]}) do
-    remote_type(line, mod, name, args)
+  defp typespec_to_quoted({:remote_type, anno, [mod, name, args]}) do
+    remote_type(anno, mod, name, args)
   end
 
-  defp typespec_to_quoted({:ann_type, line, [var, type]}) do
-    {:"::", [line: line], [typespec_to_quoted(var), typespec_to_quoted(type)]}
+  defp typespec_to_quoted({:ann_type, anno, [var, type]}) do
+    {:"::", meta(anno), [typespec_to_quoted(var), typespec_to_quoted(type)]}
   end
 
   defp typespec_to_quoted(
-         {:typed_record_field, {:record_field, line, {:atom, line1, name}}, type}
+         {:typed_record_field, {:record_field, anno1, {:atom, anno2, name}}, type}
        ) do
-    typespec_to_quoted({:ann_type, line, [{:var, line1, name}, type]})
+    typespec_to_quoted({:ann_type, anno1, [{:var, anno2, name}, type]})
   end
 
   defp typespec_to_quoted({:type, _, :any}) do
@@ -359,7 +361,7 @@ defmodule Code.Typespec do
     typespec_to_quoted(type)
   end
 
-  defp typespec_to_quoted({type, _line, atom}) when is_atom(type) do
+  defp typespec_to_quoted({type, _anno, atom}) when is_atom(type) do
     atom
   end
 
@@ -367,30 +369,30 @@ defmodule Code.Typespec do
 
   ## Helpers
 
-  defp remote_type(line, {:atom, _, :elixir}, {:atom, _, :charlist}, []) do
-    typespec_to_quoted({:type, line, :charlist, []})
+  defp remote_type(anno, {:atom, _, :elixir}, {:atom, _, :charlist}, []) do
+    typespec_to_quoted({:type, anno, :charlist, []})
   end
 
-  defp remote_type(line, {:atom, _, :elixir}, {:atom, _, :nonempty_charlist}, []) do
-    typespec_to_quoted({:type, line, :nonempty_charlist, []})
+  defp remote_type(anno, {:atom, _, :elixir}, {:atom, _, :nonempty_charlist}, []) do
+    typespec_to_quoted({:type, anno, :nonempty_charlist, []})
   end
 
-  defp remote_type(line, {:atom, _, :elixir}, {:atom, _, :struct}, []) do
-    typespec_to_quoted({:type, line, :struct, []})
+  defp remote_type(anno, {:atom, _, :elixir}, {:atom, _, :struct}, []) do
+    typespec_to_quoted({:type, anno, :struct, []})
   end
 
-  defp remote_type(line, {:atom, _, :elixir}, {:atom, _, :as_boolean}, [arg]) do
-    typespec_to_quoted({:type, line, :as_boolean, [arg]})
+  defp remote_type(anno, {:atom, _, :elixir}, {:atom, _, :as_boolean}, [arg]) do
+    typespec_to_quoted({:type, anno, :as_boolean, [arg]})
   end
 
-  defp remote_type(line, {:atom, _, :elixir}, {:atom, _, :keyword}, args) do
-    typespec_to_quoted({:type, line, :keyword, args})
+  defp remote_type(anno, {:atom, _, :elixir}, {:atom, _, :keyword}, args) do
+    typespec_to_quoted({:type, anno, :keyword, args})
   end
 
-  defp remote_type(line, mod, name, args) do
+  defp remote_type(anno, mod, name, args) do
     args = for arg <- args, do: typespec_to_quoted(arg)
-    dot = {:., [line: line], [typespec_to_quoted(mod), typespec_to_quoted(name)]}
-    {dot, [line: line], args}
+    dot = {:., meta(anno), [typespec_to_quoted(mod), typespec_to_quoted(name)]}
+    {dot, meta(anno), args}
   end
 
   defp erl_to_ex_var(var) do
@@ -414,4 +416,6 @@ defmodule Code.Typespec do
   defp unpack_typespec_kw(_, _acc) do
     :error
   end
+
+  defp meta(anno), do: [line: :erl_anno.line(anno)]
 end

lib/elixir/lib/collectable.ex

@@ -17,8 +17,8 @@ defprotocol Collectable do
 
   This design is intentional. `Enumerable` was designed to support infinite
   collections, resources and other structures with fixed shape. For example,
-  it doesn't make sense to insert values into a range, as it has a fixed
-  shape where just the range limits are stored.
+  it doesn't make sense to insert values into a `Range`, as it has a
+  fixed shape where only the range limits and step are stored.
 
   The `Collectable` module was designed to fill the gap left by the
   `Enumerable` protocol. `Collectable.into/1` can be seen as the opposite of
@@ -94,10 +94,11 @@ end
 
 defimpl Collectable, for: List do
   def into(list) do
+    # TODO: Change the behaviour so the into always comes last on Elixir v2.0
     if list != [] do
       IO.warn(
         "the Collectable protocol is deprecated for non-empty lists. The behaviour of " <>
-          "things like Enum.into/2 or \"for\" comprehensions with an :into option is incorrect " <>
+          "Enum.into/2 and \"for\" comprehensions with an :into option is incorrect " <>
           "when collecting into non-empty lists. If you're collecting into a non-empty keyword " <>
           "list, consider using Keyword.merge/2 instead. If you're collecting into a non-empty " <>
           "list, consider concatenating the two lists with the ++ operator."

lib/elixir/lib/config.ex

@@ -75,7 +75,7 @@ defmodule Config do
   @config_key {__MODULE__, :config}
   @imports_key {__MODULE__, :imports}
 
-  defp get_opts!(), do: Process.get(@opts_key)
+  defp get_opts!(), do: Process.get(@opts_key) || raise_improper_use!()
   defp put_opts(value), do: Process.put(@opts_key, value)
   defp delete_opts(), do: Process.delete(@opts_key)
 
@@ -102,8 +102,9 @@ defmodule Config do
 
   The given `opts` are merged into the existing configuration
   for the given `root_key`. Conflicting keys are overridden by the
-  ones specified in `opts`. For example, the application
-  configuration below
+  ones specified in `opts`, unless they are keywords, which are
+  deep merged recursively. For example, the application configuration
+  below
 
       config :logger,
         level: :warn,
@@ -138,8 +139,9 @@ defmodule Config do
 
   The given `opts` are merged into the existing values for `key`
   in the given `root_key`. Conflicting keys are overridden by the
-  ones specified in `opts`. For example, the application
-  configuration below
+  ones specified in `opts`, unless they are keywords, which are
+  deep merged recursively. For example, the application configuration
+  below
 
       config :ecto, Repo,
         log_level: :warn,

lib/elixir/lib/config/provider.ex

@@ -20,8 +20,8 @@ defmodule Config.Provider do
 
   For example, imagine you want to list some basic configuration
   on Mix's built-in `config/runtime.exs` file, but you also want
-  some additional configuration files. To do so, you can do this
-  in your `mix.exs`:
+  to support additional configuration files. To do so, you can add
+  this inside the `def project` portion of  your `mix.exs`:
 
       releases: [
         demo: [
@@ -42,7 +42,8 @@ defmodule Config.Provider do
       simply copy it to the release root as a step in your deployment
 
   Now once the system boots, it will load both `config/runtime.exs`
-  and `extra_config.exs` early in the boot process.
+  and `extra_config.exs` early in the boot process. You can learn
+  more options on `Config.Reader`.
 
   ## Custom config provider
 
@@ -55,8 +56,10 @@ defmodule Config.Provider do
         @behaviour Config.Provider
 
         # Let's pass the path to the JSON file as config
+        @impl true
         def init(path) when is_binary(path), do: path
 
+        @impl true
         def load(config, path) do
           # We need to start any app we may depend on.
           {:ok, _} = Application.ensure_all_started(:jason)
@@ -227,7 +230,6 @@ defmodule Config.Provider do
   end
 
   defp boot_providers(path, provider, reboot_config, reboot_fun) do
-    validate_no_cyclic_boot!(path)
     original_config = read_config!(path)
 
     config =
@@ -352,14 +354,6 @@ defmodule Config.Provider do
   defp booted_value(%{prune_runtime_sys_config_after_boot: true}, path), do: {:booted, path}
   defp booted_value(%{prune_runtime_sys_config_after_boot: false}, _path), do: {:booted, nil}
 
-  defp validate_no_cyclic_boot!(path) do
-    if System.get_env("ELIXIR_CONFIG_PROVIDER_BOOTED") do
-      bad_path_abort("Got infinite loop when running Config.Provider", path)
-    else
-      System.put_env("ELIXIR_CONFIG_PROVIDER_BOOTED", "1")
-    end
-  end
-
   defp read_config!(path) do
     case :file.consult(path) do
       {:ok, [inner]} ->

lib/elixir/lib/config/reader.ex

@@ -4,15 +4,23 @@ defmodule Config.Reader do
 
   ## As a provider
 
-  `Config.Reader` can also be used as a `Config.Provider`. When used
-  as a provider, it expects a single argument: the configuration path
-  (as outlined in `t:Config.Provider.config_path/0`) for the file to
-  be read and loaded during the system boot.
+  `Config.Reader` can also be used as a `Config.Provider`. A config
+  provider is used during releases to customize how applications are
+  configured. When used as a provider, it expects a single argument:
+  the configuration path (as outlined in `t:Config.Provider.config_path/0`)
+  for the file to be read and loaded during the system boot.
 
   For example, if you expect the target system to have a config file
-  in an absolute path, you can configure your `mix release` as:
+  in an absolute path, you can add this inside the `def project` portion
+  of  your `mix.exs`:
 
-      config_providers: [{Config.Reader, "/etc/config.exs"}]
+      releases: [
+        demo: [
+          config_providers: [
+            {Config.Reader, "/etc/config.exs"}
+          ]
+        ]
+      ]
 
   Or if you want to read a custom path inside the release:
 
@@ -28,10 +36,8 @@ defmodule Config.Reader do
          imports: :disabled}
       ]
 
-  Note by default Mix releases supports runtime configuration via
-  a `config/runtime.exs`. If a `config/runtime.exs` exists in your
-  application, it is automatically copied inside the release and
-  automatically set as a config provider.
+  Remember Mix already loads `config/runtime.exs` by default.
+  For more examples and scenarios, see the `Config.Providers` module.
   """
 
   @behaviour Config.Provider

lib/elixir/lib/dynamic_supervisor.ex

@@ -419,7 +419,7 @@ defmodule DynamicSupervisor do
   @doc since: "1.6.0"
   @spec which_children(Supervisor.supervisor()) :: [
           # module() | :dynamic here because :supervisor.modules() is not exported
-          {:undefined, pid | :restarting, :worker | :supervisor, module() | :dynamic}
+          {:undefined, pid | :restarting, :worker | :supervisor, [module()] | :dynamic}
         ]
   def which_children(supervisor) do
     call(supervisor, :which_children)

lib/elixir/lib/enum.ex

@@ -4,10 +4,7 @@ defprotocol Enumerable do
 
   When you invoke a function in the `Enum` module, the first argument
   is usually a collection that must implement this protocol.
-  For example, the expression:
-
-      Enum.map([1, 2, 3], &(&1 * 2))
-
+  For example, the expression `Enum.map([1, 2, 3], &(&1 * 2))`
   invokes `Enumerable.reduce/3` to perform the reducing operation that
   builds a mapped list by calling the mapping function `&(&1 * 2)` on
   every element in the collection and consuming the element with an
@@ -73,15 +70,20 @@ defprotocol Enumerable do
 
   It may be *done* when the enumeration is finished by reaching
   its end, or *halted*/*suspended* when the enumeration was halted
-  or suspended by the `t:reducer/0` function.
+  or suspended by the tagged accumulator.
 
-  In case a `t:reducer/0` function returns the `:suspend` accumulator, the
-  `:suspended` tuple must be explicitly handled by the caller and
-  never leak. In practice, this means regular enumeration functions
-  just need to be concerned about `:done` and `:halted` results.
+  In case the tagged `:halt` accumulator is given, the `:halted` tuple
+  with the accumulator must be returned. Functions like `Enum.take_while/2`
+  use `:halt` underneath and can be used to test halting enumerables.
 
-  Furthermore, a `:suspend` call must always be followed by another call,
-  eventually halting or continuing until the end.
+  In case the tagged `:suspend` accumulator is given, the caller must
+  return the `:suspended` tuple with the accumulator and a continuation.
+  The caller is then responsible of managing the continuation and the
+  caller must always call the continuation, eventually halting or continuing
+  until the end. `Enum.zip/2` uses suspension, so it can be used to test
+  whether your implementation handles suspension correctly. You can also use
+  `Stream.zip/2` with `Enum.take_while/2` to test the combination of
+  `:suspend` with `:halt`.
   """
   @type result ::
           {:done, term}
@@ -280,7 +282,7 @@ defmodule Enum do
   end
 
   @doc """
-  Returns `true` if  all elements in `enumerable` are truthy.
+  Returns `true` if all elements in `enumerable` are truthy.
 
   When an element has a falsy value (`false` or `nil`) iteration stops immediately
   and `false` is returned. In all other cases `true` is returned.
@@ -601,9 +603,14 @@ defmodule Enum do
 
   """
   @spec concat(t) :: t
-  def concat(enumerables) do
-    fun = &[&1 | &2]
-    enumerables |> reduce([], &reduce(&1, &2, fun)) |> :lists.reverse()
+  def concat(enumerables)
+
+  def concat(list) when is_list(list) do
+    concat_list(list)
+  end
+
+  def concat(enums) do
+    concat_enum(enums)
   end
 
   @doc """
@@ -628,7 +635,7 @@ defmodule Enum do
   end
 
   def concat(left, right) do
-    concat([left, right])
+    concat_enum([left, right])
   end
 
   @doc """
@@ -786,7 +793,7 @@ defmodule Enum do
   def dedup(enumerable) do
     Enum.reduce(enumerable, [], fn x, acc ->
       case acc do
-        [^x, _] -> acc
+        [^x | _] -> acc
         _ -> [x | acc]
       end
     end)
@@ -1204,13 +1211,16 @@ defmodule Enum do
   def flat_map(enumerable, fun) do
     reduce(enumerable, [], fn entry, acc ->
       case fun.(entry) do
-        list when is_list(list) -> :lists.reverse(list, acc)
-        other -> reduce(other, acc, &[&1 | &2])
+        list when is_list(list) -> [list | acc]
+        other -> [to_list(other) | acc]
       end
     end)
-    |> :lists.reverse()
+    |> flat_reverse([])
   end
 
+  defp flat_reverse([h | t], acc), do: flat_reverse(t, h ++ acc)
+  defp flat_reverse([], acc), do: acc
+
   @doc """
   Maps and reduces an `enumerable`, flattening the given results (only one level deep).
 
@@ -1328,7 +1338,7 @@ defmodule Enum do
       value = value_fun.(entry)
 
       case acc do
-        %{^key => existing} -> Map.put(acc, key, [value | existing])
+        %{^key => existing} -> %{acc | key => [value | existing]}
         %{} -> Map.put(acc, key, [value])
       end
     end)
@@ -1387,9 +1397,10 @@ defmodule Enum do
   @doc """
   Inserts the given `enumerable` into a `collectable`.
 
-  Note that passing a non-empty list as the `collectable` is deprecated. If you're collecting
-  into a non-empty keyword list, consider using `Keyword.merge(collectable, Enum.to_list(enumerable))`.
-  If you're collecting into a non-empty list, consider something like `Enum.to_list(enumerable) ++ collectable`.
+  Note that passing a non-empty list as the `collectable` is deprecated.
+  If you're collecting into a non-empty keyword list, consider using
+  `Keyword.merge(collectable, Enum.to_list(enumerable))`. If you're collecting
+  into a non-empty list, consider something like `Enum.to_list(enumerable) ++ collectable`.
 
   ## Examples
 
@@ -1421,28 +1432,35 @@ defmodule Enum do
     into_protocol(enumerable, collectable)
   end
 
-  def into(%{} = enumerable, %{} = collectable) do
-    Map.merge(collectable, enumerable)
-  end
-
-  def into(enumerable, %{} = collectable) when is_list(enumerable) do
-    Map.merge(collectable, :maps.from_list(enumerable))
-  end
-
   def into(enumerable, %{} = collectable) do
-    reduce(enumerable, collectable, fn {key, val}, acc ->
-      Map.put(acc, key, val)
-    end)
+    if map_size(collectable) == 0 do
+      into_map(enumerable)
+    else
+      into_map(enumerable, collectable)
+    end
   end
 
   def into(enumerable, collectable) do
     into_protocol(enumerable, collectable)
   end
 
+  defp into_map(%{} = enumerable), do: enumerable
+  defp into_map(enumerable) when is_list(enumerable), do: :maps.from_list(enumerable)
+  defp into_map(enumerable), do: enumerable |> Enum.to_list() |> :maps.from_list()
+
+  defp into_map(%{} = enumerable, collectable),
+    do: Map.merge(collectable, enumerable)
+
+  defp into_map(enumerable, collectable) when is_list(enumerable),
+    do: Map.merge(collectable, :maps.from_list(enumerable))
+
+  defp into_map(enumerable, collectable),
+    do: Enum.reduce(enumerable, collectable, fn {key, val}, acc -> Map.put(acc, key, val) end)
+
   defp into_protocol(enumerable, collectable) do
     {initial, fun} = Collectable.into(collectable)
 
-    into(enumerable, initial, fun, fn entry, acc ->
+    into_protocol(enumerable, initial, fun, fn entry, acc ->
       fun.(acc, {:cont, entry})
     end)
   end
@@ -1453,7 +1471,7 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.into([2, 3], [3], fn x -> x * 3 end)
+      iex> Enum.into([1, 2, 3], [], fn x -> x * 3 end)
       [3, 6, 9]
 
       iex> Enum.into(%{a: 1, b: 2}, %{c: 3}, fn {k, v} -> {k, v * 2} end)
@@ -1461,20 +1479,42 @@ defmodule Enum do
 
   """
   @spec into(Enumerable.t(), Collectable.t(), (term -> term)) :: Collectable.t()
+  def into(enumerable, [], transform) do
+    Enum.map(enumerable, transform)
+  end
 
-  def into(enumerable, collectable, transform) when is_list(collectable) do
-    collectable ++ map(enumerable, transform)
+  def into(%_{} = enumerable, collectable, transform) do
+    into_protocol(enumerable, collectable, transform)
+  end
+
+  def into(enumerable, %_{} = collectable, transform) do
+    into_protocol(enumerable, collectable, transform)
+  end
+
+  def into(enumerable, %{} = collectable, transform) do
+    if map_size(collectable) == 0 do
+      enumerable |> Enum.map(transform) |> :maps.from_list()
+    else
+      Enum.reduce(enumerable, collectable, fn entry, acc ->
+        {key, val} = transform.(entry)
+        Map.put(acc, key, val)
+      end)
+    end
   end
 
   def into(enumerable, collectable, transform) do
+    into_protocol(enumerable, collectable, transform)
+  end
+
+  defp into_protocol(enumerable, collectable, transform) do
     {initial, fun} = Collectable.into(collectable)
 
-    into(enumerable, initial, fun, fn entry, acc ->
+    into_protocol(enumerable, initial, fun, fn entry, acc ->
       fun.(acc, {:cont, transform.(entry)})
     end)
   end
 
-  defp into(enumerable, initial, fun, callback) do
+  defp into_protocol(enumerable, initial, fun, callback) do
     try do
       reduce(enumerable, initial, callback)
     catch
@@ -2026,11 +2066,13 @@ defmodule Enum do
   def min_max(enumerable, empty_fallback \\ fn -> raise Enum.EmptyError end)
 
   def min_max(first..last//step = range, empty_fallback) when is_function(empty_fallback, 0) do
-    if Range.empty?(range) do
-      empty_fallback.()
-    else
-      last = last - rem(last - first, step)
-      {Kernel.min(first, last), Kernel.max(first, last)}
+    case Range.size(range) do
+      0 ->
+        empty_fallback.()
+
+      _ ->
+        last = last - rem(last - first, step)
+        {Kernel.min(first, last), Kernel.max(first, last)}
     end
   end
 
@@ -2221,19 +2263,17 @@ defmodule Enum do
 
   ## Examples
 
-  The examples below use the `:exrop` pseudorandom algorithm since it's
-  the default from Erlang/OTP 20, however if you are using Erlang/OTP 22
-  or above then `:exsss` is the default algorithm. If you are using `:exsplus`,
-  then please update, as this algorithm is deprecated since Erlang/OTP 20.
+  The examples below use the `:exsss` pseudorandom algorithm since it's
+  the default from Erlang/OTP 22:
 
       # Although not necessary, let's seed the random algorithm
-      iex> :rand.seed(:exrop, {101, 102, 103})
-      iex> Enum.random([1, 2, 3])
-      3
+      iex> :rand.seed(:exsss, {100, 101, 102})
       iex> Enum.random([1, 2, 3])
       2
+      iex> Enum.random([1, 2, 3])
+      1
       iex> Enum.random(1..1_000)
-      846
+      309
 
   """
   @spec random(t) :: element
@@ -2492,6 +2532,169 @@ defmodule Enum do
     end
   end
 
+  @doc """
+  Slides a single or multiple elements given by `range_or_single_index` from `enumerable`
+  to `insertion_index`.
+
+  The semantics of the range to be moved match the semantics of `Enum.slice/2`.
+  Specifically, that means:
+
+   * Indices are normalized, meaning that negative indexes will be counted from the end
+      (for example, -1 means the last element of the enumerable). This will result in *two*
+      traversals of your enumerable on types like lists that don't provide a constant-time count.
+
+    * If the normalized index range's `last` is out of bounds, the range is truncated to the last element.
+
+    * If the normalized index range's `first` is out of bounds, the selected range for sliding
+      will be empty, so you'll get back your input list.
+
+    * Decreasing ranges (such as `5..0//1`) also select an empty range to be moved,
+      so you'll get back your input list.
+
+    * Ranges with any step but 1 will raise an error.
+
+  ## Examples
+
+      # Slide a single element
+      iex> Enum.slide([:a, :b, :c, :d, :e, :f, :g], 5, 1)
+      [:a, :f, :b, :c, :d, :e, :g]
+
+      # Slide a range of elements backward
+      iex> Enum.slide([:a, :b, :c, :d, :e, :f, :g], 3..5, 1)
+      [:a, :d, :e, :f, :b, :c, :g]
+
+      # Slide a range of elements forward
+      iex> Enum.slide([:a, :b, :c, :d, :e, :f, :g], 1..3, 5)
+      [:a, :e, :f, :b, :c, :d, :g]
+
+      # Slide with negative indices (counting from the end)
+      iex> Enum.slide([:a, :b, :c, :d, :e, :f, :g], 3..-1//1, 2)
+      [:a, :b, :d, :e, :f, :g, :c]
+      iex> Enum.slide([:a, :b, :c, :d, :e, :f, :g], -4..-2, 1)
+      [:a, :d, :e, :f, :b, :c, :g]
+
+      # Insert at negative indices (counting from the end)
+      iex> Enum.slide([:a, :b, :c, :d, :e, :f, :g], 3, -1)
+      [:a, :b, :c, :e, :f, :g, :d]
+
+  """
+  @doc since: "1.13.0"
+  def slide(enumerable, range_or_single_index, insertion_index)
+
+  def slide(enumerable, single_index, insertion_index) when is_integer(single_index) do
+    slide(enumerable, single_index..single_index, insertion_index)
+  end
+
+  # This matches the behavior of Enum.slice/2
+  def slide(_, _.._//step = index_range, _insertion_index) when step != 1 do
+    raise ArgumentError,
+          "Enum.slide/3 does not accept ranges with custom steps, got: #{inspect(index_range)}"
+  end
+
+  # Normalize negative input ranges like Enum.slice/2
+  def slide(enumerable, first..last, insertion_index)
+      when first < 0 or last < 0 or insertion_index < 0 do
+    count = Enum.count(enumerable)
+    normalized_first = if first >= 0, do: first, else: first + count
+    normalized_last = if last >= 0, do: last, else: last + count
+
+    normalized_insertion_index =
+      if insertion_index >= 0, do: insertion_index, else: insertion_index + count
+
+    if normalized_first >= 0 and normalized_first < count and
+         normalized_first != normalized_insertion_index do
+      normalized_range = normalized_first..normalized_last//1
+      slide(enumerable, normalized_range, normalized_insertion_index)
+    else
+      Enum.to_list(enumerable)
+    end
+  end
+
+  def slide(enumerable, insertion_index.._, insertion_index) do
+    Enum.to_list(enumerable)
+  end
+
+  def slide(_, first..last, insertion_index)
+      when insertion_index > first and insertion_index <= last do
+    raise "Insertion index for slide must be outside the range being moved " <>
+            "(tried to insert #{first}..#{last} at #{insertion_index})"
+  end
+
+  # Guarantees at this point: step size == 1 and first <= last and (insertion_index < first or insertion_index > last)
+  def slide(enumerable, first..last, insertion_index) do
+    impl = if is_list(enumerable), do: &slide_list_start/4, else: &slide_any/4
+
+    cond do
+      insertion_index <= first -> impl.(enumerable, insertion_index, first, last)
+      insertion_index > last -> impl.(enumerable, first, last + 1, insertion_index)
+    end
+  end
+
+  # Takes the range from middle..last and moves it to be in front of index start
+  defp slide_any(enumerable, start, middle, last) do
+    # We're going to deal with 4 "chunks" of the enumerable:
+    # 0. "Head," before the start index
+    # 1. "Slide back," between start (inclusive) and middle (exclusive)
+    # 2. "Slide front," between middle (inclusive) and last (inclusive)
+    # 3. "Tail," after last
+    #
+    # But, we're going to accumulate these into only two lists: pre and post.
+    # We'll reverse-accumulate the head into our pre list, then "slide back" into post,
+    # then "slide front" into pre, then "tail" into post.
+    #
+    # Then at the end, we're going to reassemble and reverse them, and end up with the
+    # chunks in the correct order.
+    {_size, pre, post} =
+      Enum.reduce(enumerable, {0, [], []}, fn item, {index, pre, post} ->
+        {pre, post} =
+          cond do
+            index < start -> {[item | pre], post}
+            index >= start and index < middle -> {pre, [item | post]}
+            index >= middle and index <= last -> {[item | pre], post}
+            true -> {pre, [item | post]}
+          end
+
+        {index + 1, pre, post}
+      end)
+
+    :lists.reverse(pre, :lists.reverse(post))
+  end
+
+  # Like slide_any/4 above, this optimized implementation of slide for lists depends
+  # on the indices being sorted such that we're moving middle..last to be in front of start.
+  defp slide_list_start([h | t], start, middle, last)
+       when start > 0 and start <= middle and middle <= last do
+    [h | slide_list_start(t, start - 1, middle - 1, last - 1)]
+  end
+
+  defp slide_list_start(list, 0, middle, last), do: slide_list_middle(list, middle, last, [])
+
+  defp slide_list_middle([h | t], middle, last, acc) when middle > 0 do
+    slide_list_middle(t, middle - 1, last - 1, [h | acc])
+  end
+
+  defp slide_list_middle(list, 0, last, start_to_middle) do
+    {slid_range, tail} = slide_list_last(list, last + 1, [])
+    slid_range ++ :lists.reverse(start_to_middle, tail)
+  end
+
+  # You asked for a middle index off the end of the list... you get what we've got
+  defp slide_list_middle([], _, _, acc) do
+    :lists.reverse(acc)
+  end
+
+  defp slide_list_last([h | t], last, acc) when last > 0 do
+    slide_list_last(t, last - 1, [h | acc])
+  end
+
+  defp slide_list_last(rest, 0, acc) do
+    {:lists.reverse(acc), rest}
+  end
+
+  defp slide_list_last([], _, acc) do
+    {:lists.reverse(acc), []}
+  end
+
   @doc """
   Applies the given function to each element in the `enumerable`,
   storing the result in a list and passing it as the accumulator
@@ -2549,17 +2752,15 @@ defmodule Enum do
 
   ## Examples
 
-  The examples below use the `:exrop` pseudorandom algorithm since it's
-  the default from Erlang/OTP 20, however if you are using Erlang/OTP 22
-  or above then `:exsss` is the default algorithm. If you are using `:exsplus`,
-  then please update, as this algorithm is deprecated since Erlang/OTP 20.
+  The examples below use the `:exsss` pseudorandom algorithm since it's
+  the default from Erlang/OTP 22:
 
       # Although not necessary, let's seed the random algorithm
-      iex> :rand.seed(:exrop, {1, 2, 3})
+      iex> :rand.seed(:exsss, {1, 2, 3})
       iex> Enum.shuffle([1, 2, 3])
-      [3, 1, 2]
+      [3, 2, 1]
       iex> Enum.shuffle([1, 2, 3])
-      [1, 3, 2]
+      [2, 1, 3]
 
   """
   @spec shuffle(t) :: list
@@ -2634,6 +2835,12 @@ defmodule Enum do
     end
   end
 
+  # TODO: Remove me on v2.0
+  def slice(enumerable, %{__struct__: Range, first: first, last: last} = index_range) do
+    step = if first <= last, do: 1, else: -1
+    slice(enumerable, Map.put(index_range, :step, step))
+  end
+
   defp slice_range(enumerable, first, last) when last >= first and last >= 0 and first >= 0 do
     slice_any(enumerable, first, last - first + 1)
   end
@@ -3146,11 +3353,11 @@ defmodule Enum do
   ## Examples
 
       # Although not necessary, let's seed the random algorithm
-      iex> :rand.seed(:exrop, {1, 2, 3})
+      iex> :rand.seed(:exsss, {1, 2, 3})
       iex> Enum.take_random(1..10, 2)
-      [7, 2]
+      [3, 1]
       iex> Enum.take_random(?a..?z, 5)
-      'hypnt'
+      'mikel'
 
   """
   @spec take_random(t, non_neg_integer) :: list
@@ -3354,6 +3561,15 @@ defmodule Enum do
 
   """
   @spec unzip(t) :: {[element], [element]}
+
+  def unzip([_ | _] = list) do
+    :lists.reverse(list) |> unzip([], [])
+  end
+
+  def unzip([]) do
+    {[], []}
+  end
+
   def unzip(enumerable) do
     {list1, list2} =
       reduce(enumerable, {[], []}, fn {el1, el2}, {list1, list2} ->
@@ -3363,6 +3579,14 @@ defmodule Enum do
     {:lists.reverse(list1), :lists.reverse(list2)}
   end
 
+  defp unzip([{el1, el2} | reversed_list], list1, list2) do
+    unzip(reversed_list, [el1 | list1], [el2 | list2])
+  end
+
+  defp unzip([], list1, list2) do
+    {list1, list2}
+  end
+
   @doc """
   Returns the `enumerable` with each element wrapped in a tuple
   alongside its index.
@@ -3420,7 +3644,7 @@ defmodule Enum do
   """
   @spec zip(t, t) :: [{any, any}]
   def zip(enumerable1, enumerable2) when is_list(enumerable1) and is_list(enumerable2) do
-    zip_list(enumerable1, enumerable2)
+    zip_list(enumerable1, enumerable2, [])
   end
 
   def zip(enumerable1, enumerable2) do
@@ -3493,7 +3717,7 @@ defmodule Enum do
   @spec zip_with(t, t, (enum1_elem :: term, enum2_elem :: term -> term)) :: [term]
   def zip_with(enumerable1, enumerable2, zip_fun)
       when is_list(enumerable1) and is_list(enumerable2) and is_function(zip_fun, 2) do
-    zip_list(enumerable1, enumerable2, zip_fun)
+    zip_with_list(enumerable1, enumerable2, zip_fun)
   end
 
   def zip_with(enumerable1, enumerable2, zip_fun) when is_function(zip_fun, 2) do
@@ -3562,16 +3786,17 @@ defmodule Enum do
   end
 
   @doc """
-  Reduces a over all of the given enums, halting as soon as any enumerable is empty.
+  Reduces over all of the given enumerables, halting as soon as any enumerable is
+  empty.
 
-  The reducer will receive 2 args, a list of elements (one from each enum) and the
+  The reducer will receive 2 args: a list of elements (one from each enum) and the
   accumulator.
 
   In practice, the behaviour provided by this function can be achieved with:
 
       Enum.reduce(Stream.zip(enums), acc, reducer)
 
-  But `zip_reduce/4` exists for convenience purposes.
+  But `zip_reduce/3` exists for convenience purposes.
 
   ## Examples
 
@@ -3611,15 +3836,17 @@ defmodule Enum do
   end
 
   defp aggregate(first..last//step = range, fun, empty) do
-    if Range.empty?(range) do
-      empty.()
-    else
-      last = last - rem(last - first, step)
+    case Range.size(range) do
+      0 ->
+        empty.()
 
-      case fun.(first, last) do
-        true -> first
-        false -> last
-      end
+      _ ->
+        last = last - rem(last - first, step)
+
+        case fun.(first, last) do
+          true -> first
+          false -> last
+        end
     end
   end
 
@@ -3754,6 +3981,17 @@ defmodule Enum do
     false
   end
 
+  ## concat
+
+  defp concat_list([h | t]) when is_list(h), do: h ++ concat_list(t)
+  defp concat_list([h | t]), do: concat_enum([h | t])
+  defp concat_list([]), do: []
+
+  defp concat_enum(enum) do
+    fun = &[&1 | &2]
+    enum |> reduce([], &reduce(&1, &2, fun)) |> :lists.reverse()
+  end
+
   # dedup
 
   defp dedup_list([value | tail], acc) do
@@ -4199,16 +4437,19 @@ defmodule Enum do
 
   ## zip
 
-  defp zip_list(enumerable1, enumerable2) do
-    zip_list(enumerable1, enumerable2, fn x, y -> {x, y} end)
+  defp zip_list([head1 | next1], [head2 | next2], acc) do
+    zip_list(next1, next2, [{head1, head2} | acc])
   end
 
-  defp zip_list([head1 | next1], [head2 | next2], fun) do
-    [fun.(head1, head2) | zip_list(next1, next2, fun)]
+  defp zip_list([], _, acc), do: :lists.reverse(acc)
+  defp zip_list(_, [], acc), do: :lists.reverse(acc)
+
+  defp zip_with_list([head1 | next1], [head2 | next2], fun) do
+    [fun.(head1, head2) | zip_with_list(next1, next2, fun)]
   end
 
-  defp zip_list(_, [], _fun), do: []
-  defp zip_list([], _, _fun), do: []
+  defp zip_with_list(_, [], _fun), do: []
+  defp zip_with_list([], _, _fun), do: []
 
   defp zip_reduce_list([head1 | next1], [head2 | next2], acc, fun) do
     zip_reduce_list(next1, next2, fun.(head1, head2, acc), fun)

lib/elixir/lib/exception.ex

@@ -43,10 +43,16 @@ defmodule Exception do
   @callback blame(t, stacktrace) :: {t, stacktrace}
   @optional_callbacks [blame: 2]
 
+  @doc false
+  # Callback for formatting Erlang exceptions
+  def format_error(%struct{} = exception, _stacktrace) do
+    %{general: message(exception), reason: "#" <> Atom.to_string(struct)}
+  end
+
   @doc """
   Returns `true` if the given `term` is an exception.
   """
-  # TODO: Remove this on Elixir v1.15
+  # TODO: Deprecate this on Elixir v1.15
   @doc deprecated: "Use Kernel.is_exception/1 instead"
   def exception?(term)
   def exception?(%_{__exception__: true}), do: true
@@ -62,7 +68,7 @@ defmodule Exception do
       caught_exception ->
         "got #{inspect(caught_exception.__struct__)} with message " <>
           "#{inspect(message(caught_exception))} while retrieving Exception.message/1 " <>
-          "for #{inspect(exception)}"
+          "for #{inspect(exception)}. Stacktrace:\n#{format_stacktrace(__STACKTRACE__)}"
     else
       result when is_binary(result) ->
         result
@@ -211,16 +217,17 @@ defmodule Exception do
       clauses =
         for {meta, ex_args, guards, _block} <- clauses do
           scope = :elixir_erl.scope(meta, true)
+          ann = :elixir_erl.get_ann(meta)
 
           {erl_args, scope} =
-            :elixir_erl_clauses.match(&:elixir_erl_pass.translate_args/2, ex_args, scope)
+            :elixir_erl_clauses.match(ann, &:elixir_erl_pass.translate_args/3, ex_args, scope)
 
           {args, binding} =
             [call_args, ex_args, erl_args]
             |> Enum.zip()
             |> Enum.map_reduce([], &blame_arg/2)
 
-          guards = Enum.map(guards, &blame_guard(&1, scope, binding))
+          guards = Enum.map(guards, &blame_guard(&1, ann, scope, binding))
           {args, guards}
         end
 
@@ -253,18 +260,18 @@ defmodule Exception do
   defp rewrite_arg(arg) do
     Macro.prewalk(arg, fn
       {:%{}, meta, [__struct__: Range, first: first, last: last, step: step]} ->
-        {:..//, meta, [first, last, step]}
+        {:"..//", meta, [first, last, step]}
 
       other ->
         other
     end)
   end
 
-  defp blame_guard({{:., _, [:erlang, op]}, meta, [left, right]}, scope, binding)
+  defp blame_guard({{:., _, [:erlang, op]}, meta, [left, right]}, ann, scope, binding)
        when op == :andalso or op == :orelse do
     guards = [
-      blame_guard(left, scope, binding),
-      blame_guard(right, scope, binding)
+      blame_guard(left, ann, scope, binding),
+      blame_guard(right, ann, scope, binding)
     ]
 
     kernel_op =
@@ -276,8 +283,8 @@ defmodule Exception do
     {kernel_op, meta, guards}
   end
 
-  defp blame_guard(ex_guard, scope, binding) do
-    {erl_guard, _} = :elixir_erl_pass.translate(ex_guard, scope)
+  defp blame_guard(ex_guard, ann, scope, binding) do
+    {erl_guard, _} = :elixir_erl_pass.translate(ex_guard, ann, scope)
 
     match? =
       try do
@@ -690,6 +697,17 @@ defmodule Exception do
     end
   end
 
+  @doc false
+  def format_snippet(snippet, error_line) do
+    line_digits = error_line |> Integer.to_string() |> byte_size()
+    placeholder = String.duplicate(" ", max(line_digits, 2))
+    padding = if line_digits < 2, do: " "
+
+    " #{placeholder} |\n" <>
+      " #{padding}#{error_line} | #{snippet.content}\n" <>
+      " #{placeholder} | #{String.duplicate(" ", snippet.offset)}^"
+  end
+
   defp format_location(opts) when is_list(opts) do
     format_file_line(Keyword.get(opts, :file), Keyword.get(opts, :line), " ")
   end
@@ -714,10 +732,14 @@ defmodule ArgumentError do
       ) do
     message =
       cond do
+        not proper_list?(args) ->
+          "you attempted to apply a function named #{inspect(function)} on module #{inspect(module)} " <>
+            "with arguments #{inspect(args)}. Arguments (the third argument of apply) must always be a proper list"
+
         # Note that args may be an empty list even if they were supplied
         not is_atom(module) and is_atom(function) and args == [] ->
-          "you attempted to apply #{inspect(function)} on #{inspect(module)}. " <>
-            "If you are using apply/3, make sure the module is an atom. " <>
+          "you attempted to apply a function named #{inspect(function)} on #{inspect(module)}. " <>
+            "If you are using Kernel.apply/3, make sure the module is an atom. " <>
             "If you are using the dot syntax, such as map.field or module.function(), " <>
             "make sure the left side of the dot is an atom or a map"
 
@@ -726,12 +748,9 @@ defmodule ArgumentError do
             "Modules (the first argument of apply) must always be an atom"
 
         not is_atom(function) ->
-          "you attempted to apply #{inspect(function)} on module #{inspect(module)}. " <>
-            "Functions (the second argument of apply) must always be an atom"
-
-        not is_list(args) ->
-          "you attempted to apply #{inspect(function)} on module #{inspect(module)} " <>
-            "with arguments #{inspect(args)}. Arguments (the third argument of apply) must always be a list"
+          "you attempted to apply a function named #{inspect(function)} on module #{inspect(module)}. " <>
+            "However #{inspect(function)} is not a valid function name. Function names (the second argument " <>
+            "of apply) must always be an atom"
       end
 
     {%{exception | message: message}, stacktrace}
@@ -740,6 +759,9 @@ defmodule ArgumentError do
   def blame(exception, stacktrace) do
     {exception, stacktrace}
   end
+
+  defp proper_list?(list) when length(list) >= 0, do: true
+  defp proper_list?(_), do: false
 end
 
 defmodule ArithmeticError do
@@ -787,20 +809,56 @@ defmodule SystemLimitError do
 end
 
 defmodule SyntaxError do
-  defexception [:file, :line, :column, description: "syntax error"]
+  defexception [:file, :line, :column, :snippet, description: "syntax error"]
 
   @impl true
-  def message(%{file: file, line: line, column: column, description: description}) do
+  def message(%{
+        file: file,
+        line: line,
+        column: column,
+        description: description,
+        snippet: snippet
+      })
+      when not is_nil(snippet) and not is_nil(column) do
+    Exception.format_file_line_column(Path.relative_to_cwd(file), line, column) <>
+      " " <> description <> "\n" <> Exception.format_snippet(snippet, line)
+  end
+
+  @impl true
+  def message(%{
+        file: file,
+        line: line,
+        column: column,
+        description: description
+      }) do
     Exception.format_file_line_column(Path.relative_to_cwd(file), line, column) <>
       " " <> description
   end
 end
 
 defmodule TokenMissingError do
-  defexception [:file, :line, :column, description: "expression is incomplete"]
+  defexception [:file, :line, :snippet, :column, description: "expression is incomplete"]
 
   @impl true
-  def message(%{file: file, line: line, column: column, description: description}) do
+  def message(%{
+        file: file,
+        line: line,
+        column: column,
+        description: description,
+        snippet: snippet
+      })
+      when not is_nil(snippet) and not is_nil(column) do
+    Exception.format_file_line_column(Path.relative_to_cwd(file), line, column) <>
+      " " <> description <> "\n" <> Exception.format_snippet(snippet, line)
+  end
+
+  @impl true
+  def message(%{
+        file: file,
+        line: line,
+        column: column,
+        description: description
+      }) do
     Exception.format_file_line_column(file && Path.relative_to_cwd(file), line, column) <>
       " " <> description
   end
@@ -1033,7 +1091,7 @@ defmodule UndefinedFunctionError do
 
     case result do
       [] -> []
-      suggestions -> [". Did you mean one of:\n\n" | Enum.map(suggestions, &format_fa/1)]
+      suggestions -> [". Did you mean:\n\n" | Enum.map(suggestions, &format_fa/1)]
     end
   end
 
@@ -1064,7 +1122,9 @@ defmodule UndefinedFunctionError do
   end
 
   defp expects_callback?(behaviour, function, arity) do
-    callbacks = behaviour.behaviour_info(:callbacks)
+    callbacks =
+      behaviour.behaviour_info(:callbacks) -- behaviour.behaviour_info(:optional_callbacks)
+
     Enum.member?(callbacks, {function, arity})
   end
 
@@ -1106,7 +1166,7 @@ defmodule FunctionClauseError do
 
       %{module: module, function: function, arity: arity} ->
         formatted = Exception.format_mfa(module, function, arity)
-        blamed = blame(exception, &inspect/1, &blame_match/2)
+        blamed = blame(exception, &inspect/1, &blame_match/1)
         "no function clause matching in #{formatted}" <> blamed
     end
   end
@@ -1128,24 +1188,24 @@ defmodule FunctionClauseError do
     end
   end
 
-  defp blame_match(%{match?: true, node: node}, _), do: Macro.to_string(node)
-  defp blame_match(%{match?: false, node: node}, _), do: "-" <> Macro.to_string(node) <> "-"
-  defp blame_match(_, string), do: string
+  defp blame_match(%{match?: true, node: node}), do: Macro.to_string(node)
+  defp blame_match(%{match?: false, node: node}), do: "-" <> Macro.to_string(node) <> "-"
 
   @doc false
   def blame(%{args: nil}, _, _) do
     ""
   end
 
-  def blame(exception, inspect_fun, ast_fun) do
+  def blame(exception, inspect_fun, fun) do
     %{module: module, function: function, arity: arity, kind: kind, args: args, clauses: clauses} =
       exception
 
     mfa = Exception.format_mfa(module, function, arity)
 
     format_clause_fun = fn {args, guards} ->
-      code = Enum.reduce(guards, {function, [], args}, &{:when, [], [&2, &1]})
-      "    #{kind} " <> Macro.to_string(code, ast_fun) <> "\n"
+      args = Enum.map_join(args, ", ", fun)
+      base = "    #{kind} #{function}(#{args})"
+      Enum.reduce(guards, base, &"#{&2} when #{clause_to_string(&1, fun)}") <> "\n"
     end
 
     "\n\nThe following arguments were given to #{mfa}:\n" <>
@@ -1153,6 +1213,11 @@ defmodule FunctionClauseError do
       "#{format_clauses(clauses, format_clause_fun, @clause_limit)}"
   end
 
+  defp clause_to_string({op, _, [left, right]}, fun),
+    do: clause_to_string(left, fun) <> " #{op} " <> clause_to_string(right, fun)
+
+  defp clause_to_string(node, fun), do: fun.(node)
+
   defp format_args(args, inspect_fun) do
     args
     |> Enum.with_index(1)
@@ -1297,7 +1362,7 @@ defmodule KeyError do
 
     case suggestions do
       [] -> []
-      suggestions -> [". Did you mean one of:\n\n" | format_suggestions(suggestions)]
+      suggestions -> [". Did you mean:\n\n" | format_suggestions(suggestions)]
     end
   end
 
@@ -1532,8 +1597,18 @@ defmodule ErlangError do
     {nil, nil, nil}
   end
 
-  @doc false
-  def error_info(erl_exception, stacktrace) do
+  defp error_info(:badarg, [{:erlang, fun, _, _} | _]) when fun in [:byte_size, :bit_size] do
+    {:ok,
+     """
+       * 1st argument: not a bitstring
+
+     This typically happens when calling Kernel.#{fun}/1 with an invalid argument \
+     or when performing binary construction or binary concatenation with <> and \
+     one of the arguments is not a binary\
+     """}
+  end
+
+  defp error_info(erl_exception, stacktrace) do
     with [{module, _, args_or_arity, opts} | _] <- stacktrace,
          %{} = error_info <- opts[:error_info] do
       module = Map.get(error_info, :module, module)

lib/elixir/lib/gen_server.ex

@@ -159,8 +159,8 @@ defmodule GenServer do
   a name on start via the `:name` option. Registered names are also
   automatically cleaned up on termination. The supported values are:
 
-    * an atom - the GenServer is registered locally with the given name
-      using `Process.register/2`.
+    * an atom - the GenServer is registered locally (to the current node)
+      with the given name using `Process.register/2`.
 
     * `{:global, term}` - the GenServer is registered globally with the given
       term using the functions in the [`:global` module](`:global`).
@@ -254,15 +254,20 @@ defmodule GenServer do
   a timeout value in milliseconds; if not, `:infinity` is assumed.
   The timeout can be used to detect a lull in incoming messages.
 
-  If the process has no messages waiting when the timeout is set and the
-  number of given milliseconds pass without any message arriving,
-  then `handle_info/2` will be called with `:timeout` as the first argument.
-  The timeout is cleared if any message is waiting or arrives before the
-  given timeout.
+  The `timeout()` value is used as follows:
 
-  Because a message may arrive before the timeout is set, even a timeout of `0`
-  milliseconds is not guaranteed to execute. To take another action immediately
-  and unconditionally, use a `:continue` instruction.
+    * If the process has any message already waiting when the `timeout()` value
+      is returned, the timeout is ignored and the waiting message is handled as
+      usual. This means that even a timeout of `0` milliseconds is not guaranteed
+      to execute (if you want to take another action immediately and unconditionally,
+      use a `:continue` instruction instead).
+
+    * If any message arrives before the specified number of milliseconds
+      elapse, the timeout is cleared and that message is handled as usual.
+
+    * Otherwise, when the specified number of milliseconds have elapsed with no
+      message arriving, `handle_info/2` is called with `:timeout` as the first
+      argument.
 
   ## When (not) to use a GenServer
 
@@ -585,8 +590,6 @@ defmodule GenServer do
 
   This callback is optional. If one is not implemented, the server will fail
   if a continue instruction is used.
-
-  This callback is only supported on Erlang/OTP 21+.
   """
   @callback handle_continue(continue :: term, state :: term) ::
               {:noreply, new_state}
@@ -1015,6 +1018,7 @@ defmodule GenServer do
       nil ->
         exit({:noproc, {__MODULE__, :call, [server, request, timeout]}})
 
+      # TODO: remove this clause when we require Erlang/OTP 25+
       pid when pid == self() ->
         exit({:calling_self, {__MODULE__, :call, [server, request, timeout]}})
 
@@ -1038,18 +1042,8 @@ defmodule GenServer do
   is unknown whether the destination `server` successfully
   handled the message.
 
-  `c:handle_cast/2` will be called on the server to handle
-  the request. In case the `server` is on a node which is
-  not yet connected to the caller one, the semantics differ
-  depending on the used Erlang/OTP version.
-
   `server` can be any of the values described in the "Name registration"
   section of the documentation for this module.
-
-  Before Erlang/OTP 21, the call is going to block until a
-  connection happens. This was done to guarantee ordering.
-  Starting with Erlang/OTP 21, both Erlang and Elixir do
-  not block the call.
   """
   @spec cast(server, term) :: :ok
   def cast(server, request)

lib/elixir/lib/inspect.ex

@@ -157,7 +157,7 @@ defimpl Inspect, for: BitString do
   defp each_bit(bitstring, _counter, opts) do
     size = bit_size(bitstring)
     <<h::size(size)>> = bitstring
-    Inspect.Integer.inspect(h, opts) <> "::size(" <> Integer.to_string(size) <> ")"
+    concat(Inspect.Integer.inspect(h, opts), "::size(" <> Integer.to_string(size) <> ")")
   end
 
   @compile {:inline, decrement: 1}

lib/elixir/lib/inspect/algebra.ex

@@ -32,7 +32,7 @@ defmodule Inspect.Opts do
       to pass the custom options through.
 
     * `:inspect_fun` (since v1.9.0) - a function to build algebra documents.
-      Defaults to `Inspect.inspect/2`.
+      Defaults to `Inspect.Opts.default_inspect_fun/0`.
 
     * `:limit` - limits the number of items that are inspected for tuples,
       bitstrings, maps, lists and any other collection of items, with the exception of
@@ -105,6 +105,62 @@ defmodule Inspect.Opts do
           syntax_colors: [{color_key, IO.ANSI.ansidata()}],
           width: non_neg_integer | :infinity
         }
+
+  @doc """
+  Builds an `Inspect.Opts` struct.
+  """
+  @doc since: "1.13.0"
+  @spec new(keyword()) :: t
+  def new(opts) do
+    struct(%Inspect.Opts{inspect_fun: default_inspect_fun()}, opts)
+  end
+
+  @doc """
+  Returns the default inspect function.
+  """
+  @doc since: "1.13.0"
+  @spec default_inspect_fun() :: (term, t -> Inspect.Algebra.t())
+  def default_inspect_fun do
+    :persistent_term.get({__MODULE__, :inspect_fun}, &Inspect.inspect/2)
+  end
+
+  @doc """
+  Sets the default inspect function.
+
+  Set this option with care as it will change how all values
+  in the system are inspected. The main use of this functionality
+  is to provide an entry point to filter inspected values,
+  in order for entities to comply with rules and legislations
+  on data security and data privacy.
+
+  It is **extremely discouraged** for libraries to set their own
+  function as this must be controlled by applications. Libraries
+  should instead define their own structs with custom inspect
+  implementations. If a library must change the default inspect
+  function, then it is best to define to ask users of your library
+  to explicitly call `default_inspect_fun/1` with your function of
+  choice.
+
+  The default is `Inspect.inspect/2`.
+
+  ## Examples
+
+      previous_fun = Inspect.Opts.default_inspect_fun()
+
+      Inspect.Opts.default_inspect_fun(fn
+        %{address: _} = map, opts ->
+          previous_fun.(%{map | address: "[REDACTED]"}, opts)
+
+        value, opts ->
+          previous_fun.(value, opts)
+      end)
+
+  """
+  @doc since: "1.13.0"
+  @spec default_inspect_fun((term, t -> Inspect.Algebra.t())) :: :ok
+  def default_inspect_fun(fun) when is_function(fun, 2) do
+    :persistent_term.put({__MODULE__, :inspect_fun}, fun)
+  end
 end
 
 defmodule Inspect.Error do
@@ -298,7 +354,13 @@ defmodule Inspect.Algebra do
             try do
               Process.put(:inspect_trap, true)
 
-              res = Inspect.Map.inspect(struct, %{opts | syntax_colors: []})
+              res =
+                Inspect.Map.inspect(struct, %{
+                  opts
+                  | syntax_colors: [],
+                    inspect_fun: Inspect.Opts.default_inspect_fun()
+                })
+
               res = IO.iodata_to_binary(format(res, :infinity))
 
               message =
@@ -308,7 +370,10 @@ defmodule Inspect.Algebra do
               exception = Inspect.Error.exception(message: message)
 
               if opts.safe do
-                Inspect.inspect(exception, opts)
+                Inspect.inspect(exception, %{
+                  opts
+                  | inspect_fun: Inspect.Opts.default_inspect_fun()
+                })
               else
                 reraise(exception, __STACKTRACE__)
               end
@@ -536,7 +601,7 @@ defmodule Inspect.Algebra do
   Colors a document if the `color_key` has a color in the options.
   """
   @doc since: "1.4.0"
-  @spec color(t, Inspect.Opts.color_key(), Inspect.Opts.t()) :: doc_color
+  @spec color(t, Inspect.Opts.color_key(), Inspect.Opts.t()) :: t
   def color(doc, color_key, %Inspect.Opts{syntax_colors: syntax_colors}) when is_doc(doc) do
     if precolor = Keyword.get(syntax_colors, color_key) do
       postcolor = Keyword.get(syntax_colors, :reset, :reset)

lib/elixir/lib/integer.ex

@@ -104,19 +104,13 @@ defmodule Integer do
   @spec pow(integer, non_neg_integer) :: integer
   def pow(base, exponent) when is_integer(base) and is_integer(exponent) do
     if exponent < 0, do: :erlang.error(:badarith, [base, exponent])
-    guarded_pow(base, exponent)
+    base ** exponent
   end
 
-  # https://en.wikipedia.org/wiki/Exponentiation_by_squaring
-  defp guarded_pow(_, 0), do: 1
-  defp guarded_pow(b, 1), do: b
-  defp guarded_pow(b, e) when (e &&& 1) == 0, do: guarded_pow(b * b, e >>> 1)
-  defp guarded_pow(b, e), do: b * guarded_pow(b * b, e >>> 1)
-
   @doc """
   Computes the modulo remainder of an integer division.
 
-  `Integer.mod/2` uses floored division, which means that
+  This function performs a [floored division](`floor_div/2`), which means that
   the result will always have the sign of the `divisor`.
 
   Raises an `ArithmeticError` exception if one of the arguments is not an
@@ -148,8 +142,8 @@ defmodule Integer do
   Raises an `ArithmeticError` exception if one of the arguments is not an
   integer, or when the `divisor` is `0`.
 
-  `Integer.floor_div/2` performs *floored* integer division. This means that
-  the result is always rounded towards negative infinity.
+  This function performs a *floored* integer division, which means that
+  the result will always be rounded towards negative infinity.
 
   If you want to perform truncated integer division (rounding towards zero),
   use `Kernel.div/2` instead.
@@ -318,12 +312,12 @@ defmodule Integer do
 
   defp count_digits_nosign(<<_::bits>>, _, count), do: count
 
-  # TODO: Remove Integer.to_string/1 once the minimum supported version is
-  #       Erlang/OTP 22, since it is covered by the now BIF Integer.to_string/2.
-  #       Please reapply commit 2622fd6b0aa419a983a899a1fbdb5deefba3d85d.
   @doc """
   Returns a binary which corresponds to the text representation
-  of `integer`.
+  of `integer` in the given `base`.
+
+  `base` can be an integer between 2 and 36. If no `base` is given,
+  it defaults to `10`.
 
   Inlined by the compiler.
 
@@ -341,22 +335,6 @@ defmodule Integer do
       iex> Integer.to_string(0123)
       "123"
 
-  """
-  @spec to_string(integer) :: String.t()
-  def to_string(integer) do
-    :erlang.integer_to_binary(integer)
-  end
-
-  @doc """
-  Returns a binary which corresponds to the text representation
-  of `integer` in the given `base`.
-
-  `base` can be an integer between 2 and 36.
-
-  Inlined by the compiler.
-
-  ## Examples
-
       iex> Integer.to_string(100, 16)
       "64"
 
@@ -368,15 +346,16 @@ defmodule Integer do
 
   """
   @spec to_string(integer, 2..36) :: String.t()
-  def to_string(integer, base) do
+  def to_string(integer, base \\ 10) do
     :erlang.integer_to_binary(integer, base)
   end
 
-  # TODO: Remove Integer.to_charlist/1 once the minimum supported version is
-  #       Erlang/OTP 22, since it is covered by the now BIF Integer.to_charlist/2.
-  #       Please reapply commit 2622fd6b0aa419a983a899a1fbdb5deefba3d85d.
   @doc """
-  Returns a charlist which corresponds to the text representation of the given `integer`.
+  Returns a charlist which corresponds to the text representation
+  of `integer` in the given `base`.
+
+  `base` can be an integer between 2 and 36. If no `base` is given,
+  it defaults to `10`.
 
   Inlined by the compiler.
 
@@ -394,21 +373,6 @@ defmodule Integer do
       iex> Integer.to_charlist(0123)
       '123'
 
-  """
-  @spec to_charlist(integer) :: charlist
-  def to_charlist(integer) do
-    :erlang.integer_to_list(integer)
-  end
-
-  @doc """
-  Returns a charlist which corresponds to the text representation of `integer` in the given `base`.
-
-  `base` can be an integer between 2 and 36.
-
-  Inlined by the compiler.
-
-  ## Examples
-
       iex> Integer.to_charlist(100, 16)
       '64'
 
@@ -420,7 +384,7 @@ defmodule Integer do
 
   """
   @spec to_charlist(integer, 2..36) :: charlist
-  def to_charlist(integer, base) do
+  def to_charlist(integer, base \\ 10) do
     :erlang.integer_to_list(integer, base)
   end
 
@@ -466,7 +430,7 @@ defmodule Integer do
   @doc """
   Returns the extended greatest common divisor of the two given integers.
 
-  It uses the Extended Euclidean algorithm to return a three-element tuple with the `gcd`
+  This function uses the extended Euclidean algorithm to return a three-element tuple with the `gcd`
   and the coefficients `m` and `n` of Bézout's identity such that:
 
       gcd(a, b) = m*a + n*b
@@ -498,8 +462,8 @@ defmodule Integer do
   @doc since: "1.12.0"
   @spec extended_gcd(integer, integer) :: {non_neg_integer, integer, integer}
   def extended_gcd(0, 0), do: {0, 0, 0}
-  def extended_gcd(0, n), do: {n, 0, 1}
-  def extended_gcd(n, 0), do: {n, 1, 0}
+  def extended_gcd(0, b), do: {b, 0, 1}
+  def extended_gcd(a, 0), do: {a, 1, 0}
 
   def extended_gcd(integer1, integer2) when is_integer(integer1) and is_integer(integer2) do
     extended_gcd(integer2, integer1, 0, 1, 1, 0)

lib/elixir/lib/io.ex

@@ -122,14 +122,14 @@ defmodule IO do
   @type nodata :: {:error, term} | :eof
   @type chardata :: String.t() | maybe_improper_list(char | chardata, String.t() | [])
 
+  defguardp is_device(term) when is_atom(term) or is_pid(term)
   defguardp is_iodata(data) when is_list(data) or is_binary(data)
 
   @doc """
   Reads from the IO `device`.
 
-  The `device` is iterated by the given number of characters or line by line if
-  `:line` is given.
-  Alternatively, if `:all` is given, then whole `device` is returned.
+  The `device` is iterated by the given number of characters, line by line if
+  `:line` is given, or until `:eof`.
 
   It returns:
 
@@ -141,14 +141,24 @@ defmodule IO do
       for instance, `{:error, :estale}` if reading from an
       NFS volume
 
-  If `:all` is given, `:eof` is never returned, but an
-  empty string in case the device has reached EOF.
   """
-  @spec read(device, :all | :line | non_neg_integer) :: chardata | nodata
+  @spec read(device, :eof | :line | non_neg_integer) :: chardata | nodata
   def read(device \\ :stdio, line_or_chars)
 
+  # TODO: Deprecate me on v1.17
   def read(device, :all) do
-    do_read_all(map_dev(device), :empty)
+    with :eof <- read(device, :eof) do
+      with [_ | _] = opts <- :io.getopts(device),
+           false <- Keyword.get(opts, :binary, true) do
+        ''
+      else
+        _ -> ""
+      end
+    end
+  end
+
+  def read(device, :eof) do
+    getn(device, '', :eof)
   end
 
   def read(device, :line) do
@@ -159,35 +169,11 @@ defmodule IO do
     :io.get_chars(map_dev(device), '', count)
   end
 
-  defp do_read_all(mapped_dev, acc) do
-    case :io.get_line(mapped_dev, "") do
-      line when is_binary(line) or is_list(line) -> do_read_all(mapped_dev, concat(acc, line))
-      :eof -> read_eof(mapped_dev, acc)
-      other -> other
-    end
-  end
-
-  defp concat(:empty, line), do: line
-  defp concat(acc, line) when is_binary(acc), do: acc <> line
-  defp concat(acc, line) when is_list(acc), do: acc ++ line
-
-  defp read_eof(device, :empty) do
-    with [_ | _] = opts <- :io.getopts(device),
-         false <- Keyword.get(opts, :binary, true) do
-      ''
-    else
-      _ -> ""
-    end
-  end
-
-  defp read_eof(_device, acc), do: acc
-
   @doc """
   Reads from the IO `device`. The operation is Unicode unsafe.
 
-  The `device` is iterated by the given number of bytes or line by line if
-  `:line` is given.
-  Alternatively, if `:all` is given, then whole `device` is returned.
+  The `device` is iterated by the given number of bytes, line by line if
+  `:line` is given, or until `:eof`.
 
   It returns:
 
@@ -199,17 +185,19 @@ defmodule IO do
       for instance, `{:error, :estale}` if reading from an
       NFS volume
 
-  If `:all` is given, `:eof` is never returned, but an
-  empty string in case the device has reached EOF.
-
   Note: do not use this function on IO devices in Unicode mode
   as it will return the wrong result.
   """
-  @spec binread(device, :all | :line | non_neg_integer) :: iodata | nodata
+  @spec binread(device, :eof | :line | non_neg_integer) :: iodata | nodata
   def binread(device \\ :stdio, line_or_chars)
 
+  # TODO: Deprecate me on v1.17
   def binread(device, :all) do
-    do_binread_all(map_dev(device), "")
+    with :eof <- binread(device, :eof), do: ""
+  end
+
+  def binread(device, :eof) do
+    binread_eof(map_dev(device), "")
   end
 
   def binread(device, :line) do
@@ -227,10 +215,10 @@ defmodule IO do
   end
 
   @read_all_size 4096
-  defp do_binread_all(mapped_dev, acc) do
+  defp binread_eof(mapped_dev, acc) do
     case :file.read(mapped_dev, @read_all_size) do
-      {:ok, data} -> do_binread_all(mapped_dev, acc <> data)
-      :eof -> acc
+      {:ok, data} -> binread_eof(mapped_dev, acc <> data)
+      :eof -> if acc == "", do: :eof, else: acc
       other -> other
     end
   end
@@ -293,7 +281,7 @@ defmodule IO do
 
   """
   @spec puts(device, chardata | String.Chars.t()) :: :ok
-  def puts(device \\ :stdio, item) do
+  def puts(device \\ :stdio, item) when is_device(device) do
     :io.put_chars(map_dev(device), [to_chardata(item), ?\n])
   end
 
@@ -317,7 +305,7 @@ defmodule IO do
   @spec warn(chardata | String.Chars.t(), Exception.stacktrace()) :: :ok
   def warn(message, []) do
     message = [to_chardata(message), ?\n]
-    :elixir_errors.io_warn(0, nil, message, message)
+    :elixir_errors.log_and_print_warning(0, nil, message, message)
   end
 
   def warn(message, [{_, _, _, opts} | _] = stacktrace) do
@@ -326,7 +314,7 @@ defmodule IO do
     line = opts[:line]
     file = opts[:file]
 
-    :elixir_errors.io_warn(
+    :elixir_errors.log_and_print_warning(
       line || 0,
       file && List.to_string(file),
       message,
@@ -428,9 +416,9 @@ defmodule IO do
   See `inspect/2` for a full list of options.
   """
   @spec inspect(device, item, keyword) :: item when item: var
-  def inspect(device, item, opts) when is_list(opts) do
+  def inspect(device, item, opts) when is_device(device) and is_list(opts) do
     label = if label = opts[:label], do: [to_chardata(label), ": "], else: []
-    opts = struct(Inspect.Opts, opts)
+    opts = Inspect.Opts.new(opts)
     doc = Inspect.Algebra.group(Inspect.Algebra.to_doc(item, opts))
     chardata = Inspect.Algebra.format(doc, opts.width)
     puts(device, [label, chardata])
@@ -445,12 +433,18 @@ defmodule IO do
   Otherwise, `count` is the number of raw bytes to be retrieved.
 
   See `IO.getn/3` for a description of return values.
-
   """
-  @spec getn(device | chardata | String.Chars.t(), pos_integer | chardata | String.Chars.t()) ::
+  @spec getn(
+          device | chardata | String.Chars.t(),
+          pos_integer | :eof | chardata | String.Chars.t()
+        ) ::
           chardata | nodata
   def getn(prompt, count \\ 1)
 
+  def getn(prompt, :eof) do
+    getn(:stdio, prompt, :eof)
+  end
+
   def getn(prompt, count) when is_integer(count) and count > 0 do
     getn(:stdio, prompt, count)
   end
@@ -477,11 +471,27 @@ defmodule IO do
       NFS volume
 
   """
-  @spec getn(device, chardata | String.Chars.t(), pos_integer) :: chardata | nodata
+  @spec getn(device, chardata | String.Chars.t(), pos_integer | :eof) :: chardata | nodata
+  def getn(device, prompt, :eof) do
+    getn_eof(map_dev(device), to_chardata(prompt), [])
+  end
+
   def getn(device, prompt, count) when is_integer(count) and count > 0 do
     :io.get_chars(map_dev(device), to_chardata(prompt), count)
   end
 
+  defp getn_eof(device, prompt, acc) do
+    case :io.get_line(device, prompt) do
+      line when is_binary(line) or is_list(line) -> getn_eof(device, '', [line | acc])
+      :eof -> wrap_eof(:lists.reverse(acc))
+      other -> other
+    end
+  end
+
+  defp wrap_eof([h | _] = acc) when is_binary(h), do: IO.iodata_to_binary(acc)
+  defp wrap_eof([h | _] = acc) when is_list(h), do: :lists.flatten(acc)
+  defp wrap_eof([]), do: :eof
+
   @doc ~S"""
   Reads a line from the IO `device`.
 
@@ -508,6 +518,17 @@ defmodule IO do
     :io.get_line(map_dev(device), to_chardata(prompt))
   end
 
+  @doc """
+  Returns a line-based `IO.Stream` on `:stdio`.
+
+  This is equivalent to:
+
+      IO.stream(:stdio, :line)
+
+  """
+  @doc since: "1.12.0"
+  def stream, do: stream(:stdio, :line)
+
   @doc """
   Converts the IO `device` into an `IO.Stream`.
 
@@ -524,6 +545,9 @@ defmodule IO do
   Note that an IO stream has side effects and every time
   you go over the stream you may get different results.
 
+  `stream/1` has been introduced in Elixir v1.12.0,
+  while `stream/2` has been available since v1.0.0.
+
   ## Examples
 
   Here is an example on how we mimic an echo server
@@ -533,12 +557,23 @@ defmodule IO do
 
   """
   @spec stream(device, :line | pos_integer) :: Enumerable.t()
-  def stream(device, line_or_codepoints)
+  def stream(device \\ :stdio, line_or_codepoints)
       when line_or_codepoints == :line
       when is_integer(line_or_codepoints) and line_or_codepoints > 0 do
     IO.Stream.__build__(map_dev(device), false, line_or_codepoints)
   end
 
+  @doc """
+  Returns a raw, line-based `IO.Stream` on `:stdio`. The operation is Unicode unsafe.
+
+  This is equivalent to:
+
+      IO.binstream(:stdio, :line)
+
+  """
+  @doc since: "1.12.0"
+  def binstream, do: binstream(:stdio, :line)
+
   @doc """
   Converts the IO `device` into an `IO.Stream`. The operation is Unicode unsafe.
 
@@ -547,8 +582,7 @@ defmodule IO do
   and write.
 
   The `device` is iterated by the given number of bytes or line by line if
-  `:line` is given.
-  This reads from the IO device as a raw binary.
+  `:line` is given. This reads from the IO device as a raw binary.
 
   Note that an IO stream has side effects and every time
   you go over the stream you may get different results.
@@ -556,9 +590,11 @@ defmodule IO do
   Finally, do not use this function on IO devices in Unicode
   mode as it will return the wrong result.
 
+  `binstream/1` has been introduced in Elixir v1.12.0,
+  while `binstream/2` has been available since v1.0.0.
   """
   @spec binstream(device, :line | pos_integer) :: Enumerable.t()
-  def binstream(device, line_or_bytes)
+  def binstream(device \\ :stdio, line_or_bytes)
       when line_or_bytes == :line
       when is_integer(line_or_bytes) and line_or_bytes > 0 do
     IO.Stream.__build__(map_dev(device), true, line_or_bytes)
@@ -586,6 +622,8 @@ defmodule IO do
 
   """
   @spec chardata_to_string(chardata) :: String.t()
+  def chardata_to_string(chardata)
+
   def chardata_to_string(string) when is_binary(string) do
     string
   end

lib/elixir/lib/io/ansi/docs.ex

@@ -194,6 +194,10 @@ defmodule IO.ANSI.Docs do
     inline_text("*", traverse_erlang_html(entries, indent, options), options)
   end
 
+  defp traverse_erlang_html({tag, _, entries}, indent, options) when tag in [:strong, :b] do
+    inline_text("**", traverse_erlang_html(entries, indent, options), options)
+  end
+
   defp traverse_erlang_html({:code, _, entries}, indent, options) do
     inline_text("`", traverse_erlang_html(entries, indent, options), options)
   end
@@ -295,7 +299,7 @@ defmodule IO.ANSI.Docs do
   end
 
   defp inline_html?(binary) when is_binary(binary), do: true
-  defp inline_html?({tag, _, _}) when tag in [:a, :code, :em, :i, :br], do: true
+  defp inline_html?({tag, _, _}) when tag in [:a, :code, :em, :i, :strong, :b, :br], do: true
   defp inline_html?(_), do: false
 
   ## Markdown
@@ -798,14 +802,14 @@ defmodule IO.ANSI.Docs do
     Regex.replace(~r{\[([^\]]*?)\]\((.*?)\)}, text, "\\1 (\\2)")
   end
 
-  # We have four entries: **, *, _ and `.
+  # We have four entries: **, __, *, _ and `.
   #
-  # The first three behave the same while the last one is simpler
+  # The first four behave the same while the last one is simpler
   # when it comes to delimiters as it ignores spaces and escape
-  # characters. But, since the first has two characters, we need to
-  # handle 3 cases:
+  # characters. But, since the first two has two characters,
+  # we need to handle 3 cases:
   #
-  # 1. **
+  # 1. __ and **
   # 2. _ and *
   # 3. `
   #
@@ -819,8 +823,8 @@ defmodule IO.ANSI.Docs do
 
   ### Inline start
 
-  defp handle_inline(<<?*, ?*, rest::binary>>, options) do
-    handle_inline(rest, ?d, ["**"], [], options)
+  defp handle_inline(<<mark, mark, rest::binary>>, options) when mark in @single do
+    handle_inline(rest, [mark | mark], [<<mark, mark>>], [], options)
   end
 
   defp handle_inline(<<mark, rest::binary>>, options) when mark in @single do
@@ -833,9 +837,10 @@ defmodule IO.ANSI.Docs do
 
   ### Inline delimiters
 
-  defp handle_inline(<<delimiter, ?*, ?*, rest::binary>>, nil, buffer, acc, options)
-       when rest != "" and delimiter in @delimiters do
-    handle_inline(rest, ?d, ["**"], [delimiter, Enum.reverse(buffer) | acc], options)
+  defp handle_inline(<<delimiter, mark, mark, rest::binary>>, nil, buffer, acc, options)
+       when rest != "" and delimiter in @delimiters and mark in @single do
+    acc = [delimiter, Enum.reverse(buffer) | acc]
+    handle_inline(rest, [mark | mark], [<<mark, mark>>], acc, options)
   end
 
   defp handle_inline(<<delimiter, mark, rest::binary>>, nil, buffer, acc, options)
@@ -850,9 +855,10 @@ defmodule IO.ANSI.Docs do
 
   ### Clauses for handling escape
 
-  defp handle_inline(<<?\\, ?\\, ?*, ?*, rest::binary>>, nil, buffer, acc, options)
-       when rest != "" do
-    handle_inline(rest, ?d, ["**"], [?\\, Enum.reverse(buffer) | acc], options)
+  defp handle_inline(<<?\\, ?\\, mark, mark, rest::binary>>, nil, buffer, acc, options)
+       when rest != "" and mark in @single do
+    acc = [?\\, Enum.reverse(buffer) | acc]
+    handle_inline(rest, [mark | mark], [<<mark, mark>>], acc, options)
   end
 
   defp handle_inline(<<?\\, ?\\, mark, rest::binary>>, nil, buffer, acc, options)
@@ -871,8 +877,8 @@ defmodule IO.ANSI.Docs do
 
   ### Inline end
 
-  defp handle_inline(<<?*, ?*, delimiter, rest::binary>>, ?d, buffer, acc, options)
-       when delimiter in @delimiters do
+  defp handle_inline(<<mark, mark, delimiter, rest::binary>>, [mark | mark], buffer, acc, options)
+       when delimiter in @delimiters and mark in @single do
     inline_buffer = inline_buffer(buffer, options)
     handle_inline(<<delimiter, rest::binary>>, nil, [], [inline_buffer | acc], options)
   end
@@ -883,8 +889,8 @@ defmodule IO.ANSI.Docs do
     handle_inline(<<delimiter, rest::binary>>, nil, [], [inline_buffer | acc], options)
   end
 
-  defp handle_inline(<<?*, ?*, rest::binary>>, ?d, buffer, acc, options)
-       when rest == "" do
+  defp handle_inline(<<mark, mark, rest::binary>>, [mark | mark], buffer, acc, options)
+       when rest == "" and mark in @single do
     handle_inline(<<>>, nil, [], [inline_buffer(buffer, options) | acc], options)
   end
 
@@ -930,10 +936,11 @@ defmodule IO.ANSI.Docs do
 
   defp color_for(mark, colors) do
     case mark do
-      "`" -> color(:doc_inline_code, colors)
-      "_" -> color(:doc_underline, colors)
-      "*" -> color(:doc_bold, colors)
+      "__" -> color(:doc_bold, colors)
       "**" -> color(:doc_bold, colors)
+      "_" -> color(:doc_underline, colors)
+      "*" -> color(:doc_underline, colors)
+      "`" -> color(:doc_inline_code, colors)
     end
   end
 

lib/elixir/lib/kernel.ex

@@ -305,6 +305,8 @@ defmodule Kernel do
   prefer `module.function(arg_1, arg_2, ..., arg_n)` as it is clearer than
   `apply(module, :function, [arg_1, arg_2, ..., arg_n])`.
 
+  `apply/3` cannot be used to call private functions.
+
   Inlined by the compiler.
 
   ## Examples
@@ -540,7 +542,7 @@ defmodule Kernel do
 
   Giving it an empty list raises:
 
-      tl([])
+      hd([])
       #=> ** (ArgumentError) argument error
 
   """
@@ -554,6 +556,21 @@ defmodule Kernel do
   Returns `true` if `term` is an atom; otherwise returns `false`.
 
   Allowed in guard tests. Inlined by the compiler.
+
+  ## Examples
+
+      iex> is_atom(false)
+      true
+
+      iex> is_atom(:name)
+      true
+
+      iex> is_atom(AnAtom)
+      true
+
+      iex> is_atom("true")
+      false
+
   """
   @doc guard: true
   @spec is_atom(term) :: boolean
@@ -606,6 +623,18 @@ defmodule Kernel do
   a boolean); otherwise returns `false`.
 
   Allowed in guard tests. Inlined by the compiler.
+
+  ## Examples
+
+      iex> is_boolean(false)
+      true
+
+      iex> is_boolean(true)
+      true
+
+      iex> is_boolean(:test)
+      false
+
   """
   @doc guard: true
   @spec is_boolean(term) :: boolean
@@ -628,6 +657,15 @@ defmodule Kernel do
   Returns `true` if `term` is a function; otherwise returns `false`.
 
   Allowed in guard tests. Inlined by the compiler.
+
+  ## Examples
+
+      iex> is_function(fn x -> x + x end)
+      true
+
+      iex> is_function("not a function")
+      false
+
   """
   @doc guard: true
   @spec is_function(term) :: boolean
@@ -1159,7 +1197,7 @@ defmodule Kernel do
   @doc since: "1.12.0"
   defmacro tap(value, fun) do
     quote bind_quoted: [fun: fun, value: value] do
-      fun.(value)
+      _ = fun.(value)
       value
     end
   end
@@ -1420,18 +1458,11 @@ defmodule Kernel do
   end
 
   @doc """
-  List subtraction operator. Removes the first occurrence of an element on the left list
-  for each element on the right.
+  List subtraction operator. Removes the first occurrence of an element
+  on the left list for each element on the right.
 
-  Before Erlang/OTP 22, the complexity of `a -- b` was proportional to
-  `length(a) * length(b)`, meaning that it would be very slow if
-  both `a` and `b` were long lists. In such cases, consider
-  converting each list to a `MapSet` and using `MapSet.difference/2`.
-
-  As of Erlang/OTP 22, this operation is significantly faster even if both
-  lists are very long, and using `--/2` is usually faster and uses less
-  memory than using the `MapSet`-based alternative mentioned above.
-  See also the [Erlang efficiency
+  This function is optimized so the complexity of `a -- b` is proportional
+  to `length(a) * log(length(b))`. See also the [Erlang efficiency
   guide](https://erlang.org/doc/efficiency_guide/retired_myths.html).
 
   Inlined by the compiler.
@@ -1854,6 +1885,8 @@ defmodule Kernel do
   @doc """
   Binary concatenation operator. Concatenates two binaries.
 
+  Raises an `ArgumentError` if one of the sides aren't binaries.
+
   ## Examples
 
       iex> "foo" <> "bar"
@@ -1866,7 +1899,7 @@ defmodule Kernel do
       iex> x
       "bar"
 
-  `x <> "bar" = "foobar"` would have resulted in a `CompileError` exception.
+  `x <> "bar" = "foobar"` would result in an `ArgumentError` exception.
 
   """
   defmacro left <> right do
@@ -1970,26 +2003,35 @@ defmodule Kernel do
         false -> message
       end
 
+    erlang_error =
+      case :erlang.system_info(:otp_release) >= '24' do
+        true ->
+          fn x ->
+            quote do
+              :erlang.error(unquote(x), :none, error_info: %{module: Exception})
+            end
+          end
+
+        false ->
+          fn x ->
+            quote do
+              :erlang.error(unquote(x))
+            end
+          end
+      end
+
     case message do
       message when is_binary(message) ->
-        quote do
-          :erlang.error(RuntimeError.exception(unquote(message)))
-        end
+        erlang_error.(quote do: RuntimeError.exception(unquote(message)))
 
       {:<<>>, _, _} = message ->
-        quote do
-          :erlang.error(RuntimeError.exception(unquote(message)))
-        end
+        erlang_error.(quote do: RuntimeError.exception(unquote(message)))
 
       alias when is_atom(alias) ->
-        quote do
-          :erlang.error(unquote(alias).exception([]))
-        end
+        erlang_error.(quote do: unquote(alias).exception([]))
 
       _ ->
-        quote do
-          :erlang.error(Kernel.Utils.raise(unquote(message)))
-        end
+        erlang_error.(quote do: Kernel.Utils.raise(unquote(message)))
     end
   end
 
@@ -2123,6 +2165,7 @@ defmodule Kernel do
       iex> "abcd" =~ ""
       true
 
+  For more information about regular expressions, please check the `Regex` module.
   """
   @spec String.t() =~ (String.t() | Regex.t()) :: boolean
   def left =~ "" when is_binary(left), do: true
@@ -2192,7 +2235,7 @@ defmodule Kernel do
   """
   @spec inspect(Inspect.t(), keyword) :: String.t()
   def inspect(term, opts \\ []) when is_list(opts) do
-    opts = struct(Inspect.Opts, opts)
+    opts = Inspect.Opts.new(opts)
 
     limit =
       case opts.pretty do
@@ -2506,6 +2549,9 @@ defmodule Kernel do
 
       iex> 1 |> then(fn x -> x * 2 end)
       2
+
+      iex> 1 |> then(fn x -> Enum.drop(["a", "b", "c"], x) end)
+      ["b", "c"]
   """
   @doc since: "1.12.0"
   defmacro then(value, fun) do
@@ -2527,47 +2573,66 @@ defmodule Kernel do
       iex> get_in(users, ["john", :age])
       27
 
-  In case any of the keys returns `nil`, `nil` will be returned:
+  `get_in/2` can also use the accessors in the `Access` module
+  to traverse more complex data structures. For example, here we
+  use `Access.all/0` to traverse a list:
+
+      iex> users = [%{name: "john", age: 27}, %{name: "meg", age: 23}]
+      iex> get_in(users, [Access.all(), :age])
+      [27, 23]
+
+  In case any of the components returns `nil`, `nil` will be returned
+  and `get_in/2` won't traverse any futher:
 
       iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
       iex> get_in(users, ["unknown", :age])
       nil
 
-  Note that `get_in` exists mostly for convenience and parity with
-  functionality found in `put_in` and `update_in`. Given Elixir
-  provides pattern matching, it can often be more expressive for
-  deep data traversal, for example:
+      iex> users = nil
+      iex> get_in(users, [Access.all(), :age])
+      nil
+
+  The main feature of `get_in/2` is precisely that it aborts traversal
+  when a `nil` value is found. Unless you need nil-safety, you are likely
+  better off by writing "regular" Elixir code:
+
+      iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
+      iex> users["john"][:age]
+      27
+
+      iex> users = [%{name: "john", age: 27}, %{name: "meg", age: 23}]
+      iex> Enum.map(users, fn user -> user[:age] end)
+      [27, 23]
+
+  Alternatively, if you need to access complex data-structures, you can
+  use pattern matching:
 
       case users do
-        %{"unknown" => %{age: age}} -> age
+        %{"john" => %{age: age}} -> age
         _ -> default_value
       end
 
   ## Functions as keys
 
-  If a key is a function, the function will be invoked passing three
-  arguments:
+  If a key given to `get_in/2` is a function, the function will be invoked
+  passing three arguments:
 
     * the operation (`:get`)
     * the data to be accessed
     * a function to be invoked next
 
   This means `get_in/2` can be extended to provide custom lookups.
-  In the example below, we use a function to get all the maps inside
-  a list:
+  That's precisely how the `Access.all/0` key in the previous section
+  behaves. For example, we can manually implement such traversal as
+  follows:
 
       iex> users = [%{name: "john", age: 27}, %{name: "meg", age: 23}]
       iex> all = fn :get, data, next -> Enum.map(data, next) end
       iex> get_in(users, [all, :age])
       [27, 23]
 
-  If the previous value before invoking the function is `nil`,
-  the function *will* receive `nil` as a value and must handle it
-  accordingly.
-
-  The `Access` module ships with many convenience accessor functions,
-  like the `all` anonymous function defined above. See `Access.all/0`,
-  `Access.key/2`, and others as examples.
+  The `Access` module ships with many convenience accessor functions.
+  See `Access.all/0`, `Access.key/2`, and others as examples.
 
   ## Working with structs
 
@@ -2593,12 +2658,11 @@ defmodule Kernel do
   @spec get_in(Access.t(), nonempty_list(term)) :: term
   def get_in(data, keys)
 
+  def get_in(nil, [_ | _]), do: nil
+
   def get_in(data, [h]) when is_function(h), do: h.(:get, data, & &1)
   def get_in(data, [h | t]) when is_function(h), do: h.(:get, data, &get_in(&1, t))
 
-  def get_in(nil, [_]), do: nil
-  def get_in(nil, [_ | t]), do: get_in(nil, t)
-
   def get_in(data, [h]), do: Access.get(data, h)
   def get_in(data, [h | t]), do: get_in(Access.get(data, h), t)
 
@@ -2616,8 +2680,12 @@ defmodule Kernel do
       iex> put_in(users, ["john", :age], 28)
       %{"john" => %{age: 28}, "meg" => %{age: 23}}
 
-  In case any of the entries in the middle returns `nil`,
-  an error will be raised when trying to access it next.
+  If any of the intermediate values are nil, it will raise:
+
+      iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
+      iex> put_in(users, ["jane", :age], "oops")
+      ** (ArgumentError) could not put/update key :age on a nil value
+
   """
   @spec put_in(Access.t(), nonempty_list(term), term) :: Access.t()
   def put_in(data, [_ | _] = keys, value) do
@@ -2644,8 +2712,13 @@ defmodule Kernel do
       iex> update_in(users, ["john", :age], &(&1 + 1))
       %{"john" => %{age: 28}, "meg" => %{age: 23}}
 
-  In case any of the entries in the middle returns `nil`,
-  an error will be raised when trying to access it next.
+  Note the current value given to the anonymous function may be `nil`.
+  If any of the intermediate values are nil, it will raise:
+
+      iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
+      iex> update_in(users, ["jane", :age], & &1 + 1)
+      ** (ArgumentError) could not put/update key :age on a nil value
+
   """
   @spec update_in(Access.t(), nonempty_list(term), (term -> term)) :: Access.t()
   def update_in(data, [_ | _] = keys, fun) when is_function(fun) do
@@ -2683,6 +2756,13 @@ defmodule Kernel do
       iex> get_and_update_in(users, ["john", :age], &{&1, &1 + 1})
       {27, %{"john" => %{age: 28}, "meg" => %{age: 23}}}
 
+  Note the current value given to the anonymous function may be `nil`.
+  If any of the intermediate values are nil, it will raise:
+
+      iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
+      iex> get_and_update_in(users, ["jane", :age], &{&1, &1 + 1})
+      ** (ArgumentError) could not put/update key :age on a nil value
+
   ## Functions as keys
 
   If a key is a function, the function will be invoked passing three
@@ -3168,6 +3248,24 @@ defmodule Kernel do
       iex> binding()
       []
 
+  Furthermore, remember the pin operator matches _values_, not _patterns_:
+
+      match?(%{x: 1}, %{x: 1, y: 2})
+      #=> true
+
+      attrs = %{x: 1}
+      match?(^attrs, %{x: 1, y: 2})
+      #=> false
+
+  The pin operator will check if the values are equal, using `===/2`, while
+  patterns have their own rules when matching maps, lists, and so forth.
+  Such behaviour is not specific to `match?/2`. The following code also
+  throws an exception:
+
+      attrs = %{x: 1}
+      ^attrs = %{x: 1, y: 2}
+      #=> (MatchError) no match of right hand side value: %{x: 1, y: 2}
+
   """
   defmacro match?(pattern, expr) do
     success =
@@ -3210,6 +3308,10 @@ defmodule Kernel do
   will be available at compile-time. Custom attributes may be configured to
   behave closer to Erlang by using `Module.register_attribute/3`.
 
+  > **Important:** Libraries and frameworks should consider prefixing any
+  > module attributes that are private by underscore, such as `@_my_data`
+  > so code completion tools do not show them on suggestions and prompts.
+
   Finally, note that attributes can also be read inside functions:
 
       defmodule MyServer do
@@ -3230,11 +3332,39 @@ defmodule Kernel do
   time and not at runtime. Check the `Module` module for other functions
   to manipulate module attributes.
 
-  ## Compile-time considerations
+  ## Attention! Multiple references of the same attribute
 
-  One thing to keep in mind is that references to other modules, even
-  in module attributes, generate compile-time dependencies to said
-  modules.
+  As mentioned above, every time you read a module attribute, a snapshot
+  of its current value is taken. Therefore, if you are storing large
+  values inside module attributes (for example, embedding external files
+  in module attributes), you should avoid referencing the same attribute
+  multiple times. For example, don't do this:
+
+      @files %{
+        example1: File.read!("lib/example1.data"),
+        example2: File.read!("lib/example2.data")
+      }
+
+      def example1, do: @files[:example1]
+      def example2, do: @files[:example2]
+
+  In the above, each reference to `@files` may end-up with a complete
+  and individual copy of the whole `@files` module attribute. Instead,
+  reference the module attribute once in a private function:
+
+      @files %{
+        example1: File.read!("lib/example1.data"),
+        example2: File.read!("lib/example2.data")
+      }
+
+      defp files(), do: @files
+      def example1, do: files()[:example1]
+      def example2, do: files()[:example2]
+
+  ## Attention! Compile-time dependencies
+
+  Keep in mind references to other modules, even in module attributes,
+  generate compile-time dependencies to said modules.
 
   For example, take this common pattern:
 
@@ -3373,7 +3503,7 @@ defmodule Kernel do
           end
 
         try do
-          :elixir_quote.escape(value, :default, false)
+          :elixir_quote.escape(value, :none, false)
         rescue
           ex in [ArgumentError] ->
             raise ArgumentError,
@@ -3517,7 +3647,7 @@ defmodule Kernel do
         bar
       end
 
-  Note that `do/end` become delimiters. The second example would
+  Note that `do`-`end` become delimiters. The second example would
   translate to:
 
       if foo do
@@ -3673,7 +3803,7 @@ defmodule Kernel do
   end
 
   defp range(_context, first, last) when is_integer(first) and is_integer(last) do
-    # TODO: Deprecate inferring a range with step of -1 on Elixir v1.17
+    # TODO: Deprecate inferring a range with a step of -1 on Elixir v1.17
     step = if first <= last, do: 1, else: -1
     {:%{}, [], [__struct__: Elixir.Range, first: first, last: last, step: step]}
   end
@@ -3755,7 +3885,7 @@ defmodule Kernel do
   defp validate_step!(step)
        when is_float(step) or is_atom(step) or is_binary(step) or is_list(step) or step == 0 do
     raise ArgumentError,
-          "ranges (first..last//step) expect the step to be an integer different than zero, " <>
+          "ranges (first..last//step) expect the step to be a non-zero integer, " <>
             "got: #{Macro.to_string(step)}"
   end
 
@@ -3975,6 +4105,51 @@ defmodule Kernel do
       :lists.member({macro, arity}, module.__info__(:macros))
   end
 
+  @doc """
+  Power operator.
+
+  It expects two numbers are input. If the left-hand side is an integer
+  and the right-hand side is more than or equal to 0, then the result is
+  integer. Otherwise it returns a float.
+
+  ## Examples
+
+      iex> 2 ** 2
+      4
+      iex> 2 ** -4
+      0.0625
+
+      iex> 2.0 ** 2
+      4.0
+      iex> 2 ** 2.0
+      4.0
+
+  """
+  @doc since: "1.13.0"
+  @spec integer ** non_neg_integer :: integer
+  @spec integer ** neg_integer :: float
+  @spec float ** float :: float
+  def base ** exponent when is_integer(base) and is_integer(exponent) and exponent >= 0 do
+    integer_pow(base, 1, exponent)
+  end
+
+  def base ** exponent when is_number(base) and is_number(exponent) do
+    :math.pow(base, exponent)
+  end
+
+  # https://en.wikipedia.org/wiki/Exponentiation_by_squaring
+  defp integer_pow(_, _, 0),
+    do: 1
+
+  defp integer_pow(b, a, 1),
+    do: b * a
+
+  defp integer_pow(b, a, e) when :erlang.band(e, 1) == 0,
+    do: integer_pow(b * b, a, :erlang.bsr(e, 1))
+
+  defp integer_pow(b, a, e),
+    do: integer_pow(b * b, a * b, :erlang.bsr(e, 1))
+
   @doc """
   Membership operator. Checks if the element on the left-hand side is a member of the
   collection on the right-hand side.
@@ -4009,15 +4184,9 @@ defmodule Kernel do
 
       when x === 1 or x === 2 or x === 3
 
-  When using ranges:
-
-      when x in 1..3
-
-  translates to:
-
-      when is_integer(x) and x >= 1 and x <= 3
-
-  Note that only integers can be considered inside a range by `in`.
+  However, this construct will be inneficient for large lists. In such cases, it
+  is best to stop using guards and use a more appropriate data structure, such
+  as `MapSet`.
 
   ### AST considerations
 
@@ -4050,22 +4219,12 @@ defmodule Kernel do
           false
         end
 
-      [head | tail] = list when not in_body? ->
-        in_list(left, head, tail, expand, list, in_body?)
-
-      [_ | _] = list when in_body? ->
-        case ensure_evaled(list, {0, []}, expand) do
-          {[head | tail], {_, []}} ->
-            in_var(in_body?, left, &in_list(&1, head, tail, expand, list, in_body?))
-
-          {[head | tail], {_, vars_values}} ->
-            {vars, values} = :lists.unzip(:lists.reverse(vars_values))
-            is_in_list = &in_list(&1, head, tail, expand, list, in_body?)
-
-            quote do
-              {unquote_splicing(vars)} = {unquote_splicing(values)}
-              unquote(in_var(in_body?, left, is_in_list))
-            end
+      [head | tail] = list ->
+        # We only expand lists in the body if they are relatively
+        # short and it is made only of literal expressions.
+        case not in_body? or small_literal_list?(right) do
+          true -> in_var(in_body?, left, &in_list(&1, head, tail, expand, list, in_body?))
+          false -> quote(do: :lists.member(unquote(left), unquote(right)))
         end
 
       {:%{}, _meta, [__struct__: Elixir.Range, first: first, last: last, step: step]} ->
@@ -4102,42 +4261,11 @@ defmodule Kernel do
     end
   end
 
-  # Called as ensure_evaled(list, {0, []}). Note acc is reversed.
-  defp ensure_evaled(list, acc, expand) do
-    fun = fn
-      {:|, meta, [head, tail]}, acc ->
-        {head, acc} = ensure_evaled_element(head, acc)
-        {tail, acc} = ensure_evaled_tail(expand.(tail), acc, expand)
-        {{:|, meta, [head, tail]}, acc}
-
-      elem, acc ->
-        ensure_evaled_element(elem, acc)
-    end
-
-    :lists.mapfoldl(fun, acc, list)
+  defp small_literal_list?(list) when is_list(list) and length(list) <= 32 do
+    :lists.all(fn x -> is_binary(x) or is_atom(x) or is_number(x) end, list)
   end
 
-  defp ensure_evaled_element(elem, acc)
-       when is_number(elem) or is_atom(elem) or is_binary(elem) do
-    {elem, acc}
-  end
-
-  defp ensure_evaled_element(elem, acc) do
-    ensure_evaled_var(elem, acc)
-  end
-
-  defp ensure_evaled_tail(elem, acc, expand) when is_list(elem) do
-    ensure_evaled(elem, acc, expand)
-  end
-
-  defp ensure_evaled_tail(elem, acc, _expand) do
-    ensure_evaled_var(elem, acc)
-  end
-
-  defp ensure_evaled_var(elem, {index, ast}) do
-    var = {String.to_atom("arg" <> Integer.to_string(index + 1)), [], __MODULE__}
-    {var, {index + 1, [{var, elem} | ast]}}
-  end
+  defp small_literal_list?(_list), do: false
 
   defp in_range(left, first, last, nil) do
     # TODO: nil steps are only supported due to x..y in guards. Remove me on Elixir 2.0.
@@ -4284,7 +4412,7 @@ defmodule Kernel do
   defmacro var!({name, meta, atom}, context) when is_atom(name) and is_atom(atom) do
     # Remove counter and force them to be vars
     meta = :lists.keydelete(:counter, 1, meta)
-    meta = :lists.keystore(:var, 1, meta, {:var, true})
+    meta = :lists.keystore(:if_undefined, 1, meta, {:if_undefined, :raise})
 
     case Macro.expand(context, __CALLER__) do
       context when is_atom(context) ->
@@ -4408,19 +4536,13 @@ defmodule Kernel do
 
   defmacro defmodule(alias, do: block) do
     env = __CALLER__
-    boot? = bootstrapped?(Macro)
-
-    expanded =
-      case boot? do
-        true -> Macro.expand(alias, env)
-        false -> alias
-      end
+    expanded = expand_module_alias(alias, env)
 
     {expanded, with_alias} =
-      case boot? and is_atom(expanded) do
+      case is_atom(expanded) do
         true ->
           # Expand the module considering the current environment/nesting
-          {full, old, new} = expand_module(alias, expanded, env)
+          {full, old, new} = alias_defmodule(alias, expanded, env)
           meta = [defined: full, context: env.module] ++ alias_meta(alias)
           {full, {:alias, meta, [old, [as: new, warn: false]]}}
 
@@ -4446,10 +4568,10 @@ defmodule Kernel do
           quote(do: Kernel.LexicalTracker.read_cache(unquote(pid), unquote(integer)))
 
         %{} ->
-          :elixir_quote.escape(block, :default, false)
+          :elixir_quote.escape(block, :none, false)
       end
 
-    module_vars = :lists.map(&module_var/1, :maps.keys(elem(env.current_vars, 0)))
+    module_vars = :lists.map(&module_var/1, :maps.keys(env.versioned_vars))
 
     quote do
       unquote(with_alias)
@@ -4460,16 +4582,34 @@ defmodule Kernel do
   defp alias_meta({:__aliases__, meta, _}), do: meta
   defp alias_meta(_), do: []
 
+  # We don't want to trace :alias_reference since we are defining the alias
+  defp expand_module_alias({:__aliases__, _, _} = original, env) do
+    case :elixir_aliases.expand_or_concat(original, env) do
+      receiver when is_atom(receiver) ->
+        receiver
+
+      aliases ->
+        aliases = :lists.map(&Macro.expand(&1, env), aliases)
+
+        case :lists.all(&is_atom/1, aliases) do
+          true -> :elixir_aliases.concat(aliases)
+          false -> original
+        end
+    end
+  end
+
+  defp expand_module_alias(other, env), do: Macro.expand(other, env)
+
   # defmodule Elixir.Alias
-  defp expand_module({:__aliases__, _, [:"Elixir", _ | _]}, module, _env),
+  defp alias_defmodule({:__aliases__, _, [:"Elixir", _ | _]}, module, _env),
     do: {module, module, nil}
 
   # defmodule Alias in root
-  defp expand_module({:__aliases__, _, _}, module, %{module: nil}),
+  defp alias_defmodule({:__aliases__, _, _}, module, %{module: nil}),
     do: {module, module, nil}
 
   # defmodule Alias nested
-  defp expand_module({:__aliases__, _, [h | t]}, _module, env) when is_atom(h) do
+  defp alias_defmodule({:__aliases__, _, [h | t]}, _module, env) when is_atom(h) do
     module = :elixir_aliases.concat([env.module, h])
     alias = String.to_atom("Elixir." <> Atom.to_string(h))
 
@@ -4480,7 +4620,7 @@ defmodule Kernel do
   end
 
   # defmodule _
-  defp expand_module(_raw, module, _env) do
+  defp alias_defmodule(_raw, module, _env) do
     {module, module, nil}
   end
 
@@ -4555,15 +4695,15 @@ defmodule Kernel do
   Functions containing many arguments can benefit from using `Keyword`
   lists to group and pass attributes as a single value.
 
-     defmodule MyConfiguration do
-       @default_opts [storage: "local"]
+      defmodule MyConfiguration do
+        @default_opts [storage: "local"]
 
-       def configure(resource, opts \\ []) do
-         opts = Keyword.merge(@default_opts, opts)
-         storage = opts[:storage]
-         # ...
-       end
-     end
+        def configure(resource, opts \\ []) do
+          opts = Keyword.merge(@default_opts, opts)
+          storage = opts[:storage]
+          # ...
+        end
+      end
 
   The difference between using `Map` and `Keyword` to store many
   arguments is `Keyword`'s keys:
@@ -4701,12 +4841,12 @@ defmodule Kernel do
 
     unquoted_call = :elixir_quote.has_unquotes(call)
     unquoted_expr = :elixir_quote.has_unquotes(expr)
-    escaped_call = :elixir_quote.escape(call, :default, true)
+    escaped_call = :elixir_quote.escape(call, :none, true)
 
     escaped_expr =
       case unquoted_expr do
         true ->
-          :elixir_quote.escape(expr, :default, true)
+          :elixir_quote.escape(expr, :none, true)
 
         false ->
           key = :erlang.unique_integer()
@@ -4734,13 +4874,13 @@ defmodule Kernel do
 
   A struct is a tagged map that allows developers to provide
   default values for keys, tags to be used in polymorphic
-  dispatches and compile time assertions.
+  dispatches and compile time assertions. For more information
+  about structs, please check `Kernel.SpecialForms.%/2`.
 
-  To define a struct, a developer must define both `__struct__/0` and
-  `__struct__/1` functions. `defstruct/1` is a convenience macro which
-  defines such functions with some conveniences.
-
-  For more information about structs, please check `Kernel.SpecialForms.%/2`.
+  It is only possible to define a struct per module, as the
+  struct it tied to the module itself. Calling `defstruct/1`
+  also defines a `__struct__/0` function that returns the
+  struct itself.
 
   ## Examples
 
@@ -5043,10 +5183,15 @@ defmodule Kernel do
   end
 
   @doc """
-  Makes the given functions in the current module overridable.
+  Makes the given definitions in the current module overridable.
 
-  An overridable function is lazily defined, allowing a developer to override
-  it.
+  If the user defines a new function or macro with the same name
+  and arity, then the overridable ones are discarded. Otherwise, the
+  original definitions are used.
+
+  It is possible for the overridden definition to have a different visibility
+  than the original: a public function can be overridden by a private
+  function and vice-versa.
 
   Macros cannot be overridden as functions and vice-versa.
 
@@ -5554,7 +5699,7 @@ defmodule Kernel do
     quote(do: List.to_charlist(unquote(unescape_list_tokens(pieces))))
   end
 
-  @doc """
+  @doc ~S"""
   Handles the sigil `~r` for regular expressions.
 
   It returns a regular expression pattern, unescaping characters and replacing
@@ -5564,12 +5709,15 @@ defmodule Kernel do
 
   ## Examples
 
-      iex> Regex.match?(~r(foo), "foo")
+      iex> Regex.match?(~r/foo/, "foo")
       true
 
       iex> Regex.match?(~r/a#{:b}c/, "abc")
       true
 
+  While the `~r` sigil allows parens and brackets to be used as delimiters,
+  it is preferred to use `"` or `/` to avoid escaping conflicts with reserved
+  regex characters.
   """
   defmacro sigil_r(term, modifiers)
 
@@ -5872,6 +6020,9 @@ defmodule Kernel do
       iex> ~w(foo bar baz)a
       [:foo, :bar, :baz]
 
+      iex> ~w(foo bar baz)c
+      ['foo', 'bar', 'baz']
+
   """
   defmacro sigil_w(term, modifiers)
 

lib/elixir/lib/kernel/cli.ex

@@ -16,6 +16,8 @@ defmodule Kernel.CLI do
     profile: nil
   }
 
+  @standalone_opts ["-h", "--help", "--short-version"]
+
   @doc """
   This is the API invoked by Elixir boot process.
   """
@@ -88,7 +90,7 @@ defmodule Kernel.CLI do
       case blamed do
         %FunctionClauseError{} ->
           formatted = Exception.format_banner(kind, reason, stacktrace)
-          padded_blame = pad(FunctionClauseError.blame(blamed, &inspect/1, &blame_match/2))
+          padded_blame = pad(FunctionClauseError.blame(blamed, &inspect/1, &blame_match/1))
           [formatted, padded_blame]
 
         _ ->
@@ -176,9 +178,8 @@ defmodule Kernel.CLI do
     IO.write(:stderr, format_error(kind, reason, stacktrace))
   end
 
-  defp blame_match(%{match?: true, node: node}, _), do: blame_ansi(:normal, "+", node)
-  defp blame_match(%{match?: false, node: node}, _), do: blame_ansi(:red, "-", node)
-  defp blame_match(_, string), do: string
+  defp blame_match(%{match?: true, node: node}), do: blame_ansi(:normal, "+", node)
+  defp blame_match(%{match?: false, node: node}), do: blame_ansi(:red, "-", node)
 
   defp blame_ansi(color, no_ansi, node) do
     if IO.ANSI.enabled?() do
@@ -195,8 +196,9 @@ defmodule Kernel.CLI do
   end
 
   @elixir_internals [:elixir, :elixir_aliases, :elixir_expand, :elixir_compiler, :elixir_module] ++
-                      [:elixir_clauses, :elixir_lexical, :elixir_def, :elixir_map] ++
-                      [:elixir_erl, :elixir_erl_clauses, :elixir_erl_pass, Kernel.ErrorHandler]
+                      [:elixir_clauses, :elixir_lexical, :elixir_def, :elixir_map, :elixir_locals] ++
+                      [:elixir_erl, :elixir_erl_clauses, :elixir_erl_compiler, :elixir_erl_pass] ++
+                      [Kernel.ErrorHandler, Module.ParallelChecker]
 
   defp prune_stacktrace([{mod, _, _, _} | t]) when mod in @elixir_internals do
     prune_stacktrace(t)
@@ -216,7 +218,16 @@ defmodule Kernel.CLI do
 
   # Parse shared options
 
-  defp parse_shared([opt | _t], _config) when opt in ["-v", "--version"] do
+  defp warn_standalone(opt) do
+    IO.puts(:stderr, "#{opt} : Standalone options can't be combined with other options")
+  end
+
+  defp parse_shared([opt | _], _config) when opt in @standalone_opts do
+    warn_standalone(opt)
+    System.halt(1)
+  end
+
+  defp parse_shared([opt | t], _config) when opt in ["-v", "--version"] do
     if function_exported?(IEx, :started?, 0) and IEx.started?() do
       IO.puts("IEx " <> System.build_info()[:build])
     else
@@ -224,6 +235,7 @@ defmodule Kernel.CLI do
       IO.puts("Elixir " <> System.build_info()[:build])
     end
 
+    t != [] && warn_standalone(opt)
     System.halt(0)
   end
 

lib/elixir/lib/kernel/error_handler.ex

@@ -30,10 +30,10 @@ defmodule Kernel.ErrorHandler do
   end
 
   def ensure_compiled(module, kind, deadlock) do
-    parent = :erlang.get(:elixir_compiler_pid)
+    {compiler_pid, file_pid} = :erlang.get(:elixir_compiler_info)
     ref = :erlang.make_ref()
     modules = :elixir_module.compiler_modules()
-    send(parent, {:waiting, kind, self(), ref, module, modules, deadlock})
+    send(compiler_pid, {:waiting, kind, self(), ref, file_pid, module, modules, deadlock})
     :erlang.garbage_collect(self())
 
     receive do

lib/elixir/lib/kernel/lexical_tracker.ex

@@ -30,8 +30,8 @@ defmodule Kernel.LexicalTracker do
   end
 
   @doc false
-  def add_require(pid, module) when is_atom(module) do
-    :gen_server.cast(pid, {:add_require, module})
+  def add_export(pid, module) when is_atom(module) do
+    :gen_server.cast(pid, {:add_export, module})
   end
 
   @doc false
@@ -168,15 +168,16 @@ defmodule Kernel.LexicalTracker do
     {:noreply, update_in(state.compile_env, &:ordsets.add_element({app, path, return}, &1))}
   end
 
-  def handle_cast({:add_require, module}, state) do
+  def handle_cast({:add_export, module}, state) do
     {:noreply, put_in(state.exports[module], true)}
   end
 
   def handle_cast({:add_import, module, fas, line, warn}, state) do
-    to_remove = for {{:import, {^module, _, _}} = key, _} <- state.directives, do: key
+    %{directives: directives, exports: exports} = state
+    to_remove = for {{:import, {^module, _, _}} = key, _} <- directives, do: key
 
     directives =
-      state.directives
+      directives
       |> Map.drop(to_remove)
       |> add_directive(module, line, warn, :import)
 
@@ -185,7 +186,7 @@ defmodule Kernel.LexicalTracker do
         add_directive(directives, {module, function, arity}, line, warn, :import)
       end)
 
-    {:noreply, %{state | directives: directives}}
+    {:noreply, %{state | directives: directives, exports: Map.put(exports, module, true)}}
   end
 
   def handle_cast({:add_alias, module, line, warn}, state) do
@@ -221,9 +222,9 @@ defmodule Kernel.LexicalTracker do
     do: Map.put(references, module, :compile)
 
   defp add_reference(references, module, :runtime) when is_atom(module) do
-    case Map.fetch(references, module) do
-      {:ok, _} -> references
-      :error -> Map.put(references, module, :runtime)
+    case references do
+      %{^module => _} -> references
+      _ -> Map.put(references, module, :runtime)
     end
   end
 

lib/elixir/lib/kernel/parallel_compiler.ex

@@ -3,6 +3,12 @@ defmodule Kernel.ParallelCompiler do
   A module responsible for compiling and requiring files in parallel.
   """
 
+  @typedoc "The line. 0 indicates no line."
+  @type line() :: non_neg_integer()
+  @type location() :: line() | {line(), column :: non_neg_integer}
+  @type warning() :: {file :: Path.t(), location(), message :: String.t()}
+  @type error() :: {file :: Path.t(), line(), message :: String.t()}
+
   @doc """
   Starts a task for parallel compilation.
 
@@ -16,23 +22,28 @@ defmodule Kernel.ParallelCompiler do
   """
   @doc since: "1.6.0"
   def async(fun) when is_function(fun, 0) do
-    if parent = :erlang.get(:elixir_compiler_pid) do
-      file = :erlang.get(:elixir_compiler_file)
-      dest = :erlang.get(:elixir_compiler_dest)
-      {:error_handler, error_handler} = :erlang.process_info(self(), :error_handler)
+    case :erlang.get(:elixir_compiler_info) do
+      {compiler, _} ->
+        file = :erlang.get(:elixir_compiler_file)
+        dest = :erlang.get(:elixir_compiler_dest)
 
-      Task.async(fn ->
-        send(parent, {:async, self()})
-        :erlang.put(:elixir_compiler_pid, parent)
-        :erlang.put(:elixir_compiler_file, file)
-        dest != :undefined and :erlang.put(:elixir_compiler_dest, dest)
-        :erlang.process_flag(:error_handler, error_handler)
-        fun.()
-      end)
-    else
-      raise ArgumentError,
-            "cannot spawn parallel compiler task because " <>
-              "the current file is not being compiled/required"
+        {:error_handler, error_handler} = :erlang.process_info(self(), :error_handler)
+        checker = Module.ParallelChecker.get()
+
+        Task.async(fn ->
+          send(compiler, {:async, self()})
+          Module.ParallelChecker.put(compiler, checker)
+          :erlang.put(:elixir_compiler_info, {compiler, self()})
+          :erlang.put(:elixir_compiler_file, file)
+          dest != :undefined and :erlang.put(:elixir_compiler_dest, dest)
+          :erlang.process_flag(:error_handler, error_handler)
+          fun.()
+        end)
+
+      :undefined ->
+        raise ArgumentError,
+              "cannot spawn parallel compiler task because " <>
+                "the current file is not being compiled/required"
     end
   end
 
@@ -86,6 +97,7 @@ defmodule Kernel.ParallelCompiler do
 
   """
   @doc since: "1.6.0"
+  @spec compile([Path.t()], keyword()) :: {:ok, [atom], [warning]} | {:error, [error], [warning]}
   def compile(files, options \\ []) when is_list(options) do
     spawn_workers(files, :compile, options)
   end
@@ -96,6 +108,8 @@ defmodule Kernel.ParallelCompiler do
   See `compile/2` for more information.
   """
   @doc since: "1.6.0"
+  @spec compile_to_path([Path.t()], Path.t(), keyword()) ::
+          {:ok, [atom], [warning]} | {:error, [error], [warning]}
   def compile_to_path(files, path, options \\ []) when is_binary(path) and is_list(options) do
     spawn_workers(files, {:compile, path}, options)
   end
@@ -121,10 +135,21 @@ defmodule Kernel.ParallelCompiler do
 
   """
   @doc since: "1.6.0"
+  @spec require([Path.t()], keyword()) ::
+          {:ok, [atom], [warning]} | {:error, [error], [warning]}
   def require(files, options \\ []) when is_list(options) do
     spawn_workers(files, :require, options)
   end
 
+  @doc """
+  Prints a warning returned by the compiler.
+  """
+  @doc since: "1.13.0"
+  @spec print_warning(warning) :: :ok
+  def print_warning({file, location, warning}) do
+    :elixir_errors.print_warning(location, file, warning)
+  end
+
   @doc false
   @deprecated "Use Kernel.ParallelCompiler.compile/2 instead"
   def files(files, options \\ []) when is_list(options) do
@@ -146,7 +171,32 @@ defmodule Kernel.ParallelCompiler do
   defp spawn_workers(files, output, options) do
     {:module, _} = :code.ensure_loaded(Kernel.ErrorHandler)
     schedulers = max(:erlang.system_info(:schedulers_online), 2)
-    beam_timestamp = Keyword.get(options, :beam_timestamp)
+    {:ok, checker} = Module.ParallelChecker.start_link(schedulers)
+
+    try do
+      outcome = spawn_workers(schedulers, checker, files, output, options)
+      {outcome, Code.get_compiler_option(:warnings_as_errors)}
+    else
+      {{:ok, _, [_ | _] = warnings}, true} ->
+        message = "Compilation failed due to warnings while using the --warnings-as-errors option"
+        IO.puts(:stderr, message)
+        {:error, warnings, []}
+
+      {{:ok, outcome, warnings}, _} ->
+        beam_timestamp = Keyword.get(options, :beam_timestamp)
+        {:ok, write_module_binaries(outcome, output, beam_timestamp), warnings}
+
+      {{:error, errors, warnings}, true} ->
+        {:error, errors ++ warnings, []}
+
+      {{:error, errors, warnings}, _} ->
+        {:error, errors, warnings}
+    after
+      Module.ParallelChecker.stop(checker)
+    end
+  end
+
+  defp spawn_workers(schedulers, checker, files, output, options) do
     threshold = Keyword.get(options, :long_compilation_threshold, 10) * 1000
     timer_ref = Process.send_after(self(), :threshold_check, threshold)
 
@@ -161,7 +211,8 @@ defmodule Kernel.ParallelCompiler do
         output: output,
         timer_ref: timer_ref,
         long_compilation_threshold: threshold,
-        schedulers: schedulers
+        schedulers: schedulers,
+        checker: checker
       })
 
     Process.cancel_timer(state.timer_ref)
@@ -172,21 +223,7 @@ defmodule Kernel.ParallelCompiler do
       0 -> :ok
     end
 
-    case {outcome, Code.get_compiler_option(:warnings_as_errors)} do
-      {{:ok, _, [_ | _] = warnings}, true} ->
-        message = "Compilation failed due to warnings while using the --warnings-as-errors option"
-        IO.puts(:stderr, message)
-        {:error, warnings, []}
-
-      {{:ok, outcome, warnings}, _} ->
-        {:ok, write_module_binaries(outcome, output, beam_timestamp), warnings}
-
-      {{:error, errors, warnings}, true} ->
-        {:error, errors ++ warnings, []}
-
-      {{:error, errors, warnings}, _} ->
-        {:error, errors, warnings}
-    end
+    outcome
   end
 
   defp each_file(fun) when is_function(fun, 1), do: fn file, _ -> fun.(file) end
@@ -228,32 +265,21 @@ defmodule Kernel.ParallelCompiler do
   end
 
   defp maybe_check_modules(result, runtime_modules, state) do
-    %{schedulers: schedulers, profile: profile} = state
+    %{profile: profile, checker: checker} = state
 
-    if :elixir_config.get(:bootstrap) do
-      []
-    else
-      compiled_modules = checker_compiled_modules(result)
-      runtime_modules = checker_runtime_modules(runtime_modules)
+    compiled_modules =
+      for {{:module, _module}, {_binary, info}} <- result,
+          do: info
 
-      profile_checker(profile, compiled_modules, runtime_modules, fn ->
-        Module.ParallelChecker.verify(compiled_modules, runtime_modules, schedulers)
-      end)
-    end
-  end
+    runtime_modules =
+      for module <- runtime_modules,
+          path = :code.which(module),
+          is_list(path) and path != [],
+          do: {module, path}
 
-  defp checker_compiled_modules(result) do
-    for {{:module, _module}, {binary, module_map}} <- result do
-      {module_map, binary}
-    end
-  end
-
-  defp checker_runtime_modules(modules) do
-    for module <- modules,
-        path = :code.which(module),
-        is_list(path) and path != [] do
-      {module, File.read!(path)}
-    end
+    profile_checker(profile, compiled_modules, runtime_modules, fn ->
+      Module.ParallelChecker.verify(checker, compiled_modules, runtime_modules)
+    end)
   end
 
   defp profile_init(:time), do: {:time, System.monotonic_time(), 0}
@@ -291,9 +317,9 @@ defmodule Kernel.ParallelCompiler do
   defp spawn_workers([{ref, found} | t], spawned, waiting, files, result, warnings, state) do
     {files, waiting} =
       case List.keytake(waiting, ref, 2) do
-        {{_kind, pid, ^ref, _on, _defining, _deadlock}, waiting} ->
+        {{_kind, pid, ^ref, file_pid, _on, _defining, _deadlock}, waiting} ->
           send(pid, {ref, found})
-          {update_timing(files, pid, :waiting), waiting}
+          {update_timing(files, file_pid, :waiting), waiting}
 
         nil ->
           # In case the waiting process died (for example, it was an async process),
@@ -305,13 +331,14 @@ defmodule Kernel.ParallelCompiler do
   end
 
   defp spawn_workers([file | queue], spawned, waiting, files, result, warnings, state) do
-    %{output: output, dest: dest} = state
+    %{output: output, dest: dest, checker: checker} = state
     parent = self()
     file = Path.expand(file)
 
     {pid, ref} =
       :erlang.spawn_monitor(fn ->
-        :erlang.put(:elixir_compiler_pid, parent)
+        Module.ParallelChecker.put(parent, checker)
+        :erlang.put(:elixir_compiler_info, {parent, self()})
         :erlang.put(:elixir_compiler_file, file)
 
         try do
@@ -365,7 +392,7 @@ defmodule Kernel.ParallelCompiler do
   defp spawn_workers(
          [],
          1,
-         [{_, pid, ref, _, _, _}] = waiting,
+         [{_, pid, ref, _, _, _, _}] = waiting,
          [%{pid: pid}] = files,
          result,
          warnings,
@@ -398,7 +425,7 @@ defmodule Kernel.ParallelCompiler do
     deadlocked =
       deadlocked(waiting, :soft, false) ||
         deadlocked(waiting, :soft, true) || deadlocked(waiting, :hard, false) ||
-        without_definition(waiting)
+        without_definition(waiting, files)
 
     if deadlocked do
       spawn_workers(deadlocked, spawned, waiting, files, result, warnings, state)
@@ -457,9 +484,13 @@ defmodule Kernel.ParallelCompiler do
   defp each_cycle_return({kind, modules}), do: {kind, modules, []}
   defp each_cycle_return(modules) when is_list(modules), do: {:compile, modules, []}
 
-  defp without_definition(waiting) do
+  # The goal of this function is to find leaves in the dependency graph,
+  # i.e. to find code that depends on code that we know is not being defined.
+  # Note that not all files have been compiled yet, so they may not be in waiting.
+  defp without_definition(waiting, files) do
     nillify_empty(
-      for {_, _, ref, on, _, _} <- waiting,
+      for %{pid: pid} <- files,
+          {_, _, ref, ^pid, on, _, _} <- waiting,
           not defining?(on, waiting),
           do: {ref, :not_found}
     )
@@ -467,14 +498,14 @@ defmodule Kernel.ParallelCompiler do
 
   defp deadlocked(waiting, type, defining?) do
     nillify_empty(
-      for {_, _, ref, on, _, ^type} <- waiting,
+      for {_, _, ref, _, on, _, ^type} <- waiting,
           defining?(on, waiting) == defining?,
           do: {ref, :deadlock}
     )
   end
 
   defp defining?(on, waiting) do
-    Enum.any?(waiting, fn {_, _, _, _, defining, _} -> on in defining end)
+    Enum.any?(waiting, fn {_, _, _, _, _, defining, _} -> on in defining end)
   end
 
   defp nillify_empty([]), do: nil
@@ -491,41 +522,41 @@ defmodule Kernel.ParallelCompiler do
 
       {:available, kind, module} ->
         available =
-          for {^kind, _, ref, ^module, _defining, _deadlock} <- waiting,
+          for {^kind, _, ref, _, ^module, _defining, _deadlock} <- waiting,
               do: {ref, :found}
 
         result = Map.put(result, {kind, module}, true)
         spawn_workers(available ++ queue, spawned, waiting, files, result, warnings, state)
 
-      {:module_available, child, ref, file, module, binary, module_map} ->
+      {:module_available, child, ref, file, module, binary, checker_info} ->
         state.each_module.(file, module, binary)
 
         # Release the module loader which is waiting for an ack
         send(child, {ref, :ack})
 
         available =
-          for {:module, _, ref, ^module, _defining, _deadlock} <- waiting,
+          for {:module, _, ref, _, ^module, _defining, _deadlock} <- waiting,
               do: {ref, :found}
 
-        result = Map.put(result, {:module, module}, {binary, module_map})
+        result = Map.put(result, {:module, module}, {binary, checker_info})
         spawn_workers(available ++ queue, spawned, waiting, files, result, warnings, state)
 
       # If we are simply requiring files, we do not add to waiting.
-      {:waiting, _kind, child, ref, _on, _defining, _deadlock} when output == :require ->
+      {:waiting, _kind, child, ref, _file_pid, _on, _defining, _deadlock} when output == :require ->
         send(child, {ref, :not_found})
         spawn_workers(queue, spawned, waiting, files, result, warnings, state)
 
-      {:waiting, kind, child, ref, on, defining, deadlock?} ->
+      {:waiting, kind, child_pid, ref, file_pid, on, defining, deadlock?} ->
         # If we already got what we were waiting for, do not put it on waiting.
         # If we're waiting on ourselves, send :found so that we can crash with
         # a better error.
         {files, waiting} =
           if Map.has_key?(result, {kind, on}) or on in defining do
-            send(child, {ref, :found})
+            send(child_pid, {ref, :found})
             {files, waiting}
           else
-            files = update_timing(files, child, :compiling)
-            {files, [{kind, child, ref, on, defining, deadlock?} | waiting]}
+            files = update_timing(files, file_pid, :compiling)
+            {files, [{kind, child_pid, ref, file_pid, on, defining, deadlock?} | waiting]}
           end
 
         spawn_workers(queue, spawned, waiting, files, result, warnings, state)
@@ -546,10 +577,10 @@ defmodule Kernel.ParallelCompiler do
         state = %{state | timer_ref: timer_ref}
         spawn_workers(queue, spawned, waiting, files, result, warnings, state)
 
-      {:warning, file, line, message} ->
+      {:warning, file, location, message} ->
         file = file && Path.absname(file)
         message = :unicode.characters_to_binary(message)
-        warning = {file, line, message}
+        warning = {file, location, message}
         wait_for_messages(queue, spawned, waiting, files, result, [warning | warnings], state)
 
       {:file_ok, child_pid, ref, file, lexical} ->
@@ -619,13 +650,13 @@ defmodule Kernel.ParallelCompiler do
         data = maybe_warn_long_compilation(data, state)
 
         if state.profile != :none do
-          compiling = System.convert_time_unit(data.compiling, :native, :millisecond)
-          waiting = System.convert_time_unit(data.waiting, :native, :millisecond)
-          extra = if waiting > 0, do: " (plus #{waiting}ms waiting)", else: ""
+          compiling = to_padded_ms(data.compiling)
+          waiting = to_padded_ms(data.waiting)
+          relative = Path.relative_to_cwd(data.file)
 
           IO.puts(
             :stderr,
-            "[profile] #{Path.relative_to_cwd(data.file)} compiled in #{compiling}ms" <> extra
+            "[profile] #{compiling}ms compiling + #{waiting}ms waiting for #{relative}"
           )
         end
 
@@ -636,6 +667,13 @@ defmodule Kernel.ParallelCompiler do
     end)
   end
 
+  defp to_padded_ms(time) do
+    time
+    |> System.convert_time_unit(:native, :millisecond)
+    |> Integer.to_string()
+    |> String.pad_leading(6, " ")
+  end
+
   defp discard_down(pid) do
     receive do
       {:DOWN, _, :process, ^pid, _} -> :ok
@@ -664,7 +702,7 @@ defmodule Kernel.ParallelCompiler do
         {:current_stacktrace, stacktrace} = Process.info(pid, :current_stacktrace)
         Process.exit(pid, :kill)
 
-        {kind, ^pid, _, on, _, _} = List.keyfind(waiting, pid, 1)
+        {kind, ^pid, _, _, on, _, _} = List.keyfind(waiting, pid, 1)
         description = "deadlocked waiting on #{kind} #{inspect(on)}"
         error = CompileError.exception(description: description, file: nil, line: nil)
         print_error(file, :error, error, stacktrace)
@@ -711,7 +749,7 @@ defmodule Kernel.ParallelCompiler do
     line = get_line(file, reason, stack)
     file = Path.absname(file)
     message = :unicode.characters_to_binary(Kernel.CLI.format_error(kind, reason, stack))
-    {file, line, message}
+    {file, line || 0, message}
   end
 
   defp get_line(_file, %{line: line}, _stack) when is_integer(line) and line > 0 do

lib/elixir/lib/kernel/special_forms.ex

@@ -554,7 +554,9 @@ defmodule Kernel.SpecialForms do
   defmacro alias(module, opts), do: error!([module, opts])
 
   @doc """
-  Requires a module in order to use its macros.
+  Requires a module as a compile-time dependency.
+
+  Requiring a module is necessary in order to use its macros.
 
   ## Examples
 
@@ -576,7 +578,6 @@ defmodule Kernel.SpecialForms do
 
   `require/2` also accepts `:as` as an option so it automatically sets
   up an alias. Please check `alias/2` for more information.
-
   """
   defmacro require(module, opts), do: error!([module, opts])
 
@@ -1211,6 +1212,12 @@ defmodule Kernel.SpecialForms do
   reported to where `defadd` was invoked. `location: :keep` affects
   only definitions inside the quote.
 
+  > **Important:** do not use location: :keep if the function definition
+  > also `unquote`s some of the macro arguments. If you do so, Elixir
+  > will store the file definition of the current location but the
+  > unquoted arguments may contain line information of the macro caller,
+  > leading to erroneous stacktraces.
+
   ## Binding and unquote fragments
 
   Elixir quote/unquote mechanisms provide a functionality called
@@ -1416,7 +1423,7 @@ defmodule Kernel.SpecialForms do
   The `IO` module provides streams, that are both `Enumerable` and
   `Collectable`, here is an upcase echo server using comprehensions:
 
-      for line <- IO.stream(:stdio, :line), into: IO.stream(:stdio, :line) do
+      for line <- IO.stream(), into: IO.stream() do
         String.upcase(line)
       end
 
@@ -1519,15 +1526,15 @@ defmodule Kernel.SpecialForms do
       iex> width
       nil
 
-  The behaviour of any expression in a clause is the same as outside.
-  For example, `=` will raise a `MatchError` instead of returning the
-  non-matched value:
+  The behaviour of any expression in a clause is the same as if it was
+  written outside of `with`. For example, `=` will raise a `MatchError`
+  instead of returning the non-matched value:
 
       with :foo = :bar, do: :ok
       ** (MatchError) no match of right hand side value: :bar
 
   As with any other function or macro call in Elixir, explicit parens can
-  also be used around the arguments before the `do`/`end` block:
+  also be used around the arguments before the `do`-`end` block:
 
       iex> opts = %{width: 10, height: 15}
       iex> with(
@@ -1540,6 +1547,8 @@ defmodule Kernel.SpecialForms do
 
   The choice between parens and no parens is a matter of preference.
 
+  ## Else clauses
+
   An `else` option can be given to modify what is being returned from
   `with` in the case of a failed match:
 
@@ -1562,6 +1571,48 @@ defmodule Kernel.SpecialForms do
 
   If an `else` block is used and there are no matching clauses, a `WithClauseError`
   exception is raised.
+
+  ### Beware!
+
+  Keep in mind that, one of potential drawback of `with` is that all
+  failure clauses are flattened into a single `else` block. For example,
+  take this code that checks if a given path points to an Elixir file
+  and that it exists before creating a backup copy:
+
+      with ".ex" <- Path.extname(path),
+           true <- File.exists?(path) do
+        backup_path = path <> ".backup"
+        File.cp!(path, backup_path)
+        {:ok, backup_path}
+      else
+        binary when is_binary(binary) ->
+          {:error, :invalid_extension}
+
+        false ->
+          {:error, :missing_file}
+      end
+
+  Note how we are having to reconstruct the result types of `Path.extname/1`
+  and `File.exists?/1` to build error messages. In this case, it is better
+  to change the with clauses to already return the desired format, like this:
+
+      with :ok <- validate_extension(path),
+           :ok <- validate_exists(path) do
+        backup_path = path <> ".backup"
+        File.cp!(path, backup_path)
+        {:ok, backup_path}
+      end
+
+      defp validate_extname(path) do
+        if Path.extname(path) == ".ex", do: :ok, else: {:error, :invalid_extension}
+      end
+
+      defp validate_exists(path) do
+        if File.exists?(path), do: :ok, else: {:error, :missing_file}
+      end
+
+  Note how the code above is better organized and clearer once we
+  make sure each clause in `with` returns a normalize format.
   """
   defmacro with(args), do: error!([args])
 

lib/elixir/lib/kernel/typespec.ex

@@ -553,9 +553,7 @@ defmodule Kernel.Typespec do
   end
 
   defp typespec({:%, _, [name, {:%{}, meta, fields}]}, vars, caller, state) do
-    # We cannot set a function name to avoid tracking
-    # as a compile time dependency, because for structs it actually is one.
-    module = Macro.expand(name, caller)
+    module = Macro.expand(name, %{caller | function: {:__info__, 1}})
 
     struct =
       module
@@ -577,7 +575,7 @@ defmodule Kernel.Typespec do
       unless Keyword.has_key?(struct, field) do
         compile_error(
           caller,
-          "undefined field #{inspect(field)} on struct #{Macro.to_string(name)}"
+          "undefined field #{inspect(field)} on struct #{inspect(module)}"
         )
       end
     end
@@ -1022,7 +1020,11 @@ defmodule Kernel.Typespec do
           :elixir_errors.erl_warn(caller.line, caller.file, warning)
 
         {_, :used_once} ->
-          compile_error(caller, "type variable #{name} is unused")
+          compile_error(
+            caller,
+            "type variable #{name} is used only once. Type variables in typespecs " <>
+              "must be referenced at least twice, otherwise it is equivalent to term()"
+          )
 
         _ ->
           :ok

lib/elixir/lib/kernel/utils.ex

@@ -29,9 +29,16 @@ defmodule Kernel.Utils do
     append_first? = Keyword.get(opts, :append_first, false)
 
     {name, args} =
-      case Macro.decompose_call(fun) do
-        {_, _} = pair -> pair
-        _ -> raise ArgumentError, "invalid syntax in defdelegate #{Macro.to_string(fun)}"
+      case fun do
+        {:when, _, [_left, right]} ->
+          raise ArgumentError,
+                "guards are not allowed in defdelegate/2, got: when #{Macro.to_string(right)}"
+
+        _ ->
+          case Macro.decompose_call(fun) do
+            {_, _} = pair -> pair
+            _ -> raise ArgumentError, "invalid syntax in defdelegate #{Macro.to_string(fun)}"
+          end
       end
 
     as = Keyword.get(opts, :as, name)
@@ -137,9 +144,9 @@ defmodule Kernel.Utils do
   Announcing callback for defstruct.
   """
   def announce_struct(module) do
-    case :erlang.get(:elixir_compiler_pid) do
+    case :erlang.get(:elixir_compiler_info) do
       :undefined -> :ok
-      pid -> send(pid, {:available, :struct, module})
+      {pid, _} -> send(pid, {:available, :struct, module})
     end
   end
 
@@ -219,7 +226,7 @@ defmodule Kernel.Utils do
   def defguard(args, expr, env) do
     {^args, vars} = extract_refs_from_args(args)
     env = :elixir_env.with_vars(%{env | context: :guard}, vars)
-    {expr, _scope} = :elixir_expand.expand(expr, env)
+    {expr, _, _} = :elixir_expand.expand(expr, :elixir_env.env_to_ex(env), env)
 
     quote do
       case Macro.Env.in_guard?(__CALLER__) do

lib/elixir/lib/keyword.ex

@@ -13,45 +13,43 @@ defmodule Keyword do
 
       [{:exit_on_close, true}, {:active, :once}, {:packet_size, 1024}]
 
-  Elixir provides a special and more concise syntax for keyword lists
-  that looks like this:
+  Elixir provides a special and more concise syntax for keyword lists:
 
       [exit_on_close: true, active: :once, packet_size: 1024]
 
-  The two syntaxes are completely equivalent. Like atoms, keyword
-  lists keys must be composed of Unicode characters such as letters,
-  numbers, underscore, and `@`. If the keyword has a character that
-  does not belong to the category above, such as spaces, you can wrap
-  it in quotes:
+  The two syntaxes return the exact same value.
+
+  A *key* can be any atom, consisting of Unicode letters, numbers,
+  an underscore or the `@` sign. If the *key* should have any other
+  characters, such as spaces, you can wrap it in quotes:
 
       iex> ["exit on close": true]
       ["exit on close": true]
 
-  Wrapping a keyword in quotes does not make it a string. Keyword lists
-  keys are always atoms. If you use quotes around the key when quoting
-  is not necessary, Elixir will warn.
+  Wrapping an atom in quotes does not make it a string. Keyword list
+  *keys* are always atoms. Quotes should only be used when necessary
+  or Elixir will issue a warning.
 
   ## Duplicate keys and ordering
 
-  A keyword may have duplicated keys so it is not strictly a key-value
-  data type. However most of the functions in this module behave exactly
-  as a key-value so they work similarly to the functions you would find
-  in the `Map` module. For example, `Keyword.get/3` will get the first
-  entry matching the given key, regardless if duplicated entries exist.
-  Similarly, `Keyword.put/3` and `Keyword.delete/2` ensure all duplicated
+  A keyword may have duplicate keys so it is not strictly a key-value
+  data type. However most of the functions in this module work on a
+  key-value structure and behave similar to the functions you would
+  find in the `Map` module. For example, `Keyword.get/3` will get the first
+  entry matching the given key, regardless if duplicate entries exist.
+  Similarly, `Keyword.put/3` and `Keyword.delete/2` ensure all duplicate
   entries for a given key are removed when invoked. Note, however, that
   keyword list operations need to traverse the whole list in order to find
   keys, so these operations are slower than their map counterparts.
 
-  A handful of functions exist to handle duplicated keys, for example,
+  A handful of functions exist to handle duplicate keys, for example,
   `get_values/2` returns all values for a given key and `delete_first/2`
-  deletes just one of the existing entries.
+  deletes just the first entry of the existing ones.
 
-  Even though lists preserve the user ordering, the functions in
+  Even though lists preserve the existing order, the functions in
   `Keyword` do not guarantee any ordering. For example, if you invoke
-  `Keyword.put(opts, new_key, new_value)`, there is no guarantee to
-  where `new_key` will be added (to the front, to the end, or
-  anywhere else).
+  `Keyword.put(opts, new_key, new_value)`, there is no guarantee for
+  where `new_key` will be added to (the front, the end or anywhere else).
 
   Given ordering is not guaranteed, it is not recommended to pattern
   match on keyword lists either. For example, a function such as:
@@ -67,7 +65,7 @@ defmodule Keyword do
       my_function([another_key: :bar, some_key: :foo])
 
   Most of the functions in this module work in linear time. This means
-  that, the time it takes to perform an operation grows at the same
+  that the time it takes to perform an operation grows at the same
   rate as the length of the list.
 
   ## Call syntax
@@ -83,8 +81,8 @@ defmodule Keyword do
 
       String.split("1-0", "-", trim: true, parts: 2)
 
-  Since tuples, lists, maps, and others are treated the same as function
-  calls in Elixir syntax, this property is also available to them:
+  Since tuples, lists and maps are treated similarly to function
+  arguments in Elixir syntax, this property is also available to them:
 
       iex> {1, 2, foo: :bar}
       {1, 2, [{:foo, :bar}]}
@@ -105,7 +103,9 @@ defmodule Keyword do
   @type t(value) :: [{key, value}]
 
   @doc """
-  Returns `true` if `term` is a keyword list; otherwise returns `false`.
+  Returns `true` if `term` is a keyword list, otherwise `false`.
+
+  When `term` is a list it is traversed to the end.
 
   ## Examples
 
@@ -145,7 +145,7 @@ defmodule Keyword do
   @doc """
   Creates a keyword list from an enumerable.
 
-  Duplicated entries are removed, the latest one prevails.
+  Removes duplicate entries and the last one prevails.
   Unlike `Enum.into(enumerable, [])`, `Keyword.new(enumerable)`
   guarantees the keys are unique.
 
@@ -166,7 +166,7 @@ defmodule Keyword do
   @doc """
   Creates a keyword list from an enumerable via the transformation function.
 
-  Duplicated entries are removed, the latest one prevails.
+  Removes duplicate entries and the last one prevails.
   Unlike `Enum.into(enumerable, [], fun)`,
   `Keyword.new(enumerable, fun)` guarantees the keys are unique.
 
@@ -187,12 +187,146 @@ defmodule Keyword do
   end
 
   @doc """
-  Gets the value for a specific `key`.
+  Ensures the first argument is a `keyword` with the given
+  keys and default values.
 
-  If `key` does not exist, return the default value
-  (`nil` if no default value).
+  The second argument must be a list of atoms, specifying
+  a given key, or tuples specifying a key and a default value.
 
-  If duplicated entries exist, the first one is returned.
+  If the keyword list has only the given keys, it returns
+  `{:ok, keyword}` with default values applied. Otherwise it
+  returns `{:error, invalid_keys}` with invalid keys.
+
+  See also: `validate!/2`.
+
+  ## Examples
+
+      iex> {:ok, result} = Keyword.validate([], [one: 1, two: 2])
+      iex> Enum.sort(result)
+      [one: 1, two: 2]
+
+      iex> {:ok, result} = Keyword.validate([two: 3], [one: 1, two: 2])
+      iex> Enum.sort(result)
+      [one: 1, two: 3]
+
+  If atoms are given, they are supported as keys but do not
+  provide a default value:
+
+      iex> {:ok, result} = Keyword.validate([], [:one, two: 2])
+      iex> Enum.sort(result)
+      [two: 2]
+
+      iex> {:ok, result} = Keyword.validate([one: 1], [:one, two: 2])
+      iex> Enum.sort(result)
+      [one: 1, two: 2]
+
+  Passing unknown keys returns an error:
+
+      iex> Keyword.validate([three: 3, four: 4], [one: 1, two: 2])
+      {:error, [:four, :three]}
+  """
+  @doc since: "1.13.0"
+  @spec validate(keyword(), values :: [atom() | {atom(), term()}]) ::
+          {:ok, keyword()} | {:error, [atom]}
+  def validate(keyword, values) when is_list(keyword) and is_list(values) do
+    validate(keyword, values, [], [], [])
+  end
+
+  defp validate([{key, _} = pair | keyword], values1, values2, acc, bad_keys) when is_atom(key) do
+    case find_key!(key, values1, values2) do
+      {values1, values2} ->
+        validate(keyword, values1, values2, [pair | acc], bad_keys)
+
+      :error ->
+        case find_key!(key, values2, values1) do
+          {values1, values2} ->
+            validate(keyword, values1, values2, [pair | acc], bad_keys)
+
+          :error ->
+            validate(keyword, values1, values2, acc, [key | bad_keys])
+        end
+    end
+  end
+
+  defp validate([], values1, values2, acc, []) do
+    {:ok, move_pairs!(values1, move_pairs!(values2, acc))}
+  end
+
+  defp validate([], _values1, _values2, _acc, bad_keys) do
+    {:error, bad_keys}
+  end
+
+  defp validate([pair | _], _values1, _values2, _acc, []) do
+    raise ArgumentError,
+          "expected a keyword list as first argument, got invalid entry: #{inspect(pair)}"
+  end
+
+  defp find_key!(key, [key | rest], acc), do: {rest, acc}
+  defp find_key!(key, [{key, _} | rest], acc), do: {rest, acc}
+  defp find_key!(key, [head | tail], acc), do: find_key!(key, tail, [head | acc])
+  defp find_key!(_key, [], _acc), do: :error
+
+  defp move_pairs!([key | rest], acc) when is_atom(key),
+    do: move_pairs!(rest, acc)
+
+  defp move_pairs!([{key, _} = pair | rest], acc) when is_atom(key),
+    do: move_pairs!(rest, [pair | acc])
+
+  defp move_pairs!([], acc),
+    do: acc
+
+  defp move_pairs!([other | _], _) do
+    raise ArgumentError,
+          "expected the second argument to be a list of atoms or tuples, got: #{inspect(other)}"
+  end
+
+  @doc """
+  Similar to `validate/2` but returns the keyword or raises an error.
+
+  ## Examples
+
+      iex> Keyword.validate!([], [one: 1, two: 2]) |> Enum.sort()
+      [one: 1, two: 2]
+      iex> Keyword.validate!([two: 3], [one: 1, two: 2]) |> Enum.sort()
+      [one: 1, two: 3]
+
+  If atoms are given, they are supported as keys but do not
+  provide a default value:
+
+      iex> Keyword.validate!([], [:one, two: 2]) |> Enum.sort()
+      [two: 2]
+      iex> Keyword.validate!([one: 1], [:one, two: 2]) |> Enum.sort()
+      [one: 1, two: 2]
+
+  Passing unknown keys raises an error:
+
+      iex> Keyword.validate!([three: 3], [one: 1, two: 2])
+      ** (ArgumentError) unknown keys [:three] in [three: 3], the allowed keys are: [:one, :two]
+  """
+  @doc since: "1.13.0"
+  @spec validate!(keyword(), values :: [atom() | {atom(), term()}]) :: keyword()
+  def validate!(keyword, values) do
+    case validate(keyword, values) do
+      {:ok, kw} ->
+        kw
+
+      {:error, invalid_keys} ->
+        keys =
+          for value <- values,
+              do: if(is_atom(value), do: value, else: elem(value, 0))
+
+        raise ArgumentError,
+              "unknown keys #{inspect(invalid_keys)} in #{inspect(keyword)}, the allowed keys are: #{inspect(keys)}"
+    end
+  end
+
+  @doc """
+  Gets the value under the given `key`.
+
+  Returns the default value if `key` does not exist
+  (`nil` if no default value is provided).
+
+  If duplicate entries exist, it returns the first one.
   Use `get_values/2` to retrieve all entries.
 
   ## Examples
@@ -206,7 +340,7 @@ defmodule Keyword do
       iex> Keyword.get([a: 1], :b, 3)
       3
 
-  With duplicated keys:
+  With duplicate keys:
 
       iex> Keyword.get([a: 1, a: 2], :a, 3)
       1
@@ -223,14 +357,14 @@ defmodule Keyword do
   end
 
   @doc """
-  Gets the value for a specific `key`.
+  Gets the value under the given `key`.
 
   If `key` does not exist, lazily evaluates `fun` and returns its result.
 
   This is useful if the default value is very expensive to calculate or
-  generally difficult to setup and teardown again.
+  generally difficult to set up and tear down again.
 
-  If duplicated entries exist, the first one is returned.
+  If duplicate entries exist, it returns the first one.
   Use `get_values/2` to retrieve all entries.
 
   ## Examples
@@ -258,14 +392,14 @@ defmodule Keyword do
   @doc """
   Gets the value from `key` and updates it, all in one pass.
 
-  This `fun` argument receives the value of `key` (or `nil` if `key`
+  The `fun` argument receives the value of `key` (or `nil` if `key`
   is not present) and must return a two-element tuple: the current value
   (the retrieved value, which can be operated on before being returned)
   and the new value to be stored under `key`. The `fun` may also
   return `:pop`, implying the current value shall be removed from the
   keyword list and returned.
 
-  The returned value is a tuple with the current value returned by
+  Returns a tuple that contains the current value returned by
   `fun` and a new keyword list with the updated value under `key`.
 
   ## Examples
@@ -280,6 +414,11 @@ defmodule Keyword do
       ...> end)
       {nil, [b: "new value!", a: 1]}
 
+      iex> Keyword.get_and_update([a: 2], :a, fn number ->
+      ...>   {2 * number, 3 * number}
+      ...> end)
+      {4, [a: 6]}
+
       iex> Keyword.get_and_update([a: 1], :a, fn _ -> :pop end)
       {1, []}
 
@@ -323,15 +462,15 @@ defmodule Keyword do
   end
 
   @doc """
-  Gets the value from `key` and updates it. Raises if there is no `key`.
+  Gets the value under `key` and updates it. Raises if there is no `key`.
 
-  This `fun` argument receives the value of `key` and must return a
+  The `fun` argument receives the value under `key` and must return a
   two-element tuple: the current value (the retrieved value, which can be
   operated on before being returned) and the new value to be stored under
   `key`.
 
-  The returned value is a tuple with the current value returned by `fun` and a new
-  keyword list with the updated value under `key`.
+  Returns a tuple that contains the current value returned by
+  `fun` and a new keyword list with the updated value under `key`.
 
   ## Examples
 
@@ -376,13 +515,13 @@ defmodule Keyword do
   end
 
   defp get_and_update!([], key, _fun, acc) when is_atom(key) do
-    raise(KeyError, key: key, term: acc)
+    raise KeyError, key: key, term: acc
   end
 
   @doc """
   Fetches the value for a specific `key` and returns it in a tuple.
 
-  If the `key` does not exist, returns `:error`.
+  If the `key` does not exist, it returns `:error`.
 
   ## Examples
 
@@ -403,7 +542,7 @@ defmodule Keyword do
   @doc """
   Fetches the value for specific `key`.
 
-  If `key` does not exist, a `KeyError` is raised.
+  If the `key` does not exist, it raises a `KeyError`.
 
   ## Examples
 
@@ -417,12 +556,12 @@ defmodule Keyword do
   def fetch!(keywords, key) when is_list(keywords) and is_atom(key) do
     case :lists.keyfind(key, 1, keywords) do
       {^key, value} -> value
-      false -> raise(KeyError, key: key, term: keywords)
+      false -> raise KeyError, key: key, term: keywords
     end
   end
 
   @doc """
-  Gets all values for a specific `key`.
+  Gets all values under a specific `key`.
 
   ## Examples
 
@@ -446,7 +585,7 @@ defmodule Keyword do
   @doc """
   Returns all keys from the keyword list.
 
-  Duplicated keys appear duplicated in the final list of keys.
+  Keeps duplicate keys in the resulting list of keys.
 
   ## Examples
 
@@ -462,26 +601,24 @@ defmodule Keyword do
   """
   @spec keys(t) :: [key]
   def keys(keywords) when is_list(keywords) do
-    try do
-      :lists.map(
-        fn
-          {key, _} when is_atom(key) -> key
-          element -> throw(element)
-        end,
-        keywords
-      )
-    catch
-      element ->
-        raise ArgumentError,
-              "expected a keyword list, but an entry in the list is not a two-element tuple with an atom as its first element, " <>
-                "got: #{inspect(element)}"
-    end
+    :lists.map(
+      fn
+        {key, _} when is_atom(key) -> key
+        element -> throw(element)
+      end,
+      keywords
+    )
+  catch
+    element ->
+      raise ArgumentError,
+            "expected a keyword list, but an entry in the list is not a two-element tuple " <>
+              "with an atom as its first element, got: #{inspect(element)}"
   end
 
   @doc """
   Returns all values from the keyword list.
 
-  Values from duplicated keys will be kept in the final list of values.
+  Keeps values from duplicate keys in the resulting list of values.
 
   ## Examples
 
@@ -518,11 +655,11 @@ defmodule Keyword do
   end
 
   @doc """
-  Deletes the entries in the keyword list for a specific `key`.
+  Deletes the entries in the keyword list under a specific `key`.
 
-  If the `key` does not exist, returns the keyword list unchanged.
+  If the `key` does not exist, it returns the keyword list unchanged.
   Use `delete_first/2` to delete just the first entry in case of
-  duplicated keys.
+  duplicate keys.
 
   ## Examples
 
@@ -548,9 +685,9 @@ defmodule Keyword do
   defp delete_key([], _key), do: []
 
   @doc """
-  Deletes the first entry in the keyword list for a specific `key`.
+  Deletes the first entry in the keyword list under a specific `key`.
 
-  If the `key` does not exist, returns the keyword list unchanged.
+  If the `key` does not exist, it returns the keyword list unchanged.
 
   ## Examples
 
@@ -581,10 +718,10 @@ defmodule Keyword do
   end
 
   @doc """
-  Puts the given `value` under `key`.
+  Puts the given `value` under the specified `key`.
 
-  If a previous value is already stored, all entries are
-  removed and the value is overridden.
+  If a value under `key` already exists, it overrides the value
+  and removes all duplicate entries.
 
   ## Examples
 
@@ -606,19 +743,19 @@ defmodule Keyword do
   in keyword list unless `key` is already present.
 
   This is useful if the value is very expensive to calculate or
-  generally difficult to setup and teardown again.
+  generally difficult to set up and tear down again.
 
   ## Examples
 
       iex> keyword = [a: 1]
       iex> fun = fn ->
       ...>   # some expensive operation here
-      ...>   3
+      ...>   13
       ...> end
       iex> Keyword.put_new_lazy(keyword, :a, fun)
       [a: 1]
       iex> Keyword.put_new_lazy(keyword, :b, fun)
-      [b: 3, a: 1]
+      [b: 13, a: 1]
 
   """
   @spec put_new_lazy(t, key, (() -> value)) :: t
@@ -631,8 +768,7 @@ defmodule Keyword do
   end
 
   @doc """
-  Puts the given `value` under `key` unless the entry `key`
-  already exists.
+  Puts the given `value` under `key`, unless the entry `key` already exists.
 
   ## Examples
 
@@ -653,8 +789,8 @@ defmodule Keyword do
   @doc """
   Puts a value under `key` only if the `key` already exists in `keywords`.
 
-  In the case a value is stored multiple times in the keyword list,
-  later occurrences are removed.
+  In case a key exists multiple times in the keyword list,
+  it removes later occurrences.
 
   ## Examples
 
@@ -686,7 +822,7 @@ defmodule Keyword do
   @doc """
   Puts a value under `key` only if the `key` already exists in `keywords`.
 
-  If `key` is not present in `keywords`, a `KeyError` exception is raised.
+  If `key` is not present in `keywords`, it raises a `KeyError`.
 
   ## Examples
 
@@ -714,13 +850,13 @@ defmodule Keyword do
   end
 
   defp replace!([], key, _value, original) do
-    raise(KeyError, key: key, term: original)
+    raise KeyError, key: key, term: original
   end
 
   @doc """
   Checks if two keywords are equal.
 
-  Two keywords are considered to be equal if they contain
+  Considers two keywords to be equal if they contain
   the same keys and those keys contain the same values.
 
   ## Examples
@@ -747,10 +883,10 @@ defmodule Keyword do
   @doc """
   Merges two keyword lists into one.
 
-  All keys, including duplicated keys, given in `keywords2` will be added
-  to `keywords1`, overriding any existing one.
+  Adds all keys, including duplicate keys, given in `keywords2`
+  to `keywords1`, overriding any existing ones.
 
-  There are no guarantees about the order of keys in the returned keyword.
+  There are no guarantees about the order of the keys in the returned keyword.
 
   ## Examples
 
@@ -791,13 +927,13 @@ defmodule Keyword do
   @doc """
   Merges two keyword lists into one.
 
-  All keys, including duplicated keys, given in `keywords2` will be added
-  to `keywords1`. The given function will be invoked to solve conflicts.
+  Adds all keys, including duplicate keys, given in `keywords2`
+  to `keywords1`. Invokes the given function to solve conflicts.
 
-  If `keywords2` has duplicate keys, the given function will be invoked
+  If `keywords2` has duplicate keys, it invokes the given function
   for each matching pair in `keywords1`.
 
-  There are no guarantees about the order of keys in the returned keyword.
+  There are no guarantees about the order of the keys in the returned keyword.
 
   ## Examples
 
@@ -871,12 +1007,11 @@ defmodule Keyword do
   end
 
   @doc """
-  Updates the `key` with the given function.
+  Updates the value under `key` using the given function.
 
-  If the `key` does not exist, raises `KeyError`.
+  Raises `KeyError` if the `key` does not exist.
 
-  If there are duplicated keys, they are all removed and only the first one
-  is updated.
+  Removes all duplicate keys and only updates the first one.
 
   ## Examples
 
@@ -904,18 +1039,16 @@ defmodule Keyword do
   end
 
   defp update!([], key, _fun, original) do
-    raise(KeyError, key: key, term: original)
+    raise KeyError, key: key, term: original
   end
 
   @doc """
-  Updates the `key` in `keywords` with the given function.
+  Updates the value under `key` in `keywords` using the given function.
 
   If the `key` does not exist, it inserts the given `default` value.
+  Does not pass the `default` value through the update function.
 
-  If there are duplicated keys, they are all removed and only the first one
-  is updated.
-
-  The default value will not be passed through the update function.
+  Removes all duplicate keys and only updates the first one.
 
   ## Examples
 
@@ -948,14 +1081,14 @@ defmodule Keyword do
   end
 
   @doc """
-  Takes all entries corresponding to the given keys and extracts them into a
+  Takes all entries corresponding to the given `keys` and extracts them into a
   separate keyword list.
 
   Returns a tuple with the new list and the old list with removed keys.
 
-  Keys for which there are no entries in the keyword list are ignored.
+  Ignores keys for which there are no entries in the keyword list.
 
-  Entries with duplicated keys end up in the same keyword list.
+  Entries with duplicate keys end up in the same keyword list.
 
   ## Examples
 
@@ -980,10 +1113,10 @@ defmodule Keyword do
   end
 
   @doc """
-  Takes all entries corresponding to the given keys and returns them in a new
+  Takes all entries corresponding to the given `keys` and returns them as a new
   keyword list.
 
-  Duplicated keys are preserved in the new keyword list.
+  Preserves duplicate keys in the new keyword list.
 
   ## Examples
 
@@ -999,12 +1132,14 @@ defmodule Keyword do
   end
 
   @doc """
-  Drops the given keys from the keyword list.
+  Drops the given `keys` from the keyword list.
 
-  Duplicated keys are preserved in the new keyword list.
+  Removes duplicate keys from the new keyword list.
 
   ## Examples
 
+      iex> Keyword.drop([a: 1, a: 2], [:a])
+      []
       iex> Keyword.drop([a: 1, b: 2, c: 3], [:b, :d])
       [a: 1, c: 3]
       iex> Keyword.drop([a: 1, b: 2, b: 3, c: 3, a: 5], [:b, :d])
@@ -1013,7 +1148,7 @@ defmodule Keyword do
   """
   @spec drop(t, [key]) :: t
   def drop(keywords, keys) when is_list(keywords) and is_list(keys) do
-    :lists.filter(fn {key, _} -> key not in keys end, keywords)
+    :lists.filter(fn {k, _} -> k not in keys end, keywords)
   end
 
   @doc """
@@ -1021,11 +1156,10 @@ defmodule Keyword do
 
   It returns a tuple where the first element is the first value for `key` and the
   second element is a keyword list with all entries associated with `key` removed.
-  If the `key` is not present in the keyword list, `{default, keyword_list}` is
-  returned.
+  If the `key` is not present in the keyword list, it returns `{default, keyword_list}`.
 
   If you don't want to remove all the entries associated with `key` use `pop_first/3`
-  instead, that function will remove only the first entry.
+  instead, which will remove only the first entry.
 
   ## Examples
 
@@ -1051,7 +1185,7 @@ defmodule Keyword do
   Returns the first value for `key` and removes all associated entries in the keyword list,
   raising if `key` is not present.
 
-  This function behaves like `pop/3`, but raises in cases the `key` is not present in the
+  This function behaves like `pop/3`, but raises in case the `key` is not present in the
   given `keywords`.
 
   ## Examples
@@ -1078,11 +1212,10 @@ defmodule Keyword do
 
   It returns a tuple where the first element is a list of values for `key` and the
   second element is a keyword list with all entries associated with `key` removed.
-  If the `key` is not present in the keyword list, `{[], keyword_list}` is
-  returned.
+  If the `key` is not present in the keyword list, it returns `{[], keyword_list}`.
 
   If you don't want to remove all the entries associated with `key` use `pop_first/3`
-  instead, that function will remove only the first entry.
+  instead, which will remove only the first entry.
 
   ## Examples
 
@@ -1113,10 +1246,9 @@ defmodule Keyword do
   Lazily returns and removes all values associated with `key` in the keyword list.
 
   This is useful if the default value is very expensive to calculate or
-  generally difficult to setup and teardown again.
+  generally difficult to set up and tear down again.
 
-  All duplicated keys are removed. See `pop_first/3` for
-  removing only the first entry.
+  Removes all duplicate keys. See `pop_first/3` for removing only the first entry.
 
   ## Examples
 
@@ -1135,18 +1267,15 @@ defmodule Keyword do
   def pop_lazy(keywords, key, fun)
       when is_list(keywords) and is_atom(key) and is_function(fun, 0) do
     case fetch(keywords, key) do
-      {:ok, value} ->
-        {value, delete(keywords, key)}
-
-      :error ->
-        {fun.(), keywords}
+      {:ok, value} -> {value, delete(keywords, key)}
+      :error -> {fun.(), keywords}
     end
   end
 
   @doc """
   Returns and removes the first value associated with `key` in the keyword list.
 
-  Duplicated keys are not removed.
+  Keeps duplicate keys in the resulting keyword list.
 
   ## Examples
 
@@ -1178,13 +1307,76 @@ defmodule Keyword do
 
   """
   @spec to_list(t) :: t
-  def to_list(keyword) when is_list(keyword) do
-    keyword
+  def to_list(keywords) when is_list(keywords) do
+    keywords
   end
 
   @doc false
   @deprecated "Use Kernel.length/1 instead"
-  def size(keyword) do
-    length(keyword)
+  def size(keywords) do
+    length(keywords)
+  end
+
+  @doc """
+  Returns a keyword list containing only the entries from `keywords`
+  for which the function `fun` returns a truthy value.
+
+  See also `reject/2` which discards all entries where the function
+  returns a truthy value.
+
+  ## Examples
+
+      iex> Keyword.filter([one: 1, two: 2, three: 3], fn {_key, val} -> rem(val, 2) == 1 end)
+      [one: 1, three: 3]
+
+  """
+  @doc since: "1.13.0"
+  @spec filter(t, ({key, value} -> as_boolean(term))) :: t
+  def filter(keywords, fun) when is_list(keywords) and is_function(fun, 1) do
+    do_filter(keywords, fun)
+  end
+
+  defp do_filter([], _fun), do: []
+
+  defp do_filter([{_, _} = entry | entries], fun) do
+    if fun.(entry) do
+      [entry | do_filter(entries, fun)]
+    else
+      do_filter(entries, fun)
+    end
+  end
+
+  @doc """
+  Returns a keyword list excluding the entries from `keywords`
+  for which the function `fun` returns a truthy value.
+
+  See also `filter/2`.
+
+  ## Examples
+
+      iex> Keyword.reject([one: 1, two: 2, three: 3], fn {_key, val} -> rem(val, 2) == 1 end)
+      [two: 2]
+
+  """
+  @doc since: "1.13.0"
+  @spec reject(t, ({key, value} -> as_boolean(term))) :: t
+  def reject(keywords, fun) when is_list(keywords) and is_function(fun, 1) do
+    do_reject(keywords, fun)
+  end
+
+  defp do_reject([], _fun), do: []
+
+  defp do_reject([{_, _} = entry | entries], fun) do
+    if fun.(entry) do
+      do_reject(entries, fun)
+    else
+      [entry | do_reject(entries, fun)]
+    end
+  end
+
+  @doc false
+  @deprecated "Use Keyword.new/2 instead"
+  def map(keywords, fun) when is_list(keywords) do
+    Enum.map(keywords, fn {k, v} -> {k, fun.({k, v})} end)
   end
 end

lib/elixir/lib/list.ex

@@ -230,7 +230,7 @@ defmodule List do
 
   @doc """
   Folds (reduces) the given list from the left with
-  a function. Requires an accumulator.
+  a function. Requires an accumulator, which can be any value.
 
   ## Examples
 
@@ -239,6 +239,9 @@ defmodule List do
 
       iex> List.foldl([1, 2, 3, 4], 0, fn x, acc -> x - acc end)
       2
+      
+      iex> List.foldl([1, 2, 3], {0, 0}, fn x, {a1, a2} -> {a1 + x, a2 - x} end)
+      {6, -6}
 
   """
   @spec foldl([elem], acc, (elem, acc -> acc)) :: acc when elem: var, acc: var
@@ -248,12 +251,15 @@ defmodule List do
 
   @doc """
   Folds (reduces) the given list from the right with
-  a function. Requires an accumulator.
+  a function. Requires an accumulator, which can be any value.
 
   ## Examples
 
       iex> List.foldr([1, 2, 3, 4], 0, fn x, acc -> x - acc end)
       -2
+      
+      iex> List.foldr([1, 2, 3, 4], %{sum: 0, product: 1}, fn x, %{sum: a1, product: a2} -> %{sum: a1 + x, product: a2 * x} end)
+      %{product: 24, sum: 10}
 
   """
   @spec foldr([elem], acc, (elem, acc -> acc)) :: acc when elem: var, acc: var
@@ -335,10 +341,40 @@ defmodule List do
 
   """
   @spec keyfind([tuple], any, non_neg_integer, any) :: any
-  def keyfind(list, key, position, default \\ nil) do
+  def keyfind(list, key, position, default \\ nil) when is_integer(position) do
     :lists.keyfind(key, position + 1, list) || default
   end
 
+  @doc """
+  Receives a list of tuples and returns the first tuple
+  where the element at `position` in the tuple matches the
+  given `key`.
+
+  If no matching tuple is found, an error is raised.
+
+  ## Examples
+
+      iex> List.keyfind!([a: 1, b: 2], :a, 0)
+      {:a, 1}
+
+      iex> List.keyfind!([a: 1, b: 2], 2, 1)
+      {:b, 2}
+
+      iex> List.keyfind!([a: 1, b: 2], :c, 0)
+      ** (KeyError) key :c at position 0 not found in: [a: 1, b: 2]
+
+  """
+  @doc since: "1.13.0"
+  @spec keyfind!([tuple], any, non_neg_integer) :: any
+  def keyfind!(list, key, position) when is_integer(position) do
+    :lists.keyfind(key, position + 1, list) ||
+      raise KeyError,
+        key: key,
+        term: list,
+        message:
+          "key #{inspect(key)} at position #{inspect(position)} not found in: #{inspect(list)}"
+  end
+
   @doc """
   Receives a list of tuples and returns `true` if there is
   a tuple where the element at `position` in the tuple matches
@@ -357,7 +393,7 @@ defmodule List do
 
   """
   @spec keymember?([tuple], any, non_neg_integer) :: boolean
-  def keymember?(list, key, position) do
+  def keymember?(list, key, position) when is_integer(position) do
     :lists.keymember(key, position + 1, list)
   end
 
@@ -375,7 +411,7 @@ defmodule List do
 
   """
   @spec keyreplace([tuple], any, non_neg_integer, tuple) :: [tuple]
-  def keyreplace(list, key, position, new_tuple) do
+  def keyreplace(list, key, position, new_tuple) when is_integer(position) do
     :lists.keyreplace(key, position + 1, list, new_tuple)
   end
 
@@ -393,7 +429,7 @@ defmodule List do
 
   """
   @spec keysort([tuple], non_neg_integer) :: [tuple]
-  def keysort(list, position) do
+  def keysort(list, position) when is_integer(position) do
     :lists.keysort(position + 1, list)
   end
 
@@ -413,7 +449,7 @@ defmodule List do
 
   """
   @spec keystore([tuple], any, non_neg_integer, tuple) :: [tuple, ...]
-  def keystore(list, key, position, new_tuple) do
+  def keystore(list, key, position, new_tuple) when is_integer(position) do
     :lists.keystore(key, position + 1, list, new_tuple)
   end
 
@@ -435,7 +471,7 @@ defmodule List do
 
   """
   @spec keydelete([tuple], any, non_neg_integer) :: [tuple]
-  def keydelete(list, key, position) do
+  def keydelete(list, key, position) when is_integer(position) do
     :lists.keydelete(key, position + 1, list)
   end
 
@@ -459,7 +495,7 @@ defmodule List do
 
   """
   @spec keytake([tuple], any, non_neg_integer) :: {tuple, [tuple]} | nil
-  def keytake(list, key, position) do
+  def keytake(list, key, position) when is_integer(position) do
     case :lists.keytake(key, position + 1, list) do
       {:value, element, list} -> {element, list}
       false -> nil

lib/elixir/lib/macro.ex

@@ -53,7 +53,7 @@ defmodule Macro do
   ## Custom Sigils
 
   Macros are also commonly used to implement custom sigils. To create a custom
-  sigil, define a function with the name `sigil_{identifier}` that takes two
+  sigil, define a macro with the name `sigil_{identifier}` that takes two
   arguments. The first argument will be the string, the second will be a charlist
   containing any modifiers. If the sigil is lower case (such as `sigil_x`) then
   the string argument will allow interpolation. If the sigil is upper case
@@ -167,9 +167,9 @@ defmodule Macro do
       and charlists as a string (such as `"{"`, `"/"`, `"'"`, and the like)
     * `:format` - set to `:keyword` when an atom is defined as a keyword
     * `:do` - contains metadata about the `do` location in a function call with
-      `do/end` blocks (when `:token_metadata` is true)
+      `do`-`end` blocks (when `:token_metadata` is true)
     * `:end` - contains metadata about the `end` location in a function call with
-      `do/end` blocks (when `:token_metadata` is true)
+      `do`-`end` blocks (when `:token_metadata` is true)
     * `:end_of_expression` - denotes when the end of expression effectively
       happens. Available for all expressions except the last one inside a
       `__block__` (when `:token_metadata` is true)
@@ -490,6 +490,23 @@ defmodule Macro do
 
   @doc """
   Performs a depth-first, pre-order traversal of quoted expressions.
+
+  Returns a new ast where each node is the result of invoking `fun` on each
+  corresponding node of `ast`.
+
+  ## Examples
+
+      iex> ast = quote do: 5 + 3 * 7
+      iex> new_ast = Macro.prewalk(ast, fn
+      ...>   {:+, meta, children} -> {:*, meta, children}
+      ...>   {:*, meta, children} -> {:+, meta, children}
+      ...>   other -> other
+      ...> end)
+      iex> Code.eval_quoted(ast)
+      {26, []}
+      iex> Code.eval_quoted(new_ast)
+      {50, []}
+
   """
   @spec prewalk(t, (t -> t)) :: t
   def prewalk(ast, fun) when is_function(fun, 1) do
@@ -587,8 +604,7 @@ defmodule Macro do
 
     * `:prune_metadata` - when true, removes metadata from escaped AST
       nodes. Note this option changes the semantics of escaped code and
-      it should only be used when escaping ASTs, never values. Defaults
-      to false.
+      it should only be used when escaping ASTs. Defaults to false.
 
       As an example, `ExUnit` stores the AST of every assertion, so when
       an assertion fails we can show code snippets to users. Without this
@@ -596,7 +612,8 @@ defmodule Macro do
       MD5 of the module bytecode, because the AST contains metadata,
       such as counters, specific to the compilation environment. By pruning
       the metadata, we ensure that the module is deterministic and reduce
-      the amount of data `ExUnit` needs to keep around.
+      the amount of data `ExUnit` needs to keep around. Only the minimal
+      amount of metadata is kept, such as `:line` and `:no_parens`.
 
   ## Comparison to `Kernel.SpecialForms.quote/2`
 
@@ -627,7 +644,7 @@ defmodule Macro do
   @spec escape(term, keyword) :: t()
   def escape(expr, opts \\ []) do
     unquote = Keyword.get(opts, :unquote, false)
-    kind = if Keyword.get(opts, :prune_metadata, false), do: :prune_metadata, else: :default
+    kind = if Keyword.get(opts, :prune_metadata, false), do: :prune_metadata, else: :none
     :elixir_quote.escape(expr, kind, unquote)
   end
 
@@ -644,7 +661,9 @@ defmodule Macro do
   dependency on the given struct.
   """
   @doc since: "1.8.0"
-  @spec struct!(module, Macro.Env.t()) :: %{__struct__: module} when module: module()
+  @spec struct!(module, Macro.Env.t()) ::
+          %{required(:__struct__) => module, optional(atom) => any}
+        when module: module()
   def struct!(module, env) when is_atom(module) do
     if module == env.module do
       Module.get_attribute(module, :__struct__)
@@ -700,6 +719,125 @@ defmodule Macro do
 
   defp find_invalid(other), do: {:error, other}
 
+  @doc """
+  Returns an enumerable that traverses the  `ast` in depth-first,
+  pre-order traversal.
+
+  ## Examples
+
+      iex> ast = quote do: foo(1, "abc")
+      iex> Enum.map(Macro.prewalker(ast), & &1)
+      [{:foo, [], [1, "abc"]}, 1, "abc"]
+
+  """
+  @doc since: "1.13.0"
+  def prewalker(ast) do
+    &prewalker([ast], &1, &2)
+  end
+
+  defp prewalker(_buffer, {:halt, acc}, _fun) do
+    {:halted, acc}
+  end
+
+  defp prewalker(buffer, {:suspend, acc}, fun) do
+    {:suspended, acc, &prewalker(buffer, &1, fun)}
+  end
+
+  defp prewalker([], {:cont, acc}, _fun) do
+    {:done, acc}
+  end
+
+  defp prewalker([{left, right} = node | tail], {:cont, acc}, fun) do
+    prewalker([left, right | tail], fun.(node, acc), fun)
+  end
+
+  defp prewalker([{left, meta, right} = node | tail], {:cont, acc}, fun)
+       when is_atom(left) and is_list(meta) do
+    if is_atom(right) do
+      prewalker(tail, fun.(node, acc), fun)
+    else
+      prewalker(right ++ tail, fun.(node, acc), fun)
+    end
+  end
+
+  defp prewalker([{left, meta, right} = node | tail], {:cont, acc}, fun) when is_list(meta) do
+    if is_atom(right) do
+      prewalker([left | tail], fun.(node, acc), fun)
+    else
+      prewalker([left | right] ++ tail, fun.(node, acc), fun)
+    end
+  end
+
+  defp prewalker([list | tail], {:cont, acc}, fun) when is_list(list) do
+    prewalker(list ++ tail, fun.(list, acc), fun)
+  end
+
+  defp prewalker([head | tail], {:cont, acc}, fun) do
+    prewalker(tail, fun.(head, acc), fun)
+  end
+
+  @doc """
+  Returns an enumerable that traverses the  `ast` in depth-first,
+  post-order traversal.
+
+  ## Examples
+
+      iex> ast = quote do: foo(1, "abc")
+      iex> Enum.map(Macro.postwalker(ast), & &1)
+      [1, "abc", {:foo, [], [1, "abc"]}]
+
+  """
+  @doc since: "1.13.0"
+  def postwalker(ast) do
+    &postwalker([ast], make_ref(), &1, &2)
+  end
+
+  defp postwalker(_buffer, _ref, {:halt, acc}, _fun) do
+    {:halted, acc}
+  end
+
+  defp postwalker(buffer, ref, {:suspend, acc}, fun) do
+    {:suspended, acc, &postwalker(buffer, ref, &1, fun)}
+  end
+
+  defp postwalker([], _ref, {:cont, acc}, _fun) do
+    {:done, acc}
+  end
+
+  defp postwalker([{ref, head} | tail], ref, {:cont, acc}, fun) do
+    postwalker(tail, ref, fun.(head, acc), fun)
+  end
+
+  defp postwalker([{left, right} = node | tail], ref, {:cont, acc}, fun) do
+    postwalker([right, {ref, node} | tail], ref, fun.(left, acc), fun)
+  end
+
+  defp postwalker([{left, meta, right} = node | tail], ref, {:cont, acc}, fun)
+       when is_atom(left) and is_list(meta) do
+    if is_atom(right) do
+      postwalker(tail, ref, fun.(node, acc), fun)
+    else
+      postwalker(right ++ [{ref, node} | tail], ref, {:cont, acc}, fun)
+    end
+  end
+
+  defp postwalker([{left, meta, right} = node | tail], ref, cont_acc, fun)
+       when is_list(meta) do
+    if is_atom(right) do
+      postwalker([left, {ref, node} | tail], ref, cont_acc, fun)
+    else
+      postwalker([left | right] ++ [{ref, node} | tail], ref, cont_acc, fun)
+    end
+  end
+
+  defp postwalker([list | tail], ref, cont_acc, fun) when is_list(list) do
+    postwalker(list ++ [{ref, list} | tail], ref, cont_acc, fun)
+  end
+
+  defp postwalker([head | tail], ref, {:cont, acc}, fun) do
+    postwalker(tail, ref, fun.(head, acc), fun)
+  end
+
   @doc ~S"""
   Unescapes the given chars.
 
@@ -795,6 +933,25 @@ defmodule Macro do
   @doc """
   Converts the given expression AST to a string.
 
+  This function discards all formatting of the original code.
+  See `Code.quoted_to_algebra/2` as a lower level function
+  with more control around formatting.
+
+  ## Examples
+
+      iex> Macro.to_string(quote(do: foo.bar(1, 2, 3)))
+      "foo.bar(1, 2, 3)"
+
+  """
+  @spec to_string(t()) :: String.t()
+  def to_string(tree) do
+    doc = Inspect.Algebra.format(Code.quoted_to_algebra(tree), 98)
+    IO.iodata_to_binary(doc)
+  end
+
+  @doc """
+  Converts the given expression AST to a string.
+
   The given `fun` is called for every node in the AST with two arguments: the
   AST of the node being printed and the string representation of that same
   node. The return value of this function is used as the final string
@@ -804,19 +961,17 @@ defmodule Macro do
 
   ## Examples
 
-      iex> Macro.to_string(quote(do: foo.bar(1, 2, 3)))
-      "foo.bar(1, 2, 3)"
-
-      iex> Macro.to_string(quote(do: 1 + 2), fn
-      ...>   1, _string -> "one"
-      ...>   2, _string -> "two"
-      ...>   _ast, string -> string
-      ...> end)
-      "one + two"
+      Macro.to_string(quote(do: 1 + 2), fn
+        1, _string -> "one"
+        2, _string -> "two"
+        _ast, string -> string
+      end)
+      #=> "one + two"
 
   """
+  @deprecated "Use Macro.to_string/1 instead"
   @spec to_string(t(), (t(), String.t() -> String.t())) :: String.t()
-  def to_string(tree, fun \\ fn _ast, string -> string end)
+  def to_string(tree, fun)
 
   # Variables
   def to_string({var, _, context} = ast, fun) when is_atom(var) and is_atom(context) do
@@ -1087,8 +1242,6 @@ defmodule Macro do
           "\#{" <> to_string(arg, fun) <> "}"
 
         binary when is_binary(binary) ->
-          binary = inspect_no_limit(binary)
-          binary = binary_part(binary, 1, byte_size(binary) - 2)
           escape_sigil(binary, left)
       end)
 
@@ -1143,7 +1296,7 @@ defmodule Macro do
     :error
   end
 
-  defp op_call({:..//, _, [left, middle, right]} = ast, fun) do
+  defp op_call({:"..//", _, [left, middle, right]} = ast, fun) do
     left = op_to_string(left, fun, :.., :left)
     middle = op_to_string(middle, fun, :.., :right)
     right = op_to_string(right, fun, :"//", :right)
@@ -1443,7 +1596,7 @@ defmodule Macro do
   end
 
   defp do_expand_once({:__aliases__, meta, _} = original, env) do
-    case :elixir_aliases.expand(original, env) do
+    case :elixir_aliases.expand_or_concat(original, env) do
       receiver when is_atom(receiver) ->
         :elixir_env.trace({:alias_reference, meta, receiver}, env)
         {receiver, true}
@@ -1502,7 +1655,10 @@ defmodule Macro do
           []
         end
 
-      expand = :elixir_dispatch.expand_import(meta, {atom, length(args)}, args, env, extra, true)
+      s = :elixir_env.env_to_ex(env)
+
+      expand =
+        :elixir_dispatch.expand_import(meta, {atom, length(args)}, args, s, env, extra, true)
 
       case expand do
         {:ok, receiver, quoted} ->
@@ -1533,7 +1689,9 @@ defmodule Macro do
         {original, false}
 
       true ->
-        expand = :elixir_dispatch.expand_require(meta, receiver, {right, length(args)}, args, env)
+        s = :elixir_env.env_to_ex(env)
+        name_arity = {right, length(args)}
+        expand = :elixir_dispatch.expand_require(meta, receiver, name_arity, args, s, env)
 
         case expand do
           {:ok, receiver, quoted} ->
@@ -1560,9 +1718,22 @@ defmodule Macro do
 
   @doc """
   Returns `true` if the given name and arity is an operator.
+
+  ## Examples
+
+      iex> Macro.operator?(:not_an_operator, 3)
+      false
+      iex> Macro.operator?(:+, 1)
+      true
+      iex> Macro.operator?(:++, 2)
+      true
+      iex> Macro.operator?(:..//, 3)
+      true
+
   """
   @doc since: "1.7.0"
   @spec operator?(name :: atom(), arity()) :: boolean()
+  def operator?(:"..//", 3), do: true
   def operator?(name, 2) when is_atom(name), do: Identifier.binary_op(name) != :error
   def operator?(name, 1) when is_atom(name), do: Identifier.unary_op(name) != :error
   def operator?(name, arity) when is_atom(name) and is_integer(arity), do: false
@@ -1570,7 +1741,7 @@ defmodule Macro do
   @doc """
   Returns `true` if the given quoted expression represents a quoted literal.
 
-  Atoms, numbers, and functions are always literals. Binaries, lists, tuples,
+  Atoms and numbers are always literals. Binaries, lists, tuples,
   maps, and structs are only literals if all of their terms are also literals.
 
   ## Examples
@@ -1605,9 +1776,7 @@ defmodule Macro do
   def quoted_literal?({:{}, _, args}), do: quoted_literal?(args)
   def quoted_literal?({left, right}), do: quoted_literal?(left) and quoted_literal?(right)
   def quoted_literal?(list) when is_list(list), do: Enum.all?(list, &quoted_literal?/1)
-
-  def quoted_literal?(term),
-    do: is_atom(term) or is_number(term) or is_binary(term) or is_function(term)
+  def quoted_literal?(term), do: is_atom(term) or is_number(term) or is_binary(term)
 
   @doc """
   Receives an AST node and expands it until it can no longer

lib/elixir/lib/macro/env.ex

@@ -21,8 +21,6 @@ defmodule Macro.Env do
 
   It contains the following fields:
 
-    * `aliases` -  a list of two-element tuples, where the first
-      element is the aliased name and the second one the actual name
     * `context` - the context of the environment; it can be `nil`
       (default context), `:guard` (inside a guard) or `:match` (inside a match)
     * `context_modules` - a list of modules defined in the current context
@@ -30,66 +28,44 @@ defmodule Macro.Env do
     * `function` - a tuple as `{atom, integer}`, where the first
       element is the function name and the second its arity; returns
       `nil` if not inside a function
-    * `functions` - a list of functions imported from each module
     * `line` - the current line as an integer
-    * `macro_aliases` - a list of aliases defined inside the current macro
-    * `macros` - a list of macros imported from each module
     * `module` - the current module name
-    * `requires` - the list of required modules
 
   The following fields are private to Elixir's macro expansion mechanism and
   must not be accessed directly:
 
-    * `contextual_vars`
-    * `current_vars`
+    * `aliases`
+    * `functions`
+    * `macro_aliases`
+    * `macros`
     * `lexical_tracker`
-    * `prematch_vars`
+    * `requires`
     * `tracers`
-    * `unused_vars`
-
-  The following fields are deprecated and must not be accessed or relied on:
-
-    * `vars` - a list keeping all defined variables as `{var, context}`
+    * `versioned_vars`
 
   """
 
-  @type aliases :: [{module, module}]
   @type context :: :match | :guard | nil
   @type context_modules :: [module]
   @type file :: binary
-  @type functions :: [{module, [name_arity]}]
-  @type lexical_tracker :: pid | nil
   @type line :: non_neg_integer
-  @type macro_aliases :: [{module, {term, module}}]
-  @type macros :: [{module, [name_arity]}]
   @type name_arity :: {atom, arity}
-  @type requires :: [module]
   @type variable :: {atom, atom | term}
 
-  @typep contextual_vars :: [atom]
-  @typep current_vars ::
-           {%{optional(variable) => {var_version, var_type}},
-            %{optional(variable) => {var_version, var_type}} | false}
-  @typep unused_vars ::
-           {%{optional({atom, var_version}) => non_neg_integer | false}, non_neg_integer}
-  @typep prematch_vars ::
-           {%{optional(variable) => {var_version, var_type}}, non_neg_integer}
-           | :warn
-           | :raise
-           | :pin
-           | :apply
+  @typep aliases :: [{module, module}]
+  @typep functions :: [{module, [name_arity]}]
+  @typep lexical_tracker :: pid | nil
+  @typep macro_aliases :: [{module, {term, module}}]
+  @typep macros :: [{module, [name_arity]}]
+  @typep requires :: [module]
   @typep tracers :: [module]
-  @typep var_type :: :term
-  @typep var_version :: non_neg_integer
-  @typep vars :: [variable]
+  @typep versioned_vars :: %{optional(variable) => var_version :: non_neg_integer}
 
   @type t :: %{
           __struct__: __MODULE__,
           aliases: aliases,
           context: context,
           context_modules: context_modules,
-          contextual_vars: contextual_vars,
-          current_vars: current_vars,
           file: file,
           function: name_arity | nil,
           functions: functions,
@@ -98,22 +74,19 @@ defmodule Macro.Env do
           macro_aliases: macro_aliases,
           macros: macros,
           module: module,
-          prematch_vars: prematch_vars,
-          unused_vars: unused_vars,
           requires: requires,
           tracers: tracers,
-          vars: vars
+          versioned_vars: versioned_vars
         }
 
-  # TODO: Remove :vars field on v2.0
+  # Define the __struct__ callbacks by hand for bootstrap reasons.
+  @doc false
   def __struct__ do
     %{
       __struct__: __MODULE__,
       aliases: [],
       context: nil,
       context_modules: [],
-      contextual_vars: [],
-      current_vars: {%{}, %{}},
       file: "nofile",
       function: nil,
       functions: [],
@@ -122,14 +95,13 @@ defmodule Macro.Env do
       macro_aliases: [],
       macros: [],
       module: nil,
-      prematch_vars: :warn,
       requires: [],
       tracers: [],
-      unused_vars: {%{}, 0},
-      vars: []
+      versioned_vars: %{}
     }
   end
 
+  @doc false
   def __struct__(kv) do
     Enum.reduce(kv, __struct__(), fn {k, v}, acc -> :maps.update(k, v, acc) end)
   end
@@ -146,19 +118,30 @@ defmodule Macro.Env do
   @spec vars(t) :: [variable]
   def vars(env)
 
-  def vars(%{__struct__: Macro.Env, current_vars: {read, _}}) do
-    Map.keys(read)
+  def vars(%{__struct__: Macro.Env, versioned_vars: vars}) do
+    Map.keys(vars)
   end
 
   @doc """
   Checks if a variable belongs to the environment.
+
+  ## Examples
+
+      iex> x = 13
+      iex> x
+      13
+      iex> Macro.Env.has_var?(__ENV__, {:x, nil})
+      true
+      iex> Macro.Env.has_var?(__ENV__, {:unknown, nil})
+      false
+
   """
   @doc since: "1.7.0"
   @spec has_var?(t, variable) :: boolean()
   def has_var?(env, var)
 
-  def has_var?(%{__struct__: Macro.Env, current_vars: {read, _}}, var) do
-    Map.has_key?(read, var)
+  def has_var?(%{__struct__: Macro.Env, versioned_vars: vars}, var) do
+    Map.has_key?(vars, var)
   end
 
   @doc """
@@ -172,16 +155,117 @@ defmodule Macro.Env do
     [file: file, line: line]
   end
 
+  @doc """
+  Fetches the alias for the given atom.
+
+  Returns `{:ok, alias}` if the alias exists, `:error` 
+  otherwise.
+
+  ## Examples
+
+      iex> alias Foo.Bar, as: Baz
+      iex> Baz
+      Foo.Bar
+      iex> Macro.Env.fetch_alias(__ENV__, :Baz)
+      {:ok, Foo.Bar}
+      iex> Macro.Env.fetch_alias(__ENV__, :Unknown)
+      :error
+
+  """
+  @doc since: "1.13.0"
+  @spec fetch_alias(t, atom) :: {:ok, atom} | :error
+  def fetch_alias(%{__struct__: Macro.Env, aliases: aliases}, atom) when is_atom(atom),
+    do: Keyword.fetch(aliases, :"Elixir.#{atom}")
+
+  @doc """
+  Fetches the macro alias for the given atom.
+
+  Returns `{:ok, macro_alias}` if the alias exists, `:error`
+  otherwise.
+
+  A macro alias is only used inside quoted expansion. See
+  `fetch_alias/2` for a more general example.
+  """
+  @doc since: "1.13.0"
+  @spec fetch_macro_alias(t, atom) :: {:ok, atom} | :error
+  def fetch_macro_alias(%{__struct__: Macro.Env, macro_aliases: aliases}, atom)
+      when is_atom(atom),
+      do: Keyword.fetch(aliases, :"Elixir.#{atom}")
+
+  @doc """
+  Returns the modules from which the given `{name, arity}` was
+  imported.
+
+  It returns a list of two element tuples in the shape of
+  `{:function | :macro, module}`. The elements in the list
+  are in no particular order and the order is not guaranteed.
+
+  ## Examples
+
+      iex> Macro.Env.lookup_import(__ENV__, {:duplicate, 2})
+      []
+      iex> import Tuple, only: [duplicate: 2], warn: false
+      iex> Macro.Env.lookup_import(__ENV__, {:duplicate, 2})
+      [{:function, Tuple}]
+      iex> import List, only: [duplicate: 2], warn: false
+      iex> Macro.Env.lookup_import(__ENV__, {:duplicate, 2})
+      [{:function, List}, {:function, Tuple}]
+
+      iex> Macro.Env.lookup_import(__ENV__, {:def, 1})
+      [{:macro, Kernel}]
+
+  """
+  @doc since: "1.13.0"
+  @spec lookup_import(t, name_arity) :: [{:function | :macro, module}]
+  def lookup_import(
+        %{__struct__: Macro.Env, functions: functions, macros: macros},
+        {name, arity} = pair
+      )
+      when is_atom(name) and is_integer(arity) do
+    f = for {mod, pairs} <- functions, :ordsets.is_element(pair, pairs), do: {:function, mod}
+    m = for {mod, pairs} <- macros, :ordsets.is_element(pair, pairs), do: {:macro, mod}
+    f ++ m
+  end
+
+  @doc """
+  Returns true if the given module has been required.
+
+  ## Examples
+
+      iex> Macro.Env.required?(__ENV__, Integer)
+      false
+      iex> require Integer
+      iex> Macro.Env.required?(__ENV__, Integer)
+      true
+
+      iex> Macro.Env.required?(__ENV__, Kernel)
+      true
+  """
+  @doc since: "1.13.0"
+  @spec required?(t, module) :: boolean
+  def required?(%{__struct__: Macro.Env, requires: requires}, mod) when is_atom(mod),
+    do: mod in requires
+
+  @doc """
+  Prepend a tracer to the list of tracers in the environment.
+
+  ## Examples
+
+      Macro.Env.prepend_tracer(__ENV__, MyCustomTracer)
+
+  """
+  @doc since: "1.13.0"
+  @spec prepend_tracer(t, module) :: t
+  def prepend_tracer(%{__struct__: Macro.Env, tracers: tracers} = env, tracer) do
+    %{env | tracers: [tracer | tracers]}
+  end
+
   @doc """
   Returns a `Macro.Env` in the match context.
   """
   @spec to_match(t) :: t
-  def to_match(%{__struct__: Macro.Env, context: :match} = env) do
-    env
-  end
-
-  def to_match(%{__struct__: Macro.Env, current_vars: {read, _}, unused_vars: {_, counter}} = env) do
-    %{env | context: :match, prematch_vars: {read, counter}}
+  def to_match(%{__struct__: Macro.Env} = env) do
+    %{env | context: :match}
   end
 
   @doc """

lib/elixir/lib/map.ex

@@ -214,22 +214,29 @@ defmodule Map do
 
   """
   @spec new(Enumerable.t(), (term -> {key, value})) :: map
-  def new(enumerable, transform) when is_function(transform, 1) do
+  def new(enumerable, transform)
+  def new(%_{} = enumerable, transform), do: new_from_enum(enumerable, transform)
+  def new(%{} = map, transform), do: new_from_map(map, transform)
+  def new(enumerable, transform), do: new_from_enum(enumerable, transform)
+
+  defp new_from_map(map, transform) when is_function(transform, 1) do
+    iter = :maps.iterator(map)
+    next = :maps.next(iter)
+    :maps.from_list(do_map(next, transform))
+  end
+
+  defp do_map(:none, _fun), do: []
+
+  defp do_map({key, value, iter}, transform) do
+    [transform.({key, value}) | do_map(:maps.next(iter), transform)]
+  end
+
+  defp new_from_enum(enumerable, transform) when is_function(transform, 1) do
     enumerable
-    |> Enum.to_list()
-    |> new_transform(transform, [])
-  end
-
-  defp new_transform([], _fun, acc) do
-    acc
-    |> :lists.reverse()
+    |> Enum.map(transform)
     |> :maps.from_list()
   end
 
-  defp new_transform([element | rest], fun, acc) do
-    new_transform(rest, fun, [fun.(element) | acc])
-  end
-
   @doc """
   Returns whether the given `key` exists in the given `map`.
 
@@ -328,7 +335,7 @@ defmodule Map do
   def replace(map, key, value) do
     case map do
       %{^key => _value} ->
-        put(map, key, value)
+        %{map | key => value}
 
       %{} ->
         map
@@ -624,7 +631,7 @@ defmodule Map do
   def update(map, key, default, fun) when is_function(fun, 1) do
     case map do
       %{^key => value} ->
-        put(map, key, fun.(value))
+        %{map | key => fun.(value)}
 
       %{} ->
         put(map, key, default)
@@ -820,7 +827,7 @@ defmodule Map do
   @spec update!(map, key, (existing_value :: value -> new_value :: value)) :: map
   def update!(map, key, fun) when is_function(fun, 1) do
     value = fetch!(map, key)
-    put(map, key, fun.(value))
+    %{map | key => fun.(value)}
   end
 
   @doc """
@@ -905,7 +912,7 @@ defmodule Map do
 
     case fun.(value) do
       {get, update} ->
-        {get, put(map, key, update)}
+        {get, %{map | key => update}}
 
       :pop ->
         {value, delete(map, key)}
@@ -981,4 +988,79 @@ defmodule Map do
   def size(map) do
     map_size(map)
   end
+
+  @doc """
+  Returns a map containing only those pairs from `map`
+  for which `fun` returns a truthy value.
+
+  `fun` receives the key and value of each of the
+  elements in the map as a key-value pair.
+
+  See also `reject/2` which discards all elements where the
+  function returns a truthy value.
+
+  > Note: if you find yourself doing multiple calls to `Map.filter/2`
+  > and `Map.reject/2` in a pipeline, it is likely more efficient
+  > to use `Enum.map/2` and `Enum.filter/2` instead and convert to
+  > a map at the end using `Map.new/1`.
+
+  ## Examples
+
+      iex> Map.filter(%{one: 1, two: 2, three: 3}, fn {_key, val} -> rem(val, 2) == 1 end)
+      %{one: 1, three: 3}
+
+  """
+  @doc since: "1.13.0"
+  @spec filter(map, ({key, value} -> as_boolean(term))) :: map
+  def filter(map, fun) when is_map(map) and is_function(fun, 1) do
+    iter = :maps.iterator(map)
+    next = :maps.next(iter)
+    :maps.from_list(do_filter(next, fun))
+  end
+
+  defp do_filter(:none, _fun), do: []
+
+  defp do_filter({key, value, iter}, fun) do
+    if fun.({key, value}) do
+      [{key, value} | do_filter(:maps.next(iter), fun)]
+    else
+      do_filter(:maps.next(iter), fun)
+    end
+  end
+
+  @doc """
+  Returns map excluding the pairs from `map` for which `fun` returns
+  a truthy value.
+
+  See also `filter/2`.
+
+  ## Examples
+
+      iex> Map.reject(%{one: 1, two: 2, three: 3}, fn {_key, val} -> rem(val, 2) == 1 end)
+      %{two: 2}
+
+  """
+  @doc since: "1.13.0"
+  @spec reject(map, ({key, value} -> as_boolean(term))) :: map
+  def reject(map, fun) when is_map(map) and is_function(fun, 1) do
+    iter = :maps.iterator(map)
+    next = :maps.next(iter)
+    :maps.from_list(do_reject(next, fun))
+  end
+
+  defp do_reject(:none, _fun), do: []
+
+  defp do_reject({key, value, iter}, fun) do
+    if fun.({key, value}) do
+      do_reject(:maps.next(iter), fun)
+    else
+      [{key, value} | do_reject(:maps.next(iter), fun)]
+    end
+  end
+
+  @doc false
+  @deprecated "Use Map.new/2 instead"
+  def map(map, fun) when is_map(map) do
+    new(map, fn {k, v} -> {k, fun.({k, v})} end)
+  end
 end

lib/elixir/lib/map_set.ex

@@ -402,6 +402,7 @@ defmodule MapSet do
   end
 
   defimpl Collectable do
+    # TODO: Optimize into an empty mapset by using :maps.from_keys/2 on Erlang/OTP 24+
     def into(map_set) do
       fun = fn
         list, {:cont, x} -> [{x, []} | list]

lib/elixir/lib/module.ex

@@ -335,6 +335,16 @@ defmodule Module do
         @vsn "1.0"
       end
 
+  ### Struct attributes
+
+    * `@derive` - derives an implementation for the given protocol for the
+      struct defined in the current module
+
+    * `@enforce_keys` - ensures the given keys are always set when building
+      the struct defined in the current module
+
+  See `Kernel.defstruct/1` for more information on building and using structs.
+
   ### Typespec attributes
 
   The following attributes are part of typespecs and are also built-in in
@@ -543,6 +553,103 @@ defmodule Module do
   @callback __info__(:md5) :: binary()
   @callback __info__(:module) :: module()
 
+  @doc """
+  Returns information about module attributes used by Elixir.
+
+  See the "Module attributes" section in the module documentation for more
+  information on each attribute.
+
+  ## Examples
+
+      iex> map = Module.reserved_attributes()
+      iex> Map.has_key?(map, :moduledoc)
+      true
+      iex> Map.has_key?(map, :doc)
+      true
+
+  """
+  @doc since: "1.12.0"
+  def reserved_attributes() do
+    %{
+      after_compile: %{
+        doc: "A hook that will be invoked right after the current module is compiled."
+      },
+      before_compile: %{
+        doc: "A hook that will be invoked before the module is compiled."
+      },
+      behaviour: %{
+        doc: "Specifies that the current module implements a given behaviour."
+      },
+      on_definition: %{
+        doc:
+          "A hook that will be invoked when each function or macro in the current module is defined."
+      },
+      impl: %{
+        doc: "Declares an implementation of a callback function or macro."
+      },
+      compile: %{
+        doc: "Defines options for module compilation."
+      },
+      deprecated: %{
+        doc: "Provides the deprecation reason for a function."
+      },
+      moduledoc: %{
+        doc: "Provides documentation for the current module."
+      },
+      doc: %{
+        doc: "Provides documentation for a function/macro/callback."
+      },
+      typedoc: %{
+        doc: "Provides documentation for a type."
+      },
+      dialyzer: %{
+        doc: "Defines Dialyzer warnings to request or suppress."
+      },
+      external_resource: %{
+        doc: "Specifies an external resource for the current module."
+      },
+      file: %{
+        doc:
+          "Changes the filename used in stacktraces for the function or macro that follows the attribute."
+      },
+      on_load: %{
+        doc: "A hook that will be invoked whenever the module is loaded."
+      },
+      vsn: %{
+        doc: "Specify the module version."
+      },
+      type: %{
+        doc: "Defines a type to be used in `@spec`."
+      },
+      typep: %{
+        doc: "Defines a private type to be used in `@spec`."
+      },
+      opaque: %{
+        doc: "Defines an opaque type to be used in `@spec`."
+      },
+      spec: %{
+        doc: "Provides a specification for a function."
+      },
+      callback: %{
+        doc: "Provides a specification for a behaviour callback."
+      },
+      macrocallback: %{
+        doc: "Provides a specification for a macro behaviour callback."
+      },
+      optional_callbacks: %{
+        doc: "Specifies which behaviour callbacks and macro behaviour callbacks are optional."
+      },
+      derive: %{
+        doc:
+          "Derives an implementation for the given protocol for the struct defined in the current module."
+      },
+      enforce_keys: %{
+        doc:
+          "Ensures the given keys are always set when building the struct defined in the current module."
+      }
+    }
+  end
+
   @doc """
   Checks if a module is open.
 
@@ -602,22 +709,24 @@ defmodule Module do
 
   def eval_quoted(%Macro.Env{} = env, quoted, binding, opts)
       when is_list(binding) and is_list(opts) do
-    eval_quoted(env.module, quoted, binding, Keyword.merge(Map.to_list(env), opts))
+    validated_eval_quoted(env.module, quoted, binding, struct!(env, opts))
   end
 
   def eval_quoted(module, quoted, binding, %Macro.Env{} = env)
       when is_atom(module) and is_list(binding) do
-    eval_quoted(module, quoted, binding, Map.to_list(env))
+    validated_eval_quoted(module, quoted, binding, env)
   end
 
   def eval_quoted(module, quoted, binding, opts)
       when is_atom(module) and is_list(binding) and is_list(opts) do
-    assert_not_compiled!(__ENV__.function, module)
+    validated_eval_quoted(module, quoted, binding, opts)
+  end
+
+  defp validated_eval_quoted(module, quoted, binding, env_or_opts) do
+    assert_not_compiled!({:eval_quoted, 4}, module)
     :elixir_def.reset_last(module)
-
-    {value, binding, _env} =
-      :elixir.eval_quoted(quoted, binding, Keyword.put(opts, :module, module))
-
+    env = :elixir.env_for_eval(env_or_opts)
+    {value, binding, _env} = :elixir.eval_quoted(quoted, binding, %{env | module: module})
     {value, binding}
   end
 
@@ -683,6 +792,8 @@ defmodule Module do
   @doc """
   Concatenates a list of aliases and returns a new alias.
 
+  It handles binaries and atoms.
+
   ## Examples
 
       iex> Module.concat([Foo, Bar])
@@ -700,6 +811,8 @@ defmodule Module do
   @doc """
   Concatenates two aliases and returns a new alias.
 
+  It handles binaries and atoms.
+
   ## Examples
 
       iex> Module.concat(Foo, Bar)
@@ -720,7 +833,7 @@ defmodule Module do
   was already referenced.
 
   If the alias was not referenced yet, fails with `ArgumentError`.
-  It handles charlists, binaries and atoms.
+  It handles binaries and atoms.
 
   ## Examples
 
@@ -738,7 +851,7 @@ defmodule Module do
   already referenced.
 
   If the alias was not referenced yet, fails with `ArgumentError`.
-  It handles charlists, binaries and atoms.
+  It handles binaries and atoms.
 
   ## Examples
 
@@ -854,8 +967,8 @@ defmodule Module do
 
   defp autogenerated_key(counters, key) do
     case counters do
-      %{^key => :once} -> {key, Map.put(counters, key, 2)}
-      %{^key => value} -> {key, Map.put(counters, key, value + 1)}
+      %{^key => :once} -> {key, %{counters | key => 2}}
+      %{^key => value} -> {key, %{counters | key => value + 1}}
       %{} -> {key, Map.put(counters, key, :once)}
     end
   end
@@ -1004,6 +1117,61 @@ defmodule Module do
     Kernel.Typespec.spec_to_callback(module, definition)
   end
 
+  @doc """
+  Returns all module attributes names defined in `module`.
+
+  This function can only be used on modules that have not yet been compiled.
+
+  ## Examples
+
+      defmodule Example do
+        @foo 1
+        Module.register_attribute(__MODULE__, :bar, accumulate: true)
+
+        :foo in Module.attributes_in(__MODULE__)
+        #=> true
+
+        :bar in Module.attributes_in(__MODULE__)
+        #=> true
+      end
+
+  """
+  @doc since: "1.13.0"
+  @spec attributes_in(module) :: [atom]
+  def attributes_in(module) when is_atom(module) do
+    assert_not_compiled!(__ENV__.function, module)
+    {set, _} = data_tables_for(module)
+    :ets.select(set, [{{:"$1", :_, :_}, [{:is_atom, :"$1"}], [:"$1"]}])
+  end
+
+  @doc """
+  Returns all overridable definitions in `module`.
+
+  Note a definition is included even if it was was already overridden.
+  You can use `defines?/2` to see if a definition exists or one is pending.
+
+  This function can only be used on modules that have not yet been compiled.
+
+  ## Examples
+
+      defmodule Example do
+        def foo, do: 1
+        def bar, do: 2
+
+        defoverridable foo: 1, bar: 1
+        def foo, do: 3
+
+        [:bar, :foo] = Module.overridables_in(__MODULE__) |> Enum.sort()
+      end
+
+  """
+  @doc since: "1.13.0"
+  @spec overridables_in(module) :: [atom]
+  def overridables_in(module) when is_atom(module) do
+    assert_not_compiled!(__ENV__.function, module)
+    :elixir_overridable.overridables_for(module)
+  end
+
   @doc """
   Returns all functions and macros defined in `module`.
 
@@ -1070,19 +1238,31 @@ defmodule Module do
   context. Given this AST representation is mostly internal,
   it is versioned and it may change at any time. Therefore,
   **use this API with caution**.
+
+  ## Options
+
+    * `:nillify_clauses` (since v1.13.0) - returns `nil` instead
+      of returning the clauses. This is useful when there is
+      only an interest in fetching the kind and metadata
+
   """
-  @spec get_definition(module, definition) ::
+  @spec get_definition(module, definition, keyword) ::
           {:v1, def_kind, meta :: keyword,
-           [{meta :: keyword, arguments :: [Macro.t()], guards :: [Macro.t()], Macro.t()}]}
+           [{meta :: keyword, arguments :: [Macro.t()], guards :: [Macro.t()], Macro.t()}] | nil}
   @doc since: "1.12.0"
-  def get_definition(module, {name, arity})
-      when is_atom(module) and is_atom(name) and is_integer(arity) do
+  def get_definition(module, {name, arity}, options \\ [])
+      when is_atom(module) and is_atom(name) and is_integer(arity) and is_list(options) do
     assert_not_compiled!(__ENV__.function, module, "")
     {set, bag} = data_tables_for(module)
 
     case :ets.lookup(set, {:def, {name, arity}}) do
       [{_key, kind, meta, _, _, _}] ->
-        {:v1, kind, meta, bag_lookup_element(bag, {:clauses, {name, arity}}, 2)}
+        clauses =
+          if options[:nillify_clauses],
+            do: nil,
+            else: bag_lookup_element(bag, {:clauses, {name, arity}}, 2)
+
+        {:v1, kind, meta, clauses}
 
       [] ->
         nil
@@ -1181,7 +1361,7 @@ defmodule Module do
     behaviour_definitions = bag_lookup_element(bag, {:accumulate, :behaviour}, 2)
 
     cond do
-      Code.ensure_compiled(behaviour) != {:module, behaviour} ->
+      not Code.ensure_loaded?(behaviour) ->
         {:error, "it was not defined"}
 
       not function_exported?(behaviour, :behaviour_info, 1) ->
@@ -1218,7 +1398,12 @@ defmodule Module do
   end
 
   @doc """
-  Returns `true` if `tuple` in `module` is marked as overridable.
+  Returns `true` if `tuple` in `module` was marked as overridable
+  at some point.
+
+  Note `overridable?/2` returns true even if the definition was
+  already overridden. You can use `defines?/2` to see if a definition
+  exists or one is pending.
   """
   @spec overridable?(module, definition) :: boolean
   def overridable?(module, {function_name, arity} = tuple)
@@ -1611,14 +1796,7 @@ defmodule Module do
   defp check_behaviours(env, behaviours) do
     Enum.reduce(behaviours, %{}, fn behaviour, acc ->
       cond do
-        not is_atom(behaviour) ->
-          message =
-            "@behaviour #{inspect(behaviour)} must be an atom (in module #{inspect(env.module)})"
-
-          IO.warn(message, Macro.Env.stacktrace(env))
-          acc
-
-        Code.ensure_compiled(behaviour) != {:module, behaviour} ->
+        not Code.ensure_loaded?(behaviour) ->
           message =
             "@behaviour #{inspect(behaviour)} does not exist (in module #{inspect(env.module)})"
 
@@ -1633,7 +1811,8 @@ defmodule Module do
           acc
 
         true ->
-          :elixir_env.trace({:require, [], behaviour, []}, env)
+          event = {:remote_function, [], behaviour, :behaviour_info, 1}
+          :elixir_env.trace(event, %{env | function: {:__info__, 1}})
           optional_callbacks = behaviour_info(behaviour, :optional_callbacks)
           callbacks = behaviour_info(behaviour, :callbacks)
           Enum.reduce(callbacks, acc, &add_callback(&1, behaviour, env, optional_callbacks, &2))
@@ -2007,6 +2186,15 @@ defmodule Module do
     end
   end
 
+  defp preprocess_attribute(:behaviour, value) do
+    if is_atom(value) do
+      Code.ensure_compiled(value)
+      value
+    else
+      raise ArgumentError, "@behaviour expects a module, got: #{inspect(value)}"
+    end
+  end
+
   defp preprocess_attribute(:on_load, value) do
     case value do
       _ when is_atom(value) ->
@@ -2053,7 +2241,7 @@ defmodule Module do
   defp preprocess_attribute(:external_resource, value) when not is_binary(value) do
     raise ArgumentError,
           "@external_resource is a built-in module attribute used for specifying file " <>
-            "dependencies. It should be a string the path to a file, got: #{inspect(value)}"
+            "dependencies. It should be a string path to a file, got: #{inspect(value)}"
   end
 
   defp preprocess_attribute(:deprecated, value) when not is_binary(value) do

lib/elixir/lib/module/locals_tracker.ex

@@ -71,8 +71,9 @@ defmodule Module.LocalsTracker do
     :ok
   end
 
-  # Collecting all conflicting imports with the given functions
-  @doc false
+  @doc """
+  Collect all conflicting imports with the given functions
+  """
   def collect_imports_conflicts({set, _bag}, all_defined) do
     for {pair, _, meta, _} <- all_defined, n = out_neighbour(set, {:import, pair}) do
       {meta, {n, pair}}

lib/elixir/lib/module/parallel_checker.ex

@@ -1,44 +1,141 @@
 defmodule Module.ParallelChecker do
   @moduledoc false
 
+  import Kernel, except: [spawn: 3]
+
   @type cache() :: {pid(), :ets.tid()}
   @type warning() :: term()
   @type kind() :: :def | :defmacro
   @type mode() :: :elixir | :erlang
 
   @doc """
-  Receives pairs of module maps and BEAM binaries. In parallel it verifies
-  the modules and adds the ExCk chunk to the binaries. Returns the updated
-  binaries and a list of warnings from the verification.
+  Initializes the parallel checker process.
   """
-  @spec verify([{map(), binary()}], [{module(), binary()}], pos_integer() | nil) :: [warning()]
-  def verify(compiled_modules, runtime_binaries, schedulers \\ nil) do
-    compiled_maps = Enum.map(compiled_modules, fn {map, _binary} -> {map.module, map} end)
+  def start_link(schedulers \\ nil) do
+    :gen_server.start_link(__MODULE__, schedulers, [])
+  end
 
-    case compiled_maps ++ runtime_binaries do
-      [] ->
-        []
+  @doc """
+  Stops the parallel checker process.
+  """
+  def stop(checker) do
+    send(checker, {__MODULE__, :stop})
+    :ok
+  end
 
-      check_modules ->
-        schedulers = schedulers || max(:erlang.system_info(:schedulers_online), 2)
+  @doc """
+  Gets the parallel checker data from pdict.
+  """
+  def get do
+    {_, checker} = :erlang.get(:elixir_checker_info)
+    checker
+  end
 
-        {:ok, server} =
-          :gen_server.start_link(__MODULE__, [check_modules, self(), schedulers], [])
+  @doc """
+  Stores the parallel checker information.
+  """
+  def put(pid, checker) do
+    :erlang.put(:elixir_checker_info, {pid, checker})
+  end
 
-        preload_cache(get_ets(server), check_modules)
-        start(server)
-        collect_results(length(check_modules), [])
+  @doc """
+  Spawns a process that runs the parallel checker.
+  """
+  def spawn({pid, checker}, module, info) do
+    ref = make_ref()
+
+    spawned =
+      spawn(fn ->
+        Process.link(pid)
+        mon_ref = Process.monitor(pid)
+
+        receive do
+          {^ref, :cache, ets} ->
+            loaded_info =
+              if is_map(info) do
+                cache_from_module_map(ets, info)
+                info
+              else
+                info = File.read!(info)
+                cache_from_chunk(ets, module, info)
+                info
+              end
+
+            send(checker, {ref, :cached})
+
+            receive do
+              {^ref, :check} ->
+                warnings = check_module(module, loaded_info, {checker, ets})
+                send(pid, {__MODULE__, module, warnings})
+                send(checker, {__MODULE__, :done})
+            end
+
+          {:DOWN, ^mon_ref, _, _, _} ->
+            :ok
+        end
+      end)
+
+    {spawned, ref}
+  end
+
+  @doc """
+  Verifies the given compilation function
+  by starting a checker if one does not exist.
+  See `verify/3`.
+  """
+  def verify(fun) do
+    case :erlang.get(:elixir_compiler_info) do
+      :undefined ->
+        previous = :erlang.get(:elixir_checker_info)
+        {:ok, checker} = start_link()
+        put(self(), checker)
+
+        try do
+          {result, compile_info} = Enum.unzip(fun.())
+          _ = verify(checker, compile_info, [])
+          result
+        after
+          if previous != :undefined do
+            :erlang.put(:elixir_checker_info, previous)
+          else
+            :erlang.erase(:elixir_checker_info)
+          end
+
+          stop(checker)
+        end
+
+      _ ->
+        # If we are during compilation, then they will be
+        # reported to the compiler, which will validate them.
+        Enum.map(fun.(), &elem(&1, 0))
     end
   end
 
-  defp collect_results(0, warnings) do
+  @doc """
+  Receives pairs of module maps and BEAM binaries. In parallel it verifies
+  the modules and adds the ExCk chunk to the binaries. Returns the updated
+  list of warnings from the verification.
+  """
+  @spec verify(pid(), [{pid(), reference()}], [{module(), binary()}]) :: [warning()]
+  def verify(checker, compiled_info, runtime_files) do
+    runtime_info =
+      for {module, file} <- runtime_files do
+        spawn({self(), checker}, module, file)
+      end
+
+    modules = compiled_info ++ runtime_info
+    :gen_server.cast(checker, {:start, modules})
+    collect_results(modules, [])
+  end
+
+  defp collect_results([], warnings) do
     warnings
   end
 
-  defp collect_results(count, warnings) do
+  defp collect_results([_ | modules], warnings) do
     receive do
       {__MODULE__, _module, new_warnings} ->
-        collect_results(count - 1, new_warnings ++ warnings)
+        collect_results(modules, new_warnings ++ warnings)
     end
   end
 
@@ -46,8 +143,8 @@ defmodule Module.ParallelChecker do
   Test cache.
   """
   def test_cache do
-    {:ok, pid} = :gen_server.start_link(__MODULE__, [[], self(), 1], [])
-    {pid, get_ets(pid)}
+    {:ok, checker} = start_link()
+    {checker, :gen_server.call(checker, :ets)}
   end
 
   @doc """
@@ -98,8 +195,8 @@ defmodule Module.ParallelChecker do
 
   ## Module checking
 
-  defp check_module(module, cache) do
-    case extract_definitions(module) do
+  defp check_module(module, info, cache) do
+    case extract_definitions(module, info) do
       {:ok, module, file, definitions, no_warn_undefined} ->
         Module.Types.warnings(module, file, definitions, no_warn_undefined, cache)
         |> group_warnings()
@@ -110,7 +207,7 @@ defmodule Module.ParallelChecker do
     end
   end
 
-  defp extract_definitions({module, module_map}) when is_map(module_map) do
+  defp extract_definitions(module, module_map) when is_map(module_map) do
     no_warn_undefined =
       module_map.compile_opts
       |> extract_no_warn_undefined()
@@ -119,11 +216,11 @@ defmodule Module.ParallelChecker do
     {:ok, module, module_map.file, module_map.definitions, no_warn_undefined}
   end
 
-  defp extract_definitions({module, binary}) when is_binary(binary) do
+  defp extract_definitions(module, binary) when is_binary(binary) do
     with {:ok, {_, [debug_info: chunk]}} <- :beam_lib.chunks(binary, [:debug_info]),
          {:debug_info_v1, backend, data} <- chunk,
          {:ok, module_map} <- backend.debug_info(:elixir_v1, module, data, []) do
-      extract_definitions({module, module_map})
+      extract_definitions(module, module_map)
     else
       _ -> :error
     end
@@ -176,7 +273,7 @@ defmodule Module.ParallelChecker do
 
   defp format_locations(locations) do
     [
-      "Found at #{length(locations)} locations:\n",
+      "Invalid call found at #{length(locations)} locations:\n",
       Enum.map(locations, &format_location/1)
     ]
   end
@@ -204,106 +301,7 @@ defmodule Module.ParallelChecker do
     IO.puts(:stderr, [:elixir_errors.warning_prefix(), message])
   end
 
-  ## Server callbacks
-
-  def init([modules, send_results, schedulers]) do
-    ets = :ets.new(:checker_cache, [:set, :public, {:read_concurrency, true}])
-
-    state = %{
-      ets: ets,
-      waiting: %{},
-      send_results: send_results,
-      modules: modules,
-      spawned: 0,
-      schedulers: schedulers
-    }
-
-    {:ok, state}
-  end
-
-  def handle_call({:lock, module}, from, %{waiting: waiting} = state) do
-    case waiting do
-      %{^module => froms} ->
-        waiting = Map.put(state.waiting, module, [from | froms])
-        {:noreply, %{state | waiting: waiting}}
-
-      %{} ->
-        waiting = Map.put(state.waiting, module, [])
-        {:reply, true, %{state | waiting: waiting}}
-    end
-  end
-
-  def handle_call({:unlock, module}, _from, %{waiting: waiting} = state) do
-    froms = Map.fetch!(waiting, module)
-    Enum.each(froms, &:gen_server.reply(&1, false))
-    waiting = Map.delete(waiting, module)
-    {:reply, :ok, %{state | waiting: waiting}}
-  end
-
-  def handle_call(:get_ets, _from, %{ets: ets} = state) do
-    {:reply, ets, state}
-  end
-
-  def handle_cast(:start, state) do
-    {:noreply, spawn_checkers(state)}
-  end
-
-  def handle_info({__MODULE__, :done}, state) do
-    state = %{state | spawned: state.spawned - 1}
-
-    if state.spawned == 0 and state.modules == [] do
-      {:stop, :normal, state}
-    else
-      state = spawn_checkers(state)
-      {:noreply, state}
-    end
-  end
-
-  defp lock(server, module) do
-    :gen_server.call(server, {:lock, module}, :infinity)
-  end
-
-  defp unlock(server, module) do
-    :gen_server.call(server, {:unlock, module})
-  end
-
-  defp get_ets(server) do
-    :gen_server.call(server, :get_ets)
-  end
-
-  defp start(server) do
-    :gen_server.cast(server, :start)
-  end
-
-  defp preload_cache(ets, modules) do
-    Enum.each(modules, fn
-      {_module, map} when is_map(map) -> cache_from_module_map(ets, map)
-      {module, binary} when is_binary(binary) -> cache_from_chunk(ets, module, binary)
-    end)
-  end
-
-  defp spawn_checkers(%{modules: []} = state) do
-    state
-  end
-
-  defp spawn_checkers(%{spawned: spawned, schedulers: schedulers} = state)
-       when spawned >= schedulers do
-    state
-  end
-
-  defp spawn_checkers(%{modules: [{module, _} = verify | modules]} = state) do
-    parent = self()
-    ets = state.ets
-    send_results_pid = state.send_results
-
-    spawn_link(fn ->
-      warnings = check_module(verify, {parent, ets})
-      send(send_results_pid, {__MODULE__, module, warnings})
-      send(parent, {__MODULE__, :done})
-    end)
-
-    spawn_checkers(%{state | modules: modules, spawned: state.spawned + 1})
-  end
+  ## Cache
 
   defp cache_module({server, ets}, module) do
     if lock(server, module) do
@@ -410,4 +408,88 @@ defmodule Module.ParallelChecker do
       end
     end)
   end
+
+  defp lock(server, module) do
+    :gen_server.call(server, {:lock, module}, :infinity)
+  end
+
+  defp unlock(server, module) do
+    :gen_server.call(server, {:unlock, module})
+  end
+
+  ## Server callbacks
+
+  def init(schedulers) do
+    ets = :ets.new(__MODULE__, [:set, :public, {:read_concurrency, true}])
+
+    state = %{
+      ets: ets,
+      waiting: %{},
+      modules: [],
+      spawned: 0,
+      schedulers: schedulers || max(:erlang.system_info(:schedulers_online), 2)
+    }
+
+    {:ok, state}
+  end
+
+  def handle_call(:ets, _from, state) do
+    {:reply, state.ets, state}
+  end
+
+  def handle_call({:lock, module}, from, %{waiting: waiting} = state) do
+    case waiting do
+      %{^module => froms} ->
+        waiting = Map.put(state.waiting, module, [from | froms])
+        {:noreply, %{state | waiting: waiting}}
+
+      %{} ->
+        waiting = Map.put(state.waiting, module, [])
+        {:reply, true, %{state | waiting: waiting}}
+    end
+  end
+
+  def handle_call({:unlock, module}, _from, %{waiting: waiting} = state) do
+    froms = Map.fetch!(waiting, module)
+    Enum.each(froms, &:gen_server.reply(&1, false))
+    waiting = Map.delete(waiting, module)
+    {:reply, :ok, %{state | waiting: waiting}}
+  end
+
+  def handle_info({__MODULE__, :done}, state) do
+    state = %{state | spawned: state.spawned - 1}
+    {:noreply, run_checkers(state)}
+  end
+
+  def handle_info({__MODULE__, :stop}, state) do
+    {:stop, :normal, state}
+  end
+
+  def handle_cast({:start, modules}, %{ets: ets} = state) do
+    for {pid, ref} <- modules do
+      send(pid, {ref, :cache, ets})
+    end
+
+    for {_pid, ref} <- modules do
+      receive do
+        {^ref, :cached} -> :ok
+      end
+    end
+
+    {:noreply, run_checkers(%{state | modules: modules})}
+  end
+
+  defp run_checkers(%{modules: []} = state) do
+    state
+  end
+
+  defp run_checkers(%{spawned: spawned, schedulers: schedulers} = state)
+       when spawned >= schedulers do
+    state
+  end
+
+  defp run_checkers(%{modules: [{pid, ref} | modules]} = state) do
+    send(pid, {ref, :check})
+    run_checkers(%{state | modules: modules, spawned: state.spawned + 1})
+  end
 end

lib/elixir/lib/module/types.ex

@@ -133,13 +133,24 @@ defmodule Module.Types do
   ## ERROR TO WARNING
 
   # Collect relevant information from context and traces to report error
+  def error_to_warning(:unable_apply, {mfa, args, expected, signature, stack}, context) do
+    {fun, arity} = context.function
+    line = get_meta(stack.last_expr)[:line]
+    location = {context.file, line, {context.module, fun, arity}}
+
+    traces = type_traces(stack, context)
+    {[signature | args], traces} = lift_all_types([signature | args], traces, context)
+    error = {:unable_apply, mfa, args, expected, signature, {location, stack.last_expr, traces}}
+    {Module.Types, error, location}
+  end
+
   def error_to_warning(:unable_unify, {left, right, stack}, context) do
     {fun, arity} = context.function
     line = get_meta(stack.last_expr)[:line]
     location = {context.file, line, {context.module, fun, arity}}
 
     traces = type_traces(stack, context)
-    {left, right, traces} = lift_all_types(left, right, traces, context)
+    {[left, right], traces} = lift_all_types([left, right], traces, context)
     error = {:unable_unify, left, right, {location, stack.last_expr, traces}}
     {Module.Types, error, location}
   end
@@ -183,58 +194,83 @@ defmodule Module.Types do
     end
   end
 
-  defp lift_all_types(left, right, traces, context) do
-    all_types = [left, right] ++ for({:type, _, type, _, _} <- traces, do: type)
-    [left, right | all_types] = Unify.lift_types(all_types, context)
+  defp lift_all_types(types, traces, context) do
+    trace_types = for({:type, _, type, _, _} <- traces, do: type)
+    {types, lift_context} = Unify.lift_types(types, context)
+    {trace_types, _lift_context} = Unify.lift_types(trace_types, lift_context)
 
     {traces, []} =
-      Enum.map_reduce(traces, all_types, fn
+      Enum.map_reduce(traces, trace_types, fn
         {:type, var, _, expr, location}, [type | acc] -> {{:type, var, type, expr, location}, acc}
         other, acc -> {other, acc}
       end)
 
-    {left, right, traces}
+    {types, traces}
   end
 
   ## FORMAT WARNINGS
 
+  def format_warning({:unable_apply, mfa, args, expected, signature, {location, expr, traces}}) do
+    {module, function, arity} = mfa
+    mfa_args = Macro.generate_arguments(arity, __MODULE__)
+    {module, function, ^arity} = call_to_mfa(erl_to_ex(module, function, mfa_args, []))
+    format_mfa = Exception.format_mfa(module, function, arity)
+    {traces, [] = _hints} = format_traces(traces, [], false)
+
+    clauses =
+      Enum.map(
+        signature,
+        &String.slice(IO.iodata_to_binary(Unify.format_type({:fun, [&1]}, false)), 1..-2)
+      )
+
+    [
+      "expected #{format_mfa} to have signature:\n\n    ",
+      Enum.map_join(args, ", ", &Unify.format_type(&1, false)),
+      " -> #{Unify.format_type(expected, false)}",
+      "\n\nbut it has signature:\n\n    ",
+      indent(Enum.join(clauses, "\n")),
+      "\n\n",
+      format_expr(expr, location),
+      traces,
+      "Conflict found at"
+    ]
+  end
+
   def format_warning({:unable_unify, left, right, {location, expr, traces}}) do
-    cond do
-      map_type?(left) and map_type?(right) and match?({:ok, _, _}, missing_field(left, right)) ->
-        {:ok, atom, known_atoms} = missing_field(left, right)
+    if map_type?(left) and map_type?(right) and match?({:ok, _, _}, missing_field(left, right)) do
+      {:ok, atom, known_atoms} = missing_field(left, right)
 
-        # Drop the last trace which is the expression map.foo
-        traces = Enum.drop(traces, 1)
-        {traces, hints} = format_traces(traces, true)
+      # Drop the last trace which is the expression map.foo
+      traces = Enum.drop(traces, 1)
+      {traces, hints} = format_traces(traces, [left, right], true)
 
-        [
-          "undefined field \"#{atom}\" ",
-          format_expr(expr, location),
-          "expected one of the following fields: ",
-          Enum.map_join(Enum.sort(known_atoms), ", ", & &1),
-          "\n\n",
-          traces,
-          format_message_hints(hints),
-          "Conflict found at"
-        ]
+      [
+        "undefined field \"#{atom}\" ",
+        format_expr(expr, location),
+        "expected one of the following fields: ",
+        Enum.map_join(Enum.sort(known_atoms), ", ", & &1),
+        "\n\n",
+        traces,
+        format_message_hints(hints),
+        "Conflict found at"
+      ]
+    else
+      simplify_left? = simplify_type?(left, right)
+      simplify_right? = simplify_type?(right, left)
 
-      true ->
-        simplify_left? = simplify_type?(left, right)
-        simplify_right? = simplify_type?(right, left)
+      {traces, hints} = format_traces(traces, [left, right], simplify_left? or simplify_right?)
 
-        {traces, hints} = format_traces(traces, simplify_left? or simplify_right?)
-
-        [
-          "incompatible types:\n\n    ",
-          Unify.format_type(left, simplify_left?),
-          " !~ ",
-          Unify.format_type(right, simplify_right?),
-          "\n\n",
-          format_expr(expr, location),
-          traces,
-          format_message_hints(hints),
-          "Conflict found at"
-        ]
+      [
+        "incompatible types:\n\n    ",
+        Unify.format_type(left, simplify_left?),
+        " !~ ",
+        Unify.format_type(right, simplify_right?),
+        "\n\n",
+        format_expr(expr, location),
+        traces,
+        format_message_hints(hints),
+        "Conflict found at"
+      ]
     end
   end
 
@@ -263,17 +299,17 @@ defmodule Module.Types do
     end
   end
 
-  defp format_traces([], _simplify?) do
+  defp format_traces([], _types, _simplify?) do
     {[], []}
   end
 
-  defp format_traces(traces, simplify?) do
+  defp format_traces(traces, types, simplify?) do
     traces
     |> Enum.uniq()
     |> Enum.reverse()
     |> Enum.map_reduce([], fn
       {:type, var, type, expr, location}, hints ->
-        {hint, hints} = format_type_hint(type, expr, hints)
+        {hint, hints} = format_type_hint(type, types, expr, hints)
 
         trace = [
           "where \"",
@@ -318,7 +354,7 @@ defmodule Module.Types do
   end
 
   defp simplify_type?(type, other) do
-    map_type?(type) and not map_type?(other)
+    map_like_type?(type) and not map_like_type?(other)
   end
 
   ## EXPRESSION FORMATTING
@@ -361,14 +397,16 @@ defmodule Module.Types do
   ## Hints
 
   defp format_message_hints(hints) do
-    hints |> Enum.uniq() |> Enum.reverse() |> Enum.map(&format_message_hint/1)
+    hints
+    |> Enum.uniq()
+    |> Enum.reverse()
+    |> Enum.map(&[format_message_hint(&1), "\n"])
   end
 
   defp format_message_hint(:inferred_dot) do
     """
     HINT: "var.field" (without parentheses) implies "var" is a map() while \
     "var.fun()" (with parentheses) implies "var" is an atom()
-
     """
   end
 
@@ -378,18 +416,24 @@ defmodule Module.Types do
     integer() unless said otherwise. For example, <<expr>> assumes "expr" \
     is an integer. Pass a modifier, such as <<expr::float>> or <<expr::binary>>, \
     to change the default behaviour.
-
     """
   end
 
-  defp format_type_hint(type, expr, hints) do
-    case format_type_hint(type, expr) do
+  defp format_message_hint({:sized_and_unsize_tuples, {size, var}}) do
+    """
+    HINT: use pattern matching or "is_tuple(#{Macro.to_string(var)}) and \
+    tuple_size(#{Macro.to_string(var)}) == #{size}" to guard a sized tuple.
+    """
+  end
+
+  defp format_type_hint(type, types, expr, hints) do
+    case format_type_hint(type, types, expr) do
       {message, hint} -> {message, [hint | hints]}
       :error -> {[], hints}
     end
   end
 
-  defp format_type_hint(type, expr) do
+  defp format_type_hint(type, types, expr) do
     cond do
       dynamic_map_dot?(type, expr) ->
         {" (due to calling var.field)", :inferred_dot}
@@ -400,6 +444,9 @@ defmodule Module.Types do
       inferred_bitstring_spec?(type, expr) ->
         {[], :inferred_bitstring_spec}
 
+      message = sized_and_unsize_tuples(expr, types) ->
+        {[], {:sized_and_unsize_tuples, message}}
+
       true ->
         :error
     end
@@ -435,15 +482,33 @@ defmodule Module.Types do
     end
   end
 
+  defp sized_and_unsize_tuples({{:., _, [:erlang, :is_tuple]}, _, [var]}, types) do
+    case Enum.find(types, &match?({:tuple, _, _}, &1)) do
+      {:tuple, size, _} ->
+        {size, var}
+
+      nil ->
+        nil
+    end
+  end
+
+  defp sized_and_unsize_tuples(_expr, _types) do
+    nil
+  end
+
   ## Formatting helpers
 
   defp indent(string) do
-    String.replace(string, "\n", "    \n")
+    String.replace(string, "\n", "\n    ")
   end
 
   defp map_type?({:map, _}), do: true
   defp map_type?(_other), do: false
 
+  defp map_like_type?({:map, _}), do: true
+  defp map_like_type?({:union, union}), do: Enum.any?(union, &map_like_type?/1)
+  defp map_like_type?(_other), do: false
+
   defp atom_type?(:atom), do: true
   defp atom_type?({:atom, _}), do: false
   defp atom_type?({:union, union}), do: Enum.all?(union, &atom_type?/1)
@@ -451,4 +516,7 @@ defmodule Module.Types do
 
   defp integer_type?(:integer), do: true
   defp integer_type?(_other), do: false
+
+  defp call_to_mfa({{:., _, [mod, fun]}, _, args}), do: {mod, fun, length(args)}
+  defp call_to_mfa({fun, _, args}) when is_atom(fun), do: {Kernel, fun, length(args)}
 end

lib/elixir/lib/module/types/expr.ex

@@ -334,15 +334,10 @@ defmodule Module.Types.Expr do
     # TODO: Use expected type to infer intersection return type
     stack = push_expr_stack(expr, stack)
 
-    case of_expr(fun, :dynamic, stack, context) do
-      {:ok, _fun_type, context} ->
-        case map_reduce_ok(args, context, &of_expr(&1, :dynamic, stack, &2)) do
-          {:ok, _arg_types, context} -> {:ok, :dynamic, context}
-          {:error, reason} -> {:error, reason}
-        end
-
-      {:error, reason} ->
-        {:error, reason}
+    with {:ok, _fun_type, context} <- of_expr(fun, :dynamic, stack, context),
+         {:ok, _arg_types, context} <-
+           map_reduce_ok(args, context, &of_expr(&1, :dynamic, stack, &2)) do
+      {:ok, :dynamic, context}
     end
   end
 
@@ -375,11 +370,10 @@ defmodule Module.Types.Expr do
     stack = push_expr_stack(expr2, stack)
 
     with {:ok, _expr_type, context} <- of_expr(expr1, :dynamic, stack, context),
-         {:ok, _fun_type, context} <- of_expr(fun, :dynamic, stack, context) do
-      case map_reduce_ok(args, context, &of_expr(&1, :dynamic, stack, &2)) do
-        {:ok, _arg_types, context} -> {:ok, :dynamic, context}
-        {:error, reason} -> {:error, reason}
-      end
+         {:ok, _fun_type, context} <- of_expr(fun, :dynamic, stack, context),
+         {:ok, _arg_types, context} <-
+           map_reduce_ok(args, context, &of_expr(&1, :dynamic, stack, &2)) do
+      {:ok, :dynamic, context}
     end
   end
 
@@ -475,12 +469,19 @@ defmodule Module.Types.Expr do
   end
 
   defp of_clauses(clauses, stack, context) do
-    reduce_ok(clauses, context, fn {:->, _meta, [head, body]}, context = acc ->
+    reduce_ok(clauses, context, fn {:->, meta, [head, body]}, context = acc ->
       {patterns, guards} = extract_head(head)
 
-      with {:ok, _, context} <- Pattern.of_head(patterns, guards, stack, context),
-           {:ok, _expr_type, context} <- of_expr(body, :dynamic, stack, context),
-           do: {:ok, keep_warnings(acc, context)}
+      case Pattern.of_head(patterns, guards, stack, context) do
+        {:ok, _, context} ->
+          with {:ok, _expr_type, context} <- of_expr(body, :dynamic, stack, context) do
+            {:ok, keep_warnings(acc, context)}
+          end
+
+        error ->
+          # Skip the clause if it the head has an error
+          if meta[:generated], do: {:ok, acc}, else: error
+      end
     end)
   end
 

lib/elixir/lib/module/types/helpers.ex

@@ -101,6 +101,30 @@ defmodule Module.Types.Helpers do
 
   defp do_map_reduce_ok([], {list, acc}, _fun), do: {:ok, Enum.reverse(list), acc}
 
+  @doc """
+  Like `Enum.flat_map/2` but only continues while `fun` returns `{:ok, list}`
+  and stops on `{:error, reason}`.
+  """
+  def flat_map_ok(list, fun) do
+    do_flat_map_ok(list, [], fun)
+  end
+
+  defp do_flat_map_ok([head | tail], acc, fun) do
+    case fun.(head) do
+      {:ok, elem} ->
+        do_flat_map_ok(tail, [elem | acc], fun)
+
+      {:error, reason} ->
+        {:error, reason}
+    end
+  end
+
+  defp do_flat_map_ok([], acc, _fun), do: {:ok, Enum.reverse(Enum.concat(acc))}
+
+  @doc """
+  Like `Enum.flat_map_reduce/3` but only continues while `fun` returns `{:ok, list, acc}`
+  and stops on `{:error, reason}`.
+  """
   def flat_map_reduce_ok(list, acc, fun) do
     do_flat_map_reduce_ok(list, {[], acc}, fun)
   end
@@ -130,6 +154,10 @@ defmodule Module.Types.Helpers do
     end
   end
 
+  @doc """
+  Combines a list of guard expressions `when x when y when z` to an expression
+  combined with `or`, `x or y or z`.
+  """
   # TODO: Remove this and let multiple when be treated as multiple clauses,
   #       meaning they will be intersection types
   def guards_to_or([]) do
@@ -139,4 +167,30 @@ defmodule Module.Types.Helpers do
   def guards_to_or(guards) do
     Enum.reduce(guards, fn guard, acc -> {{:., [], [:erlang, :orelse]}, [], [guard, acc]} end)
   end
+
+  @doc """
+  Like `Enum.zip/1` but will zip multiple lists together instead of only two.
+  """
+  def zip_many(lists) do
+    zip_many(lists, [], [[]])
+  end
+
+  defp zip_many([], [], [[] | acc]) do
+    map_reverse(acc, [], &Enum.reverse/1)
+  end
+
+  defp zip_many([], remain, [last | acc]) do
+    zip_many(Enum.reverse(remain), [], [[] | [last | acc]])
+  end
+
+  defp zip_many([[] | _], remain, [last | acc]) do
+    zip_many(Enum.reverse(remain), [], [last | acc])
+  end
+
+  defp zip_many([[elem | list1] | list2], remain, [last | acc]) do
+    zip_many(list2, [list1 | remain], [[elem | last] | acc])
+  end
+
+  defp map_reverse([], acc, _fun), do: acc
+  defp map_reverse([head | tail], acc, fun), do: map_reverse(tail, [fun.(head) | acc], fun)
 end

lib/elixir/lib/module/types/of.ex

@@ -327,7 +327,7 @@ defmodule Module.Types.Of do
     %{context | warnings: [{__MODULE__, warning, location} | context.warnings]}
   end
 
-  ## Warning formating
+  ## Warning formatting
 
   def format_warning({:undefined_module, module, fun, arity}) do
     [

lib/elixir/lib/module/types/pattern.ex

@@ -10,8 +10,8 @@ defmodule Module.Types.Pattern do
   def of_head(patterns, guards, stack, context) do
     with {:ok, types, context} <-
            map_reduce_ok(patterns, context, &of_pattern(&1, stack, &2)),
-         # TODO: Check that of_guard/3 returns boolean() | :fail
-         {:ok, _, context} <- of_guard(guards_to_or(guards), stack, context),
+         # TODO: Check that of_guard/4 returns boolean() | :fail
+         {:ok, _, context} <- of_guard(guards_to_or(guards), :dynamic, stack, context),
          do: {:ok, types, context}
   end
 
@@ -86,69 +86,75 @@ defmodule Module.Types.Pattern do
   # TODO: Some guards can be changed to intersection types or higher order types
   @boolean {:union, [{:atom, true}, {:atom, false}]}
   @number {:union, [:integer, :float]}
+  @unary_number_fun [{[:integer], :integer}, {[@number], :float}]
+  @binary_number_fun [
+    {[:integer, :integer], :integer},
+    {[:float, @number], :float},
+    {[@number, :float], :float}
+  ]
 
   @guard_functions %{
-    {:is_atom, 1} => {[:atom], @boolean},
-    {:is_binary, 1} => {[:binary], @boolean},
-    {:is_bitstring, 1} => {[:binary], @boolean},
-    {:is_boolean, 1} => {[@boolean], @boolean},
-    {:is_float, 1} => {[:float], @boolean},
-    {:is_function, 1} => {[:fun], @boolean},
-    {:is_function, 2} => {[:fun, :integer], @boolean},
-    {:is_integer, 1} => {[:integer], @boolean},
-    {:is_list, 1} => {[{:list, :dynamic}], @boolean},
-    {:is_map, 1} => {[{:map, [{:optional, :dynamic, :dynamic}]}], @boolean},
-    {:is_map_key, 2} => {[:dynamic, {:map, [{:optional, :dynamic, :dynamic}]}], :dynamic},
-    {:is_number, 1} => {[@number], @boolean},
-    {:is_pid, 1} => {[:pid], @boolean},
-    {:is_port, 1} => {[:port], @boolean},
-    {:is_reference, 1} => {[:reference], @boolean},
-    {:is_tuple, 1} => {[:tuple], @boolean},
-    {:<, 2} => {[:dynamic, :dynamic], @boolean},
-    {:"=<", 2} => {[:dynamic, :dynamic], @boolean},
-    {:>, 2} => {[:dynamic, :dynamic], @boolean},
-    {:>=, 2} => {[:dynamic, :dynamic], @boolean},
-    {:"/=", 2} => {[:dynamic, :dynamic], @boolean},
-    {:"=/=", 2} => {[:dynamic, :dynamic], @boolean},
-    {:==, 2} => {[:dynamic, :dynamic], @boolean},
-    {:"=:=", 2} => {[:dynamic, :dynamic], @boolean},
-    {:*, 2} => {[@number, @number], @number},
-    {:+, 1} => {[@number], @number},
-    {:+, 2} => {[@number, @number], @number},
-    {:-, 1} => {[@number], @number},
-    {:-, 2} => {[@number, @number], @number},
-    {:/, 2} => {[@number, @number], @number},
-    {:abs, 1} => {[@number], @number},
-    {:ceil, 1} => {[@number], :integer},
-    {:floor, 1} => {[@number], :integer},
-    {:round, 1} => {[@number], :integer},
-    {:trunc, 1} => {[@number], :integer},
-    {:element, 2} => {[:integer, :tuple], :dynamic},
-    {:hd, 1} => {[{:list, :dynamic}], :dynamic},
-    {:length, 1} => {[{:list, :dynamic}], :integer},
-    {:map_get, 2} => {[:dynamic, {:map, [{:optional, :dynamic, :dynamic}]}], :dynamic},
-    {:map_size, 1} => {[{:map, [{:optional, :dynamic, :dynamic}]}], :integer},
-    {:tl, 1} => {[{:list, :dynamic}], :dynamic},
-    {:tuple_size, 1} => {[:tuple], :integer},
-    {:node, 1} => {[{:union, [:pid, :reference, :port]}], :atom},
-    {:binary_part, 3} => {[:binary, :integer, :integer], :binary},
-    {:bit_size, 1} => {[:binary], :integer},
-    {:byte_size, 1} => {[:binary], :integer},
-    {:size, 1} => {[{:union, [:binary, :tuple]}], @boolean},
-    {:div, 2} => {[:integer, :integer], :integer},
-    {:rem, 2} => {[:integer, :integer], :integer},
-    {:node, 0} => {[], :atom},
-    {:self, 0} => {[], :pid},
-    {:bnot, 1} => {[:integer], :integer},
-    {:band, 2} => {[:integer, :integer], :integer},
-    {:bor, 2} => {[:integer, :integer], :integer},
-    {:bxor, 2} => {[:integer, :integer], :integer},
-    {:bsl, 2} => {[:integer, :integer], :integer},
-    {:bsr, 2} => {[:integer, :integer], :integer},
-    {:or, 2} => {[@boolean, @boolean], @boolean},
-    {:and, 2} => {[@boolean, @boolean], @boolean},
-    {:xor, 2} => {[@boolean, @boolean], @boolean},
-    {:not, 1} => {[@boolean], @boolean}
+    {:is_atom, 1} => [{[:atom], @boolean}],
+    {:is_binary, 1} => [{[:binary], @boolean}],
+    {:is_bitstring, 1} => [{[:binary], @boolean}],
+    {:is_boolean, 1} => [{[@boolean], @boolean}],
+    {:is_float, 1} => [{[:float], @boolean}],
+    {:is_function, 1} => [{[:fun], @boolean}],
+    {:is_function, 2} => [{[:fun, :integer], @boolean}],
+    {:is_integer, 1} => [{[:integer], @boolean}],
+    {:is_list, 1} => [{[{:list, :dynamic}], @boolean}],
+    {:is_map, 1} => [{[{:map, [{:optional, :dynamic, :dynamic}]}], @boolean}],
+    {:is_map_key, 2} => [{[:dynamic, {:map, [{:optional, :dynamic, :dynamic}]}], :dynamic}],
+    {:is_number, 1} => [{[@number], @boolean}],
+    {:is_pid, 1} => [{[:pid], @boolean}],
+    {:is_port, 1} => [{[:port], @boolean}],
+    {:is_reference, 1} => [{[:reference], @boolean}],
+    {:is_tuple, 1} => [{[:tuple], @boolean}],
+    {:<, 2} => [{[:dynamic, :dynamic], @boolean}],
+    {:"=<", 2} => [{[:dynamic, :dynamic], @boolean}],
+    {:>, 2} => [{[:dynamic, :dynamic], @boolean}],
+    {:>=, 2} => [{[:dynamic, :dynamic], @boolean}],
+    {:"/=", 2} => [{[:dynamic, :dynamic], @boolean}],
+    {:"=/=", 2} => [{[:dynamic, :dynamic], @boolean}],
+    {:==, 2} => [{[:dynamic, :dynamic], @boolean}],
+    {:"=:=", 2} => [{[:dynamic, :dynamic], @boolean}],
+    {:*, 2} => @binary_number_fun,
+    {:+, 1} => @unary_number_fun,
+    {:+, 2} => @binary_number_fun,
+    {:-, 1} => @unary_number_fun,
+    {:-, 2} => @binary_number_fun,
+    {:/, 2} => @binary_number_fun,
+    {:abs, 1} => @unary_number_fun,
+    {:ceil, 1} => [{[@number], :integer}],
+    {:floor, 1} => [{[@number], :integer}],
+    {:round, 1} => [{[@number], :integer}],
+    {:trunc, 1} => [{[@number], :integer}],
+    {:element, 2} => [{[:integer, :tuple], :dynamic}],
+    {:hd, 1} => [{[{:list, :dynamic}], :dynamic}],
+    {:length, 1} => [{[{:list, :dynamic}], :integer}],
+    {:map_get, 2} => [{[:dynamic, {:map, [{:optional, :dynamic, :dynamic}]}], :dynamic}],
+    {:map_size, 1} => [{[{:map, [{:optional, :dynamic, :dynamic}]}], :integer}],
+    {:tl, 1} => [{[{:list, :dynamic}], :dynamic}],
+    {:tuple_size, 1} => [{[:tuple], :integer}],
+    {:node, 1} => [{[{:union, [:pid, :reference, :port]}], :atom}],
+    {:binary_part, 3} => [{[:binary, :integer, :integer], :binary}],
+    {:bit_size, 1} => [{[:binary], :integer}],
+    {:byte_size, 1} => [{[:binary], :integer}],
+    {:size, 1} => [{[{:union, [:binary, :tuple]}], @boolean}],
+    {:div, 2} => [{[:integer, :integer], :integer}],
+    {:rem, 2} => [{[:integer, :integer], :integer}],
+    {:node, 0} => [{[], :atom}],
+    {:self, 0} => [{[], :pid}],
+    {:bnot, 1} => [{[:integer], :integer}],
+    {:band, 2} => [{[:integer, :integer], :integer}],
+    {:bor, 2} => [{[:integer, :integer], :integer}],
+    {:bxor, 2} => [{[:integer, :integer], :integer}],
+    {:bsl, 2} => [{[:integer, :integer], :integer}],
+    {:bsr, 2} => [{[:integer, :integer], :integer}],
+    {:or, 2} => [{[@boolean, @boolean], @boolean}],
+    {:and, 2} => [{[@boolean, @boolean], @boolean}],
+    {:xor, 2} => [{[@boolean, @boolean], @boolean}],
+    {:not, 1} => [{[@boolean], @boolean}]
 
     # Following guards are matched explicitly to handle
     # type guard functions such as is_atom/1
@@ -163,7 +169,6 @@ defmodule Module.Types.Pattern do
     :is_boolean,
     :is_float,
     :is_function,
-    :is_function,
     :is_integer,
     :is_list,
     :is_map,
@@ -178,26 +183,27 @@ defmodule Module.Types.Pattern do
   Refines the type variables in the typing context using type check guards
   such as `is_integer/1`.
   """
-  def of_guard(expr, %{context: stack_context} = stack, context) when stack_context != :pattern do
-    of_guard(expr, %{stack | context: :pattern}, context)
+  def of_guard(expr, expected, %{context: stack_context} = stack, context)
+      when stack_context != :pattern do
+    of_guard(expr, expected, %{stack | context: :pattern}, context)
   end
 
-  def of_guard({{:., _, [:erlang, :andalso]}, _, [left, right]} = expr, stack, context) do
+  def of_guard({{:., _, [:erlang, :andalso]}, _, [left, right]} = expr, _expected, stack, context) do
     stack = push_expr_stack(expr, stack)
 
-    with {:ok, left_type, context} <- of_guard(left, stack, context),
+    with {:ok, left_type, context} <- of_guard(left, @boolean, stack, context),
          {:ok, _, context} <- unify(left_type, @boolean, stack, context),
-         {:ok, right_type, context} <- of_guard(right, keep_guarded(stack), context),
+         {:ok, right_type, context} <- of_guard(right, :dynamic, keep_guarded(stack), context),
          do: {:ok, to_union([@boolean, right_type], context), context}
   end
 
-  def of_guard({{:., _, [:erlang, :orelse]}, _, [left, right]} = expr, stack, context) do
+  def of_guard({{:., _, [:erlang, :orelse]}, _, [left, right]} = expr, _expected, stack, context) do
     stack = push_expr_stack(expr, stack)
     left_indexes = collect_var_indexes_from_expr(left, context)
     right_indexes = collect_var_indexes_from_expr(right, context)
 
-    with {:ok, left_type, left_context} <- of_guard(left, stack, context),
-         {:ok, _right_type, right_context} <- of_guard(right, stack, context),
+    with {:ok, left_type, left_context} <- of_guard(left, @boolean, stack, context),
+         {:ok, _right_type, right_context} <- of_guard(right, :dynamic, stack, context),
          context =
            merge_context_or(
              left_indexes,
@@ -214,71 +220,147 @@ defmodule Module.Types.Pattern do
   # The unary operators + and - are special cased to avoid common warnings until
   # we add support for intersection types for the guard functions
   # -integer / +integer
-  def of_guard({{:., _, [:erlang, guard]}, _, [integer]}, _stack, context)
+  def of_guard({{:., _, [:erlang, guard]}, _, [integer]}, _expected, _stack, context)
       when guard in [:+, :-] and is_integer(integer) do
     {:ok, :integer, context}
   end
 
   # -float / +float
-  def of_guard({{:., _, [:erlang, guard]}, _, [float]}, _stack, context)
+  def of_guard({{:., _, [:erlang, guard]}, _, [float]}, _expected, _stack, context)
       when guard in [:+, :-] and is_float(float) do
     {:ok, :float, context}
   end
 
+  # tuple_size(arg) == integer
+  def of_guard(
+        {{:., _, [:erlang, :==]}, _, [{{:., _, [:erlang, :tuple_size]}, _, [var]}, size]} = expr,
+        expected,
+        stack,
+        context
+      )
+      when is_var(var) and is_integer(size) do
+    of_tuple_size(var, size, expr, expected, stack, context)
+  end
+
+  # integer == tuple_size(arg)
+  def of_guard(
+        {{:., _, [:erlang, :==]}, _, [size, {{:., _, [:erlang, :tuple_size]}, _, [var]}]} = expr,
+        expected,
+        stack,
+        context
+      )
+      when is_var(var) and is_integer(size) do
+    of_tuple_size(var, size, expr, expected, stack, context)
+  end
+
   # fun(args)
-  def of_guard({{:., _, [:erlang, guard]}, _, args} = expr, stack, context) do
-    stack = push_expr_stack(expr, stack)
-    {param_types, return_type} = guard_signature(guard, length(args))
+  def of_guard({{:., _, [:erlang, guard]}, _, args} = expr, expected, stack, context) do
     type_guard? = type_guard?(guard)
     {consider_type_guards?, keep_guarded?} = stack.type_guards
+    signature = guard_signature(guard, length(args))
 
     # Only check type guards in the context of and/or/not,
     # a type guard in the context of is_tuple(x) > :foo
     # should not affect the inference of x
     if not type_guard? or consider_type_guards? do
+      stack = push_expr_stack(expr, stack)
+      expected_clauses = filter_clauses(signature, expected, stack, context)
+      param_unions = signature_to_param_unions(expected_clauses, context)
       arg_stack = %{stack | type_guards: {false, keep_guarded?}}
+      mfa = {:erlang, guard, length(args)}
 
       with {:ok, arg_types, context} <-
-             map_reduce_ok(args, context, &of_guard(&1, arg_stack, &2)),
-           {:ok, context} <- unify_call(arg_types, param_types, stack, context) do
-        {arg_types, guard_sources} =
-          case arg_types do
-            [{:var, index} | rest_arg_types] when type_guard? ->
-              guard_sources = Map.put_new(context.guard_sources, index, :guarded)
-              {rest_arg_types, guard_sources}
-
-            _ ->
-              {arg_types, context.guard_sources}
-          end
-
-        guard_sources =
-          Enum.reduce(arg_types, guard_sources, fn
-            {:var, index}, guard_sources ->
-              Map.update(guard_sources, index, :fail, &guarded_if_keep_guarded(&1, keep_guarded?))
-
-            _, guard_sources ->
-              guard_sources
-          end)
-
+             map_reduce_ok(Enum.zip(args, param_unions), context, fn {arg, param}, context ->
+               of_guard(arg, param, arg_stack, context)
+             end),
+           {:ok, return_type, context} <-
+             unify_call(
+               arg_types,
+               expected_clauses,
+               expected,
+               mfa,
+               signature,
+               stack,
+               context,
+               type_guard?
+             ) do
+        guard_sources = guard_sources(arg_types, type_guard?, keep_guarded?, context)
         {:ok, return_type, %{context | guard_sources: guard_sources}}
       end
     else
-      {:ok, return_type, context}
+      # Assume that type guards always return boolean
+      boolean = {:union, [atom: true, atom: false]}
+      [{_params, ^boolean}] = signature
+      {:ok, boolean, context}
     end
   end
 
   # map.field
-  def of_guard({{:., meta1, [map, field]}, meta2, []}, stack, context) do
-    of_guard({{:., meta1, [:erlang, :map_get]}, meta2, [field, map]}, stack, context)
+  def of_guard({{:., meta1, [map, field]}, meta2, []}, expected, stack, context) do
+    of_guard({{:., meta1, [:erlang, :map_get]}, meta2, [field, map]}, expected, stack, context)
   end
 
   # var
-  def of_guard(var, _stack, context) when is_var(var) do
+  def of_guard(var, _expected, _stack, context) when is_var(var) do
     {:ok, get_var!(var, context), context}
   end
 
-  def of_guard(expr, stack, context) do
-    of_shared(expr, stack, context, &of_guard/3)
+  def of_guard(expr, _expected, stack, context) do
+    of_shared(expr, stack, context, &of_guard(&1, :dynamic, &2, &3))
+  end
+
+  defp of_tuple_size(var, size, expr, _expected, stack, context) do
+    {consider_type_guards?, _keep_guarded?} = stack.type_guards
+
+    result =
+      if consider_type_guards? do
+        stack = push_expr_stack(expr, stack)
+        tuple_elems = Enum.map(1..size//1, fn _ -> :dynamic end)
+
+        with {:ok, type, context} <- of_guard(var, :dynamic, stack, context),
+             {:ok, _type, context} <- unify({:tuple, size, tuple_elems}, type, stack, context),
+             do: {:ok, context}
+      else
+        {:ok, context}
+      end
+
+    case result do
+      {:ok, context} ->
+        boolean = {:union, [atom: true, atom: false]}
+        {:ok, boolean, context}
+
+      {:error, reason} ->
+        {:error, reason}
+    end
+  end
+
+  defp signature_to_param_unions(signature, context) do
+    signature
+    |> Enum.map(fn {params, _return} -> params end)
+    |> zip_many()
+    |> Enum.map(&to_union(&1, context))
+  end
+
+  # Collect guard sources from argument types, see type context documentation
+  # for more information
+  defp guard_sources(arg_types, type_guard?, keep_guarded?, context) do
+    {arg_types, guard_sources} =
+      case arg_types do
+        [{:var, index} | rest_arg_types] when type_guard? ->
+          guard_sources = Map.put_new(context.guard_sources, index, :guarded)
+          {rest_arg_types, guard_sources}
+
+        _ ->
+          {arg_types, context.guard_sources}
+      end
+
+    Enum.reduce(arg_types, guard_sources, fn
+      {:var, index}, guard_sources ->
+        Map.update(guard_sources, index, :fail, &guarded_if_keep_guarded(&1, keep_guarded?))
+
+      _, guard_sources ->
+        guard_sources
+    end)
   end
 
   defp collect_var_indexes_from_expr(expr, context) do
@@ -296,15 +378,162 @@ defmodule Module.Types.Pattern do
     Map.keys(vars)
   end
 
-  defp unify_call(args, params, stack, context) do
-    reduce_ok(Enum.zip(args, params), context, fn {arg, param}, context ->
-      case unify(arg, param, stack, context) do
-        {:ok, _, context} -> {:ok, context}
-        {:error, reason} -> {:error, reason}
-      end
+  defp unify_call(args, clauses, _expected, _mfa, _signature, stack, context, true = _type_guard?) do
+    unify_type_guard_call(args, clauses, stack, context)
+  end
+
+  defp unify_call(args, clauses, expected, mfa, signature, stack, context, false = _type_guard?) do
+    unify_call(args, clauses, expected, mfa, signature, stack, context)
+  end
+
+  defp unify_call([], [{[], return}], _expected, _mfa, _signature, _stack, context) do
+    {:ok, return, context}
+  end
+
+  defp unify_call(args, clauses, expected, mfa, signature, stack, context) do
+    # Given the arguments:
+    # foo | bar, {:ok, baz | bat}
+
+    # Expand unions in arguments:
+    # foo | bar, {:ok, baz} | {:ok, bat}
+
+    # Permute arguments:
+    # foo, {:ok, baz}
+    # foo, {:ok, bat}
+    # bar, {:ok, baz}
+    # bar, {:ok, bat}
+
+    flatten_args = Enum.map(args, &flatten_union(&1, context))
+    cartesian_args = cartesian_product(flatten_args)
+
+    # Remove clauses that do not match the expected type
+    # Ignore type variables in parameters by changing them to dynamic
+
+    clauses =
+      clauses
+      |> filter_clauses(expected, stack, context)
+      |> Enum.map(fn {params, return} ->
+        {Enum.map(params, &var_to_dynamic/1), return}
+      end)
+
+    # For each permuted argument find the clauses they match
+    # All arguments must match at least one clause, but all clauses
+    # do not need to match
+    # Collect the return values from clauses that matched and collect
+    # the type contexts from unifying argument and parameter to
+    # infer type variables in arguments
+    result =
+      flat_map_ok(cartesian_args, fn cartesian_args ->
+        result =
+          Enum.flat_map(clauses, fn {params, return} ->
+            result =
+              map_ok(Enum.zip(cartesian_args, params), fn {arg, param} ->
+                case unify(arg, param, stack, context) do
+                  {:ok, _type, context} -> {:ok, context}
+                  {:error, reason} -> {:error, reason}
+                end
+              end)
+
+            case result do
+              {:ok, contexts} -> [{return, contexts}]
+              {:error, _reason} -> []
+            end
+          end)
+
+        if result != [] do
+          {:ok, result}
+        else
+          {:error, args}
+        end
+      end)
+
+    case result do
+      {:ok, returns_contexts} ->
+        {success_returns, contexts} = Enum.unzip(returns_contexts)
+        contexts = Enum.concat(contexts)
+
+        indexes =
+          for types <- flatten_args,
+              type <- types,
+              index <- collect_var_indexes_from_type(type),
+              do: index,
+              uniq: true
+
+        # Build unions from collected type contexts to unify with
+        # type variables from arguments
+        result =
+          map_reduce_ok(indexes, context, fn index, context ->
+            union =
+              contexts
+              |> Enum.map(&Map.fetch!(&1.types, index))
+              |> Enum.reject(&(&1 == :unbound))
+
+            if union == [] do
+              {:ok, {:var, index}, context}
+            else
+              unify({:var, index}, to_union(union, context), stack, context)
+            end
+          end)
+
+        case result do
+          {:ok, _types, context} -> {:ok, to_union(success_returns, context), context}
+          {:error, reason} -> {:error, reason}
+        end
+
+      {:error, args} ->
+        error(:unable_apply, {mfa, args, expected, signature, stack}, context)
+    end
+  end
+
+  defp unify_type_guard_call(args, [{params, return}], stack, context) do
+    result =
+      reduce_ok(Enum.zip(args, params), context, fn {arg, param}, context ->
+        case unify(arg, param, stack, context) do
+          {:ok, _, context} -> {:ok, context}
+          {:error, reason} -> {:error, reason}
+        end
+      end)
+
+    case result do
+      {:ok, context} -> {:ok, return, context}
+      {:error, reason} -> {:error, reason}
+    end
+  end
+
+  defp cartesian_product(lists) do
+    List.foldr(lists, [[]], fn list, acc ->
+      for elem_list <- list,
+          list_acc <- acc,
+          do: [elem_list | list_acc]
     end)
   end
 
+  defp var_to_dynamic(type) do
+    {type, _acc} =
+      walk(type, :ok, fn
+        {:var, _index}, :ok ->
+          {:dynamic, :ok}
+
+        other, :ok ->
+          {other, :ok}
+      end)
+
+    type
+  end
+
+  defp collect_var_indexes_from_type(type) do
+    {_type, indexes} =
+      walk(type, [], fn
+        {:var, index}, indexes ->
+          {{:var, index}, [index | indexes]}
+
+        other, indexes ->
+          {other, indexes}
+      end)
+
+    indexes
+  end
+
   defp merge_context_or(left_indexes, right_indexes, context, stack, left, right) do
     left_different = filter_different_indexes(left_indexes, left, right)
     right_different = filter_different_indexes(right_indexes, left, right)
@@ -376,13 +605,21 @@ defmodule Module.Types.Pattern do
   defp keep_guarded(%{type_guards: {consider?, _}} = stack),
     do: %{stack | type_guards: {consider?, true}}
 
-  defp guard_signature(name, arity) do
-    Map.fetch!(@guard_functions, {name, arity})
+  defp filter_clauses(signature, expected, stack, context) do
+    Enum.filter(signature, fn {_params, return} ->
+      match?({:ok, _type, _context}, unify(return, expected, stack, context))
+    end)
   end
 
-  defp type_guard?(name) do
-    name in @type_guards
-  end
+  Enum.each(@guard_functions, fn {{name, arity}, signature} ->
+    defp guard_signature(unquote(name), unquote(arity)), do: unquote(Macro.escape(signature))
+  end)
+
+  Enum.each(@type_guards, fn name ->
+    defp type_guard?(unquote(name)), do: true
+  end)
+
+  defp type_guard?(name) when is_atom(name), do: false
 
   ## Shared
 

lib/elixir/lib/module/types/unify.ex

@@ -10,6 +10,7 @@ defmodule Module.Types.Unify do
   #   {:atom, atom} < :atom
   #   :integer
   #   :float
+  #   :binary
   #   :pid
   #   :port
   #   :reference
@@ -20,55 +21,37 @@ defmodule Module.Types.Unify do
   #   {:tuple, size, [type]} < :tuple
   #   {:union, [type]}
   #   {:map, [{:required | :optional, key_type, value_type}]}
+  #   {:fun, [{params, return}]}
   #
   # Once new types are added, they should be considered in:
   #
   #   * unify (all)
   #   * format_type (all)
   #   * subtype? (subtypes only)
-  #   * has_unbound_var? (composite only)
   #   * recursive_type? (composite only)
-  #   * collect_vars (composite only)
+  #   * collect_var_indexes (composite only)
   #   * lift_types (composite only)
+  #   * flatten_union (composite only)
+  #   * walk (composite only)
   #
 
   @doc """
   Unifies two types and returns the unified type and an updated typing context
   or an error in case of a typing conflict.
   """
-  def unify(source, target, stack, context) do
-    case do_unify(source, target, stack, context) do
-      {:ok, type, context} ->
-        {:ok, type, context}
-
-      {:error, reason} ->
-        if stack.context == :pattern do
-          case do_unify(target, source, stack, context) do
-            {:ok, type, context} ->
-              {:ok, type, context}
-
-            {:error, _} ->
-              {:error, reason}
-          end
-        else
-          {:error, reason}
-        end
-    end
-  end
-
-  defp do_unify(same, same, _stack, context) do
+  def unify(same, same, _stack, context) do
     {:ok, same, context}
   end
 
-  defp do_unify(type, {:var, var}, stack, context) do
-    unify_var(var, type, stack, context, _var_source = false)
-  end
-
-  defp do_unify({:var, var}, type, stack, context) do
+  def unify({:var, var}, type, stack, context) do
     unify_var(var, type, stack, context, _var_source = true)
   end
 
-  defp do_unify({:tuple, n, sources}, {:tuple, n, targets}, stack, context) do
+  def unify(type, {:var, var}, stack, context) do
+    unify_var(var, type, stack, context, _var_source = false)
+  end
+
+  def unify({:tuple, n, sources}, {:tuple, n, targets}, stack, context) do
     result =
       map_reduce_ok(Enum.zip(sources, targets), context, fn {source, target}, context ->
         unify(source, target, stack, context)
@@ -80,26 +63,26 @@ defmodule Module.Types.Unify do
     end
   end
 
-  defp do_unify({:list, source}, {:list, target}, stack, context) do
+  def unify({:list, source}, {:list, target}, stack, context) do
     case unify(source, target, stack, context) do
       {:ok, type, context} -> {:ok, {:list, type}, context}
       {:error, reason} -> {:error, reason}
     end
   end
 
-  defp do_unify({:map, source_pairs}, {:map, target_pairs}, stack, context) do
+  def unify({:map, source_pairs}, {:map, target_pairs}, stack, context) do
     unify_maps(source_pairs, target_pairs, stack, context)
   end
 
-  defp do_unify(source, :dynamic, _stack, context) do
+  def unify(source, :dynamic, _stack, context) do
     {:ok, source, context}
   end
 
-  defp do_unify(:dynamic, target, _stack, context) do
+  def unify(:dynamic, target, _stack, context) do
     {:ok, target, context}
   end
 
-  defp do_unify({:union, types}, target, stack, context) do
+  def unify({:union, types}, target, stack, context) do
     unify_result =
       map_reduce_ok(types, context, fn type, context ->
         unify(type, target, stack, context)
@@ -111,7 +94,7 @@ defmodule Module.Types.Unify do
     end
   end
 
-  defp do_unify(source, target, stack, context) do
+  def unify(source, target, stack, context) do
     cond do
       # TODO: This condition exists to handle unions with unbound vars.
       match?({:union, _}, target) and has_unbound_var?(target, context) ->
@@ -125,11 +108,11 @@ defmodule Module.Types.Unify do
     end
   end
 
-  defp unify_var(var, :dynamic, _stack, context, _var_source?) do
+  def unify_var(var, :dynamic, _stack, context, _var_source?) do
     {:ok, {:var, var}, context}
   end
 
-  defp unify_var(var, type, stack, context, var_source?) do
+  def unify_var(var, type, stack, context, var_source?) do
     case context.types do
       %{^var => :unbound} ->
         context = refine_var!(var, type, stack, context)
@@ -205,7 +188,7 @@ defmodule Module.Types.Unify do
   # * All required keys on each side need to match to the other side.
   # * All optional keys on each side that do not match must be discarded.
 
-  defp unify_maps(source_pairs, target_pairs, stack, context) do
+  def unify_maps(source_pairs, target_pairs, stack, context) do
     {source_required, source_optional} = split_pairs(source_pairs)
     {target_required, target_optional} = split_pairs(target_pairs)
 
@@ -236,7 +219,7 @@ defmodule Module.Types.Unify do
     end
   end
 
-  defp unify_source_required(source_required, target_pairs, stack, context) do
+  def unify_source_required(source_required, target_pairs, stack, context) do
     map_reduce_ok(source_required, context, fn {source_key, source_value}, context ->
       Enum.find_value(target_pairs, fn {target_kind, target_key, target_value} ->
         with {:ok, key, context} <- unify(source_key, target_key, stack, context) do
@@ -256,7 +239,7 @@ defmodule Module.Types.Unify do
     end)
   end
 
-  defp unify_target_required(target_required, source_pairs, stack, context) do
+  def unify_target_required(target_required, source_pairs, stack, context) do
     map_reduce_ok(target_required, context, fn {target_key, target_value}, context ->
       Enum.find_value(source_pairs, fn {source_kind, source_key, source_value} ->
         with {:ok, key, context} <- unify(source_key, target_key, stack, context) do
@@ -276,7 +259,7 @@ defmodule Module.Types.Unify do
     end)
   end
 
-  defp unify_source_optional(source_optional, target_optional, stack, context) do
+  def unify_source_optional(source_optional, target_optional, stack, context) do
     flat_map_reduce_ok(source_optional, context, fn {source_key, source_value}, context ->
       Enum.find_value(target_optional, fn {target_key, target_value} ->
         with {:ok, key, context} <- unify(source_key, target_key, stack, context) do
@@ -296,7 +279,7 @@ defmodule Module.Types.Unify do
     end)
   end
 
-  defp unify_target_optional(target_optional, source_optional, stack, context) do
+  def unify_target_optional(target_optional, source_optional, stack, context) do
     flat_map_reduce_ok(target_optional, context, fn {target_key, target_value}, context ->
       Enum.find_value(source_optional, fn {source_key, source_value} ->
         with {:ok, key, context} <- unify(source_key, target_key, stack, context) do
@@ -325,7 +308,7 @@ defmodule Module.Types.Unify do
     {required, optional}
   end
 
-  defp error(type, reason, context), do: {:error, {type, reason, context}}
+  def error(type, reason, context), do: {:error, {type, reason, context}}
 
   @doc """
   Push expression to stack.
@@ -505,6 +488,12 @@ defmodule Module.Types.Unify do
     end)
   end
 
+  defp recursive_type?({:fun, clauses}, parents, context) do
+    Enum.any?(clauses, fn {args, return} ->
+      Enum.any?([return | args], &recursive_type?(&1, [clauses | parents], context))
+    end)
+  end
+
   defp recursive_type?(_other, _parents, _context) do
     false
   end
@@ -512,64 +501,54 @@ defmodule Module.Types.Unify do
   @doc """
   Collects all type vars recursively.
   """
-  def collect_var_indexes(type, context, acc \\ %{})
+  def collect_var_indexes(type, context, acc \\ %{}) do
+    {_type, indexes} =
+      walk(type, acc, fn
+        {:var, var}, acc ->
+          case acc do
+            %{^var => _} ->
+              {{:var, var}, acc}
 
-  def collect_var_indexes({:var, var}, context, acc) do
-    case acc do
-      %{^var => _} ->
-        acc
+            %{} ->
+              case context.types do
+                %{^var => :unbound} ->
+                  {{:var, var}, Map.put(acc, var, true)}
 
-      %{} ->
-        case context.types do
-          %{^var => :unbound} -> Map.put(acc, var, true)
-          %{^var => type} -> collect_var_indexes(type, context, Map.put(acc, var, true))
-        end
-    end
+                %{^var => type} ->
+                  {{:var, var}, collect_var_indexes(type, context, Map.put(acc, var, true))}
+              end
+          end
+
+        other, acc ->
+          {other, acc}
+      end)
+
+    indexes
   end
 
-  def collect_var_indexes({:tuple, _, args}, context, acc),
-    do: Enum.reduce(args, acc, &collect_var_indexes(&1, context, &2))
-
-  def collect_var_indexes({:union, args}, context, acc),
-    do: Enum.reduce(args, acc, &collect_var_indexes(&1, context, &2))
-
-  def collect_var_indexes({:list, arg}, context, acc),
-    do: collect_var_indexes(arg, context, acc)
-
-  def collect_var_indexes({:map, pairs}, context, acc) do
-    Enum.reduce(pairs, acc, fn {_, key, value}, acc ->
-      collect_var_indexes(value, context, collect_var_indexes(key, context, acc))
-    end)
-  end
-
-  def collect_var_indexes(_type, _context, acc), do: acc
-
   @doc """
   Checks if the type has a type var.
   """
-  def has_unbound_var?({:var, var}, context) do
-    case context.types do
-      %{^var => :unbound} -> true
-      %{^var => type} -> has_unbound_var?(type, context)
-    end
-  end
+  def has_unbound_var?(type, context) do
+    walk(type, :ok, fn
+      {:var, var}, acc ->
+        case context.types do
+          %{^var => :unbound} ->
+            throw(:has_unbound_var?)
 
-  def has_unbound_var?({:tuple, _, args}, context),
-    do: Enum.any?(args, &has_unbound_var?(&1, context))
+          %{^var => type} ->
+            has_unbound_var?(type, context)
+            {{:var, var}, acc}
+        end
 
-  def has_unbound_var?({:union, args}, context),
-    do: Enum.any?(args, &has_unbound_var?(&1, context))
-
-  def has_unbound_var?({:list, arg}, context),
-    do: has_unbound_var?(arg, context)
-
-  def has_unbound_var?({:map, pairs}, context) do
-    Enum.any?(pairs, fn {_, key, value} ->
-      has_unbound_var?(key, context) or has_unbound_var?(value, context)
+      other, acc ->
+        {other, acc}
     end)
-  end
 
-  def has_unbound_var?(_type, _context), do: false
+    false
+  catch
+    :throw, :has_unbound_var? -> true
+  end
 
   @doc """
   Returns true if it is a singleton type.
@@ -669,17 +648,15 @@ defmodule Module.Types.Unify do
   def to_union([type], _context), do: type
 
   def to_union(types, context) when types != [] do
-    flat_types = flatten_union(types)
-
-    case unique_super_types(flat_types, context) do
+    case unique_super_types(unnest_unions(types), context) do
       [type] -> type
       types -> {:union, types}
     end
   end
 
-  defp flatten_union(types) do
+  defp unnest_unions(types) do
     Enum.flat_map(types, fn
-      {:union, types} -> flatten_union(types)
+      {:union, types} -> unnest_unions(types)
       type -> [type]
     end)
   end
@@ -709,6 +686,10 @@ defmodule Module.Types.Unify do
   @doc """
   Lifts type variables to their inferred types from the context.
   """
+  def lift_types(types, %{lifted_types: _} = context) do
+    Enum.map_reduce(types, context, &lift_type/2)
+  end
+
   def lift_types(types, context) do
     context = %{
       types: context.types,
@@ -716,8 +697,7 @@ defmodule Module.Types.Unify do
       lifted_counter: 0
     }
 
-    {types, _context} = Enum.map_reduce(types, context, &lift_type/2)
-    types
+    Enum.map_reduce(types, context, &lift_type/2)
   end
 
   # Lift type variable to its inferred (hopefully concrete) types from the context
@@ -775,6 +755,16 @@ defmodule Module.Types.Unify do
     {{:list, type}, context}
   end
 
+  defp lift_type({:fun, clauses}, context) do
+    clauses =
+      Enum.map_reduce(clauses, context, fn {args, return}, context ->
+        {[return | args], context} = Enum.map_reduce([return | args], context, &lift_type/2)
+        {{args, return}, context}
+      end)
+
+    {{:fun, clauses}, context}
+  end
+
   defp lift_type(other, context) do
     {other, context}
   end
@@ -788,6 +778,107 @@ defmodule Module.Types.Unify do
     {type, context}
   end
 
+  # TODO: Figure out function expansion
+
+  @doc """
+  Expand unions so that all unions are at the top level.
+
+      {integer() | float()} => {integer()} | {float()}
+  """
+  def flatten_union({:union, types}, context) do
+    Enum.flat_map(types, &flatten_union(&1, context))
+  end
+
+  def flatten_union(type, context) do
+    List.wrap(do_flatten_union(type, context))
+  end
+
+  def do_flatten_union({:tuple, num, types}, context) do
+    flatten_union_tuple(types, num, context, [])
+  end
+
+  def do_flatten_union({:list, type}, context) do
+    case do_flatten_union(type, context) do
+      {:union, union_types} -> Enum.map(union_types, &{:list, &1})
+      _type -> [{:list, type}]
+    end
+  end
+
+  def do_flatten_union({:map, pairs}, context) do
+    flatten_union_map(pairs, context, [])
+  end
+
+  def do_flatten_union({:var, var}, context) do
+    if looping_var?(var, context, []) do
+      {:var, var}
+    else
+      case context.types do
+        %{^var => :unbound} -> {:var, var}
+        %{^var => {:union, types}} -> Enum.map(types, &do_flatten_union(&1, context))
+        %{^var => type} -> do_flatten_union(type, context)
+      end
+    end
+  end
+
+  def do_flatten_union(type, _context) do
+    type
+  end
+
+  defp flatten_union_tuple([type | types], num, context, acc) do
+    case do_flatten_union(type, context) do
+      {:union, union_types} ->
+        Enum.flat_map(union_types, &flatten_union_tuple(types, num, context, [&1 | acc]))
+
+      type ->
+        flatten_union_tuple(types, num, context, [type | acc])
+    end
+  end
+
+  defp flatten_union_tuple([], num, _context, acc) do
+    [{:tuple, num, Enum.reverse(acc)}]
+  end
+
+  defp flatten_union_map([{kind, key, value} | pairs], context, acc) do
+    case do_flatten_union(key, context) do
+      {:union, union_types} ->
+        Enum.flat_map(union_types, &flatten_union_map_value(kind, &1, value, pairs, context, acc))
+
+      type ->
+        flatten_union_map_value(kind, type, value, pairs, context, acc)
+    end
+  end
+
+  defp flatten_union_map([], _context, acc) do
+    [{:map, Enum.reverse(acc)}]
+  end
+
+  defp flatten_union_map_value(kind, key, value, pairs, context, acc) do
+    case do_flatten_union(value, context) do
+      {:union, union_types} ->
+        Enum.flat_map(union_types, &flatten_union_map(pairs, context, [{kind, key, &1} | acc]))
+
+      value ->
+        flatten_union_map(pairs, context, [{kind, key, value} | acc])
+    end
+  end
+
+  defp looping_var?(var, context, parents) do
+    case context.types do
+      %{^var => :unbound} ->
+        false
+
+      %{^var => {:var, type}} ->
+        if var in parents do
+          true
+        else
+          looping_var?(type, context, [var | parents])
+        end
+
+      %{^var => _type} ->
+        false
+    end
+  end
+
   @doc """
   Formats types.
 
@@ -797,7 +888,7 @@ defmodule Module.Types.Unify do
   def format_type({:map, pairs}, true) do
     case List.keyfind(pairs, {:atom, :__struct__}, 1) do
       {:required, {:atom, :__struct__}, {:atom, struct}} ->
-        "%#{inspect(struct)}{}"
+        ["%", inspect(struct), "{}"]
 
       _ ->
         "map()"
@@ -805,24 +896,31 @@ defmodule Module.Types.Unify do
   end
 
   def format_type({:union, types}, simplify?) do
-    "#{Enum.map_join(types, " | ", &format_type(&1, simplify?))}"
+    types
+    |> Enum.map(&format_type(&1, simplify?))
+    |> Enum.intersperse(" | ")
   end
 
   def format_type({:tuple, _, types}, simplify?) do
-    "{#{Enum.map_join(types, ", ", &format_type(&1, simplify?))}}"
+    format =
+      types
+      |> Enum.map(&format_type(&1, simplify?))
+      |> Enum.intersperse(", ")
+
+    ["{", format, "}"]
   end
 
   def format_type({:list, type}, simplify?) do
-    "[#{format_type(type, simplify?)}]"
+    ["[", format_type(type, simplify?), "]"]
   end
 
   def format_type({:map, pairs}, false) do
     case List.keytake(pairs, {:atom, :__struct__}, 1) do
       {{:required, {:atom, :__struct__}, {:atom, struct}}, pairs} ->
-        "%#{inspect(struct)}{#{format_map_pairs(pairs)}}"
+        ["%", inspect(struct), "{", format_map_pairs(pairs), "}"]
 
       _ ->
-        "%{#{format_map_pairs(pairs)}}"
+        ["%{", format_map_pairs(pairs), "}"]
     end
   end
 
@@ -831,26 +929,84 @@ defmodule Module.Types.Unify do
   end
 
   def format_type({:var, index}, _simplify?) do
-    "var#{index}"
+    ["var", Integer.to_string(index + 1)]
+  end
+
+  def format_type({:fun, clauses}, simplify?) do
+    format =
+      Enum.map(clauses, fn {params, return} ->
+        params = Enum.intersperse(Enum.map(params, &format_type(&1, simplify?)), ", ")
+        params = if params == [], do: params, else: [params, " "]
+        return = format_type(return, simplify?)
+        [params, "-> ", return]
+      end)
+
+    ["(", Enum.intersperse(format, "; "), ")"]
   end
 
   def format_type(atom, _simplify?) when is_atom(atom) do
-    "#{atom}()"
+    [Atom.to_string(atom), "()"]
   end
 
   defp format_map_pairs(pairs) do
     {atoms, others} = Enum.split_with(pairs, &match?({:required, {:atom, _}, _}, &1))
     {required, optional} = Enum.split_with(others, &match?({:required, _, _}, &1))
 
-    Enum.map_join(atoms ++ required ++ optional, ", ", fn
+    (atoms ++ required ++ optional)
+    |> Enum.map(fn
       {:required, {:atom, atom}, right} ->
-        "#{atom}: #{format_type(right, false)}"
+        [Atom.to_string(atom), ": ", format_type(right, false)]
 
       {:required, left, right} ->
-        "#{format_type(left, false)} => #{format_type(right, false)}"
+        [format_type(left, false), " => ", format_type(right, false)]
 
       {:optional, left, right} ->
-        "optional(#{format_type(left, false)}) => #{format_type(right, false)}"
+        ["optional(", format_type(left, false), ") => ", format_type(right, false)]
     end)
+    |> Enum.intersperse(", ")
+  end
+
+  @doc """
+  Performs a depth-first, pre-order traversal of the type tree using an accumulator.
+  """
+  def walk({:map, pairs}, acc, fun) do
+    {pairs, acc} =
+      Enum.map_reduce(pairs, acc, fn {kind, key, value}, acc ->
+        {key, acc} = walk(key, acc, fun)
+        {value, acc} = walk(value, acc, fun)
+        {{kind, key, value}, acc}
+      end)
+
+    fun.({:map, pairs}, acc)
+  end
+
+  def walk({:union, types}, acc, fun) do
+    {types, acc} = Enum.map_reduce(types, acc, &walk(&1, &2, fun))
+    fun.({:union, types}, acc)
+  end
+
+  def walk({:tuple, num, types}, acc, fun) do
+    {types, acc} = Enum.map_reduce(types, acc, &walk(&1, &2, fun))
+    fun.({:tuple, num, types}, acc)
+  end
+
+  def walk({:list, type}, acc, fun) do
+    {type, acc} = walk(type, acc, fun)
+    fun.({:list, type}, acc)
+  end
+
+  def walk({:fun, clauses}, acc, fun) do
+    {clauses, acc} =
+      Enum.map_reduce(clauses, acc, fn {params, return}, acc ->
+        {params, acc} = Enum.map_reduce(params, acc, &walk(&1, &2, fun))
+        {return, acc} = walk(return, acc, fun)
+        {{params, return}, acc}
+      end)
+
+    fun.({:fun, clauses}, acc)
+  end
+
+  def walk(type, acc, fun) do
+    fun.(type, acc)
   end
 end

lib/elixir/lib/option_parser.ex

@@ -596,9 +596,11 @@ defmodule OptionParser do
           raise ArgumentError, ":switches and :strict cannot be given together"
 
         switches = opts[:switches] ->
+          validate_switches(switches)
           {switches, false}
 
         strict = opts[:strict] ->
+          validate_switches(strict)
           {strict, true}
 
         true ->
@@ -614,6 +616,20 @@ defmodule OptionParser do
     }
   end
 
+  defp validate_switches(switches) do
+    Enum.map(switches, &validate_switch/1)
+  end
+
+  defp validate_switch({_name, type_or_type_and_modifiers}) do
+    valid = [:boolean, :count, :integer, :float, :string, :keep]
+    invalid = List.wrap(type_or_type_and_modifiers) -- valid
+
+    if invalid != [] do
+      raise ArgumentError,
+            "invalid switch types/modifiers: " <> Enum.map_join(invalid, ", ", &inspect/1)
+    end
+  end
+
   defp validate_option(value, kinds) do
     {invalid?, value} =
       cond do
@@ -812,7 +828,15 @@ defmodule OptionParser do
     if type = get_type(option, opts, types) do
       "#{option} : Missing argument of type #{type}"
     else
-      "#{option} : Unknown option"
+      msg = "#{option} : Unknown option"
+
+      case did_you_mean(option, types) do
+        {similar, score} when score > 0.8 ->
+          msg <> ". Did you mean --#{similar}?"
+
+        _ ->
+          msg
+      end
     end
   end
 
@@ -831,4 +855,17 @@ defmodule OptionParser do
       types[key]
     end
   end
+
+  defp did_you_mean(option, types) do
+    key = option |> String.trim_leading("-") |> String.replace("-", "_")
+    Enum.reduce(types, {nil, 0}, &max_similar(&1, key, &2))
+  end
+
+  defp max_similar({source, _}, target, {_, current} = best) do
+    source = Atom.to_string(source)
+
+    score = String.jaro_distance(source, target)
+    option = String.replace(source, "_", "-")
+    if score < current, do: best, else: {option, score}
+  end
 end

lib/elixir/lib/path.ex

@@ -5,7 +5,8 @@ defmodule Path do
 
   The functions in this module may receive a chardata as
   argument (i.e. a string or a list of characters / string)
-  and will always return a string (encoded in UTF-8).
+  and will always return a string (encoded in UTF-8). If a binary
+  is given, in whatever encoding, its encoding will be kept.
 
   The majority of the functions in this module do not
   interact with the file system, except for a few functions
@@ -66,7 +67,7 @@ defmodule Path do
 
     case type(path) do
       :relative ->
-        absname_join(relative_to, path)
+        absname_join([relative_to, path])
 
       :absolute ->
         absname_join([path])
@@ -80,11 +81,11 @@ defmodule Path do
   # Absolute path on current drive
   defp absname_vr(["/" | rest], [volume | _], _relative), do: absname_join([volume | rest])
 
-  # Relative to current directory on current drive.
+  # Relative to current directory on current drive
   defp absname_vr([<<x, ?:>> | rest], [<<x, _::binary>> | _], relative),
     do: absname(absname_join(rest), relative)
 
-  # Relative to current directory on another drive.
+  # Relative to current directory on another drive
   defp absname_vr([<<x, ?:>> | name], _, _relative) do
     cwd =
       case :file.get_cwd([x, ?:]) do
@@ -97,25 +98,25 @@ defmodule Path do
 
   @slash [?/, ?\\]
 
-  # Joins a list
-  defp absname_join([name1, name2 | rest]), do: absname_join([absname_join(name1, name2) | rest])
+  defp absname_join([]), do: ""
+  defp absname_join(list), do: absname_join(list, major_os_type())
 
-  defp absname_join([name]),
-    do: do_absname_join(IO.chardata_to_string(name), <<>>, [], major_os_type())
+  defp absname_join([name1, name2 | rest], os_type) do
+    joined = do_absname_join(IO.chardata_to_string(name1), relative(name2), [], os_type)
+    absname_join([joined | rest], os_type)
+  end
 
-  # Joins two paths
-  defp absname_join(left, right),
-    do: do_absname_join(IO.chardata_to_string(left), relative(right), [], major_os_type())
+  defp absname_join([name], os_type) do
+    do_absname_join(IO.chardata_to_string(name), <<>>, [], os_type)
+  end
 
   defp do_absname_join(<<uc_letter, ?:, rest::binary>>, relativename, [], :win32)
-       when uc_letter in ?A..?Z do
-    do_absname_join(rest, relativename, [?:, uc_letter + ?a - ?A], :win32)
-  end
+       when uc_letter in ?A..?Z,
+       do: do_absname_join(rest, relativename, [?:, uc_letter + ?a - ?A], :win32)
 
   defp do_absname_join(<<c1, c2, rest::binary>>, relativename, [], :win32)
-       when c1 in @slash and c2 in @slash do
-    do_absname_join(rest, relativename, '//', :win32)
-  end
+       when c1 in @slash and c2 in @slash,
+       do: do_absname_join(rest, relativename, '//', :win32)
 
   defp do_absname_join(<<?\\, rest::binary>>, relativename, result, :win32),
     do: do_absname_join(<<?/, rest::binary>>, relativename, result, :win32)
@@ -425,6 +426,16 @@ defmodule Path do
   @doc """
   Returns the extension of the last component of `path`.
 
+  The behaviour of this function changed in Erlang/OTP 24 for filenames
+  starting with a dot and without an extension. For example, for a file
+  named ".gitignore", `extname/1` now returns an empty string, while it
+  would return ".gitignore" in previous Erlang/OTP versions. This was
+  done to match the behaviour of `rootname/1`, which would return
+  ".gitignore" as its name (and therefore it cannot also be an extension).
+
+  See `basename/1` and `rootname/1` for related functions to extract
+  information from paths.
+
   ## Examples
 
       iex> Path.extname("foo.erl")

lib/elixir/lib/port.ex

@@ -222,7 +222,7 @@ defmodule Port do
   @doc """
   Sends `data` to the port driver `port`.
 
-  For more information, see `:erlang.port_command/2`.
+  For more information, see `:erlang.port_command/3`.
 
   Inlined by the compiler.
   """

lib/elixir/lib/process.ex

@@ -383,12 +383,19 @@ defmodule Process do
   @type spawn_opt ::
           :link
           | :monitor
+          | {:monitor, monitor_option()}
           | {:priority, :low | :normal | :high}
           | {:fullsweep_after, non_neg_integer}
           | {:min_heap_size, non_neg_integer}
           | {:min_bin_vheap_size, non_neg_integer}
+          | {:max_heap_size, heap_size}
+          | {:message_queue_data, :off_heap | :on_heap}
   @type spawn_opts :: [spawn_opt]
 
+  # TODO: Use :erlang.monitor_option() on Erlang/OTP 24+
+  @typep monitor_option ::
+           [alias: :explicit_unalias | :demonitor | :reply_demonitor, tag: term()]
+
   @doc """
   Spawns the given function according to the given options.
 

lib/elixir/lib/protocol.ex

@@ -275,7 +275,7 @@ defmodule Protocol do
       name = unquote(name)
       arity = unquote(arity)
 
-      @functions [{name, arity} | @functions]
+      @__functions__ [{name, arity} | @__functions__]
 
       # Generate a fake definition with the user
       # signature that will be used by docs
@@ -548,6 +548,9 @@ defmodule Protocol do
           | {:error, :not_a_protocol}
           | {:error, :no_beam_info}
   def consolidate(protocol, types) when is_atom(protocol) do
+    # Ensure the types are sorted so the compiled beam is deterministic
+    types = Enum.sort(types)
+
     with {:ok, ast_info, specs, compile_info} <- beam_protocol(protocol),
          {:ok, definitions} <- change_debug_info(protocol, ast_info, types),
          do: compile(definitions, specs, compile_info)
@@ -681,6 +684,8 @@ defmodule Protocol do
   def __protocol__(name, do: block) do
     quote do
       defmodule unquote(name) do
+        @before_compile Protocol
+
         # We don't allow function definition inside protocols
         import Kernel,
           except: [
@@ -689,7 +694,6 @@ defmodule Protocol do
             defp: 1,
             defp: 2,
             defdelegate: 2,
-            defexception: 1,
             defguard: 1,
             defguardp: 1,
             defmacro: 1,
@@ -705,7 +709,7 @@ defmodule Protocol do
         @compile :debug_info
 
         # Set up a clear slate to store defined functions
-        @functions []
+        @__functions__ []
         @fallback_to_any false
 
         # Invoke the user given block
@@ -717,6 +721,85 @@ defmodule Protocol do
     end
   end
 
+  defp callback_ast_to_fa({kind, {:"::", meta, [{name, _, args}, _return]}, _pos})
+       when kind in [:callback, :macrocallback] do
+    [{{name, length(List.wrap(args))}, meta}]
+  end
+
+  defp callback_ast_to_fa(
+         {kind, {:when, _, [{:"::", meta, [{name, _, args}, _return]}, _vars]}, _pos}
+       )
+       when kind in [:callback, :macrocallback] do
+    [{{name, length(List.wrap(args))}, meta}]
+  end
+
+  defp callback_ast_to_fa({kind, _, _pos}) when kind in [:callback, :macrocallback] do
+    []
+  end
+
+  defp callback_metas(module, kind)
+       when kind in [:callback, :macrocallback] do
+    :lists.flatmap(&callback_ast_to_fa/1, Module.get_attribute(module, kind))
+    |> :maps.from_list()
+  end
+
+  defp get_callback_line(fa, metas),
+    do: :maps.get(fa, metas, [])[:line]
+
+  defp warn(message, env, nil) do
+    IO.warn(message, Macro.Env.stacktrace(env))
+  end
+
+  defp warn(message, env, line) when is_integer(line) do
+    stacktrace = :maps.update(:line, line, env) |> Macro.Env.stacktrace()
+    IO.warn(message, stacktrace)
+  end
+
+  # TODO: Convert the following warnings into errors future Elixir versions
+  def __before_compile__(env) do
+    # Callbacks
+    callback_metas = callback_metas(env.module, :callback)
+    callbacks = :maps.keys(callback_metas)
+    functions = Module.get_attribute(env.module, :__functions__)
+
+    :lists.map(
+      fn {name, arity} = fa ->
+        warn(
+          "cannot define @callback #{name}/#{arity} inside protocol, use def/1 to outline your protocol definition",
+          env,
+          get_callback_line(fa, callback_metas)
+        )
+      end,
+      callbacks -- functions
+    )
+
+    # Macro Callbacks
+    macrocallback_metas = callback_metas(env.module, :macrocallback)
+    macrocallbacks = :maps.keys(macrocallback_metas)
+
+    :lists.map(
+      fn {name, arity} = fa ->
+        warn(
+          "cannot define @macrocallback #{name}/#{arity} inside protocol, use def/1 to outline your protocol definition",
+          env,
+          get_callback_line(fa, macrocallback_metas)
+        )
+      end,
+      macrocallbacks
+    )
+
+    # Optional Callbacks
+    optional_callbacks = Module.get_attribute(env.module, :optional_callbacks)
+
+    if length(optional_callbacks) > 0 do
+      warn(
+        "cannot define @optional_callbacks inside protocol, all of the protocol definitions are required",
+        env,
+        nil
+      )
+    end
+  end
+
   defp after_defprotocol do
     quote bind_quoted: [built_in: __built_in__()] do
       any_impl_for =
@@ -807,11 +890,11 @@ defmodule Protocol do
 
       @doc false
       @spec __protocol__(:module) :: __MODULE__
-      @spec __protocol__(:functions) :: unquote(Protocol.__functions_spec__(@functions))
+      @spec __protocol__(:functions) :: unquote(Protocol.__functions_spec__(@__functions__))
       @spec __protocol__(:consolidated?) :: boolean
       @spec __protocol__(:impls) :: :not_consolidated | {:consolidated, [module]}
       Kernel.def(__protocol__(:module), do: __MODULE__)
-      Kernel.def(__protocol__(:functions), do: unquote(:lists.sort(@functions)))
+      Kernel.def(__protocol__(:functions), do: unquote(:lists.sort(@__functions__)))
       Kernel.def(__protocol__(:consolidated?), do: false)
       Kernel.def(__protocol__(:impls), do: :not_consolidated)
     end

lib/elixir/lib/range.ex

@@ -1,13 +1,12 @@
 defmodule Range do
   @moduledoc """
   Ranges represent a sequence of zero, one or many, ascending
-  or descending, consecutive integers.
+  or descending integers with a common difference called step.
 
   Ranges are always inclusive and they may have custom steps.
   The most common form of creating and matching on ranges is
-  via the `start..stop` and `start..stop//step` notations,
-  defined respectively as the `../2` and `..///3` macros
-  auto-imported from `Kernel`:
+  via the [`first..last`](`../2`) and [`first..last//step`](`..///3`)
+  notations, auto-imported from `Kernel`:
 
       iex> Enum.to_list(1..3)
       [1, 2, 3]
@@ -30,10 +29,10 @@ defmodule Range do
       iex> Enum.to_list(0..10//-1)
       []
 
-  When defining a range without steps, the step will be
-  defined based on the start and stop position of the
-  range, If `start >= stop`, it will be an increasing range
-  with step of 1. Otherwise, it is a decreasing range.
+  When defining a range without a step, the step will be
+  defined based on the first and last position of the
+  range, If `first >= last`, it will be an increasing range
+  with a step of 1. Otherwise, it is a decreasing range.
   Note however implicitly decreasing ranges are deprecated.
   Therefore, if you need a decreasing range from `3` to `1`,
   prefer to write `3..1//-1` instead.
@@ -41,14 +40,14 @@ defmodule Range do
   ## Definition
 
   An increasing range `first..last//step` is a range from
-  `first` to `last` increasing by `step` where all values
-  `v` must be `first <= v and v <= last`. Therefore, a range
+  `first` to `last` increasing by `step` where  `step` must be a positive
+  integer and all values `v` must be `first <= v and v <= last`. Therefore, a range
   `10..0//1` is an empty range because there is no value `v`
   that is `10 <= v and v <= 0`.
 
-  Similarly, a decreasing range `first..last//-step` is a range
-  from `first` to `last` decreasing by `step` where all values
-  `v` must be `first >= v and v >= last`. Therefore, a range
+  Similarly, a decreasing range `first..last//step` is a range
+  from `first` to `last` decreasing by `step` where `step` must be a negative
+  integer and  values `v` must be `first >= v and v >= last`. Therefore, a range
   `0..10//-1` is an empty range because there is no value `v`
   that is `0 >= v and v >= 10`.
 
@@ -68,6 +67,10 @@ defmodule Range do
       iex> range.step
       2
 
+  You can access the range fields (`first`, `last`, and `step`)
+  directly but you should not modify nor create ranges by hand.
+  Instead use the proper operators or `new/2` and `new/3`.
+
   A range implements the `Enumerable` protocol, which means
   functions in the `Enum` module can be used to work with
   ranges:
@@ -92,22 +95,21 @@ defmodule Range do
   @enforce_keys [:first, :last, :step]
   defstruct first: nil, last: nil, step: nil
 
-  @type first :: integer
-  @type last :: integer
+  @type limit :: integer
   @type step :: pos_integer | neg_integer
-  @type t :: %__MODULE__{first: first, last: last, step: step}
-  @type t(first, last) :: %__MODULE__{first: first, last: last}
+  @type t :: %__MODULE__{first: limit, last: limit, step: step}
+  @type t(first, last) :: %__MODULE__{first: first, last: last, step: step}
 
   @doc """
   Creates a new range.
 
-  If first is less than last, the range will be increasing from
-  first to last. If first is equal to last, the range will contain
+  If `first` is less than `last`, the range will be increasing from
+  `first` to `last`. If `first` is equal to `last`, the range will contain
   one element, which is the number itself.
 
-  If first is more than last, the range will be decreasing from first
-  to last, albeit this behaviour is deprecated. Instead prefer to
-  explicitly list the step `new/3`.
+  If `first` is greater than `last`, the range will be decreasing from `first`
+  to `last`, albeit this behaviour is deprecated. Therefore, it is advised to
+  explicitly list the step with `new/3`.
 
   ## Examples
 
@@ -115,9 +117,10 @@ defmodule Range do
       -100..100
 
   """
-  @spec new(integer, integer) :: t
+
+  @spec new(limit, limit) :: t
   def new(first, last) when is_integer(first) and is_integer(last) do
-    # TODO: Deprecate inferring a range with step of -1 on Elixir v1.17
+    # TODO: Deprecate inferring a range with a step of -1 on Elixir v1.17
     step = if first <= last, do: 1, else: -1
     %Range{first: first, last: last, step: step}
   end
@@ -129,7 +132,7 @@ defmodule Range do
   end
 
   @doc """
-  Creates a new range with step.
+  Creates a new range with `step`.
 
   ## Examples
 
@@ -138,7 +141,7 @@ defmodule Range do
 
   """
   @doc since: "1.12.0"
-  @spec new(integer, integer, integer) :: t
+  @spec new(limit, limit, step) :: t
   def new(first, last, step)
       when is_integer(first) and is_integer(last) and is_integer(step) and step != 0 do
     %Range{first: first, last: last, step: step}
@@ -146,32 +149,12 @@ defmodule Range do
 
   def new(first, last, step) do
     raise ArgumentError,
-          "ranges (first..last//step) expect both sides to be integers and the step to be an integer " <>
-            "different than zero, got: #{inspect(first)}..#{inspect(last)}//#{inspect(step)}"
+          "ranges (first..last//step) expect both sides to be integers and the step to be a " <>
+            "non-zero integer, got: #{inspect(first)}..#{inspect(last)}//#{inspect(step)}"
   end
 
   @doc """
-  Checks if the range is empty.
-
-  ## Examples
-
-      iex> Range.empty?(1..0//1)
-      true
-      iex> Range.empty?(0..1//-1)
-      true
-      iex> Range.empty?(1..0)
-      false
-      iex> Range.empty?(0..1)
-      false
-
-  """
-  @doc since: "1.12.0"
-  def empty?(first..last//step) when step > 0 and first > last, do: true
-  def empty?(first..last//step) when step < 0 and first < last, do: true
-  def empty?(_.._//_), do: false
-
-  @doc """
-  Returns the size of the range.
+  Returns the size of `range`.
 
   ## Examples
 
@@ -197,10 +180,17 @@ defmodule Range do
 
   """
   @doc since: "1.12.0"
+  def size(range)
   def size(first..last//step) when step > 0 and first > last, do: 0
   def size(first..last//step) when step < 0 and first < last, do: 0
   def size(first..last//step), do: abs(div(last - first, step)) + 1
 
+  # TODO: Remove me on v2.0
+  def size(%{__struct__: Range, first: first, last: last} = range) do
+    step = if first <= last, do: 1, else: -1
+    size(Map.put(range, :step, step))
+  end
+
   @doc """
   Checks if two ranges are disjoint.
 
@@ -242,7 +232,7 @@ defmodule Range do
   @doc since: "1.8.0"
   @spec disjoint?(t, t) :: boolean
   def disjoint?(first1..last1//step1 = range1, first2..last2//step2 = range2) do
-    if empty?(range1) or empty?(range2) do
+    if size(range1) == 0 or size(range2) == 0 do
       true
     else
       {first1, last1, step1} = normalize(first1, last1, step1)
@@ -273,7 +263,7 @@ defmodule Range do
     end
   end
 
-  @compile inline: [normalize: 3, empty?: 1]
+  @compile inline: [normalize: 3]
   defp normalize(first, last, step) when first > last, do: {last, first, -step}
   defp normalize(first, last, step), do: {first, last, step}
 
@@ -289,6 +279,12 @@ defimpl Enumerable, for: Range do
     reduce(first, last, acc, fun, step)
   end
 
+  # TODO: Remove me on v2.0
+  def reduce(%{__struct__: Range, first: first, last: last} = range, acc, fun) do
+    step = if first <= last, do: 1, else: -1
+    reduce(Map.put(range, :step, step), acc, fun)
+  end
+
   defp reduce(_first, _last, {:halt, acc}, _fun, _step) do
     {:halted, acc}
   end
@@ -309,7 +305,7 @@ defimpl Enumerable, for: Range do
 
   def member?(first..last//step = range, value) when is_integer(value) do
     cond do
-      Range.empty?(range) ->
+      Range.size(range) == 0 ->
         {:ok, false}
 
       first <= last ->
@@ -320,6 +316,13 @@ defimpl Enumerable, for: Range do
     end
   end
 
+  # TODO: Remove me on v2.0
+  def member?(%{__struct__: Range, first: first, last: last} = range, value)
+      when is_integer(value) do
+    step = if first <= last, do: 1, else: -1
+    member?(Map.put(range, :step, step), value)
+  end
+
   def member?(_, _value) do
     {:ok, false}
   end
@@ -332,18 +335,31 @@ defimpl Enumerable, for: Range do
     {:ok, Range.size(range), &slice(first + &1 * step, step, &2)}
   end
 
+  # TODO: Remove me on v2.0
+  def slice(%{__struct__: Range, first: first, last: last} = range) do
+    step = if first <= last, do: 1, else: -1
+    slice(Map.put(range, :step, step))
+  end
+
   defp slice(current, _step, 1), do: [current]
   defp slice(current, step, remaining), do: [current | slice(current + step, step, remaining - 1)]
 end
 
 defimpl Inspect, for: Range do
   import Inspect.Algebra
+  import Kernel, except: [inspect: 2]
 
-  def inspect(first..last//1, opts) do
+  def inspect(first..last//1, opts) when last >= first do
     concat([to_doc(first, opts), "..", to_doc(last, opts)])
   end
 
   def inspect(first..last//step, opts) do
     concat([to_doc(first, opts), "..", to_doc(last, opts), "//", to_doc(step, opts)])
   end
+
+  # TODO: Remove me on v2.0
+  def inspect(%{__struct__: Range, first: first, last: last} = range, opts) do
+    step = if first <= last, do: 1, else: -1
+    inspect(Map.put(range, :step, step), opts)
+  end
 end

lib/elixir/lib/record.ex

@@ -34,6 +34,12 @@ defmodule Record do
         # expands to: "@type user :: {:user, String.t(), integer}"
       end
 
+  ## Reflection
+
+  A list of all records in a module, if any, can be retrieved by reading the
+  `@__records__` module attribute. It returns a list of maps with the record
+  kind, name, tag, and fields. The attribute is only available inside the
+  module definition.
   """
 
   @doc """
@@ -47,8 +53,8 @@ defmodule Record do
 
   ## Options
 
-  This function accepts the following options, which are exclusive to each other
-  (i.e., only one of them can be used in the same call):
+  This function requires one of the following options, which are exclusive to each
+  other (i.e., only one of them can be used in the same call):
 
     * `:from` - (binary representing a path to a file) path to the Erlang file
       that contains the record definition to extract; with this option, this
@@ -60,6 +66,8 @@ defmodule Record do
       this function uses the same path lookup used by the `-include_lib`
       attribute used in Erlang modules.
 
+  It additionally accepts the following optional, non-exclusive options:
+
     * `:includes` - (a list of directories as binaries) if the record being
       extracted depends on relative includes, this option allows developers
       to specify the directory where those relative includes exist.
@@ -105,21 +113,8 @@ defmodule Record do
 
   ## Options
 
-  This function accepts the following options, which are exclusive to each other
-  (i.e., only one of them can be used in the same call):
+  Accepts the same options as listed for `Record.extract/2`.
 
-    * `:from` - (binary representing a path to a file) path to the Erlang file
-      that contains the record definitions to extract; with this option, this
-      function uses the same path lookup used by the `-include` attribute used in
-      Erlang modules.
-
-    * `:from_lib` - (binary representing a path to a file) path to the Erlang
-      file that contains the record definitions to extract; with this option,
-      this function uses the same path lookup used by the `-include_lib`
-      attribute used in Erlang modules.
-
-  These options are expected to be literals (including the binary values) at
-  compile time.
   """
   @spec extract_all(keyword) :: [{name :: atom, keyword}]
   def extract_all(opts) when is_list(opts) do
@@ -255,10 +250,8 @@ defmodule Record do
   """
   defmacro defrecord(name, tag \\ nil, kv) do
     quote bind_quoted: [name: name, tag: tag, kv: kv] do
-      fields = Record.__fields__(:defrecord, kv)
-      Record.__validate__(__MODULE__, name, fields)
-
       tag = tag || name
+      fields = Record.__record__(__MODULE__, :defrecord, name, tag, kv)
 
       defmacro unquote(name)(args \\ []) do
         Record.__access__(unquote(tag), unquote(fields), args, __CALLER__)
@@ -275,10 +268,8 @@ defmodule Record do
   """
   defmacro defrecordp(name, tag \\ nil, kv) do
     quote bind_quoted: [name: name, tag: tag, kv: kv] do
-      fields = Record.__fields__(:defrecordp, kv)
-      Record.__validate__(__MODULE__, name, fields)
-
       tag = tag || name
+      fields = Record.__record__(__MODULE__, :defrecordp, name, tag, kv)
 
       defmacrop unquote(name)(args \\ []) do
         Record.__access__(unquote(tag), unquote(fields), args, __CALLER__)
@@ -290,13 +281,6 @@ defmodule Record do
     end
   end
 
-  @doc false
-  def __validate__(module, name, fields) do
-    error_on_duplicate_record(module, name)
-    # TODO: Make it raise on v2.0
-    warn_on_duplicate_key(:lists.keysort(1, fields))
-  end
-
   defp error_on_duplicate_record(module, name) do
     defined_arity =
       Enum.find(0..2, fn arity ->
@@ -322,9 +306,28 @@ defmodule Record do
     warn_on_duplicate_key(rest)
   end
 
-  # Normalizes of record fields to have default values.
+  # Callback invoked from the record/2 macro.
   @doc false
-  def __fields__(type, fields) do
+  def __record__(module, kind, name, tag, kv) do
+    error_on_duplicate_record(module, name)
+
+    fields = fields(kind, kv)
+    Module.register_attribute(module, :__records__, accumulate: true)
+
+    Module.put_attribute(module, :__records__, %{
+      kind: kind,
+      name: name,
+      tag: tag,
+      fields: :lists.map(&elem(&1, 0), fields)
+    })
+
+    # TODO: Make it raise on v2.0
+    warn_on_duplicate_key(:lists.keysort(1, fields))
+    fields
+  end
+
+  # Normalizes of record fields to have default values.
+  defp fields(kind, fields) do
     normalizer_fun = fn
       {key, value} when is_atom(key) ->
         try do
@@ -340,7 +343,7 @@ defmodule Record do
         {key, nil}
 
       other ->
-        raise ArgumentError, "#{type} fields must be atoms, got: #{inspect(other)}"
+        raise ArgumentError, "#{kind} fields must be atoms, got: #{inspect(other)}"
     end
 
     :lists.map(normalizer_fun, fields)

lib/elixir/lib/regex.ex

@@ -274,6 +274,9 @@ defmodule Regex do
       iex> Regex.match?(~r/foo/, "bar")
       false
 
+  Elixir also provides `Kernel.=~/2` and `String.match?/2` as
+  an alternative to test strings against regular expressions and
+  strings.
   """
   @spec match?(t, String.t()) :: boolean
   def match?(%Regex{} = regex, string) when is_binary(string) do
@@ -371,7 +374,7 @@ defmodule Regex do
 
   ## Examples
 
-      iex> Regex.source(~r(foo))
+      iex> Regex.source(~r/foo/)
       "foo"
 
   """
@@ -385,7 +388,7 @@ defmodule Regex do
 
   ## Examples
 
-      iex> Regex.opts(~r(foo)m)
+      iex> Regex.opts(~r/foo/m)
       "m"
 
   """
@@ -453,7 +456,7 @@ defmodule Regex do
       [[{0, 1}], [{9, 3}]]
 
   """
-  @spec scan(t, String.t(), [term]) :: [[String.t()]]
+  @spec scan(t(), String.t(), [term()]) :: [[String.t()]] | [[{integer(), integer()}]]
   def scan(regex, string, options \\ [])
 
   def scan(%Regex{} = regex, string, options) when is_binary(string) do

lib/elixir/lib/registry.ex

@@ -260,6 +260,10 @@ defmodule Registry do
     end
   end
 
+  def send({registry, key, _value}, msg) do
+    Registry.send({registry, key}, msg)
+  end
+
   @doc false
   def unregister_name({registry, key}), do: unregister(registry, key)
   def unregister_name({registry, key, _value}), do: unregister(registry, key)
@@ -731,6 +735,64 @@ defmodule Registry do
     acc
   end
 
+  @doc """
+  Reads the values for the given `key` for `pid` in `registry`.
+
+  For unique registries, it is either an empty list or a list
+  with a single element. For duplicate registries, it is a list
+  with zero, one, or multiple elements.
+
+  ## Examples
+
+  In the example below we register the current process and look it up
+  both from itself and other processes:
+
+      iex> Registry.start_link(keys: :unique, name: Registry.UniqueLookupTest)
+      iex> Registry.values(Registry.UniqueLookupTest, "hello", self())
+      []
+      iex> {:ok, _} = Registry.register(Registry.UniqueLookupTest, "hello", :world)
+      iex> Registry.values(Registry.UniqueLookupTest, "hello", self())
+      [:world]
+      iex> Task.async(fn -> Registry.values(Registry.UniqueLookupTest, "hello", self()) end) |> Task.await()
+      []
+      iex> parent = self()
+      iex> Task.async(fn -> Registry.values(Registry.UniqueLookupTest, "hello", parent) end) |> Task.await()
+      [:world]
+
+  The same applies to duplicate registries:
+
+      iex> Registry.start_link(keys: :duplicate, name: Registry.DuplicateLookupTest)
+      iex> Registry.values(Registry.DuplicateLookupTest, "hello", self())
+      []
+      iex> {:ok, _} = Registry.register(Registry.DuplicateLookupTest, "hello", :world)
+      iex> Registry.values(Registry.DuplicateLookupTest, "hello", self())
+      [:world]
+      iex> {:ok, _} = Registry.register(Registry.DuplicateLookupTest, "hello", :another)
+      iex> Enum.sort(Registry.values(Registry.DuplicateLookupTest, "hello", self()))
+      [:another, :world]
+
+  """
+  @doc since: "1.12.0"
+  @spec values(registry, key, pid) :: [value]
+  def values(registry, key, pid) when is_atom(registry) do
+    case key_info!(registry) do
+      {:unique, partitions, key_ets} ->
+        key_ets = key_ets || key_ets!(registry, key, partitions)
+
+        case safe_lookup_second(key_ets, key) do
+          {^pid, value} ->
+            [value]
+
+          _ ->
+            []
+        end
+
+      {:duplicate, partitions, key_ets} ->
+        key_ets = key_ets || key_ets!(registry, pid, partitions)
+        for {^pid, value} <- safe_lookup_second(key_ets, key), do: value
+    end
+  end
+
   @doc """
   Unregisters all entries for the given `key` associated to the current
   process in `registry`.
@@ -1003,7 +1065,9 @@ defmodule Registry do
       :ets.lookup(registry, key)
     catch
       :error, :badarg ->
-        raise ArgumentError, "unknown registry: #{inspect(registry)}"
+        raise ArgumentError,
+              "unknown registry: #{inspect(registry)}. Either the registry name is invalid or " <>
+                "the registry is not running, possibly because its application isn't started"
     else
       [{^key, value}] -> {:ok, value}
       _ -> :error

lib/elixir/lib/stream.ex

@@ -1443,9 +1443,9 @@ defmodule Stream do
   ## Examples
 
       # Although not necessary, let's seed the random algorithm
-      iex> :rand.seed(:exrop, {1, 2, 3})
+      iex> :rand.seed(:exsss, {1, 2, 3})
       iex> Stream.repeatedly(&:rand.uniform/0) |> Enum.take(3)
-      [0.7498295129076106, 0.06161655489244533, 0.7924073127680873]
+      [0.5455598952593053, 0.6039309974353404, 0.6684893034823949]
 
   """
   @spec repeatedly((() -> element)) :: Enumerable.t()

lib/elixir/lib/string.ex

@@ -68,8 +68,8 @@ defmodule String do
 
   ## Code points and grapheme cluster
 
-  The functions in this module act according to the Unicode
-  Standard, version 12.1.0.
+  The functions in this module act according to
+  [The Unicode Standard, Version 14.0.0](http://www.unicode.org/versions/Unicode14.0.0/).
 
   As per the standard, a code point is a single Unicode Character,
   which may be represented by one or more bytes.
@@ -494,6 +494,12 @@ defmodule String do
       {:infinity, false} ->
         :binary.split(string, pattern, [:global])
 
+      {:infinity, true} ->
+        :binary.split(string, pattern, [:global, :trim_all])
+
+      {2, false} ->
+        :binary.split(string, pattern)
+
       _ ->
         pattern = maybe_compile_pattern(pattern)
         split_each(string, pattern, trim, parts_to_index(parts))
@@ -507,9 +513,11 @@ defmodule String do
   defp split_empty(string, _, 1), do: [string]
 
   defp split_empty(string, trim, count) do
-    case next_grapheme(string) do
-      {h, t} -> [h | split_empty(t, trim, count - 1)]
-      nil -> split_empty("", trim, 1)
+    case :unicode_util.gc(string) do
+      [gc] -> [grapheme_to_binary(gc) | split_empty(<<>>, trim, count - 1)]
+      [gc | rest] -> [grapheme_to_binary(gc) | split_empty(rest, trim, count - 1)]
+      [] -> split_empty("", trim, 1)
+      {:error, <<byte, rest::bits>>} -> [<<byte>> | split_empty(rest, trim, count - 1)]
     end
   end
 
@@ -642,8 +650,10 @@ defmodule String do
   end
 
   defp do_split_at(string, position) do
-    {byte_size, rest} = String.Unicode.split_at(string, position)
-    {binary_part(string, 0, byte_size), rest || ""}
+    remaining = byte_size_remaining_at(string, position)
+    start = byte_size(string) - remaining
+    <<left::size(start)-binary, right::size(remaining)-binary>> = string
+    {left, right}
   end
 
   @doc ~S"""
@@ -801,7 +811,7 @@ defmodule String do
   end
 
   def upcase(string, :default) when is_binary(string) do
-    String.Casing.upcase(string, [], :default)
+    String.Unicode.upcase(string, [], :default)
   end
 
   def upcase(string, :ascii) when is_binary(string) do
@@ -809,7 +819,7 @@ defmodule String do
   end
 
   def upcase(string, mode) when is_binary(string) and mode in @conditional_mappings do
-    String.Casing.upcase(string, [], mode)
+    String.Unicode.upcase(string, [], mode)
   end
 
   defp upcase_ascii(<<char, rest::bits>>) when char >= ?a and char <= ?z,
@@ -869,7 +879,7 @@ defmodule String do
   end
 
   def downcase(string, :default) when is_binary(string) do
-    String.Casing.downcase(string, [], :default)
+    String.Unicode.downcase(string, [], :default)
   end
 
   def downcase(string, :ascii) when is_binary(string) do
@@ -877,7 +887,7 @@ defmodule String do
   end
 
   def downcase(string, mode) when is_binary(string) and mode in @conditional_mappings do
-    String.Casing.downcase(string, [], mode)
+    String.Unicode.downcase(string, [], mode)
   end
 
   defp downcase_ascii(<<char, rest::bits>>) when char >= ?A and char <= ?Z,
@@ -916,7 +926,7 @@ defmodule String do
   end
 
   def capitalize(string, mode) when is_binary(string) do
-    {char, rest} = String.Casing.titlecase_once(string, mode)
+    {char, rest} = String.Unicode.titlecase_once(string, mode)
     char <> downcase(rest, mode)
   end
 
@@ -1482,7 +1492,7 @@ defmodule String do
   defp replace_guarded(subject, "", replacement_binary, options)
        when is_binary(replacement_binary) do
     if Keyword.get(options, :global, true) do
-      IO.iodata_to_binary([replacement_binary | intersperse_bin(subject, replacement_binary)])
+      intersperse_bin(subject, replacement_binary, [replacement_binary])
     else
       replacement_binary <> subject
     end
@@ -1490,7 +1500,7 @@ defmodule String do
 
   defp replace_guarded(subject, "", replacement_fun, options) do
     if Keyword.get(options, :global, true) do
-      IO.iodata_to_binary([replacement_fun.("") | intersperse_fun(subject, replacement_fun)])
+      intersperse_fun(subject, replacement_fun, [replacement_fun.("")])
     else
       IO.iodata_to_binary([replacement_fun.("") | subject])
     end
@@ -1520,17 +1530,31 @@ defmodule String do
     end
   end
 
-  defp intersperse_bin(subject, replacement) do
-    case next_grapheme(subject) do
-      {current, rest} -> [current, replacement | intersperse_bin(rest, replacement)]
-      nil -> []
+  defp intersperse_bin(subject, replacement, acc) do
+    case :unicode_util.gc(subject) do
+      [current | rest] ->
+        intersperse_bin(rest, replacement, [replacement, current | acc])
+
+      [] ->
+        reverse_characters_to_binary(acc)
+
+      {:error, <<byte, rest::bits>>} ->
+        reverse_characters_to_binary(acc) <>
+          <<byte>> <> intersperse_bin(rest, replacement, [replacement])
     end
   end
 
-  defp intersperse_fun(subject, replacement) do
-    case next_grapheme(subject) do
-      {current, rest} -> [current, replacement.("") | intersperse_fun(rest, replacement)]
-      nil -> []
+  defp intersperse_fun(subject, replacement, acc) do
+    case :unicode_util.gc(subject) do
+      [current | rest] ->
+        intersperse_fun(rest, replacement, [replacement.(""), current | acc])
+
+      [] ->
+        reverse_characters_to_binary(acc)
+
+      {:error, <<byte, rest::bits>>} ->
+        reverse_characters_to_binary(acc) <>
+          <<byte>> <> intersperse_fun(rest, replacement, [replacement.("")])
     end
   end
 
@@ -1583,16 +1607,17 @@ defmodule String do
   """
   @spec reverse(t) :: t
   def reverse(string) when is_binary(string) do
-    do_reverse(next_grapheme(string), [])
+    do_reverse(:unicode_util.gc(string), [])
   end
 
-  defp do_reverse({grapheme, rest}, acc) do
-    do_reverse(next_grapheme(rest), [grapheme | acc])
-  end
+  defp do_reverse([grapheme | rest], acc),
+    do: do_reverse(:unicode_util.gc(rest), [grapheme | acc])
 
-  defp do_reverse(nil, acc), do: IO.iodata_to_binary(acc)
+  defp do_reverse([], acc),
+    do: :unicode.characters_to_binary(acc)
 
-  @compile {:inline, duplicate: 2}
+  defp do_reverse({:error, <<byte, rest::bits>>}, acc),
+    do: :unicode.characters_to_binary(acc) <> <<byte>> <> do_reverse(:unicode_util.gc(rest), [])
 
   @doc """
   Returns a string `subject` repeated `n` times.
@@ -1611,6 +1636,7 @@ defmodule String do
       "abcabc"
 
   """
+  @compile {:inline, duplicate: 2}
   @spec duplicate(t, non_neg_integer) :: t
   def duplicate(subject, n) when is_binary(subject) and is_integer(n) and n >= 0 do
     :binary.copy(subject, n)
@@ -1643,7 +1669,19 @@ defmodule String do
 
   """
   @spec codepoints(t) :: [codepoint]
-  defdelegate codepoints(string), to: String.Unicode
+  def codepoints(string) when is_binary(string) do
+    do_codepoints(string)
+  end
+
+  defp do_codepoints(<<codepoint::utf8, rest::bits>>) do
+    [<<codepoint::utf8>> | do_codepoints(rest)]
+  end
+
+  defp do_codepoints(<<byte, rest::bits>>) do
+    [<<byte>> | do_codepoints(rest)]
+  end
+
+  defp do_codepoints(<<>>), do: []
 
   @doc ~S"""
   Returns the next code point in a string.
@@ -1686,9 +1724,10 @@ defmodule String do
   Binary pattern matching, however, is simpler and more efficient,
   so pick the option that better suits your use case.
   """
-  @compile {:inline, next_codepoint: 1}
   @spec next_codepoint(t) :: {codepoint, t} | nil
-  defdelegate next_codepoint(string), to: String.Unicode
+  def next_codepoint(<<cp::utf8, rest::binary>>), do: {<<cp::utf8>>, rest}
+  def next_codepoint(<<byte, rest::binary>>), do: {<<byte>>, rest}
+  def next_codepoint(<<>>), do: nil
 
   @doc ~S"""
   Checks whether `string` contains only valid characters.
@@ -1712,6 +1751,8 @@ defmodule String do
 
   """
   @spec valid?(t) :: boolean
+  def valid?(string)
+
   def valid?(<<string::binary>>), do: valid_utf8?(string)
   def valid?(_), do: false
 
@@ -1808,10 +1849,17 @@ defmodule String do
       ["é"]
 
   """
+  @compile {:inline, graphemes: 1}
   @spec graphemes(t) :: [grapheme]
-  defdelegate graphemes(string), to: String.Unicode
+  def graphemes(string) when is_binary(string), do: do_graphemes(string)
 
-  @compile {:inline, next_grapheme: 1, next_grapheme_size: 1}
+  defp do_graphemes(gcs) do
+    case :unicode_util.gc(gcs) do
+      [gc | rest] -> [grapheme_to_binary(gc) | do_graphemes(rest)]
+      [] -> []
+      {:error, <<byte, rest::bits>>} -> [<<byte>> | do_graphemes(rest)]
+    end
+  end
 
   @doc """
   Returns the next grapheme in a string.
@@ -1829,32 +1877,28 @@ defmodule String do
       nil
 
   """
+  @compile {:inline, next_grapheme: 1}
   @spec next_grapheme(t) :: {grapheme, t} | nil
-  def next_grapheme(binary) when is_binary(binary) do
-    case next_grapheme_size(binary) do
-      {size, rest} -> {binary_part(binary, 0, size), rest}
-      nil -> nil
+  def next_grapheme(string) when is_binary(string) do
+    case :unicode_util.gc(string) do
+      [gc] -> {grapheme_to_binary(gc), <<>>}
+      [gc | rest] -> {grapheme_to_binary(gc), rest}
+      [] -> nil
+      {:error, <<byte, rest::bits>>} -> {<<byte>>, rest}
     end
   end
 
-  @doc """
-  Returns the size (in bytes) of the next grapheme.
-
-  The result is a tuple with the next grapheme size in bytes and
-  the remainder of the string or `nil` in case the string
-  reached its end.
-
-  ## Examples
-
-      iex> String.next_grapheme_size("olá")
-      {1, "lá"}
-
-      iex> String.next_grapheme_size("")
-      nil
-
-  """
+  @doc false
+  @deprecated "Use String.next_grapheme/1 instead"
   @spec next_grapheme_size(t) :: {pos_integer, t} | nil
-  defdelegate next_grapheme_size(string), to: String.Unicode
+  def next_grapheme_size(string) when is_binary(string) do
+    case :unicode_util.gc(string) do
+      [gc] -> {grapheme_byte_size(gc), <<>>}
+      [gc | rest] -> {grapheme_byte_size(gc), rest}
+      [] -> nil
+      {:error, <<_, rest::bits>>} -> {1, rest}
+    end
+  end
 
   @doc """
   Returns the first grapheme from a UTF-8 string,
@@ -1874,9 +1918,10 @@ defmodule String do
   """
   @spec first(t) :: grapheme | nil
   def first(string) when is_binary(string) do
-    case next_grapheme(string) do
-      {char, _} -> char
-      nil -> nil
+    case :unicode_util.gc(string) do
+      [gc | _] -> grapheme_to_binary(gc)
+      [] -> nil
+      {:error, <<byte, _::bits>>} -> <<byte>>
     end
   end
 
@@ -1884,8 +1929,13 @@ defmodule String do
   Returns the last grapheme from a UTF-8 string,
   `nil` if the string is empty.
 
+  It traverses the whole string to find its last grapheme.
+
   ## Examples
 
+      iex> String.last("")
+      nil
+
       iex> String.last("elixir")
       "r"
 
@@ -1894,15 +1944,13 @@ defmodule String do
 
   """
   @spec last(t) :: grapheme | nil
-  def last(string) when is_binary(string) do
-    do_last(next_grapheme(string), nil)
-  end
+  def last(""), do: nil
+  def last(string) when is_binary(string), do: do_last(:unicode_util.gc(string), nil)
 
-  defp do_last({char, rest}, _) do
-    do_last(next_grapheme(rest), char)
-  end
-
-  defp do_last(nil, last_char), do: last_char
+  defp do_last([gc | rest], _), do: do_last(:unicode_util.gc(rest), gc)
+  defp do_last([], acc) when is_binary(acc), do: acc
+  defp do_last([], acc), do: :unicode.characters_to_binary([acc])
+  defp do_last({:error, <<byte, rest::bits>>}, _), do: do_last(:unicode_util.gc(rest), <<byte>>)
 
   @doc """
   Returns the number of Unicode graphemes in a UTF-8 string.
@@ -1917,7 +1965,15 @@ defmodule String do
 
   """
   @spec length(t) :: non_neg_integer
-  defdelegate length(string), to: String.Unicode
+  def length(string) when is_binary(string), do: length(string, 0)
+
+  defp length(gcs, acc) do
+    case :unicode_util.gc(gcs) do
+      [_ | rest] -> length(rest, acc + 1)
+      [] -> acc
+      {:error, <<_, rest::bits>>} -> length(rest, acc + 1)
+    end
+  end
 
   @doc """
   Returns the grapheme at the `position` of the given UTF-8 `string`.
@@ -1957,10 +2013,11 @@ defmodule String do
   end
 
   defp do_at(string, position) do
-    case String.Unicode.split_at(string, position) do
-      {_, nil} -> nil
-      {_, rest} -> first(rest)
-    end
+    left = byte_size_remaining_at(string, position)
+
+    string
+    |> binary_part(byte_size(string) - left, left)
+    |> first()
   end
 
   @doc """
@@ -2008,14 +2065,7 @@ defmodule String do
   def slice(string, start, length)
       when is_binary(string) and is_integer(start) and is_integer(length) and start >= 0 and
              length >= 0 do
-    case String.Unicode.split_at(string, start) do
-      {_, nil} ->
-        ""
-
-      {start_bytes, rest} ->
-        {len_bytes, _} = String.Unicode.split_at(rest, length)
-        binary_part(string, start_bytes, len_bytes)
-    end
+    do_slice(string, start, length)
   end
 
   def slice(string, start, length)
@@ -2024,11 +2074,19 @@ defmodule String do
     start = length(string) + start
 
     case start >= 0 do
-      true -> slice(string, start, length)
+      true -> do_slice(string, start, length)
       false -> ""
     end
   end
 
+  defp do_slice(string, start, length) do
+    from_start = byte_size_remaining_at(string, start)
+    rest = binary_part(string, byte_size(string) - from_start, from_start)
+
+    from_end = byte_size_remaining_at(rest, length)
+    binary_part(rest, 0, from_start - from_end)
+  end
+
   @doc """
   Returns a substring from the offset given by the start of the
   range to the offset given by the end of the range.
@@ -2058,7 +2116,7 @@ defmodule String do
       iex> String.slice("elixir", -4..6)
       "ixir"
 
-  For ranges where `start > stop`, you need to explicit
+  For ranges where `start > stop`, you need to explicitly
   mark them as increasing:
 
       iex> String.slice("elixir", 2..-1//1)
@@ -2098,13 +2156,18 @@ defmodule String do
     end
   end
 
+  # TODO: Remove me on v2.0
+  def slice(string, %{__struct__: Range, first: first, last: last} = range)
+      when is_binary(string) do
+    step = if first <= last, do: 1, else: -1
+    slice(string, Map.put(range, :step, step))
+  end
+
   defp slice_range("", _, _), do: ""
 
   defp slice_range(string, first, -1) when first >= 0 do
-    case String.Unicode.split_at(string, first) do
-      {_, nil} -> ""
-      {start_bytes, _} -> binary_part(string, start_bytes, byte_size(string) - start_bytes)
-    end
+    left = byte_size_remaining_at(string, first)
+    binary_part(string, byte_size(string) - left, left)
   end
 
   defp slice_range(string, first, last) when first >= 0 and last >= 0 do
@@ -2116,7 +2179,7 @@ defmodule String do
   end
 
   defp slice_range(string, first, last) do
-    {bytes, length} = acc_bytes(next_grapheme_size(string), [], 0)
+    {bytes, length} = acc_bytes(:unicode_util.gc(string), [], 0)
     first = add_if_negative(first, length)
     last = add_if_negative(last, length)
 
@@ -2131,13 +2194,14 @@ defmodule String do
     end
   end
 
-  defp acc_bytes({size, rest}, bytes, length) do
-    acc_bytes(next_grapheme_size(rest), [size | bytes], length + 1)
-  end
+  defp acc_bytes([gc | rest], bytes, length),
+    do: acc_bytes(:unicode_util.gc(rest), [grapheme_byte_size(gc) | bytes], length + 1)
 
-  defp acc_bytes(nil, bytes, length) do
-    {bytes, length}
-  end
+  defp acc_bytes([], bytes, length),
+    do: {bytes, length}
+
+  defp acc_bytes({:error, <<_, rest::bits>>}, bytes, length),
+    do: acc_bytes(:unicode_util.gc(rest), [1 | bytes], length + 1)
 
   defp add_if_negative(value, to_add) when value < 0, do: value + to_add
   defp add_if_negative(value, _to_add), do: value
@@ -2254,6 +2318,8 @@ defmodule String do
       iex> String.match?("bar", ~r/foo/)
       false
 
+  Elixir also provides `Kernel.=~/2` and `Regex.match?/2` as
+  alternatives to test strings against regular expressions.
   """
   @spec match?(t, Regex.t()) :: boolean
   def match?(string, regex) when is_binary(string) do
@@ -2502,18 +2568,17 @@ defmodule String do
   end
 
   defp string_to_bag(string, bag, length) do
-    case next_grapheme(string) do
-      {char, rest} ->
-        bag =
-          case bag do
-            %{^char => current} -> %{bag | char => current + 1}
-            %{} -> Map.put(bag, char, 1)
-          end
+    case :unicode_util.gc(string) do
+      [gc | rest] -> string_to_bag(rest, bag_store(bag, gc), length + 1)
+      [] -> {bag, length}
+      {:error, <<byte, rest::bits>>} -> string_to_bag(rest, bag_store(bag, <<byte>>), length + 1)
+    end
+  end
 
-        string_to_bag(rest, bag, length + 1)
-
-      nil ->
-        {bag, length}
+  defp bag_store(bag, gc) do
+    case bag do
+      %{^gc => current} -> %{bag | gc => current + 1}
+      %{} -> Map.put(bag, gc, 1)
     end
   end
 
@@ -2558,8 +2623,8 @@ defmodule String do
   def jaro_distance("", _string), do: 0.0
 
   def jaro_distance(string1, string2) when is_binary(string1) and is_binary(string2) do
-    {chars1, len1} = chars_and_length(string1)
-    {chars2, len2} = chars_and_length(string2)
+    {chars1, len1} = graphemes_and_length(string1)
+    {chars2, len2} = graphemes_and_length(string2)
 
     case match(chars1, len1, chars2, len2) do
       {0, _trans} ->
@@ -2570,12 +2635,6 @@ defmodule String do
     end
   end
 
-  @compile {:inline, chars_and_length: 1}
-  defp chars_and_length(string) do
-    chars = graphemes(string)
-    {chars, Kernel.length(chars)}
-  end
-
   defp match(chars1, len1, chars2, len2) do
     if len1 < len2 do
       match(chars1, chars2, div(len2, 2) - 1)
@@ -2654,4 +2713,66 @@ defmodule String do
   @deprecated "Use String.to_charlist/1 instead"
   @spec to_char_list(t) :: charlist
   def to_char_list(string), do: String.to_charlist(string)
+
+  ## Helpers
+
+  @compile {:inline,
+            codepoint_byte_size: 1,
+            grapheme_byte_size: 1,
+            grapheme_to_binary: 1,
+            graphemes_and_length: 1,
+            reverse_characters_to_binary: 1}
+
+  defp byte_size_unicode(binary) when is_binary(binary), do: byte_size(binary)
+  defp byte_size_unicode([head]), do: byte_size_unicode(head)
+  defp byte_size_unicode([head | tail]), do: byte_size_unicode(head) + byte_size_unicode(tail)
+
+  defp byte_size_remaining_at(unicode, 0) do
+    byte_size_unicode(unicode)
+  end
+
+  defp byte_size_remaining_at(unicode, n) do
+    case :unicode_util.gc(unicode) do
+      [_] -> 0
+      [_ | rest] -> byte_size_remaining_at(rest, n - 1)
+      [] -> 0
+      {:error, <<_, bin::bits>>} -> byte_size_remaining_at(bin, n - 1)
+    end
+  end
+
+  defp codepoint_byte_size(cp) when cp <= 0x007F, do: 1
+  defp codepoint_byte_size(cp) when cp <= 0x07FF, do: 2
+  defp codepoint_byte_size(cp) when cp <= 0xFFFF, do: 3
+  defp codepoint_byte_size(_), do: 4
+
+  defp grapheme_to_binary(cp) when is_integer(cp), do: <<cp::utf8>>
+  defp grapheme_to_binary(gc), do: :unicode.characters_to_binary(gc)
+
+  defp grapheme_byte_size(cp) when is_integer(cp), do: codepoint_byte_size(cp)
+  defp grapheme_byte_size(cps), do: grapheme_byte_size(cps, 0)
+
+  defp grapheme_byte_size([cp | cps], acc),
+    do: grapheme_byte_size(cps, acc + codepoint_byte_size(cp))
+
+  defp grapheme_byte_size([], acc),
+    do: acc
+
+  defp graphemes_and_length(string),
+    do: graphemes_and_length(string, [], 0)
+
+  defp graphemes_and_length(string, acc, length) do
+    case :unicode_util.gc(string) do
+      [gc | rest] ->
+        graphemes_and_length(rest, [gc | acc], length + 1)
+
+      [] ->
+        {:lists.reverse(acc), length}
+
+      {:error, <<byte, rest::bits>>} ->
+        graphemes_and_length(rest, [<<byte>> | acc], length + 1)
+    end
+  end
+
+  defp reverse_characters_to_binary(acc),
+    do: acc |> :lists.reverse() |> :unicode.characters_to_binary()
 end

lib/elixir/lib/supervisor.ex

@@ -284,7 +284,7 @@ defmodule Supervisor do
   supervisor gives you more direct control over how the supervisor
   is initialized. Instead of calling `Supervisor.start_link/2` with
   a list of children that are automatically initialized, we manually
-  initialized the children by calling `Supervisor.init/2` inside its
+  initialize the children by calling `Supervisor.init/2` inside its
   `c:init/1` callback.
 
   `use Supervisor` also defines a `child_spec/1` function which allows
@@ -930,7 +930,7 @@ defmodule Supervisor do
   """
   @spec which_children(supervisor) :: [
           # inlining module() | :dynamic here because :supervisor.modules() is not exported
-          {term() | :undefined, child | :restarting, :worker | :supervisor, module() | :dynamic}
+          {term() | :undefined, child | :restarting, :worker | :supervisor, [module()] | :dynamic}
         ]
   def which_children(supervisor) do
     call(supervisor, :which_children)

lib/elixir/lib/system.ex

@@ -606,7 +606,6 @@ defmodule System do
   The returned value is a map containing name-value pairs.
   Variable names and their values are strings.
   """
-  # TODO: Remove this once we require Erlang/OTP 24+
   @spec get_env() :: %{optional(String.t()) => String.t()}
   def get_env do
     if function_exported?(:os, :env, 0) do
@@ -708,8 +707,7 @@ defmodule System do
 
   For more information, see `:os.getpid/0`.
   """
-  # TODO: deprecate permanently on v1.13
-  @doc deprecated: "Use System.pid/0 instead"
+  @deprecated "Use System.pid/0 instead"
   @spec get_pid() :: binary
   def get_pid, do: IO.iodata_to_binary(:os.getpid())
 
@@ -857,8 +855,13 @@ defmodule System do
   All applications are taken down smoothly, all code is unloaded, and all ports
   are closed before the system terminates by calling `halt/1`.
 
-  `status` must be a non-negative integer value which is returned by the
-  runtime system to the operating system.
+  `status` must be a non-negative integer or a binary.
+
+    * If an integer, the runtime system exits with the integer value which is
+      returned to the operating system.
+
+    * If a binary, an Erlang crash dump is produced with status as slogan, and
+      then the runtime system exits with status code 1.
 
   Note that on many platforms, only the status codes 0-255 are supported
   by the operating system.
@@ -881,6 +884,62 @@ defmodule System do
     :init.stop(String.to_charlist(status))
   end
 
+  @doc ~S"""
+  Executes the given `command` in the OS shell.
+
+  It uses `sh` for Unix-like systems and `cmd` for Windows.
+
+  **Important**: Use this function with care. In particular, **never
+  pass untrusted user input to this function**, as the user would be
+  able to perform "command injection attacks" by executing any code
+  directly on the machine. Generally speaking, prefer to use `cmd/3`
+  over this function.
+
+  ## Examples
+
+      iex> System.shell("echo hello")
+      {"hello\n", 0}
+
+  If you want to stream the output to Standard IO as it arrives:
+
+      iex> System.shell("echo hello", into: IO.stream())
+      hello
+      {%IO.Stream{}, 0}
+
+  ## Options
+
+  It accepts the same options as `cmd/3`, except for `arg0`.
+  """
+  @doc since: "1.12.0"
+  @spec shell(binary, keyword) :: {Collectable.t(), exit_status :: non_neg_integer}
+  def shell(command, opts \\ []) when is_binary(command) do
+    assert_no_null_byte!(command, "System.shell/2")
+
+    # Finding shell command logic from :os.cmd in OTP
+    # https://github.com/erlang/otp/blob/8deb96fb1d017307e22d2ab88968b9ef9f1b71d0/lib/kernel/src/os.erl#L184
+    command =
+      case :os.type() do
+        {:unix, _} ->
+          command =
+            command
+            |> String.replace("\"", "\\\"")
+            |> String.to_charlist()
+
+          'sh -c "' ++ command ++ '"'
+
+        {:win32, osname} ->
+          command = String.to_charlist(command)
+
+          case {System.get_env("COMSPEC"), osname} do
+            {nil, :windows} -> 'command.com /s /c ' ++ command
+            {nil, _} -> 'cmd /s /c ' ++ command
+            {cmd, _} -> '#{cmd} /s /c ' ++ command
+          end
+      end
+
+    do_cmd({:spawn, command}, [], opts)
+  end
+
   @doc ~S"""
   Executes the given `command` with `args`.
 
@@ -913,7 +972,9 @@ defmodule System do
       iex> System.cmd("echo", ["hello"], env: [{"MIX_ENV", "test"}])
       {"hello\n", 0}
 
-      iex> System.cmd("echo", ["hello"], into: IO.stream(:stdio, :line))
+  If you want to stream the output to Standard IO as it arrives:
+
+      iex> System.cmd("echo", ["hello"], into: IO.stream())
       hello
       {%IO.Stream{}, 0}
 
@@ -964,7 +1025,7 @@ defmodule System do
   ## Shell commands
 
   If you desire to execute a trusted command inside a shell, with pipes,
-  redirecting and so on, please check `:os.cmd/1`.
+  redirecting and so on, please check `shell/2`.
   """
   @spec cmd(binary, [binary], keyword) :: {Collectable.t(), exit_status :: non_neg_integer}
   def cmd(command, args, opts \\ []) when is_binary(command) and is_list(args) do
@@ -983,11 +1044,15 @@ defmodule System do
         :os.find_executable(cmd) || :erlang.error(:enoent, [command, args, opts])
       end
 
-    {into, opts} = cmd_opts(opts, [:use_stdio, :exit_status, :binary, :hide, args: args], "")
+    do_cmd({:spawn_executable, cmd}, [args: args], opts)
+  end
+
+  defp do_cmd(port_init, base_opts, opts) do
+    {into, opts} = cmd_opts(opts, [:use_stdio, :exit_status, :binary, :hide] ++ base_opts, "")
     {initial, fun} = Collectable.into(into)
 
     try do
-      do_cmd(Port.open({:spawn_executable, cmd}, opts), initial, fun)
+      do_port(Port.open(port_init, opts), initial, fun)
     catch
       kind, reason ->
         fun.(initial, :halt)
@@ -997,17 +1062,18 @@ defmodule System do
     end
   end
 
-  defp do_cmd(port, acc, fun) do
+  defp do_port(port, acc, fun) do
     receive do
       {^port, {:data, data}} ->
-        do_cmd(port, fun.(acc, {:cont, data}), fun)
+        do_port(port, fun.(acc, {:cont, data}), fun)
 
       {^port, {:exit_status, status}} ->
         {acc, status}
     end
   end
 
-  defp cmd_opts([{:into, any} | t], opts, _into), do: cmd_opts(t, opts, any)
+  defp cmd_opts([{:into, any} | t], opts, _into),
+    do: cmd_opts(t, opts, any)
 
   defp cmd_opts([{:cd, bin} | t], opts, into) when is_binary(bin),
     do: cmd_opts(t, [{:cd, bin} | opts], into)
@@ -1018,7 +1084,8 @@ defmodule System do
   defp cmd_opts([{:stderr_to_stdout, true} | t], opts, into),
     do: cmd_opts(t, [:stderr_to_stdout | opts], into)
 
-  defp cmd_opts([{:stderr_to_stdout, false} | t], opts, into), do: cmd_opts(t, opts, into)
+  defp cmd_opts([{:stderr_to_stdout, false} | t], opts, into),
+    do: cmd_opts(t, opts, into)
 
   defp cmd_opts([{:parallelism, bool} | t], opts, into) when is_boolean(bool),
     do: cmd_opts(t, [{:parallelism, bool} | opts], into)
@@ -1029,7 +1096,8 @@ defmodule System do
   defp cmd_opts([{key, val} | _], _opts, _into),
     do: raise(ArgumentError, "invalid option #{inspect(key)} with value #{inspect(val)}")
 
-  defp cmd_opts([], opts, into), do: {into, opts}
+  defp cmd_opts([], opts, into),
+    do: {into, opts}
 
   defp validate_env(enum) do
     Enum.map(enum, fn

lib/elixir/lib/task.ex

@@ -35,7 +35,7 @@ defmodule Task do
 
     1. If you are using async tasks, you **must await** a reply
        as they are *always* sent. If you are not expecting a reply,
-       consider using `Task.start_link/1` detailed below.
+       consider using `Task.start_link/1` as detailed below.
 
     2. async tasks link the caller and the spawned process. This
        means that, if the caller crashes, the task will crash
@@ -69,8 +69,8 @@ defmodule Task do
         {Task.Supervisor, name: MyApp.TaskSupervisor}
       ], strategy: :one_for_one)
 
-  And now you can use async/await once again passig the name of
-  the supervisor isntead of the pid:
+  And now you can use async/await by passing the name of
+  the supervisor instead of the pid:
 
       Task.Supervisor.async(MyApp.TaskSupervisor, fn ->
         # Do something
@@ -79,22 +79,21 @@ defmodule Task do
 
   We encourage developers to rely on supervised tasks as much as
   possible. Supervised tasks enable a huge variety of patterns
-  which allows you explicit control on how to handle the results,
+  that allow you explicit control on how to handle the results,
   errors, and timeouts. Here is a summary:
 
-    * Use `Task.Supervisor.start_child/2` to start a fire-and-forget
-      task and you don't care about its results nor about if it completes
-      successfully
+    * Using `Task.Supervisor.start_child/2` allows you to start a fire-and-forget
+      task that you don't care about its results or if it completes successfully or not.
 
-    * Use `Task.Supervisor.async/2` + `Task.await/2` allows you to execute
+    * Using `Task.Supervisor.async/2` + `Task.await/2` allows you to execute
       tasks concurrently and retrieve its result. If the task fails,
-      the caller will also fail
+      the caller will also fail.
 
-    * Use `Task.Supervisor.async_nolink/2` + `Task.yield/2` + `Task.shutdown/2`
+    * Using `Task.Supervisor.async_nolink/2` + `Task.yield/2` + `Task.shutdown/2`
       allows you to execute tasks concurrently and retrieve their results
       or the reason they failed within a given time frame. If the task fails,
-      the caller won't fail: you will receive the error reason either on
-      `yield` or `shutdown`
+      the caller won't fail. You will receive the error reason either on
+      `yield` or `shutdown`.
 
   See the `Task.Supervisor` module for details on the supported operations.
 
@@ -111,8 +110,8 @@ defmodule Task do
       Task.Supervisor.async(supervisor, MyMod, :my_fun, [arg1, arg2, arg3])
 
   Note that, when working with distributed tasks, one should use the
-  `Task.Supervisor.async/4` function that expects explicit module, function,
-  and arguments, instead of `Task.Supervisor.async/2` that works with anonymous
+  `Task.Supervisor.async/5` function that expects explicit module, function,
+  and arguments, instead of `Task.Supervisor.async/3` that works with anonymous
   functions. That's because anonymous functions expect the same module version
   to exist on all involved nodes. Check the `Agent` module documentation for
   more information on distributed processes as the limitations described there
@@ -156,8 +155,8 @@ defmodule Task do
       ], strategy: :one_for_one)
 
   Since these tasks are supervised and not directly linked to the caller,
-  they cannot be awaited on. By default, the functions `Task.start`
-  and `Task.start_link` are for fire-and-forget tasks, where you don't
+  they cannot be awaited on. By default, the functions `Task.start/1`
+  and `Task.start_link/1` are for fire-and-forget tasks, where you don't
   care about the results or if it completes successfully or not.
 
   `use Task` defines a `child_spec/1` function, allowing the
@@ -193,7 +192,7 @@ defmodule Task do
   For example, we recommend developers to always start tasks under a supervisor.
   This provides more visibility and allows you to control how those tasks are
   terminated when a node shuts down. That might look something like
-  `Task.Supervisor.start_child(MySupervisor, task_specification)`. This means
+  `Task.Supervisor.start_child(MySupervisor, task_function)`. This means
   that, although your code is the one who invokes the task, the actual ancestor of
   the task is the supervisor, as the supervisor is the one effectively starting it.
 
@@ -242,8 +241,8 @@ defmodule Task do
   """
   @type t :: %__MODULE__{
           pid: pid() | nil,
-          ref: reference() | nil,
-          owner: pid() | nil
+          ref: reference(),
+          owner: pid()
         }
 
   defguardp is_timeout(timeout)
@@ -391,13 +390,13 @@ defmodule Task do
       Task.await(x) + y
 
   As before, if `heavy_fun/0` fails, the whole computation will
-  fail, including the parent process. If you don't want the task
+  fail, including the caller process. If you don't want the task
   to fail then you must change the `heavy_fun/0` code in the
   same way you would achieve it if you didn't have the async call.
   For example, to either return `{:ok, val} | :error` results or,
   in more extreme cases, by using `try/rescue`. In other words,
-  an asynchronous task should be thought of as an extension of a
-  process rather than a mechanism to isolate it from all errors.
+  an asynchronous task should be thought of as an extension of the
+  caller process rather than a mechanism to isolate it from all errors.
 
   If you don't want to link the caller to the task, then you
   must use a supervised task with `Task.Supervisor` and call
@@ -417,7 +416,7 @@ defmodule Task do
     * Unlinking the task process started with `async`/`await`.
       If you unlink the processes and the task does not belong
       to any supervisor, you may leave dangling tasks in case
-      the parent dies.
+      the caller process dies.
 
   """
   @spec async((() -> any)) :: t
@@ -425,6 +424,9 @@ defmodule Task do
     async(:erlang, :apply, [fun, []])
   end
 
+  # TODO: Remove conditional on Erlang/OTP 24
+  @compile {:no_warn_undefined, {:erlang, :monitor, 3}}
+
   @doc """
   Starts a task that must be awaited on.
 
@@ -436,21 +438,72 @@ defmodule Task do
       when is_atom(module) and is_atom(function_name) and is_list(args) do
     mfa = {module, function_name, args}
     owner = self()
-    {:ok, pid} = Task.Supervised.start_link(get_owner(owner), get_callers(owner), :nomonitor, mfa)
-    ref = Process.monitor(pid)
-    send(pid, {owner, ref})
+    {:ok, pid} = Task.Supervised.start_link(get_owner(owner), :nomonitor)
+
+    {reply_to, ref} =
+      if function_exported?(:erlang, :monitor, 3) do
+        ref = :erlang.monitor(:process, pid, alias: :demonitor)
+        {ref, ref}
+      else
+        {owner, Process.monitor(pid)}
+      end
+
+    send(pid, {owner, ref, reply_to, get_callers(owner), mfa})
     %Task{pid: pid, ref: ref, owner: owner}
   end
 
+  @doc """
+  Starts a task that immediately completes with the given `result`.
+
+  Unlike `async/1`, this task does not spawn a linked process. It can
+  be awaited or yielded like any other task.
+
+  ## Usage
+
+  In some cases, it is useful to create a "completed" task that represents
+  a task that has already run and generated a result. For example, when
+  processing data you may be able to determine that certain inputs are
+  invalid before dispatching them for further processing:
+
+      def process(data) do
+        tasks =
+          for entry <- data do
+            if invalid_input?(entry) do
+              Task.completed({:error, :invalid_input})
+            else
+              Task.async(fn -> further_process(entry) end)
+            end
+          end
+
+        Task.await_many(tasks)
+      end
+
+  In many cases, `Task.completed/1` may be avoided in favor of returning the
+  result directly.  You should generally only require this variant when working
+  with mixed asynchrony, when a group of inputs will be handled partially
+  synchronously and partially asynchronously.
+  """
+  @doc since: "1.13.0"
+  @spec completed(any) :: t
+  def completed(result) do
+    ref = make_ref()
+    owner = self()
+
+    # "complete" the task immediately
+    send(owner, {ref, result})
+
+    %Task{pid: nil, ref: ref, owner: owner}
+  end
+
   @doc """
   Returns a stream where the given function (`module` and `function_name`)
   is mapped concurrently on each element in `enumerable`.
 
   Each element of `enumerable` will be prepended to the given `args` and
-  processed by its own task. The tasks will be linked to an intermediate
-  process that is then linked to the current process. This means a failure
-  in a task terminates the current process and a failure in the current process
-  terminates all tasks.
+  processed by its own task. Those tasks will be linked to an intermediate
+  process that is then linked to the caller process. This means a failure
+  in a task terminates the caller process and a failure in the caller
+  process terminates all tasks.
 
   When streamed, each task will emit `{:ok, value}` upon successful
   completion or `{:exit, reason}` if the caller is trapping exits.
@@ -460,9 +513,10 @@ defmodule Task do
   be controlled via options (see the "Options" section below).
 
   Consider using `Task.Supervisor.async_stream/6` to start tasks
-  under a supervisor. If you find yourself trapping exits to handle exits
-  inside the async stream, consider using `Task.Supervisor.async_stream_nolink/6`
-  to start tasks that are not linked to the calling process.
+  under a supervisor. If you find yourself trapping exits to ensure
+  errors in the tasks do not terminate the caller process, consider
+  using `Task.Supervisor.async_stream_nolink/6` to start tasks that
+  are not linked to the caller process.
 
   ## Options
 
@@ -483,7 +537,7 @@ defmodule Task do
 
     * `:on_timeout` - what to do when a task times out. The possible
       values are:
-      * `:exit` (default) - the process that spawned the tasks exits.
+      * `:exit` (default) - the caller (the process that spawned the tasks) exits.
       * `:kill_task` - the task that timed out is killed. The value
         emitted for that task is `{:exit, :timeout}`.
 
@@ -508,11 +562,32 @@ defmodule Task do
       stream = Task.async_stream(collection, Mod, :expensive_fun, [], ordered: false)
       Stream.run(stream)
 
-  ## Attention: async + take
+  ## First async tasks to complete
 
-  Given items in an async stream are processed concurrently, doing
-  `async_stream` followed by `Enum.take/2` may cause more items than
-  requested to be processed. Let's see an example:
+  You can also use `async_stream/3` to execute M tasks and find the N tasks
+  to complete. For example:
+
+      [
+        &heavy_call_1/0,
+        &heavy_call_2/0,
+        &heavy_call_3/0
+      ]
+      |> Task.async_stream(fn fun -> fun.() end, ordered: false, max_concurrency: 3)
+      |> Stream.filter(&match?({:ok, _}, &1))
+      |> Enum.take(2)
+
+  In the example above, we are executing three tasks and waiting for the
+  first 2 to complete. We use `Stream.filter/2` to restrict ourselves only
+  to successfully completed tasks, and then use `Enum.take/2` to retrieve
+  N items. Note it is important to set both `ordered: false` and
+  `max_concurrency: M`, where M is the number of tasks, to make sure all
+  calls execute concurrently.
+
+  ### Attention: unbound async + take
+
+  If you want to potentially process a high number of items and keep only
+  part of the results, you may end-up processing more items than desired.
+  Let's see an example:
 
       1..100
       |> Task.async_stream(fn i ->
@@ -521,13 +596,15 @@ defmodule Task do
       end)
       |> Enum.take(10)
 
-  For a machine with 8 cores, the above will process 16 items instead
-  of 10. The reason is that `async_stream/5` always have 8 elements
-  processing at once. So by the time `Enum` says it got all elements
-  it needed, there are still 6 elements left to be processed.
+  Running the example above in a machine with 8 cores will process 16 items,
+  even though you want only 10 elements, since `async_stream/3` process items
+  concurrently. That's because it will process 8 elements at once. Then all 8
+  elements complete at roughly the same time, causing 8 elements to be kicked
+  off for processing. Out of these extra 8, only 2 will be used, and the rest
+  will be terminated.
 
-  The solution here is to use `Stream.take/2` instead of `Enum.take/2`
-  to filter elements before-hand:
+  Depending on the problem, you can filter or limit the number of elements
+  upfront:
 
       1..100
       |> Stream.take(10)
@@ -537,9 +614,11 @@ defmodule Task do
       end)
       |> Enum.to_list()
 
-  If for some reason you cannot take the elements before hand,
-  you can use `:max_concurrency` to limit how many elements
-  may be over processed at the cost of reducing concurrency.
+  In other cases, you likely want to tweak `:max_concurrency` to limit how
+  many elements may be over processed at the cost of reducing concurrency.
+  You can also set the number of elements to take to be a multiple of
+  `:max_concurrency`. For instance, setting `max_concurrency: 5` in the
+  example above.
   """
   @doc since: "1.4.0"
   @spec async_stream(Enumerable.t(), module, atom, [term], keyword) :: Enumerable.t()
@@ -556,8 +635,8 @@ defmodule Task do
   module-function-arguments tuple. `fun` must be a one-arity anonymous function.
 
   Each `enumerable` element is passed as argument to the given function `fun` and
-  processed by its own task. The tasks will be linked to the current process,
-  similarly to `async/1`.
+  processed by its own task. The tasks will be linked to the caller process, similarly
+  to `async/1`.
 
   ## Example
 
@@ -578,10 +657,14 @@ defmodule Task do
   end
 
   defp build_stream(enumerable, fun, options) do
-    &Task.Supervised.stream(enumerable, &1, &2, fun, options, fn [owner | _] = callers, mfa ->
-      {:ok, pid} = Task.Supervised.start_link(get_owner(owner), callers, :nomonitor, mfa)
-      {:ok, :link, pid}
-    end)
+    fn acc, acc_fun ->
+      owner = get_owner(self())
+
+      Task.Supervised.stream(enumerable, acc, acc_fun, get_callers(self()), fun, options, fn ->
+        {:ok, pid} = Task.Supervised.start_link(owner, :nomonitor)
+        {:ok, :link, pid}
+      end)
+    end
   end
 
   # Returns a tuple with the node where this is executed and either the
@@ -607,14 +690,14 @@ defmodule Task do
   @doc ~S"""
   Awaits a task reply and returns it.
 
-  In case the task process dies, the current process will exit with the same
+  In case the task process dies, the caller process will exit with the same
   reason as the task.
 
   A timeout, in milliseconds or `:infinity`, can be given with a default value
-  of `5000`. If the timeout is exceeded, then the current process will exit. If
-  the task process is linked to the current process which is the case when a
-  task is started with `async`, then the task process will also exit. If the
-  task process is trapping exits or not linked to the current process, then it
+  of `5000`. If the timeout is exceeded, then the caller process will exit.
+  If the task process is linked to the caller process which is the case when
+  a task is started with `async`, then the task process will also exit. If the
+  task process is trapping exits or not linked to the caller process, then it
   will continue to run.
 
   This function assumes the task's monitor is still active or the monitor's
@@ -727,6 +810,50 @@ defmodule Task do
     end
   end
 
+  @doc """
+  Ignores an existing task.
+
+  This means the task will continue running, but it will be unlinked
+  and you can no longer yield, await or shut it down.
+
+  Returns `{:ok, reply}` if the reply is received before ignoring the task,
+  `{:exit, reason}` if the task died before ignoring it, otherwise `nil`.
+
+  Important: avoid using `Task.async` and then immediately ignoring
+  the task. If you want to start tasks you don't care about their
+  results, use `Task.Supervisor.start_child/2` instead.
+
+  Requires Erlang/OTP 24+.
+  """
+  @doc since: "1.13.0"
+  def ignore(%Task{ref: ref, pid: pid, owner: owner} = task) do
+    unless function_exported?(:erlang, :monitor, 3) do
+      raise "Task.ignore/1 requires Erlang/OTP 24+"
+    end
+
+    if owner != self() do
+      raise ArgumentError, invalid_owner_error(task)
+    end
+
+    receive do
+      {^ref, reply} ->
+        Process.unlink(pid)
+        Process.demonitor(ref, [:flush])
+        {:ok, reply}
+
+      {:DOWN, ^ref, _, proc, :noconnection} ->
+        exit({reason(:noconnection, proc), {__MODULE__, :ignore, [task]}})
+
+      {:DOWN, ^ref, _, _, reason} ->
+        {:exit, reason}
+    after
+      0 ->
+        Process.unlink(pid)
+        Process.demonitor(ref, [:flush])
+        nil
+    end
+  end
+
   @doc """
   Awaits replies from multiple tasks and returns them.
 
@@ -734,16 +861,16 @@ defmodule Task do
   given time interval. It returns a list of the results, in the same order as
   the tasks supplied in the `tasks` input argument.
 
-  If any of the task processes dies, the current process will exit with the
-  same reason as that task.
+  If any of the task processes dies, the caller process will exit with the same
+  reason as that task.
 
   A timeout, in milliseconds or `:infinity`, can be given with a default value
-  of `5000`. If the timeout is exceeded, then the current process will exit.
-  Any task processes that are linked to the current process (which is the case
+  of `5000`. If the timeout is exceeded, then the caller process will exit.
+  Any task processes that are linked to the caller process (which is the case
   when a task is started with `async`) will also exit. Any task processes that
-  are trapping exits or not linked to the current process will continue to run.
+  are trapping exits or not linked to the caller process will continue to run.
 
-  This function assumes the tasks' monitors are still active or the monitors'
+  This function assumes the tasks' monitors are still active or the monitor's
   `:DOWN` message is in the message queue. If any tasks have been demonitored,
   or the message already received, this function will wait for the duration of
   the timeout.
@@ -856,16 +983,17 @@ defmodule Task do
   end
 
   @doc ~S"""
-  Temporarily blocks the current process waiting for a task reply.
+  Temporarily blocks the caller process waiting for a task reply.
 
   Returns `{:ok, reply}` if the reply is received, `nil` if
   no reply has arrived, or `{:exit, reason}` if the task has already
   exited. Keep in mind that normally a task failure also causes
   the process owning the task to exit. Therefore this function can
-  return `{:exit, reason}` only if
+  return `{:exit, reason}` if at least one of the conditions below apply:
 
     * the task process exited with the reason `:normal`
-    * it isn't linked to the caller
+    * the task isn't linked to the caller (the task was started
+      with `Task.Supervisor.async_nolink/2` or `Task.Supervisor.async_nolink/4`)
     * the caller is trapping exits
 
   A timeout, in milliseconds or `:infinity`, can be given with a default value
@@ -890,6 +1018,18 @@ defmodule Task do
           nil
       end
 
+  If you intend to check on the task but leave it running after the timeout,
+  you can chain this together with `ignore/1`, like so:
+
+      case Task.yield(task, timeout) || Task.ignore(task) do
+        {:ok, result} ->
+          result
+
+        nil ->
+          Logger.warn("Failed to get a result in #{timeout}ms")
+          nil
+      end
+
   That ensures that if the task completes after the `timeout` but before `shutdown/1`
   has been called, you will still get the result, since `shutdown/1` is designed to
   handle this case and return the result.
@@ -942,8 +1082,9 @@ defmodule Task do
 
   `Task.yield_many/2` allows developers to spawn multiple tasks
   and retrieve the results received in a given timeframe.
-  If we combine it with `Task.shutdown/2`, it allows us to gather
-  those results and cancel the tasks that have not replied in time.
+  If we combine it with `Task.shutdown/2` (or `Task.ignore/1`),
+  it allows us to gather those results and cancel (or ignore)
+  the tasks that have not replied in time.
 
   Let's see an example.
 
@@ -1028,7 +1169,8 @@ defmodule Task do
   Unlinks and shuts down the task, and then checks for a reply.
 
   Returns `{:ok, reply}` if the reply is received while shutting down the task,
-  `{:exit, reason}` if the task died, otherwise `nil`.
+  `{:exit, reason}` if the task died, otherwise `nil`. Once shut down,
+  you can no longer await or yield it.
 
   The second argument is either a timeout or `:brutal_kill`. In case
   of a timeout, a `:shutdown` exit signal is sent to the task process

lib/elixir/lib/task/supervised.ex

@@ -10,29 +10,28 @@ defmodule Task.Supervised do
     {:ok, :proc_lib.spawn_link(__MODULE__, :noreply, [owner, callers, fun])}
   end
 
-  def start_link(owner, callers, monitor, fun) do
-    {:ok, :proc_lib.spawn_link(__MODULE__, :reply, [owner, callers, monitor, fun])}
+  def start_link(owner, monitor) do
+    {:ok, :proc_lib.spawn_link(__MODULE__, :reply, [owner, monitor])}
   end
 
-  def reply({_, _, owner_pid} = owner, callers, monitor, mfa) do
-    initial_call(mfa)
-    put_callers(callers)
-
+  def reply({_, _, owner_pid} = owner, monitor) do
     case monitor do
       :monitor ->
         mref = Process.monitor(owner_pid)
-        reply(owner, owner_pid, mref, @ref_timeout, mfa)
+        reply(owner, owner_pid, mref, @ref_timeout)
 
       :nomonitor ->
-        reply(owner, owner_pid, nil, :infinity, mfa)
+        reply(owner, owner_pid, nil, :infinity)
     end
   end
 
-  defp reply(owner, owner_pid, mref, timeout, mfa) do
+  defp reply(owner, owner_pid, mref, timeout) do
     receive do
-      {^owner_pid, ref} ->
-        _ = if mref, do: Process.demonitor(mref, [:flush])
-        send(owner_pid, {ref, invoke_mfa(owner, mfa)})
+      {^owner_pid, ref, reply_to, callers, mfa} ->
+        initial_call(mfa)
+        put_callers(callers)
+        _ = mref && Process.demonitor(mref, [:flush])
+        send(reply_to, {ref, invoke_mfa(owner, mfa)})
 
       {:DOWN, ^mref, _, _, reason} ->
         exit({:shutdown, reason})
@@ -174,14 +173,18 @@ defmodule Task.Supervised do
 
   ## Stream
 
-  def stream(enumerable, acc, reducer, mfa, options, spawn) do
+  def stream(enumerable, acc, reducer, callers, mfa, options, spawn) do
     next = &Enumerable.reduce(enumerable, &1, fn x, acc -> {:suspend, [x | acc]} end)
     max_concurrency = Keyword.get(options, :max_concurrency, System.schedulers_online())
+
+    unless is_integer(max_concurrency) and max_concurrency > 0 do
+      raise ArgumentError, ":max_concurrency must be an integer greater than zero"
+    end
+
     ordered? = Keyword.get(options, :ordered, true)
     timeout = Keyword.get(options, :timeout, 5000)
     on_timeout = Keyword.get(options, :on_timeout, :exit)
     parent = self()
-    callers = get_callers()
 
     {:trap_exit, trap_exit?} = Process.info(self(), :trap_exit)
 
@@ -192,7 +195,7 @@ defmodule Task.Supervised do
 
     {monitor_pid, monitor_ref} =
       Process.spawn(
-        fn -> stream_monitor(callers, mfa, spawn, trap_exit?, timeout) end,
+        fn -> stream_monitor(parent, spawn, trap_exit?, timeout) end,
         spawn_opts
       )
 
@@ -207,7 +210,9 @@ defmodule Task.Supervised do
       monitor_ref: monitor_ref,
       ordered: ordered?,
       timeout: timeout,
-      on_timeout: on_timeout
+      on_timeout: on_timeout,
+      callers: callers,
+      mfa: mfa
     }
 
     stream_reduce(
@@ -221,16 +226,8 @@ defmodule Task.Supervised do
     )
   end
 
-  defp get_callers do
-    case :erlang.get(:"$callers") do
-      [_ | _] = list -> [self() | list]
-      _ -> [self()]
-    end
-  end
-
   defp stream_reduce({:halt, acc}, _max, _spawned, _delivered, _waiting, next, config) do
-    %{monitor_pid: monitor_pid, monitor_ref: monitor_ref, timeout: timeout} = config
-    stream_close(monitor_pid, monitor_ref, timeout)
+    stream_close(config)
     is_function(next) && next.({:halt, []})
     {:halted, acc}
   end
@@ -243,13 +240,7 @@ defmodule Task.Supervised do
   # All spawned, all delivered, next is :done.
   defp stream_reduce({:cont, acc}, _max, spawned, delivered, _waiting, next, config)
        when spawned == delivered and next == :done do
-    %{
-      monitor_pid: monitor_pid,
-      monitor_ref: monitor_ref,
-      timeout: timeout
-    } = config
-
-    stream_close(monitor_pid, monitor_ref, timeout)
+    stream_close(config)
     {:done, acc}
   end
 
@@ -318,28 +309,26 @@ defmodule Task.Supervised do
 
       # The monitor process died. We just cleanup the messages from the monitor
       # process and exit.
-      {:DOWN, ^monitor_ref, _, ^monitor_pid, reason} ->
+      {:DOWN, ^monitor_ref, _, _, reason} ->
         stream_cleanup_inbox(monitor_pid, monitor_ref)
         exit({reason, {__MODULE__, :stream, [timeout]}})
     end
   end
 
   defp stream_reduce({:cont, acc}, max, spawned, delivered, waiting, next, config) do
-    %{monitor_pid: monitor_pid, monitor_ref: monitor_ref, timeout: timeout} = config
-
     try do
       next.({:cont, []})
     catch
       kind, reason ->
-        stream_close(monitor_pid, monitor_ref, timeout)
+        stream_close(config)
         :erlang.raise(kind, reason, __STACKTRACE__)
     else
       {:suspended, [value], next} ->
-        waiting = stream_spawn(value, spawned, waiting, monitor_pid, monitor_ref, timeout)
+        waiting = stream_spawn(value, spawned, waiting, config)
         stream_reduce({:cont, acc}, max - 1, spawned + 1, delivered, waiting, next, config)
 
       {_, [value]} ->
-        waiting = stream_spawn(value, spawned, waiting, monitor_pid, monitor_ref, timeout)
+        waiting = stream_spawn(value, spawned, waiting, config)
         stream_reduce({:cont, acc}, max - 1, spawned + 1, delivered, waiting, :done, config)
 
       {_, []} ->
@@ -348,19 +337,14 @@ defmodule Task.Supervised do
   end
 
   defp deliver_now(reply, acc, next, config) do
-    %{
-      reducer: reducer,
-      monitor_pid: monitor_pid,
-      monitor_ref: monitor_ref,
-      timeout: timeout
-    } = config
+    %{reducer: reducer} = config
 
     try do
       reducer.(reply, acc)
     catch
       kind, reason ->
         is_function(next) && next.({:halt, []})
-        stream_close(monitor_pid, monitor_ref, timeout)
+        stream_close(config)
         :erlang.raise(kind, reason, __STACKTRACE__)
     end
   end
@@ -375,12 +359,7 @@ defmodule Task.Supervised do
   end
 
   defp stream_deliver({:cont, acc}, max, spawned, delivered, waiting, next, config) do
-    %{
-      reducer: reducer,
-      monitor_pid: monitor_pid,
-      monitor_ref: monitor_ref,
-      timeout: timeout
-    } = config
+    %{reducer: reducer} = config
 
     case waiting do
       %{^delivered => {:done, reply}} ->
@@ -389,7 +368,7 @@ defmodule Task.Supervised do
         catch
           kind, reason ->
             is_function(next) && next.({:halt, []})
-            stream_close(monitor_pid, monitor_ref, timeout)
+            stream_close(config)
             :erlang.raise(kind, reason, __STACKTRACE__)
         else
           pair ->
@@ -402,7 +381,7 @@ defmodule Task.Supervised do
     end
   end
 
-  defp stream_close(monitor_pid, monitor_ref, timeout) do
+  defp stream_close(%{monitor_pid: monitor_pid, monitor_ref: monitor_ref, timeout: timeout}) do
     send(monitor_pid, {:stop, monitor_ref})
 
     receive do
@@ -439,16 +418,25 @@ defmodule Task.Supervised do
 
   # This function spawns a task for the given "value", and puts the pid of this
   # new task in the map of "waiting" tasks, which is returned.
-  defp stream_spawn(value, spawned, waiting, monitor_pid, monitor_ref, timeout) do
-    send(monitor_pid, {:spawn, spawned, value})
+  defp stream_spawn(value, spawned, waiting, config) do
+    %{
+      monitor_pid: monitor_pid,
+      monitor_ref: monitor_ref,
+      timeout: timeout,
+      callers: callers,
+      mfa: mfa
+    } = config
+
+    send(monitor_pid, {:spawn, spawned})
 
     receive do
       {:spawned, {^monitor_ref, ^spawned}, pid} ->
-        send(pid, {self(), {monitor_ref, spawned}})
+        mfa_with_value = normalize_mfa_with_arg(mfa, value)
+        send(pid, {self(), {monitor_ref, spawned}, self(), callers, mfa_with_value})
         Map.put(waiting, spawned, {pid, :running})
 
       {:max_children, ^monitor_ref} ->
-        stream_close(monitor_pid, monitor_ref, timeout)
+        stream_close(config)
 
         raise """
         reached the maximum number of tasks for this task supervisor. The maximum number \
@@ -465,7 +453,7 @@ defmodule Task.Supervised do
     end
   end
 
-  defp stream_monitor([parent_pid | _] = callers, mfa, spawn, trap_exit?, timeout) do
+  defp stream_monitor(parent_pid, spawn, trap_exit?, timeout) do
     Process.flag(:trap_exit, trap_exit?)
     parent_ref = Process.monitor(parent_pid)
 
@@ -475,9 +463,8 @@ defmodule Task.Supervised do
     receive do
       {^parent_pid, monitor_ref} ->
         config = %{
-          callers: callers,
+          parent_pid: parent_pid,
           parent_ref: parent_ref,
-          mfa: mfa,
           spawn: spawn,
           monitor_ref: monitor_ref,
           timeout: timeout
@@ -492,9 +479,8 @@ defmodule Task.Supervised do
 
   defp stream_monitor_loop(running_tasks, config) do
     %{
-      callers: [parent_pid | _] = callers,
-      mfa: mfa,
       spawn: spawn,
+      parent_pid: parent_pid,
       monitor_ref: monitor_ref,
       timeout: timeout
     } = config
@@ -502,8 +488,8 @@ defmodule Task.Supervised do
     receive do
       # The parent process is telling us to spawn a new task to process
       # "value". We spawn it and notify the parent about its pid.
-      {:spawn, position, value} ->
-        case spawn.(callers, normalize_mfa_with_arg(mfa, value)) do
+      {:spawn, position} ->
+        case spawn.() do
           {:ok, type, pid} ->
             ref = Process.monitor(pid)
 

lib/elixir/lib/task/supervisor.ex

@@ -74,7 +74,7 @@ defmodule Task.Supervisor do
 
   This function could also receive `:restart` and `:shutdown` as options
   but those two options have been deprecated and it is now preferred to
-  give them directly to `start_child` and `async`.
+  give them directly to `start_child`.
   """
   @spec start_link([option]) :: Supervisor.on_start()
   def start_link(options \\ []) do
@@ -105,7 +105,7 @@ defmodule Task.Supervisor do
 
   The `supervisor` must be a reference as defined in `Supervisor`.
   The task will still be linked to the caller, see `Task.async/3` for
-  more information and `async_nolink/2` for a non-linked variant.
+  more information and `async_nolink/3` for a non-linked variant.
 
   Raises an error if `supervisor` has reached the maximum number of
   children.
@@ -126,7 +126,7 @@ defmodule Task.Supervisor do
 
   The `supervisor` must be a reference as defined in `Supervisor`.
   The task will still be linked to the caller, see `Task.async/3` for
-  more information and `async_nolink/2` for a non-linked variant.
+  more information and `async_nolink/3` for a non-linked variant.
 
   Raises an error if `supervisor` has reached the maximum number of
   children.
@@ -235,7 +235,7 @@ defmodule Task.Supervisor do
   children.
 
   Note this function requires the task supervisor to have `:temporary`
-  as the `:restart` option (the default), as `async_nolink/4` keeps a
+  as the `:restart` option (the default), as `async_nolink/5` keeps a
   direct reference to the task which is lost if the task is restarted.
   """
   @spec async_nolink(Supervisor.supervisor(), module, atom, [term], Keyword.t()) :: Task.t()
@@ -249,7 +249,7 @@ defmodule Task.Supervisor do
 
   Each element will be prepended to the given `args` and processed by its
   own task. The tasks will be spawned under the given `supervisor` and
-  linked to the current process, similarly to `async/4`.
+  linked to the caller process, similarly to `async/5`.
 
   When streamed, each task will emit `{:ok, value}` upon successful
   completion or `{:exit, reason}` if the caller is trapping exits.
@@ -308,7 +308,7 @@ defmodule Task.Supervisor do
 
   Each element in `enumerable` is passed as argument to the given function `fun`
   and processed by its own task. The tasks will be spawned under the given
-  `supervisor` and linked to the current process, similarly to `async/2`.
+  `supervisor` and linked to the caller process, similarly to `async/3`.
 
   See `async_stream/6` for discussion, options, and examples.
   """
@@ -325,7 +325,7 @@ defmodule Task.Supervisor do
 
   Each element in `enumerable` will be prepended to the given `args` and processed
   by its own task. The tasks will be spawned under the given `supervisor` and
-  will not be linked to the current process, similarly to `async_nolink/4`.
+  will not be linked to the caller process, similarly to `async_nolink/5`.
 
   See `async_stream/6` for discussion, options, and examples.
   """
@@ -349,7 +349,8 @@ defmodule Task.Supervisor do
 
   Each element in `enumerable` is passed as argument to the given function `fun`
   and processed by its own task. The tasks will be spawned under the given
-  `supervisor` and will not be linked to the current process, similarly to `async_nolink/2`.
+  `supervisor` and will not be linked to the caller process, similarly
+  to `async_nolink/3`.
 
   See `async_stream/6` for discussion and examples.
   """
@@ -386,7 +387,7 @@ defmodule Task.Supervisor do
   Note that the spawned process is not linked to the caller, but
   only to the supervisor. This command is useful in case the
   task needs to perform side-effects (like I/O) and you have no
-  interest on its results nor if it completes successfully.
+  interest in its results nor if it completes successfully.
 
   ## Options
 
@@ -394,9 +395,9 @@ defmodule Task.Supervisor do
       `:transient` or `:permanent`. `:temporary` means the task is never
       restarted, `:transient` means it is restarted if the exit is not
       `:normal`, `:shutdown` or `{:shutdown, reason}`. A `:permanent` restart
-      strategy means it is always restarted. It defaults to `:temporary`.
+      strategy means it is always restarted.
 
-    * `:shutdown` - `:brutal_kill` if the tasks must be killed directly on shutdown
+    * `:shutdown` - `:brutal_kill` if the task must be killed directly on shutdown
       or an integer indicating the timeout value, defaults to 5000 milliseconds.
 
   """
@@ -412,7 +413,7 @@ defmodule Task.Supervisor do
   @doc """
   Starts a task as a child of the given `supervisor`.
 
-  Similar to `start_child/2` except the task is specified
+  Similar to `start_child/3` except the task is specified
   by the given `module`, `fun` and `args`.
   """
   @spec start_child(Supervisor.supervisor(), module, atom, [term], keyword) ::
@@ -451,16 +452,26 @@ defmodule Task.Supervisor do
     end
   end
 
+  # TODO: Remove conditional on Erlang/OTP 24
+  @compile {:no_warn_undefined, {:erlang, :monitor, 3}}
+
   defp async(supervisor, link_type, module, fun, args, options) do
     owner = self()
-    args = [get_owner(owner), get_callers(owner), :monitor, {module, fun, args}]
     shutdown = options[:shutdown]
 
-    case start_child_with_spec(supervisor, args, :temporary, shutdown) do
+    case start_child_with_spec(supervisor, [get_owner(owner), :monitor], :temporary, shutdown) do
       {:ok, pid} ->
         if link_type == :link, do: Process.link(pid)
-        ref = Process.monitor(pid)
-        send(pid, {owner, ref})
+
+        {reply_to, ref} =
+          if function_exported?(:erlang, :monitor, 3) do
+            ref = :erlang.monitor(:process, pid, alias: :demonitor)
+            {ref, ref}
+          else
+            {owner, Process.monitor(pid)}
+          end
+
+        send(pid, {owner, ref, reply_to, get_callers(owner), {module, fun, args}})
         %Task{pid: pid, ref: ref, owner: owner}
 
       {:error, :max_children} ->
@@ -473,19 +484,22 @@ defmodule Task.Supervisor do
   end
 
   defp build_stream(supervisor, link_type, enumerable, fun, options) do
-    shutdown = options[:shutdown]
+    fn acc, acc_fun ->
+      shutdown = options[:shutdown]
+      owner = get_owner(self())
 
-    &Task.Supervised.stream(enumerable, &1, &2, fun, options, fn [owner | _] = callers, mfa ->
-      args = [get_owner(owner), callers, :monitor, mfa]
+      Task.Supervised.stream(enumerable, acc, acc_fun, get_callers(self()), fun, options, fn ->
+        args = [owner, :monitor]
 
-      case start_child_with_spec(supervisor, args, :temporary, shutdown) do
-        {:ok, pid} ->
-          if link_type == :link, do: Process.link(pid)
-          {:ok, link_type, pid}
+        case start_child_with_spec(supervisor, args, :temporary, shutdown) do
+          {:ok, pid} ->
+            if link_type == :link, do: Process.link(pid)
+            {:ok, link_type, pid}
 
-        {:error, :max_children} ->
-          {:error, :max_children}
-      end
-    end)
+          {:error, :max_children} ->
+            {:error, :max_children}
+        end
+      end)
+    end
   end
 end

lib/elixir/lib/uri.ex

@@ -5,6 +5,10 @@ defmodule URI do
   This module provides functions for working with URIs (for example, parsing
   URIs or encoding query strings). The functions in this module are implemented
   according to [RFC 3986](https://tools.ietf.org/html/rfc3986).
+
+  URIs are structs behind the scenes. You can access the URI fields directly
+  but you should not create a new `URI` directly via the struct syntax. Instead
+  use the functions in this module.
   """
 
   defstruct scheme: nil,
@@ -17,16 +21,28 @@ defmodule URI do
             port: nil
 
   @type t :: %__MODULE__{
-          scheme: nil | binary,
-          path: nil | binary,
-          query: nil | binary,
+          authority: authority,
           fragment: nil | binary,
-          authority: nil | binary,
-          userinfo: nil | binary,
           host: nil | binary,
-          port: nil | :inet.port_number()
+          path: nil | binary,
+          port: nil | :inet.port_number(),
+          query: nil | binary,
+          scheme: nil | binary,
+          userinfo: nil | binary
         }
 
+  @typedoc deprecated: "The authority field is deprecated"
+  @opaque authority :: nil | binary
+
+  defmodule Error do
+    defexception [:action, :reason, :part]
+
+    @doc false
+    def message(%Error{action: action, reason: reason, part: part}) do
+      "cannot #{action} due to reason #{reason}: #{inspect(part)}"
+    end
+  end
+
   import Bitwise
 
   @reserved_characters ':/?#[]@!$&\'()*+,;='
@@ -414,9 +430,6 @@ defmodule URI do
   @spec decode(binary) :: binary
   def decode(uri) do
     unpercent(uri, "", false)
-  catch
-    :malformed_uri ->
-      raise ArgumentError, "malformed URI #{inspect(uri)}"
   end
 
   @doc """
@@ -435,48 +448,238 @@ defmodule URI do
   @spec decode_www_form(binary) :: binary
   def decode_www_form(string) when is_binary(string) do
     unpercent(string, "", true)
-  catch
-    :malformed_uri ->
-      raise ArgumentError, "malformed URI #{inspect(string)}"
   end
 
   defp unpercent(<<?+, tail::binary>>, acc, spaces = true) do
     unpercent(tail, <<acc::binary, ?\s>>, spaces)
   end
 
-  defp unpercent(<<?%, hex1, hex2, tail::binary>>, acc, spaces) do
-    unpercent(tail, <<acc::binary, bsl(hex_to_dec(hex1), 4) + hex_to_dec(hex2)>>, spaces)
+  defp unpercent(<<?%, tail::binary>>, acc, spaces) do
+    with <<hex1, hex2, tail::binary>> <- tail,
+         dec1 when is_integer(dec1) <- hex_to_dec(hex1),
+         dec2 when is_integer(dec2) <- hex_to_dec(hex2) do
+      unpercent(tail, <<acc::binary, bsl(dec1, 4) + dec2>>, spaces)
+    else
+      _ -> unpercent(tail, <<acc::binary, ?%>>, spaces)
+    end
   end
 
-  defp unpercent(<<?%, _::binary>>, _acc, _spaces), do: throw(:malformed_uri)
-
   defp unpercent(<<head, tail::binary>>, acc, spaces) do
     unpercent(tail, <<acc::binary, head>>, spaces)
   end
 
   defp unpercent(<<>>, acc, _spaces), do: acc
 
+  @compile {:inline, hex_to_dec: 1}
   defp hex_to_dec(n) when n in ?A..?F, do: n - ?A + 10
   defp hex_to_dec(n) when n in ?a..?f, do: n - ?a + 10
   defp hex_to_dec(n) when n in ?0..?9, do: n - ?0
-  defp hex_to_dec(_n), do: throw(:malformed_uri)
+  defp hex_to_dec(_n), do: nil
 
   @doc """
-  Parses a well-formed URI reference into its components.
+  Creates a new URI struct from a URI or a string.
 
-  Note this function expects a well-formed URI and does not perform
-  any validation. See the "Examples" section below for examples of how
-  `URI.parse/1` can be used to parse a wide range of URIs.
+  If a `%URI{}` struct is given, it returns `{:ok, uri}`. If a string is
+  given, it will parse and validate it. If the string is valid, it returns
+  `{:ok, uri}`, otherwise it returns `{:error, part}` with the invalid part
+  of the URI. For parsing URIs without further validation, see `parse/1`.
 
-  This function uses the parsing regular expression as defined
-  in [RFC 3986, Appendix B](https://tools.ietf.org/html/rfc3986#appendix-B).
+  This function can parse both absolute and relative URLs. You can check
+  if a URI is absolute or relative by checking if the `scheme` field is
+  `nil` or not.
 
-  When a URI is given without a port, the value returned by
-  `URI.default_port/1` for the URI's scheme is used for the `:port` field.
+  When a URI is given without a port, the value returned by `URI.default_port/1`
+  for the URI's scheme is used for the `:port` field. The scheme is also
+  normalized to lowercase.
+
+  ## Examples
+
+      iex> URI.new("https://elixir-lang.org/")
+      {:ok, %URI{
+        fragment: nil,
+        host: "elixir-lang.org",
+        path: "/",
+        port: 443,
+        query: nil,
+        scheme: "https",
+        userinfo: nil
+      }}
+
+      iex> URI.new("//elixir-lang.org/")
+      {:ok, %URI{
+        fragment: nil,
+        host: "elixir-lang.org",
+        path: "/",
+        port: nil,
+        query: nil,
+        scheme: nil,
+        userinfo: nil
+      }}
+
+      iex> URI.new("/foo/bar")
+      {:ok, %URI{
+        fragment: nil,
+        host: nil,
+        path: "/foo/bar",
+        port: nil,
+        query: nil,
+        scheme: nil,
+        userinfo: nil
+      }}
+
+      iex> URI.new("foo/bar")
+      {:ok, %URI{
+        fragment: nil,
+        host: nil,
+        path: "foo/bar",
+        port: nil,
+        query: nil,
+        scheme: nil,
+        userinfo: nil
+      }}
+
+      iex> URI.new("//[fe80::]/")
+      {:ok, %URI{
+        fragment: nil,
+        host: "fe80::",
+        path: "/",
+        port: nil,
+        query: nil,
+        scheme: nil,
+        userinfo: nil
+      }}
+
+      iex> URI.new("https:?query")
+      {:ok, %URI{
+        fragment: nil,
+        host: nil,
+        path: nil,
+        port: 443,
+        query: "query",
+        scheme: "https",
+        userinfo: nil
+      }}
+
+      iex> URI.new("/invalid_greater_than_in_path/>")
+      {:error, ">"}
+
+  Giving an existing URI simply returns it wrapped in a tuple:
+
+      iex> {:ok, uri} = URI.new("https://elixir-lang.org/")
+      iex> URI.new(uri)
+      {:ok, %URI{
+        fragment: nil,
+        host: "elixir-lang.org",
+        path: "/",
+        port: 443,
+        query: nil,
+        scheme: "https",
+        userinfo: nil
+      }}
+  """
+  @doc since: "1.13.0"
+  @spec new(t() | String.t()) :: {:ok, t()} | {:error, String.t()}
+  def new(%URI{} = uri), do: {:ok, uri}
+
+  def new(binary) when is_binary(binary) do
+    case :uri_string.parse(binary) do
+      %{} = map -> {:ok, uri_from_map(map)}
+      {:error, :invalid_uri, term} -> {:error, Kernel.to_string(term)}
+    end
+  end
+
+  @doc """
+  Similar to `new/0` but raises `URI.Error` if an invalid string is given.
+
+  ## Examples
+
+      iex> URI.new!("https://elixir-lang.org/")
+      %URI{
+        fragment: nil,
+        host: "elixir-lang.org",
+        path: "/",
+        port: 443,
+        query: nil,
+        scheme: "https",
+        userinfo: nil
+      }
+
+      iex> URI.new!("/invalid_greater_than_in_path/>")
+      ** (URI.Error) cannot parse due to reason invalid_uri: ">"
+
+  Giving an existing URI simply returns it:
+
+      iex> uri = URI.new!("https://elixir-lang.org/")
+      iex> URI.new!(uri)
+      %URI{
+        fragment: nil,
+        host: "elixir-lang.org",
+        path: "/",
+        port: 443,
+        query: nil,
+        scheme: "https",
+        userinfo: nil
+      }
+  """
+  @doc since: "1.13.0"
+  @spec new!(t() | String.t()) :: t()
+  def new!(%URI{} = uri), do: uri
+
+  def new!(binary) when is_binary(binary) do
+    case :uri_string.parse(binary) do
+      %{} = map ->
+        uri_from_map(map)
+
+      {:error, reason, part} ->
+        raise Error, action: :parse, reason: reason, part: Kernel.to_string(part)
+    end
+  end
+
+  defp uri_from_map(%{path: ""} = map), do: uri_from_map(%{map | path: nil})
+
+  defp uri_from_map(map) do
+    uri = Map.merge(%URI{}, map)
+
+    case map do
+      %{scheme: scheme} ->
+        scheme = String.downcase(scheme, :ascii)
+
+        case map do
+          %{port: _} ->
+            %{uri | scheme: scheme}
+
+          %{} ->
+            case default_port(scheme) do
+              nil -> %{uri | scheme: scheme}
+              port -> %{uri | scheme: scheme, port: port}
+            end
+        end
+
+      %{} ->
+        uri
+    end
+  end
+
+  @doc """
+  Parses a URI into its components, without further validation.
+
+  This function can parse both absolute and relative URLs. You can check
+  if a URI is absolute or relative by checking if the `scheme` field is
+  nil or not. Furthermore, this function expects both absolute and
+  relative URIs to be well-formed and does not perform any validation.
+  See the "Examples" section below. Use `new/1` if you want more strict
+  validation.
+
+  When a URI is given without a port, the value returned by `URI.default_port/1`
+  for the URI's scheme is used for the `:port` field. The scheme is also
+  normalized to lowercase.
 
   If a `%URI{}` struct is given to this function, this function returns it
   unmodified.
 
+  > Note: this function sets the field :authority for backwards
+  > compatibility reasons but it is deprecated.
+
   ## Examples
 
       iex> URI.parse("https://elixir-lang.org/")
@@ -527,6 +730,36 @@ defmodule URI do
         userinfo: nil
       }
 
+  In contrast to `URI.new/1`, this function will parse poorly-formed
+  URIs, for example:
+
+      iex> URI.parse("/invalid_greater_than_in_path/>")
+      %URI{
+        authority: nil,
+        fragment: nil,
+        host: nil,
+        path: "/invalid_greater_than_in_path/>",
+        port: nil,
+        query: nil,
+        scheme: nil,
+        userinfo: nil
+      }
+
+  Another example is a URI with brackets in query strings. It is accepted
+  by `parse/1` but it will be refused by `new/1`:
+
+      iex> URI.parse("/?foo[bar]=baz")
+      %URI{
+        authority: nil,
+        fragment: nil,
+        host: nil,
+        path: "/",
+        port: nil,
+        query: "foo[bar]=baz",
+        scheme: nil,
+        userinfo: nil
+      }
+
   """
   @spec parse(t | binary) :: t
   def parse(%URI{} = uri), do: uri
@@ -561,8 +794,8 @@ defmodule URI do
                 ],
                 parts
 
-    scheme = nillify(scheme)
     path = nillify(path)
+    scheme = nillify(scheme)
     query = nillify_query(query_with_question_mark)
     {authority, userinfo, host, port} = split_authority(authority_with_slashes)
 
@@ -585,6 +818,9 @@ defmodule URI do
   defp nillify_query(_other), do: nil
 
   # Split an authority into its userinfo, host and port parts.
+  #
+  # Note that the host field is returned *without* [] even if, according to
+  # RFC3986 grammar, a native IPv6 address requires them.
   defp split_authority("") do
     {nil, nil, nil, nil}
   end
@@ -623,24 +859,6 @@ defmodule URI do
       iex> URI.to_string(uri)
       "foo://bar.baz"
 
-  Note that when creating this string representation, the `:authority` value will be
-  used if the `:host` is `nil`. Otherwise, the `:userinfo`, `:host`, and `:port` will
-  be used.
-
-      iex> URI.to_string(%URI{authority: "foo@example.com:80"})
-      "//foo@example.com:80"
-
-      iex> URI.to_string(%URI{userinfo: "bar", host: "example.org", port: 81})
-      "//bar@example.org:81"
-
-      iex> URI.to_string(%URI{
-      ...>   authority: "foo@example.com:80",
-      ...>   userinfo: "bar",
-      ...>   host: "example.org",
-      ...>   port: 81
-      ...> })
-      "//bar@example.org:81"
-
   """
   @spec to_string(t) :: binary
   defdelegate to_string(uri), to: String.Chars.URI
@@ -663,7 +881,7 @@ defmodule URI do
   @spec merge(t | binary, t | binary) :: t
   def merge(uri, rel)
 
-  def merge(%URI{authority: nil}, _rel) do
+  def merge(%URI{host: nil}, _rel) do
     raise ArgumentError, "you must merge onto an absolute URI"
   end
 
@@ -671,10 +889,11 @@ defmodule URI do
     %{rel | path: remove_dot_segments_from_path(rel.path)}
   end
 
-  def merge(base, %URI{authority: authority} = rel) when authority != nil do
+  def merge(base, %URI{host: host} = rel) when host != nil do
     %{rel | scheme: base.scheme, path: remove_dot_segments_from_path(rel.path)}
   end
 
+  # TODO: Check only for nils in future versions
   def merge(%URI{} = base, %URI{path: rel_path} = rel) when rel_path in ["", nil] do
     %{base | query: rel.query || base.query, fragment: rel.fragment}
   end
@@ -727,12 +946,11 @@ defmodule URI do
 end
 
 defimpl String.Chars, for: URI do
-  def to_string(%{host: host, authority: authority, path: path} = uri)
-      when (host != nil or authority != nil) and is_binary(path) and
+  def to_string(%{host: host, path: path} = uri)
+      when host != nil and is_binary(path) and
              path != "" and binary_part(path, 0, 1) != "/" do
     raise ArgumentError,
-          ":path in URI must be nil or an absolute path if :host or :authority are given, " <>
-            "got: #{inspect(uri)}"
+          ":path in URI must be empty or an absolute path if URL has a :host, got: #{inspect(uri)}"
   end
 
   def to_string(%{scheme: scheme, port: port, path: path, query: query, fragment: fragment} = uri) do

lib/elixir/lib/version.ex

@@ -30,14 +30,17 @@ defmodule Version do
 
   The version is represented by the `Version` struct and fields
   are named according to SemVer 2.0: `:major`, `:minor`, `:patch`,
-  `:pre`, and `:build`.
+  `:pre`, and `:build`. You can read those fields but you should
+  not create a new `Version` directly via the struct syntax. Instead
+  use the functions in this module.
 
   ## Requirements
 
   Requirements allow you to specify which versions of a given
   dependency you are willing to work against. Requirements support the common
-  comparison operators such as `>`, `>=`, `<`, `<=`, `==`, `!=` that work as one would expect,
-  and additionally the special operator `~>` described in detail further below.
+  comparison operators such as `>`, `>=`, `<`, `<=`, and `==` that work as one
+  would expect, and additionally the special operator `~>` described in detail
+  further below.
 
       # Only version 2.0.0
       "== 2.0.0"
@@ -131,28 +134,25 @@ defmodule Version do
     @compile inline: [compare: 2]
 
     @doc false
-    @spec new(String.t(), :ets.match_spec()) :: t
+    @spec new(String.t(), [atom | matchable]) :: t
     def new(source, lexed) do
       %__MODULE__{source: source, lexed: lexed}
     end
 
     @doc false
     @spec match?(t, tuple) :: boolean
-    def match?(%__MODULE__{lexed: lexed}, matchable_pattern) do
-      match_lexed?(lexed, matchable_pattern)
+    def match?(%__MODULE__{lexed: [operator, req | rest]}, version) do
+      match_lexed?(rest, version, match_op?(operator, req, version))
     end
 
-    defp match_lexed?([operator, req, :&& | rest], version) do
-      match_op?(operator, req, version) and match_lexed?(rest, version)
-    end
+    defp match_lexed?([:and, operator, req | rest], version, acc),
+      do: match_lexed?(rest, version, acc and match_op?(operator, req, version))
 
-    defp match_lexed?([operator, req, :|| | rest], version) do
-      match_op?(operator, req, version) or match_lexed?(rest, version)
-    end
+    defp match_lexed?([:or, operator, req | rest], version, acc),
+      do: acc or match_lexed?(rest, version, match_op?(operator, req, version))
 
-    defp match_lexed?([operator, req], version) do
-      match_op?(operator, req, version)
-    end
+    defp match_lexed?([], _version, acc),
+      do: acc
 
     defp match_op?(:==, req, version) do
       compare(version, req) == :eq
@@ -440,7 +440,7 @@ defmodule Version do
   The internal representation is opaque.
   """
   @spec compile_requirement(Requirement.t()) :: Requirement.t()
-  def compile_requirement(requirement) do
+  def compile_requirement(%Requirement{} = requirement) do
     requirement
   end
 
@@ -468,64 +468,77 @@ defmodule Version do
       {">", :>},
       {"<", :<},
       {"==", :==},
-      {"!=", :!=},
-      {"!", :!=},
-      {" or ", :||},
-      {" and ", :&&}
+      {" or ", :or},
+      {" and ", :and}
     ]
 
+    def lexer(string) do
+      lexer(string, "", [])
+    end
+
     for {string_op, atom_op} <- operators do
-      def lexer(unquote(string_op) <> rest, acc) do
-        lexer(rest, [unquote(atom_op) | acc])
+      defp lexer(unquote(string_op) <> rest, buffer, acc) do
+        lexer(rest, "", [unquote(atom_op) | maybe_prepend_buffer(buffer, acc)])
       end
     end
 
-    def lexer(" " <> rest, acc) do
-      lexer(rest, acc)
+    defp lexer("!=" <> rest, buffer, acc) do
+      IO.warn("!= inside Version requirements is deprecated, use ~> or >= instead")
+      lexer(rest, "", [:!= | maybe_prepend_buffer(buffer, acc)])
     end
 
-    def lexer(<<char::utf8, rest::binary>>, []) do
-      lexer(rest, [<<char::utf8>>, :==])
+    defp lexer("!" <> rest, buffer, acc) do
+      IO.warn("! inside Version requirements is deprecated, use ~> or >= instead")
+      lexer(rest, "", [:!= | maybe_prepend_buffer(buffer, acc)])
     end
 
-    def lexer(<<char::utf8, body::binary>>, [head | acc]) do
-      acc =
-        case head do
-          head when is_binary(head) ->
-            [<<head::binary, char::utf8>> | acc]
-
-          head when head in [:||, :&&] ->
-            [<<char::utf8>>, :==, head | acc]
-
-          _other ->
-            [<<char::utf8>>, head | acc]
-        end
-
-      lexer(body, acc)
+    defp lexer(" " <> rest, buffer, acc) do
+      lexer(rest, "", maybe_prepend_buffer(buffer, acc))
     end
 
-    def lexer("", acc) do
-      Enum.map(Enum.reverse(acc), fn
-        op when is_atom(op) ->
-          op
+    defp lexer(<<char::utf8, rest::binary>>, buffer, acc) do
+      lexer(rest, <<buffer::binary, char::utf8>>, acc)
+    end
 
-        version when is_binary(version) ->
-          case Version.Parser.parse_version(version, true) do
-            {:ok, version} -> version
-            :error -> :error
-          end
-      end)
+    defp lexer(<<>>, buffer, acc) do
+      maybe_prepend_buffer(buffer, acc)
+    end
+
+    defp maybe_prepend_buffer("", acc), do: acc
+
+    defp maybe_prepend_buffer(buffer, [head | _] = acc)
+         when is_atom(head) and head not in [:and, :or],
+         do: [buffer | acc]
+
+    defp maybe_prepend_buffer(buffer, acc),
+      do: [buffer, :== | acc]
+
+    defp revert_lexed([version, op, cond | rest], acc)
+         when is_binary(version) and is_atom(op) and cond in [:or, :and] do
+      with {:ok, version} <- validate_requirement(op, version) do
+        revert_lexed(rest, [cond, op, version | acc])
+      end
+    end
+
+    defp revert_lexed([version, op], acc) when is_binary(version) and is_atom(op) do
+      with {:ok, version} <- validate_requirement(op, version) do
+        {:ok, [op, version | acc]}
+      end
+    end
+
+    defp revert_lexed(_rest, _acc), do: :error
+
+    defp validate_requirement(op, version) do
+      case parse_version(version, true) do
+        {:ok, version} when op == :~> -> {:ok, version}
+        {:ok, {_, _, patch, _, _} = version} when is_integer(patch) -> {:ok, version}
+        _ -> :error
+      end
     end
 
     @spec parse_requirement(String.t()) :: {:ok, term} | :error
     def parse_requirement(source) do
-      lexed = lexer(source, [])
-
-      if valid_requirement?(lexed) do
-        {:ok, lexed}
-      else
-        :error
-      end
+      revert_lexed(lexer(source), [])
     end
 
     def parse_version(string, approximate? \\ false) when is_binary(string) do
@@ -610,44 +623,6 @@ defmodule Version do
     defp valid_identifier?(_other) do
       false
     end
-
-    defp valid_requirement?([]), do: false
-    defp valid_requirement?([a | next]), do: valid_requirement?(a, next)
-
-    # it must finish with a version
-    defp valid_requirement?(a, []) when is_tuple(a) do
-      true
-    end
-
-    # or <op> | and <op>
-    defp valid_requirement?(a, [b | next]) when is_atom(a) and is_atom(b) and a in [:||, :&&] do
-      valid_requirement?(b, next)
-    end
-
-    # <version> or | <version> and
-    defp valid_requirement?(a, [b | next]) when is_tuple(a) and is_atom(b) and b in [:||, :&&] do
-      valid_requirement?(b, next)
-    end
-
-    # or <version> | and <version>
-    defp valid_requirement?(a, [b | next]) when is_atom(a) and is_tuple(b) and a in [:||, :&&] do
-      valid_requirement?(b, next)
-    end
-
-    # ~> <version>
-    defp valid_requirement?(:~>, [b | next]) when is_tuple(b) do
-      valid_requirement?(b, next)
-    end
-
-    # <op> <version>
-    defp valid_requirement?(a, [{_major, _minor, patch, _pre, _build} = b | next])
-         when is_atom(a) and is_integer(patch) do
-      valid_requirement?(b, next)
-    end
-
-    defp valid_requirement?(_, _) do
-      false
-    end
   end
 end
 

lib/elixir/pages/compatibility-and-deprecations.md

@@ -8,12 +8,11 @@ Elixir applies bug fixes only to the latest minor branch. Security patches are a
 
 Elixir version | Support
 :------------- | :-----------------------------
-1.12           | Development
-1.11           | Bug fixes and security patches
+1.13           | Bug fixes and security patches
+1.12           | Security patches only
+1.11           | Security patches only
 1.10           | Security patches only
 1.9            | Security patches only
-1.8            | Security patches only
-1.7            | Security patches only
 
 New releases are announced in the read-only [announcements mailing list](https://groups.google.com/group/elixir-lang-ann). All security releases [will be tagged with `[security]`](https://groups.google.com/forum/#!searchin/elixir-lang-ann/%5Bsecurity%5D%7Csort:date).
 
@@ -39,25 +38,26 @@ The only exception to the compatibility guarantees above are experimental featur
 
 ## Compatibility between Elixir and Erlang/OTP
 
-Erlang/OTP versioning is independent from the versioning of Elixir. Each version of Elixir supports a specific range of Erlang/OTP versions. The compatibility table is shown below.
+Erlang/OTP versioning is independent from the versioning of Elixir. Erlang releases a new major version yearly. Our goal is to support the last three Erlang major versions by the time Elixir is released. The compatibility table is shown below.
 
 Elixir version | Supported Erlang/OTP versions
 :------------- | :-------------------------------
-1.0            | 17 - 17 (and Erlang/OTP 18 from v1.0.5)
-1.1            | 17 - 18
-1.2            | 18 - 18 (and Erlang/OTP 19 from v1.2.6)
-1.3            | 18 - 19
-1.4            | 18 - 19 (and Erlang/OTP 20 from v1.4.5)
-1.5            | 18 - 20
-1.6            | 19 - 20 (and Erlang/OTP 21 from v1.6.6)
-1.7            | 19 - 22
-1.8            | 20 - 22
-1.9            | 20 - 22
+1.13           | 22 - 24
+1.12           | 22 - 24
+1.11           | 21 - 23 (and Erlang/OTP 24 from v1.11.4)
 1.10           | 21 - 22 (and Erlang/OTP 23 from v1.10.3)
-1.11           | 21 - 23
-1.12           | 21 - 23
+1.9            | 20 - 22
+1.8            | 20 - 22
+1.7            | 19 - 22
+1.6            | 19 - 20 (and Erlang/OTP 21 from v1.6.6)
+1.5            | 18 - 20
+1.4            | 18 - 19 (and Erlang/OTP 20 from v1.4.5)
+1.3            | 18 - 19
+1.2            | 18 - 18 (and Erlang/OTP 19 from v1.2.6)
+1.1            | 17 - 18
+1.0            | 17 - 17 (and Erlang/OTP 18 from v1.0.5)
 
-While Elixir often adds compatibility to new Erlang/OTP versions on released branches, such as support for Erlang/OTP 20 in v1.4.5, those releases usually contain the minimum changes for Elixir to run without errors. Only the next minor release, in this case v1.5.0, does effectively leverage the new features provided by the latest Erlang/OTP release.
+Note Elixir may add compatibility to new Erlang/OTP versions on patch releases, such as support for Erlang/OTP 20 in v1.4.5. Those releases are made for convenience and typically contain the minimum changes for Elixir to run without errors, if any changes are necessary. Only the next minor release, in this case v1.5.0, effectively leverages the new features provided by the latest Erlang/OTP release.
 
 ## Deprecations
 
@@ -77,6 +77,13 @@ The first column is the version the feature was hard deprecated. The second colu
 
 Version | Deprecated feature                                  | Replaced by (available since)
 :-------| :-------------------------------------------------- | :---------------------------------------------------------------
+[v1.13] | `!` and `!=` in Version requirements                | `~>` or `>=` (v1.0)
+[v1.13] | `Mix.Config`                                        | `Config` (v1.9)
+[v1.13] | `:strip_beam` config to `mix escript.build`         | `:strip_beams` (v1.9)
+[v1.13] | `Macro.to_string/2`                                 | `Macro.to_string/1` (v1.0)
+[v1.13] | `System.get_pid/0`                                  | `System.pid/0` (v1.9)
+[v1.12] | `^^^/2`                                             | `bxor/2` (v1.0)
+[v1.12] | `@foo()` to read module attributes                  | Remove the parenthesis (v1.0)
 [v1.12] | `use EEx.Engine`                                    | Explicitly delegate to EEx.Engine instead (v1.0)
 [v1.12] | `:xref` compiler in Mix                             | Nothing (it always runs as part of the compiler now)
 [v1.11] | `Mix.Project.compile/2`                             | `Mix.Task.run("compile", args)` (v1.0)
@@ -179,4 +186,5 @@ Version | Deprecated feature                                  | Replaced by (ava
 [v1.9]: https://github.com/elixir-lang/elixir/blob/v1.9/CHANGELOG.md#4-hard-deprecations
 [v1.10]: https://github.com/elixir-lang/elixir/blob/v1.10/CHANGELOG.md#4-hard-deprecations
 [v1.11]: https://github.com/elixir-lang/elixir/blob/v1.11/CHANGELOG.md#4-hard-deprecations
-[v1.12]: https://github.com/elixir-lang/elixir/blob/master/CHANGELOG.md#4-hard-deprecations
+[v1.12]: https://github.com/elixir-lang/elixir/blob/v1.12/CHANGELOG.md#4-hard-deprecations
+[v1.13]: https://github.com/elixir-lang/elixir/blob/v1.13/CHANGELOG.md#4-hard-deprecations

lib/elixir/pages/operators.md

@@ -6,11 +6,12 @@ This document covers operators in Elixir, how they are parsed, how they can be d
 
 The following is a list of all operators that Elixir is capable of parsing, ordered from higher to lower precedence, alongside their associativity:
 
-Operator                                                                                 | Associativity
-------------------------------------------------------| -------------
+Operator                                              | Associativity
+----------------------------------------------------- | -------------
 `@`                                                   | Unary
 `.`                                                   | Left
 `+` `-` `!` `^` `not` `~~~`                           | Unary
+`**`                                                  | Left
 `*` `/`                                               | Left
 `+` `-`                                               | Left
 `++` `--` `+++` `---` `..` `<>`                       | Right

lib/elixir/pages/patterns-and-guards.md

@@ -205,6 +205,43 @@ iex> %{} = %{name: "meg"}
 
 Finally, note map keys in patterns must always be literals or previously bound variables matched with the pin operator.
 
+### Structs
+
+Structs may appear in patterns using the percentage sign, the struct module name or a variable followed by the curly brackets syntax (`%{}`).
+
+Given the following struct:
+
+```elixir
+defmodule User do
+  defstruct [:name]
+end
+```
+
+Here is an example where all keys match:
+
+```iex
+iex> %User{name: name} = %User{name: "meg"}
+%User{name: "meg"}
+iex> name
+"meg"
+```
+
+If an unknown key is given, the compiler will raise an error:
+
+```iex
+iex> %User{type: type} = %User{name: "meg"}
+** (CompileError) iex: unknown key :type for struct User
+```
+
+The struct name can be extracted when putting a variable instead of a module name:
+
+```
+iex> %struct_name{} = %User{name: "meg"}
+%User{name: "meg"}
+iex> struct_name
+User
+```
+
 ### Binaries
 
 Binaries may appear in patterns using the double less-than/greater-than syntax ([`<<>>`](`<<>>/1`)). A binary in a pattern can match multiple segments at the same, each with different type, size, and unit:
@@ -250,7 +287,7 @@ You can find the built-in list of guards [in the `Kernel` module](Kernel.html#gu
 
 The module `Bitwise` also includes a handful of [Erlang bitwise operations as guards](Bitwise.html#guards).
 
-Macros constructed out of any combination of the above guards are also valid guards - for example, `Integer.is_even/1`. For more information, see the "Defining custom guard expressions" section shown below.
+Macros constructed out of any combination of the above guards are also valid guards - for example, `Integer.is_even/1`. For more information, see the "Custom patterns and guards expressions" section shown below.
 
 ### Why guards
 

lib/elixir/pages/syntax-reference.md

@@ -11,7 +11,7 @@ These are the reserved words in the Elixir language. They are detailed throughou
   * `true`, `false`, `nil` - used as atoms
   * `when`, `and`, `or`, `not`, `in` - used as operators
   * `fn` - used for anonymous function definitions
-  * `do`, `end`, `catch`, `rescue`, `after`, `else` - used in do/end blocks
+  * `do`, `end`, `catch`, `rescue`, `after`, `else` - used in do-end blocks
 
 ## Data types
 
@@ -122,9 +122,9 @@ Blocks are multiple Elixir expressions separated by newlines or semi-colons. A n
 
 ### Left to right arrow
 
-The left to right arrow (`->`) is used to establish a relationship between left and right, commonly referred as clauses. The left side may have zero, one, or more arguments; the right side is zero, one, or more expressions separated by new line. The `->` may appear one or more times between one of the following terminators: `do`/`end`, `fn`/`end` or `(`/`)`. When `->` is used, only other clauses are allowed between those terminators. Mixing clauses and regular expressions is invalid syntax.
+The left to right arrow (`->`) is used to establish a relationship between left and right, commonly referred as clauses. The left side may have zero, one, or more arguments; the right side is zero, one, or more expressions separated by new line. The `->` may appear one or more times between one of the following terminators: `do`-`end`, `fn`-`end` or `(`-`)`. When `->` is used, only other clauses are allowed between those terminators. Mixing clauses and regular expressions is invalid syntax.
 
-It is seen on `case` and `cond` constructs between `do`/`end`:
+It is seen on `case` and `cond` constructs between `do` and `end`:
 
 ```elixir
 case 1 do
@@ -137,13 +137,13 @@ cond do
 end
 ```
 
-Seen in typespecs between `(`/`)`:
+Seen in typespecs between `(` and `)`:
 
 ```elixir
 (integer(), boolean() -> integer())
 ```
 
-It is also used between `fn/end` for building anonymous functions:
+It is also used between `fn` and `end` for building anonymous functions:
 
 ```elixir
 fn
@@ -352,7 +352,7 @@ end
 #=> {:cond, [], [[do: [{:->, [], [[true], false]}]]]}
 ```
 
-Between `(`/`)`:
+Between `(` and `)`:
 
 ```elixir
 quote do
@@ -362,7 +362,7 @@ end
 #=> [{:->, [], [[1, 2], 3]}, {:->, [], [[4, 5], 6]}]
 ```
 
-Between `fn/end`:
+Between `fn` and `end`:
 
 ```elixir
 quote do
@@ -374,6 +374,17 @@ end
 #=> {:fn, [], [{:->, [], [[1, 2], 3]}, {:->, [], [[4, 5], 6]}]}
 ```
 
+### Qualified tuples
+
+Qualified tuples (`foo.{bar, baz}`) is represented by a `{:., [], [expr, :{}]}` call, where the `expr` represents the left hand side of the dot, and the arguments represent the elements inside the curly braces. This is used in Elixir to provide multi aliases:
+
+```elixir
+quote do
+  Foo.{Bar, Baz}
+end
+#=> {{:., [], [{:__aliases__, [], [:Foo]}, :{}]}, [], [{:__aliases__, [], [:Bar]}, {:__aliases__, [], [:Baz]}]}
+```
+
 ## Syntactic sugar
 
 All of the constructs above are part of Elixir's syntax and have their own representation as part of the Elixir AST. This section will discuss the remaining constructs that "desugar" to one of the constructs explored above. In other words, the constructs below can be represented in more than one way in your Elixir code and retain AST equivalence.
@@ -414,7 +425,7 @@ end
 
 ### Optional parentheses
 
-Elixir provides optional parentheses for non-qualified and qualified calls.
+Elixir provides optional parentheses:
 
 ```elixir
 quote do
@@ -423,15 +434,9 @@ end
 #=> {:sum, [], [1, 2, 3]}
 ```
 
-The above is treated the same as `sum(1, 2, 3)` by the parser.
+The above is treated the same as `sum(1, 2, 3)` by the parser. You can remove the parentheses on all calls with at least one argument.
 
-The same applies to qualified calls such as `Foo.bar(1, 2, 3)`, which is equivalent to `Foo.bar 1, 2, 3`. There are, however, some situations where parentheses are required:
-
-  * when calling anonymous functions, such as `f.(1, 2)`;
-
-  * for non-qualified calls with no arguments, such as `sum()`. Removing the parentheses for `sum` causes it to be represented as the variable `sum`;
-
-  * for dynamic qualified calls with no arguments. `data.key` means accessing a field named `key` in the map given by `data`. `mod.fun()`, with parens, means calling a function named `fun` in the module `mod`;
+You can also skip parentheses on qualified calls, such as `Foo.bar 1, 2, 3`. Parentheses are required when invoking anonymous functions, such as `f.(1, 2, 3)`.
 
 In practice, developers prefer to add parentheses to most of their calls. They are skipped mainly in Elixir's control-flow constructs, such as `defmodule`, `if`, `case`, etc, and in certain DSLs.
 
@@ -477,9 +482,9 @@ which in turn is the same as
 if(condition, [{:do, this}, {:else, that}])
 ```
 
-### `do`/`end` blocks
+### `do`-`end` blocks
 
-The last syntax convenience are `do`/`end` blocks. `do`/`end` blocks are equivalent to keywords as the last argument of a function call where the block contents are wrapped in parentheses. For example:
+The last syntax convenience are `do`-`end` blocks. `do`-`end` blocks are equivalent to keywords as the last argument of a function call where the block contents are wrapped in parentheses. For example:
 
 ```elixir
 if true do
@@ -515,7 +520,7 @@ if(true, do: (
 ))
 ```
 
-Inside `do`/`end` blocks you may introduce other keywords, such as `else` used in the `if` above. The supported keywords between `do`/`end` are static and are:
+Inside `do`-`end` blocks you may introduce other keywords, such as `else` used in the `if` above. The supported keywords between `do`-`end` are static and are:
 
   * `after`
   * `catch`

lib/elixir/src/elixir.erl

@@ -4,8 +4,7 @@
 -behaviour(application).
 -export([start_cli/0,
   string_to_tokens/5, tokens_to_quoted/3, 'string_to_quoted!'/5,
-  env_for_eval/1, env_for_eval/2, quoted_to_erl/2,
-  eval_forms/3, eval_quoted/3]).
+  env_for_eval/1, quoted_to_erl/2, eval_forms/3, eval_quoted/3]).
 -include("elixir.hrl").
 -define(system, 'Elixir.System').
 
@@ -55,10 +54,6 @@ start(_Type, _Args) ->
     {argv, []},
     {no_halt, false},
 
-    %% Static options
-    {bootstrap, false},
-    {identifier_tokenizer, Tokenizer},
-
     %% Compiler options
     {docs, true},
     {ignore_module_conflict, false},
@@ -71,6 +66,8 @@ start(_Type, _Args) ->
     | URIConfig
   ],
 
+  elixir_config:static(#{bootstrap => false, identifier_tokenizer => Tokenizer}),
+
   Tab = elixir_config:new(Config),
   case elixir_sup:start_link() of
     {ok, Sup} ->
@@ -111,10 +108,10 @@ preload_common_modules() ->
 parse_otp_release() ->
   %% Whenever we change this check, we should also change Makefile.
   case string:to_integer(erlang:system_info(otp_release)) of
-    {Num, _} when Num >= 21 ->
+    {Num, _} when Num >= 22 ->
       Num;
     _ ->
-      io:format(standard_error, "ERROR! Unsupported Erlang/OTP version, expected Erlang/OTP 21+~n", []),
+      io:format(standard_error, "ERROR! Unsupported Erlang/OTP version, expected Erlang/OTP 22+~n", []),
       erlang:halt(1)
   end.
 
@@ -165,10 +162,22 @@ start_cli() ->
 
 %% EVAL HOOKS
 
-env_for_eval(Opts) ->
-  env_for_eval(elixir_env:new(), Opts).
+env_for_eval(#{lexical_tracker := Pid} = Env) ->
+  NewEnv = Env#{
+    context := nil,
+    context_modules := [],
+    macro_aliases := [],
+    versioned_vars := #{}
+  },
+
+  case is_pid(Pid) andalso is_process_alive(Pid) of
+    true -> NewEnv;
+    false -> NewEnv#{lexical_tracker := nil, tracers := []}
+  end;
+%% TODO: Deprecate all options except line and file.
+env_for_eval(Opts) when is_list(Opts) ->
+  Env = elixir_env:new(),
 
-env_for_eval(Env, Opts) ->
   Line = case lists:keyfind(line, 1, Opts) of
     {line, LineOpt} when is_integer(LineOpt) -> LineOpt;
     false -> ?key(Env, line)
@@ -244,15 +253,15 @@ eval_quoted(Tree, Binding, #{line := Line} = E) ->
 
 eval_forms(Tree, Binding, Opts) when is_list(Opts) ->
   eval_forms(Tree, Binding, env_for_eval(Opts));
-eval_forms(Tree, RawBinding, OE) ->
-  {Vars, Binding} = normalize_binding(RawBinding, [], []),
-  E = elixir_env:with_vars(OE, Vars),
-  {_, S} = elixir_env:env_to_scope(E),
-  {Erl, NewE, NewS} = quoted_to_erl(Tree, E, S),
+eval_forms(Tree, RawBinding, OrigE) ->
+  {Vars, Binding} = normalize_binding(RawBinding, #{}, [], 0),
+  E = elixir_env:with_vars(OrigE, Vars),
+  {_, S} = elixir_env:env_to_erl(E),
+  {Erl, NewErlS, NewExS, NewE} = quoted_to_erl(Tree, E, S),
 
   case Erl of
     {atom, _, Atom} ->
-      {Atom, Binding, NewE};
+      {Atom, RawBinding, NewE};
 
     _  ->
       Exprs =
@@ -263,15 +272,22 @@ eval_forms(Tree, RawBinding, OE) ->
 
       ErlBinding = elixir_erl_var:load_binding(Binding, E, S),
       {value, Value, NewBinding} = recur_eval(Exprs, ErlBinding, NewE),
-      {Value, elixir_erl_var:dump_binding(NewBinding, NewE, NewS), NewE}
+      {Value, elixir_erl_var:dump_binding(NewBinding, NewExS, NewErlS), NewE}
   end.
 
-normalize_binding([{Key, Value} | Binding], Vars, Acc) when is_atom(Key) ->
-  normalize_binding(Binding, [{Key, nil} | Vars], [{{Key, nil}, Value} | Acc]);
-normalize_binding([{Pair, Value} | Binding], Vars, Acc) ->
-  normalize_binding(Binding, [Pair | Vars], [{Pair, Value} | Acc]);
-normalize_binding([], Vars, Acc) ->
-  {Vars, Acc}.
+normalize_binding([Binding | NextBindings], VarsMap, Normalized, Counter) ->
+  {Pair, Value} = normalize_pair(Binding),
+  case VarsMap of
+    #{Pair := _} ->
+      normalize_binding(NextBindings, VarsMap, [{Pair, Value} | Normalized], Counter);
+    #{} ->
+      normalize_binding(NextBindings, VarsMap#{Pair => Counter}, [{Pair, Value} | Normalized], Counter + 1)
+  end;
+normalize_binding([], VarsMap, Normalized, _Counter) ->
+  {VarsMap, Normalized}.
+
+normalize_pair({Key, Value}) when is_atom(Key) -> {{Key, nil}, Value};
+normalize_pair({Pair, Value}) -> {Pair, Value}.
 
 recur_eval([Expr | Exprs], Binding, Env) ->
   {value, Value, NewBinding} =
@@ -327,30 +343,31 @@ merge_stacktrace([StackItem | Stacktrace], CurrentStack) ->
 %% Converts a quoted expression to Erlang abstract format
 
 quoted_to_erl(Quoted, E) ->
-  {_, S} = elixir_env:env_to_scope(E),
+  {_, S} = elixir_env:env_to_erl(E),
   quoted_to_erl(Quoted, E, S).
 
 quoted_to_erl(Quoted, Env, Scope) ->
-  {Expanded, NewEnv} = elixir_expand:expand(Quoted, Env),
-  {Erl, NewScope} = elixir_erl_pass:translate(Expanded, Scope),
-  {Erl, NewEnv, NewScope}.
+  {Expanded, NewExS, NewEnv} = elixir_expand:expand(Quoted, elixir_env:env_to_ex(Env), Env),
+  {Erl, NewErlS} = elixir_erl_pass:translate(Expanded, erl_anno:new(?key(Env, line)), Scope),
+  {Erl, NewErlS, NewExS, NewEnv}.
 
 %% Converts a given string (charlist) into quote expression
 
 string_to_tokens(String, StartLine, StartColumn, File, Opts) when is_integer(StartLine), is_binary(File) ->
   case elixir_tokenizer:tokenize(String, StartLine, StartColumn, [{file, File} | Opts]) of
-    {ok, _Tokens} = Ok ->
-      Ok;
-    {error, {Line, Column, {ErrorPrefix, ErrorSuffix}, Token}, _Rest, _SoFar} ->
+    {ok, _Line, _Column, Warnings, Tokens} ->
+      [elixir_errors:erl_warn(L, F, M) || {L, F, M} <- lists:reverse(Warnings)],
+      {ok, Tokens};
+    {error, {Line, Column, {ErrorPrefix, ErrorSuffix}, Token}, _Rest, _Warnings, _SoFar} ->
       Location = [{line, Line}, {column, Column}],
       {error, {Location, {to_binary(ErrorPrefix), to_binary(ErrorSuffix)}, to_binary(Token)}};
-    {error, {Line, Column, Error, Token}, _Rest, _SoFar} ->
+    {error, {Line, Column, Error, Token}, _Rest, _Warnings, _SoFar} ->
       Location = [{line, Line}, {column, Column}],
       {error, {Location, to_binary(Error), to_binary(Token)}}
   end.
 
-tokens_to_quoted(Tokens, File, Opts) ->
-  handle_parsing_opts(File, Opts),
+tokens_to_quoted(Tokens, WarningFile, Opts) ->
+  handle_parsing_opts(WarningFile, Opts),
 
   try elixir_parser:parse(Tokens) of
     {ok, Forms} ->
@@ -360,7 +377,7 @@ tokens_to_quoted(Tokens, File, Opts) ->
     {error, {Line, _, [Error, Token]}} ->
       {error, {parser_location(Line), to_binary(Error), to_binary(Token)}}
   after
-    erase(elixir_parser_file),
+    erase(elixir_parser_warning_file),
     erase(elixir_parser_columns),
     erase(elixir_token_metadata),
     erase(elixir_literal_encoder)
@@ -386,17 +403,17 @@ parser_location(Meta) ->
       case tokens_to_quoted(Tokens, File, Opts) of
         {ok, Forms} ->
           Forms;
-        {error, {Line, Error, Token}} ->
-          elixir_errors:parse_error(Line, File, Error, Token)
+        {error, {Meta, Error, Token}} ->
+          elixir_errors:parse_error(Meta, File, Error, Token, {String, StartLine, StartColumn})
       end;
-    {error, {Line, Error, Token}} ->
-      elixir_errors:parse_error(Line, File, Error, Token)
+    {error, {Meta, Error, Token}} ->
+      elixir_errors:parse_error(Meta, File, Error, Token, {String, StartLine, StartColumn})
   end.
 
 to_binary(List) when is_list(List) -> elixir_utils:characters_to_binary(List);
 to_binary(Atom) when is_atom(Atom) -> atom_to_binary(Atom, utf8).
 
-handle_parsing_opts(File, Opts) ->
+handle_parsing_opts(WarningFile, Opts) ->
   LiteralEncoder =
     case lists:keyfind(literal_encoder, 1, Opts) of
       {literal_encoder, Fun} -> Fun;
@@ -404,7 +421,7 @@ handle_parsing_opts(File, Opts) ->
     end,
   TokenMetadata = lists:keyfind(token_metadata, 1, Opts) == {token_metadata, true},
   Columns = lists:keyfind(columns, 1, Opts) == {columns, true},
-  put(elixir_parser_file, File),
+  put(elixir_parser_warning_file, WarningFile),
   put(elixir_parser_columns, Columns),
   put(elixir_token_metadata, TokenMetadata),
   put(elixir_literal_encoder, LiteralEncoder).

lib/elixir/src/elixir.hrl

@@ -1,10 +1,18 @@
 -define(key(M, K), maps:get(K, M)).
--define(ann(Opts), elixir_erl:get_ann(Opts)).
--define(line(Opts), elixir_utils:get_line(Opts)).
+-define(ann(Meta), elixir_erl:get_ann(Meta)).
+-define(line(Meta), elixir_utils:get_line(Meta)).
 -define(generated(Meta), [{generated, true} | Meta]).
 -define(var_context, ?MODULE).
 -define(remote(Ann, Module, Function, Args), {call, Ann, {remote, Ann, {atom, Ann, Module}, {atom, Ann, Function}}, Args}).
 
+-record(elixir_ex, {
+  caller=false,            %% stores if __CALLER__ is allowed
+  prematch=warn,           %% {Read, Counter} | warn | raise | pin
+  stacktrace=false,        %% stores if __STACKTRACE__ is allowed
+  unused={#{}, 0},         %% a map of unused vars and a version counter for vars
+  vars={#{}, false}        %% a tuple with maps of read and optional write current vars
+}).
+
 -record(elixir_erl, {
   context=nil,             %% can be match, guards or nil
   extra=nil,               %% extra information about the context, like pin_guard and map_key
@@ -20,7 +28,7 @@
   file=(<<"nofile">>),
   terminators=[],
   unescape=true,
-  check_terminators=true,
+  cursor_completion=false,
   existing_atoms_only=false,
   static_atoms_encoder=nil,
   preserve_comments=nil,
@@ -30,11 +38,3 @@
   warn_on_unnecessary_quotes=true,
   warnings=[]
 }).
-
-%% TODO: Remove this once we support Erlang/OTP 22+ exclusively.
-%% See https://github.com/erlang/otp/pull/1972
--if(?OTP_RELEASE >= 22).
-  -define(NO_SPAWN_COMPILER_PROCESS, no_spawn_compiler_process).
--else.
-  -define(NO_SPAWN_COMPILER_PROCESS, dialyzer, no_spawn_compiler_process).
--endif.

lib/elixir/src/elixir_aliases.erl

@@ -1,10 +1,10 @@
 -module(elixir_aliases).
 -export([inspect/1, last/1, concat/1, safe_concat/1, format_error/1,
-         ensure_loaded/3, expand/2, store/5]).
+         ensure_loaded/3, expand/2, expand_or_concat/2, store/5]).
 -include("elixir.hrl").
 
 inspect(Atom) when is_atom(Atom) ->
-  case elixir_config:get(bootstrap) of
+  case elixir_config:is_bootstrap() of
     true  -> atom_to_binary(Atom, utf8);
     false -> 'Elixir.Code.Identifier':inspect_as_atom(Atom)
   end.
@@ -56,10 +56,12 @@ expand({'__aliases__', Meta, _} = Alias, #{aliases := Aliases, macro_aliases :=
 
 expand({'__aliases__', Meta, [H | T]}, Aliases, E) when is_atom(H) ->
   Lookup  = list_to_atom("Elixir." ++ atom_to_list(H)),
+
   Counter = case lists:keyfind(counter, 1, Meta) of
     {counter, C} -> C;
     _ -> nil
   end,
+
   case lookup(Lookup, Aliases, Counter) of
     Lookup -> [H | T];
     Atom ->
@@ -73,6 +75,14 @@ expand({'__aliases__', Meta, [H | T]}, Aliases, E) when is_atom(H) ->
 expand({'__aliases__', _Meta, List}, _Aliases, _E) ->
   List.
 
+%% Expands or concat if possible.
+
+expand_or_concat(Aliases, E) ->
+  case expand(Aliases, E) of
+    [H | T] when is_atom(H) -> concat([H | T]);
+    AtomOrList -> AtomOrList
+  end.
+
 %% Ensure a module is loaded before its usage.
 
 ensure_loaded(_Meta, 'Elixir.Kernel', _E) -> ok;
@@ -104,16 +114,21 @@ ensure_loaded(Meta, Module, E) ->
   end.
 
 wait_for_module(Module) ->
-  case is_pid(erlang:get(elixir_compiler_pid)) of
-    true -> 'Elixir.Kernel.ErrorHandler':ensure_compiled(Module, module, hard);
-    false -> not_found
+  case erlang:get(elixir_compiler_info) of
+    undefined -> not_found;
+    _ -> 'Elixir.Kernel.ErrorHandler':ensure_compiled(Module, module, hard)
   end.
 
 %% Receives an atom and returns the last bit as an alias.
 
 last(Atom) ->
-  Last = last(lists:reverse(atom_to_list(Atom)), []),
-  list_to_atom("Elixir." ++ Last).
+  case atom_to_list(Atom) of
+    ("Elixir." ++ [FirstLetter | _]) = List when FirstLetter >= $A, FirstLetter =< $Z ->
+      Last = last(lists:reverse(List), []),
+      {ok, list_to_atom("Elixir." ++ Last)};
+    _ ->
+      error
+  end.
 
 last([$. | _], Acc) -> Acc;
 last([H | T], Acc)  -> last(T, [H | Acc]);

lib/elixir/src/elixir_bitstring.erl

@@ -1,47 +1,47 @@
 -module(elixir_bitstring).
--export([expand/4, format_error/1]).
+-export([expand/5, format_error/1]).
 -import(elixir_errors, [form_error/4]).
 -include("elixir.hrl").
 
-expand_match(Expr, {E, OriginalE}) ->
-  {EExpr, EE} = elixir_expand:expand(Expr, E),
-  {EExpr, {EE, OriginalE}}.
+expand_match(Expr, {S, OriginalS}, E) ->
+  {EExpr, SE, EE} = elixir_expand:expand(Expr, S, E),
+  {EExpr, {SE, OriginalS}, EE}.
 
-expand(Meta, Args, E, RequireSize) ->
+expand(Meta, Args, S, E, RequireSize) ->
   case ?key(E, context) of
     match ->
-      {EArgs, Alignment, {EA, _}} =
-        expand(Meta, fun expand_match/2, Args, [], {E, E}, 0, RequireSize),
+      {EArgs, Alignment, {SA, _}, EA} =
+        expand(Meta, fun expand_match/3, Args, [], {S, S}, E, 0, RequireSize),
 
       case find_match(EArgs) of
         false ->
-          {{'<<>>', [{alignment, Alignment} | Meta], EArgs}, EA};
+          {{'<<>>', [{alignment, Alignment} | Meta], EArgs}, SA, EA};
         Match ->
           form_error(Meta, EA, ?MODULE, {nested_match, Match})
       end;
     _ ->
-      PairE = {elixir_env:prepare_write(E), E},
+      PairS = {elixir_env:prepare_write(S), S},
 
-      {EArgs, Alignment, {EA, _}} =
-        expand(Meta, fun elixir_expand:expand_arg/2, Args, [], PairE, 0, RequireSize),
+      {EArgs, Alignment, {SA, _}, EA} =
+        expand(Meta, fun elixir_expand:expand_arg/3, Args, [], PairS, E, 0, RequireSize),
 
-      {{'<<>>', [{alignment, Alignment} | Meta], EArgs}, elixir_env:close_write(EA, E)}
+      {{'<<>>', [{alignment, Alignment} | Meta], EArgs}, elixir_env:close_write(SA, S), EA}
   end.
 
-expand(_BitstrMeta, _Fun, [], Acc, E, Alignment, _RequireSize) ->
-  {lists:reverse(Acc), Alignment, E};
-expand(BitstrMeta, Fun, [{'::', Meta, [Left, Right]} | T], Acc, E, Alignment, RequireSize) ->
-  {ELeft, {EL, OriginalE}} = expand_expr(Meta, Left, Fun, E),
+expand(_BitstrMeta, _Fun, [], Acc, S, E, Alignment, _RequireSize) ->
+  {lists:reverse(Acc), Alignment, S, E};
+expand(BitstrMeta, Fun, [{'::', Meta, [Left, Right]} | T], Acc, S, E, Alignment, RequireSize) ->
+  {ELeft, {SL, OriginalS}, EL} = expand_expr(Meta, Left, Fun, S, E),
 
   MatchOrRequireSize = RequireSize or is_match_size(T, EL),
   EType = expr_type(ELeft),
-  {ERight, EAlignment, ES} = expand_specs(EType, Meta, Right, EL, OriginalE, MatchOrRequireSize),
+  {ERight, EAlignment, SS, ES} = expand_specs(EType, Meta, Right, SL, OriginalS, EL, MatchOrRequireSize),
 
   EAcc = concat_or_prepend_bitstring(Meta, ELeft, ERight, Acc, ES, MatchOrRequireSize),
-  expand(BitstrMeta, Fun, T, EAcc, {ES, OriginalE}, alignment(Alignment, EAlignment), RequireSize);
-expand(BitstrMeta, Fun, [H | T], Acc, E, Alignment, RequireSize) ->
+  expand(BitstrMeta, Fun, T, EAcc, {SS, OriginalS}, ES, alignment(Alignment, EAlignment), RequireSize);
+expand(BitstrMeta, Fun, [H | T], Acc, S, E, Alignment, RequireSize) ->
   Meta = extract_meta(H, BitstrMeta),
-  {ELeft, {ES, OriginalE}} = expand_expr(Meta, H, Fun, E),
+  {ELeft, {SS, OriginalS}, ES} = expand_expr(Meta, H, Fun, S, E),
 
   MatchOrRequireSize = RequireSize or is_match_size(T, ES),
   EType = expr_type(ELeft),
@@ -49,7 +49,7 @@ expand(BitstrMeta, Fun, [H | T], Acc, E, Alignment, RequireSize) ->
 
   InferredMeta = [{inferred_bitstring_spec, true} | Meta],
   EAcc = concat_or_prepend_bitstring(InferredMeta, ELeft, ERight, Acc, ES, MatchOrRequireSize),
-  expand(Meta, Fun, T, EAcc, {ES, OriginalE}, Alignment, RequireSize).
+  expand(Meta, Fun, T, EAcc, {SS, OriginalS}, ES, Alignment, RequireSize).
 
 extract_meta({_, Meta, _}, _) -> Meta;
 extract_meta(_, Meta) -> Meta.
@@ -133,37 +133,39 @@ compute_alignment(_, _, _) -> unknown.
 %% If we are inside a match/guard, we inline interpolations explicitly,
 %% otherwise they are inlined by elixir_rewrite.erl.
 
-expand_expr(_Meta, {{'.', _, [Mod, to_string]}, _, [Arg]} = AST, Fun, {#{context := Context}, _} = E)
+expand_expr(_Meta, {{'.', _, [Mod, to_string]}, _, [Arg]} = AST, Fun, S, #{context := Context} = E)
     when Context /= nil, (Mod == 'Elixir.Kernel') orelse (Mod == 'Elixir.String.Chars') ->
-  case Fun(Arg, E) of
-    {EBin, EE} when is_binary(EBin) -> {EBin, EE};
-    _ -> Fun(AST, E) % Let it raise
+  case Fun(Arg, S, E) of
+    {EBin, SE, EE} when is_binary(EBin) -> {EBin, SE, EE};
+    _ -> Fun(AST, S, E) % Let it raise
   end;
-expand_expr(Meta, Component, Fun, E) ->
-  case Fun(Component, E) of
-    {EComponent, {ErrorE, _}} when is_list(EComponent); is_atom(EComponent) ->
+expand_expr(Meta, Component, Fun, S, E) ->
+  case Fun(Component, S, E) of
+    {EComponent, _, ErrorE} when is_list(EComponent); is_atom(EComponent) ->
       form_error(Meta, ErrorE, ?MODULE, {invalid_literal, EComponent});
-    {_, _} = Expanded ->
+    {_, _, _} = Expanded ->
       Expanded
   end.
 
 %% Expands and normalizes types of a bitstring.
 
-expand_specs(ExprType, Meta, Info, E, OriginalE, RequireSize) ->
+expand_specs(ExprType, Meta, Info, S, OriginalS, E, RequireSize) ->
   Default =
     #{size => default,
       unit => default,
       sign => default,
       type => default,
       endianness => default},
-  {#{size := Size, unit := Unit, type := Type, endianness := Endianness, sign := Sign}, ES} =
-    expand_each_spec(Meta, unpack_specs(Info, []), Default, E, OriginalE),
+  {#{size := Size, unit := Unit, type := Type, endianness := Endianness, sign := Sign}, SS, ES} =
+    expand_each_spec(Meta, unpack_specs(Info, []), Default, S, OriginalS, E),
+
   MergedType = type(Meta, ExprType, Type, E),
   validate_size_required(Meta, RequireSize, ExprType, MergedType, Size, ES),
   SizeAndUnit = size_and_unit(Meta, ExprType, Size, Unit, ES),
   Alignment = compute_alignment(MergedType, Size, Unit),
+
   [H | T] = build_spec(Meta, Size, Unit, MergedType, Endianness, Sign, SizeAndUnit, ES),
-  {lists:foldl(fun(I, Acc) -> {'-', Meta, [Acc, I]} end, H, T), Alignment, ES}.
+  {lists:foldl(fun(I, Acc) -> {'-', Meta, [Acc, I]} end, H, T), Alignment, SS, ES}.
 
 type(_, default, default, _) ->
   integer;
@@ -182,11 +184,11 @@ type(_, default, Type, _) ->
 type(Meta, Other, Value, E) ->
   form_error(Meta, E, ?MODULE, {bittype_mismatch, Value, Other, type}).
 
-expand_each_spec(Meta, [{Expr, _, Args} = H | T], Map, E, OriginalE) when is_atom(Expr) ->
+expand_each_spec(Meta, [{Expr, _, Args} = H | T], Map, S, OriginalS, E) when is_atom(Expr) ->
   case validate_spec(Expr, Args) of
     {Key, Arg} ->
-      {Value, EE} = expand_spec_arg(Arg, E, OriginalE),
-      validate_spec_arg(Meta, Key, Value, EE, OriginalE),
+      {Value, SE, EE} = expand_spec_arg(Arg, S, OriginalS, E),
+      validate_spec_arg(Meta, Key, Value, SE, OriginalS, EE),
 
       case maps:get(Key, Map) of
         default -> ok;
@@ -194,19 +196,21 @@ expand_each_spec(Meta, [{Expr, _, Args} = H | T], Map, E, OriginalE) when is_ato
         Other -> form_error(Meta, E, ?MODULE, {bittype_mismatch, Value, Other, Key})
       end,
 
-      expand_each_spec(Meta, T, maps:put(Key, Value, Map), EE, OriginalE);
+      expand_each_spec(Meta, T, maps:put(Key, Value, Map), SE, OriginalS, EE);
+
     none ->
-      case 'Elixir.Macro':expand(H, elixir_env:linify({?line(Meta), E})) of
+      case 'Elixir.Macro':expand(H, E#{line := ?line(Meta)}) of
         H ->
           form_error(Meta, E, ?MODULE, {undefined_bittype, H});
+
         NewTypes ->
-          expand_each_spec(Meta, unpack_specs(NewTypes, []) ++ T, Map, E, OriginalE)
+          expand_each_spec(Meta, unpack_specs(NewTypes, []) ++ T, Map, S, OriginalS, E)
       end
   end;
-expand_each_spec(Meta, [Expr | _], _Map, E, _OriginalE) ->
+expand_each_spec(Meta, [Expr | _], _Map, _S, _OriginalS, E) ->
   form_error(Meta, E, ?MODULE, {undefined_bittype, Expr});
-expand_each_spec(_Meta, [], Map, E, _OriginalE) ->
-  {Map, E}.
+expand_each_spec(_Meta, [], Map, S, _OriginalS, E) ->
+  {Map, S, E}.
 
 unpack_specs({'-', _, [H, T]}, Acc) ->
   unpack_specs(H, unpack_specs(T, Acc));
@@ -240,20 +244,20 @@ validate_spec(signed, [])    -> {sign, signed};
 validate_spec(unsigned, [])  -> {sign, unsigned};
 validate_spec(_, _)          -> none.
 
-expand_spec_arg(Expr, E, _OriginalE) when is_atom(Expr); is_integer(Expr) ->
-  {Expr, E};
-expand_spec_arg(Expr, #{context := match} = E, _OriginalE) ->
-  {EExpr, EE} = elixir_expand:expand(Expr, E#{context := nil, prematch_vars := raise}),
-  {EExpr, EE#{context := match, prematch_vars := ?key(E, prematch_vars)}};
-expand_spec_arg(Expr, E, OriginalE) ->
-  elixir_expand:expand(Expr, elixir_env:reset_read(E, OriginalE)).
+expand_spec_arg(Expr, S, _OriginalS, E) when is_atom(Expr); is_integer(Expr) ->
+  {Expr, S, E};
+expand_spec_arg(Expr, S, _OriginalS, #{context := match} = E) ->
+  {EExpr, SE, EE} = elixir_expand:expand(Expr, S#elixir_ex{prematch=raise}, E#{context := nil}),
+  {EExpr, SE#elixir_ex{prematch=S#elixir_ex.prematch}, EE#{context := match}};
+expand_spec_arg(Expr, S, OriginalS, E) ->
+  elixir_expand:expand(Expr, elixir_env:reset_read(S, OriginalS), E).
 
-validate_spec_arg(Meta, size, Value, E, OriginalE) ->
+validate_spec_arg(Meta, size, Value, S, OriginalS, E) ->
   case Value of
     {Var, VarMeta, Context} when is_atom(Var) and is_atom(Context) ->
       Tuple = {Var, elixir_utils:var_context(VarMeta, Context)},
 
-      case is_valid_spec_arg_var(Tuple, E, OriginalE) of
+      case is_valid_spec_arg_var(Tuple, S, OriginalS, E) of
         true -> ok;
         false -> form_error(Meta, E, ?MODULE, {undefined_var_in_spec, Value})
       end;
@@ -264,20 +268,20 @@ validate_spec_arg(Meta, size, Value, E, OriginalE) ->
     _ ->
       form_error(Meta, E, ?MODULE, {bad_size_argument, Value})
   end;
-validate_spec_arg(Meta, unit, Value, E, _OriginalE) when not is_integer(Value) ->
+validate_spec_arg(Meta, unit, Value, _S, _OriginalS, E) when not is_integer(Value) ->
   form_error(Meta, E, ?MODULE, {bad_unit_argument, Value});
-validate_spec_arg(_Meta, _Key, _Value, _E, _OriginalE) ->
+validate_spec_arg(_Meta, _Key, _Value, _S, _OriginalS, _E) ->
   ok.
 
-is_valid_spec_arg_var(Var, E, #{context := match} = OriginalE) ->
-  case OriginalE of
-    #{prematch_vars := {#{Var := _}, _}} -> true;
-    _ -> is_var(Var, E) andalso not is_var(Var, OriginalE)
+is_valid_spec_arg_var(Var, S, OriginalS, #{context := match}) ->
+  case S#elixir_ex.prematch of
+    {#{Var := _}, _} -> true;
+    _ -> is_var(Var, S) andalso not is_var(Var, OriginalS)
   end;
-is_valid_spec_arg_var(_Var, _E, _OriginalE) ->
+is_valid_spec_arg_var(_Var, _S, _OriginalS, _E) ->
   true.
 
-is_var(Var, #{current_vars := {Read, _}}) ->
+is_var(Var, #elixir_ex{vars={Read, _}}) ->
   maps:is_key(Var, Read).
 
 validate_size_required(Meta, true, default, Type, default, E) when Type == binary; Type == bitstring ->
@@ -336,7 +340,7 @@ number_size(Size, default) when is_integer(Size) -> Size;
 number_size(Size, Unit) when is_integer(Size) -> Size * Unit;
 number_size(Size, _) -> Size.
 
-%% TODO: Simplify when we require OTP 24
+%% TODO: Simplify when we require Erlang/OTP 24
 valid_float_size(16) -> erlang:system_info(otp_release) >= "24";
 valid_float_size(32) -> true;
 valid_float_size(64) -> true;

lib/elixir/src/elixir_bootstrap.erl

@@ -19,7 +19,7 @@
 'MACRO-defmacrop'(Caller, Call, Expr) -> define(Caller, defmacrop, Call, Expr).
 
 'MACRO-defmodule'(_Caller, Alias, [{do, Block}]) ->
-  Escaped = elixir_quote:escape(Block, default, false),
+  Escaped = elixir_quote:escape(Block, none, false),
   Args = [Alias, Escaped, [], env()],
   {{'.', [], [elixir_module, compile]}, [], Args}.
 
@@ -35,11 +35,11 @@
    {defmodule, 2},
    {defp, 2}].
 
-define({Line, E}, Kind, Call, Expr) ->
+define({Line, _S, E}, Kind, Call, Expr) ->
   UC = elixir_quote:has_unquotes(Call),
   UE = elixir_quote:has_unquotes(Expr),
-  EscapedCall = elixir_quote:escape(Call, default, true),
-  EscapedExpr = elixir_quote:escape(Expr, default, true),
+  EscapedCall = elixir_quote:escape(Call, none, true),
+  EscapedExpr = elixir_quote:escape(Expr, none, true),
   Args = [Kind, not(UC or UE), EscapedCall, EscapedExpr, elixir_locals:cache_env(E#{line := Line})],
   {{'.', [], [elixir_def, store_definition]}, [], Args}.
 

lib/elixir/src/elixir_clauses.erl

@@ -1,79 +1,75 @@
 %% Handle code related to args, guard and -> matching for case,
 %% fn, receive and friends. try is handled in elixir_try.
 -module(elixir_clauses).
--export([match/4, clause/5, def/2, head/2, head/3,
-         'case'/3, 'receive'/3, 'try'/3, 'cond'/3, with/3,
+-export([match/5, clause/6, def/3, head/3,
+         'case'/4, 'receive'/4, 'try'/4, 'cond'/4, with/4,
          format_error/1]).
 -import(elixir_errors, [form_error/4, form_warn/4]).
 -include("elixir.hrl").
 
-match(Fun, Expr, E, #{context := match}) ->
-  Fun(Expr, E);
-match(Fun, Expr, #{current_vars := Current, unused_vars := {_, Counter} = Unused} = AfterE, BeforeE) ->
-  #{
-    context := Context,
-    prematch_vars := Prematch,
-    current_vars := {Read, _}
-  } = BeforeE,
+match(Fun, Expr, AfterS, _BeforeS, #{context := match} = E) ->
+  Fun(Expr, AfterS, E);
+match(Fun, Expr, AfterS, BeforeS, E) ->
+  #elixir_ex{vars=Current, unused={_, Counter} = Unused} = AfterS,
+  #elixir_ex{vars={Read, _}, prematch=Prematch} = BeforeS,
 
-  CallE = BeforeE#{
-    context := match,
-    prematch_vars := {Read, Counter},
-    current_vars := Current,
-    unused_vars := Unused
+  CallS = BeforeS#elixir_ex{
+    prematch={Read, Counter},
+    unused=Unused,
+    vars=Current
   },
 
-  {EExpr, #{current_vars := NewCurrent, unused_vars := NewUnused}} = Fun(Expr, CallE),
+  CallE = E#{context := match},
+  {EExpr, #elixir_ex{vars=NewCurrent, unused=NewUnused}, EE} = Fun(Expr, CallS, CallE),
 
-  EndE = AfterE#{
-    context := Context,
-    prematch_vars := Prematch,
-    current_vars := NewCurrent,
-    unused_vars := NewUnused
+  EndS = AfterS#elixir_ex{
+    prematch=Prematch,
+    unused=NewUnused,
+    vars=NewCurrent
   },
 
-  {EExpr, EndE}.
+  EndE = EE#{context := ?key(E, context)},
+  {EExpr, EndS, EndE}.
 
-def({Meta, Args, Guards, Body}, E) ->
-  {EArgs, EA}   = elixir_expand:expand_args(Args, E#{context := match, prematch_vars := {#{}, 0}}),
-  {EGuards, EG} = guard(Guards, EA#{context := guard, prematch_vars := warn}),
-  {EBody, EB}   = elixir_expand:expand(Body, EG#{context := nil}),
-  elixir_env:check_unused_vars(EB),
+def({Meta, Args, Guards, Body}, S, E) ->
+  {EArgs, SA, EA} = elixir_expand:expand_args(Args, S#elixir_ex{prematch={#{}, 0}}, E#{context := match}),
+  {EGuards, SG, EG} = guard(Guards, SA#elixir_ex{prematch=warn}, EA#{context := guard}),
+  {EBody, SB, EB} = elixir_expand:expand(Body, SG, EG#{context := nil}),
+  elixir_env:check_unused_vars(SB, EB),
   {Meta, EArgs, EGuards, EBody}.
 
-clause(Meta, Kind, Fun, {'->', ClauseMeta, [_, _]} = Clause, E) when is_function(Fun, 3) ->
-  clause(Meta, Kind, fun(X, Acc) -> Fun(ClauseMeta, X, Acc) end, Clause, E);
-clause(_Meta, _Kind, Fun, {'->', Meta, [Left, Right]}, E) ->
-  {ELeft, EL}  = Fun(Left, E),
-  {ERight, ER} = elixir_expand:expand(Right, EL),
-  {{'->', Meta, [ELeft, ERight]}, ER};
-clause(Meta, Kind, _Fun, _, E) ->
+clause(Meta, Kind, Fun, {'->', ClauseMeta, [_, _]} = Clause, S, E) when is_function(Fun, 4) ->
+  clause(Meta, Kind, fun(X, SA, EA) -> Fun(ClauseMeta, X, SA, EA) end, Clause, S, E);
+clause(_Meta, _Kind, Fun, {'->', Meta, [Left, Right]}, S, E) ->
+  {ELeft, SL, EL}  = Fun(Left, S, E),
+  {ERight, SR, ER} = elixir_expand:expand(Right, SL, EL),
+  {{'->', Meta, [ELeft, ERight]}, SR, ER};
+clause(Meta, Kind, _Fun, _, _, E) ->
   form_error(Meta, E, ?MODULE, {bad_or_missing_clauses, Kind}).
 
-head(Args, E) ->
-  head(Args, E, E).
-head([{'when', Meta, [_ | _] = All}], AfterE, BeforeE) ->
+head([{'when', Meta, [_ | _] = All}], S, E) ->
   {Args, Guard} = elixir_utils:split_last(All),
+  Prematch = S#elixir_ex.prematch,
 
-  {{EArgs, EGuard}, EG} =
-    match(fun(ok, EM) ->
-      {EArgs, EA} = elixir_expand:expand_args(Args, EM),
-      {EGuard, EG} = guard(Guard, EA#{context := guard, prematch_vars := ?key(BeforeE, prematch_vars)}),
-      {{EArgs, EGuard}, EG}
-    end, ok, AfterE, BeforeE),
+  {{EArgs, EGuard}, SG, EG} =
+    match(fun(ok, SM, EM) ->
+      {EArgs, SA, EA} = elixir_expand:expand_args(Args, SM, EM),
+      {EGuard, SG, EG} = guard(Guard, SA#elixir_ex{prematch=Prematch}, EA#{context := guard}),
+      {{EArgs, EGuard}, SG, EG}
+    end, ok, S, S, E),
 
-  {[{'when', Meta, EArgs ++ [EGuard]}], EG};
-head(Args, AfterE, BeforeE) ->
-  match(fun elixir_expand:expand_args/2, Args, AfterE, BeforeE).
+  {[{'when', Meta, EArgs ++ [EGuard]}], SG, EG};
+head(Args, S, E) ->
+  match(fun elixir_expand:expand_args/3, Args, S, S, E).
 
-guard({'when', Meta, [Left, Right]}, E) ->
-  {ELeft, EL}  = guard(Left, E),
-  {ERight, ER} = guard(Right, EL),
-  {{'when', Meta, [ELeft, ERight]}, ER};
-guard(Guard, E) ->
-  {EGuard, EG} = elixir_expand:expand(Guard, E),
+guard({'when', Meta, [Left, Right]}, S, E) ->
+  {ELeft, SL, EL}  = guard(Left, S, E),
+  {ERight, SR, ER} = guard(Right, SL, EL),
+  {{'when', Meta, [ELeft, ERight]}, SR, ER};
+guard(Guard, S, E) ->
+  {EGuard, SG, EG} = elixir_expand:expand(Guard, S, E),
   warn_zero_length_guard(EGuard, EG),
-  {EGuard, EG}.
+  {EGuard, SG, EG}.
 
 warn_zero_length_guard({{'.', _, [erlang, Op]}, Meta,
                         [{{'.', _, [erlang, length]}, _, [Arg]}, 0]}, E) when Op == '=='; Op == '>' ->
@@ -91,70 +87,73 @@ warn_zero_length_guard(_, _) ->
 
 %% Case
 
-'case'(Meta, [], E) ->
+'case'(Meta, [], _S, E) ->
   form_error(Meta, E, elixir_expand, {missing_option, 'case', [do]});
-'case'(Meta, Opts, E) when not is_list(Opts) ->
+'case'(Meta, Opts, _S, E) when not is_list(Opts) ->
   form_error(Meta, E, elixir_expand, {invalid_args, 'case'});
-'case'(Meta, Opts, E) ->
+'case'(Meta, Opts, S, E) ->
   ok = assert_at_most_once('do', Opts, 0, fun(Key) ->
     form_error(Meta, E, ?MODULE, {duplicated_clauses, 'case', Key})
   end),
-  lists:mapfoldl(fun(X, Acc) -> expand_case(Meta, X, Acc) end, E, Opts).
+  {Case, SA} = lists:mapfoldl(fun(X, SA) -> expand_case(Meta, X, SA, E) end, S, Opts),
+  {Case, SA, E}.
 
-expand_case(Meta, {'do', _} = Do, E) ->
+expand_case(Meta, {'do', _} = Do, S, E) ->
   Fun = expand_head(Meta, 'case', 'do'),
-  expand_clauses(Meta, 'case', Fun, Do, E);
-expand_case(Meta, {Key, _}, E) ->
+  expand_clauses(Meta, 'case', Fun, Do, S, E);
+expand_case(Meta, {Key, _}, _S, E) ->
   form_error(Meta, E, ?MODULE, {unexpected_option, 'case', Key}).
 
 %% Cond
 
-'cond'(Meta, [], E) ->
+'cond'(Meta, [], _S, E) ->
   form_error(Meta, E, elixir_expand, {missing_option, 'cond', [do]});
-'cond'(Meta, Opts, E) when not is_list(Opts) ->
+'cond'(Meta, Opts, _S, E) when not is_list(Opts) ->
   form_error(Meta, E, elixir_expand, {invalid_args, 'cond'});
-'cond'(Meta, Opts, E) ->
+'cond'(Meta, Opts, S, E) ->
   ok = assert_at_most_once('do', Opts, 0, fun(Key) ->
     form_error(Meta, E, ?MODULE, {duplicated_clauses, 'cond', Key})
   end),
-  lists:mapfoldl(fun(X, Acc) -> expand_cond(Meta, X, Acc) end, E, Opts).
+  {Cond, SA} = lists:mapfoldl(fun(X, SA) -> expand_cond(Meta, X, SA, E) end, S, Opts),
+  {Cond, SA, E}.
 
-expand_cond(Meta, {'do', _} = Do, E) ->
-  Fun = expand_one(Meta, 'cond', 'do', fun elixir_expand:expand_args/2),
-  expand_clauses(Meta, 'cond', Fun, Do, E);
-expand_cond(Meta, {Key, _}, E) ->
+expand_cond(Meta, {'do', _} = Do, S, E) ->
+  Fun = expand_one(Meta, 'cond', 'do', fun elixir_expand:expand_args/3),
+  expand_clauses(Meta, 'cond', Fun, Do, S, E);
+expand_cond(Meta, {Key, _}, _S, E) ->
   form_error(Meta, E, ?MODULE, {unexpected_option, 'cond', Key}).
 
 %% Receive
 
-'receive'(Meta, [], E) ->
+'receive'(Meta, [], _S, E) ->
   form_error(Meta, E, elixir_expand, {missing_option, 'receive', [do, 'after']});
-'receive'(Meta, Opts, E) when not is_list(Opts) ->
+'receive'(Meta, Opts, _S, E) when not is_list(Opts) ->
   form_error(Meta, E, elixir_expand, {invalid_args, 'receive'});
-'receive'(Meta, Opts, E) ->
+'receive'(Meta, Opts, S, E) ->
   RaiseError = fun(Key) ->
     form_error(Meta, E, ?MODULE, {duplicated_clauses, 'receive', Key})
   end,
   ok = assert_at_most_once('do', Opts, 0, RaiseError),
   ok = assert_at_most_once('after', Opts, 0, RaiseError),
-  lists:mapfoldl(fun(X, Acc) -> expand_receive(Meta, X, Acc) end, E, Opts).
+  {Receive, SA} = lists:mapfoldl(fun(X, SA) -> expand_receive(Meta, X, SA, E) end, S, Opts),
+  {Receive, SA, E}.
 
-expand_receive(_Meta, {'do', {'__block__', _, []}} = Do, E) ->
-  {Do, E};
-expand_receive(Meta, {'do', _} = Do, E) ->
+expand_receive(_Meta, {'do', {'__block__', _, []}} = Do, S, _E) ->
+  {Do, S};
+expand_receive(Meta, {'do', _} = Do, S, E) ->
   Fun = expand_head(Meta, 'receive', 'do'),
-  expand_clauses(Meta, 'receive', Fun, Do, E);
-expand_receive(Meta, {'after', [_]} = After, E) ->
-  Fun = expand_one(Meta, 'receive', 'after', fun elixir_expand:expand_args/2),
-  expand_clauses(Meta, 'receive', Fun, After, E);
-expand_receive(Meta, {'after', _}, E) ->
+  expand_clauses(Meta, 'receive', Fun, Do, S, E);
+expand_receive(Meta, {'after', [_]} = After, S, E) ->
+  Fun = expand_one(Meta, 'receive', 'after', fun elixir_expand:expand_args/3),
+  expand_clauses(Meta, 'receive', Fun, After, S, E);
+expand_receive(Meta, {'after', _}, _S, E) ->
   form_error(Meta, E, ?MODULE, multiple_after_clauses_in_receive);
-expand_receive(Meta, {Key, _}, E) ->
+expand_receive(Meta, {Key, _}, _S, E) ->
   form_error(Meta, E, ?MODULE, {unexpected_option, 'receive', Key}).
 
 %% With
 
-with(Meta, Args, E) ->
+with(Meta, Args, S, E) ->
   {Exprs, Opts0} =
     case elixir_utils:split_last(Args) of
       {_, LastArg} = SplitResult when is_list(LastArg) ->
@@ -163,10 +162,10 @@ with(Meta, Args, E) ->
         {Args, []}
     end,
 
-  E0 = elixir_env:reset_unused_vars(E),
-  {EExprs, {E1, HasMatch}} = lists:mapfoldl(fun expand_with/2, {E0, false}, Exprs),
-  {EDo, Opts1, E2} = expand_with_do(Meta, Opts0, E, E1),
-  {EOpts, Opts2, E3} = expand_with_else(Meta, Opts1, E2, HasMatch),
+  S0 = elixir_env:reset_unused_vars(S),
+  {EExprs, {S1, E1, HasMatch}} = lists:mapfoldl(fun expand_with/2, {S0, E, false}, Exprs),
+  {EDo, Opts1, S2} = expand_with_do(Meta, Opts0, S, S1, E1),
+  {EOpts, Opts2, S3} = expand_with_else(Meta, Opts1, S2, E, HasMatch),
 
   case Opts2 of
     [{Key, _} | _] ->
@@ -175,28 +174,27 @@ with(Meta, Args, E) ->
       ok
   end,
 
-  {{with, Meta, EExprs ++ [[{do, EDo} | EOpts]]}, E3}.
+  {{with, Meta, EExprs ++ [[{do, EDo} | EOpts]]}, S3, E}.
 
-expand_with({'<-', Meta, [{Name, _, Ctx}, _] = Args}, Acc) when is_atom(Name), is_atom(Ctx) ->
-  expand_with({'=', Meta, Args}, Acc);
-expand_with({'<-', Meta, [Left, Right]}, {E, _HasMatch}) ->
-  {ERight, ER} = elixir_expand:expand(Right, E),
-  {[ELeft], EL}  = head([Left], ER, E),
-  {{'<-', Meta, [ELeft, ERight]}, {EL, true}};
-expand_with(Expr, {E, HasMatch}) ->
-  {EExpr, EE} = elixir_expand:expand(Expr, E),
-  {EExpr, {EE, HasMatch}}.
+expand_with({'<-', Meta, [Left, Right]}, {S, E, _HasMatch}) ->
+  {ERight, SR, ER} = elixir_expand:expand(Right, S, E),
+  SM = elixir_env:reset_read(SR, S),
+  {[ELeft], SL, EL} = head([Left], SM, ER),
+  {{'<-', Meta, [ELeft, ERight]}, {SL, EL, true}};
+expand_with(Expr, {S, E, HasMatch}) ->
+  {EExpr, SE, EE} = elixir_expand:expand(Expr, S, E),
+  {EExpr, {SE, EE, HasMatch}}.
 
-expand_with_do(Meta, Opts, E, Acc) ->
+expand_with_do(Meta, Opts, S, Acc, E) ->
   case lists:keytake(do, 1, Opts) of
     {value, {do, Expr}, RestOpts} ->
-      {EExpr, EAcc} = elixir_expand:expand(Expr, Acc),
-      {EExpr, RestOpts, elixir_env:merge_and_check_unused_vars(E, EAcc)};
+      {EExpr, SAcc, EAcc} = elixir_expand:expand(Expr, Acc, E),
+      {EExpr, RestOpts, elixir_env:merge_and_check_unused_vars(SAcc, S, EAcc)};
     false ->
       form_error(Meta, E, elixir_expand, {missing_option, 'with', [do]})
   end.
 
-expand_with_else(Meta, Opts, E, HasMatch) ->
+expand_with_else(Meta, Opts, S, E, HasMatch) ->
   case lists:keytake(else, 1, Opts) of
     {value, Pair, RestOpts} ->
       if
@@ -204,21 +202,21 @@ expand_with_else(Meta, Opts, E, HasMatch) ->
         true -> form_warn(Meta, ?key(E, file), ?MODULE, unmatchable_else_in_with)
       end,
       Fun = expand_head(Meta, 'with', 'else'),
-      {EPair, EE} = expand_clauses(Meta, 'with', Fun, Pair, E),
-      {[EPair], RestOpts, EE};
+      {EPair, SE} = expand_clauses(Meta, 'with', Fun, Pair, S, E),
+      {[EPair], RestOpts, SE};
     false ->
-      {[], Opts, E}
+      {[], Opts, S}
   end.
 
 %% Try
 
-'try'(Meta, [], E) ->
+'try'(Meta, [], _S, E) ->
   form_error(Meta, E, elixir_expand, {missing_option, 'try', [do]});
-'try'(Meta, [{do, _}], E) ->
+'try'(Meta, [{do, _}], _S, E) ->
   form_error(Meta, E, elixir_expand, {missing_option, 'try', ['catch', 'rescue', 'after']});
-'try'(Meta, Opts, E) when not is_list(Opts) ->
+'try'(Meta, Opts, _S, E) when not is_list(Opts) ->
   form_error(Meta, E, elixir_expand, {invalid_args, 'try'});
-'try'(Meta, Opts, E) ->
+'try'(Meta, Opts, S, E) ->
   % TODO: Make this an error on v2.0
   case Opts of
     [{do, _}, {else, _}] ->
@@ -235,76 +233,77 @@ expand_with_else(Meta, Opts, E, HasMatch) ->
   ok = assert_at_most_once('else', Opts, 0, RaiseError),
   ok = assert_at_most_once('after', Opts, 0, RaiseError),
   ok = warn_catch_before_rescue(Opts, Meta, E, false),
-  lists:mapfoldl(fun(X, Acc) -> expand_try(Meta, X, Acc) end, E, Opts).
+  {Try, SA} = lists:mapfoldl(fun(X, SA) -> expand_try(Meta, X, SA, E) end, S, Opts),
+  {Try, SA, E}.
 
-expand_try(_Meta, {'do', Expr}, E) ->
-  {EExpr, EE} = elixir_expand:expand(Expr, elixir_env:reset_unused_vars(E)),
-  {{'do', EExpr}, elixir_env:merge_and_check_unused_vars(E, EE)};
-expand_try(_Meta, {'after', Expr}, E) ->
-  {EExpr, EE} = elixir_expand:expand(Expr, elixir_env:reset_unused_vars(E)),
-  {{'after', EExpr}, elixir_env:merge_and_check_unused_vars(E, EE)};
-expand_try(Meta, {'else', _} = Else, E) ->
+expand_try(_Meta, {'do', Expr}, S, E) ->
+  {EExpr, SE, EE} = elixir_expand:expand(Expr, elixir_env:reset_unused_vars(S), E),
+  {{'do', EExpr}, elixir_env:merge_and_check_unused_vars(SE, S, EE)};
+expand_try(_Meta, {'after', Expr}, S, E) ->
+  {EExpr, SE, EE} = elixir_expand:expand(Expr, elixir_env:reset_unused_vars(S), E),
+  {{'after', EExpr}, elixir_env:merge_and_check_unused_vars(SE, S, EE)};
+expand_try(Meta, {'else', _} = Else, S, E) ->
   Fun = expand_head(Meta, 'try', 'else'),
-  expand_clauses(Meta, 'try', Fun, Else, E);
-expand_try(Meta, {'catch', _} = Catch, E) ->
-  expand_clauses_with_stacktrace(Meta, fun expand_catch/3, Catch, E);
-expand_try(Meta, {'rescue', _} = Rescue, E) ->
-  expand_clauses_with_stacktrace(Meta, fun expand_rescue/3, Rescue, E);
-expand_try(Meta, {Key, _}, E) ->
+  expand_clauses(Meta, 'try', Fun, Else, S, E);
+expand_try(Meta, {'catch', _} = Catch, S, E) ->
+  expand_clauses_with_stacktrace(Meta, fun expand_catch/4, Catch, S, E);
+expand_try(Meta, {'rescue', _} = Rescue, S, E) ->
+  expand_clauses_with_stacktrace(Meta, fun expand_rescue/4, Rescue, S, E);
+expand_try(Meta, {Key, _}, _S, E) ->
   form_error(Meta, E, ?MODULE, {unexpected_option, 'try', Key}).
 
-expand_clauses_with_stacktrace(Meta, Fun, Clauses, E) ->
-  OldContextualVars = ?key(E, contextual_vars),
-  ES = E#{contextual_vars := ['__STACKTRACE__' | OldContextualVars]},
-  {Ret, EE} = expand_clauses(Meta, 'try', Fun, Clauses, ES),
-  {Ret, EE#{contextual_vars := OldContextualVars}}.
+expand_clauses_with_stacktrace(Meta, Fun, Clauses, S, E) ->
+  OldStacktrace = S#elixir_ex.stacktrace,
+  SS = S#elixir_ex{stacktrace=true},
+  {Ret, SE} = expand_clauses(Meta, 'try', Fun, Clauses, SS, E),
+  {Ret, SE#elixir_ex{stacktrace=OldStacktrace}}.
 
-expand_catch(_Meta, [_] = Args, E) ->
-  head(Args, E);
-expand_catch(_Meta, [_, _] = Args, E) ->
-  head(Args, E);
-expand_catch(Meta, _, E) ->
+expand_catch(_Meta, [_] = Args, S, E) ->
+  head(Args, S, E);
+expand_catch(_Meta, [_, _] = Args, S, E) ->
+  head(Args, S, E);
+expand_catch(Meta, _, _, E) ->
   Error = {wrong_number_of_args_for_clause, "one or two args", origin(Meta, 'try'), 'catch'},
   form_error(Meta, E, ?MODULE, Error).
 
-expand_rescue(Meta, [Arg], E) ->
-  case expand_rescue(Arg, E) of
-    {EArg, EA} ->
-      {[EArg], EA};
+expand_rescue(Meta, [Arg], S, E) ->
+  case expand_rescue(Arg, S, E) of
+    {EArg, SA, EA} ->
+      {[EArg], SA, EA};
     false ->
       form_error(Meta, E, ?MODULE, invalid_rescue_clause)
   end;
-expand_rescue(Meta, _, E) ->
+expand_rescue(Meta, _, _, E) ->
   Error = {wrong_number_of_args_for_clause, "one argument", origin(Meta, 'try'), 'rescue'},
   form_error(Meta, E, ?MODULE, Error).
 
 %% rescue var
-expand_rescue({Name, _, Atom} = Var, E) when is_atom(Name), is_atom(Atom) ->
-  match(fun elixir_expand:expand/2, Var, E, E);
+expand_rescue({Name, _, Atom} = Var, S, E) when is_atom(Name), is_atom(Atom) ->
+  match(fun elixir_expand:expand/3, Var, S, S, E);
 
 %% rescue var in _ => rescue var
-expand_rescue({in, _, [{Name, _, VarContext} = Var, {'_', _, UnderscoreContext}]}, E)
+expand_rescue({in, _, [{Name, _, VarContext} = Var, {'_', _, UnderscoreContext}]}, S, E)
     when is_atom(Name), is_atom(VarContext), is_atom(UnderscoreContext) ->
-  expand_rescue(Var, E);
+  expand_rescue(Var, S, E);
 
 %% rescue var in [Exprs]
-expand_rescue({in, Meta, [Left, Right]}, E) ->
-  {ELeft, EL}  = match(fun elixir_expand:expand/2, Left, E, E),
-  {ERight, ER} = elixir_expand:expand(Right, EL),
+expand_rescue({in, Meta, [Left, Right]}, S, E) ->
+  {ELeft, SL, EL}  = match(fun elixir_expand:expand/3, Left, S, S, E),
+  {ERight, SR, ER} = elixir_expand:expand(Right, SL, EL),
 
   case ELeft of
     {Name, _, Atom} when is_atom(Name), is_atom(Atom) ->
       case normalize_rescue(ERight) of
         false -> false;
-        Other -> {{in, Meta, [ELeft, Other]}, ER}
+        Other -> {{in, Meta, [ELeft, Other]}, SR, ER}
       end;
     _ ->
       false
   end;
 
 %% rescue Error => _ in [Error]
-expand_rescue(Arg, E) ->
-  expand_rescue({in, [], [{'_', [], ?key(E, module)}, Arg]}, E).
+expand_rescue(Arg, S, E) ->
+  expand_rescue({in, [], [{'_', [], ?key(E, module)}, Arg]}, S, E).
 
 normalize_rescue({'_', _, Atom} = N) when is_atom(Atom) -> N;
 normalize_rescue(Atom) when is_atom(Atom) -> [Atom];
@@ -315,11 +314,11 @@ normalize_rescue(Other) ->
 
 expand_head(Meta, Kind, Key) ->
   fun
-    ([{'when', _, [_, _, _ | _]}], E) ->
+    ([{'when', _, [_, _, _ | _]}], _, E) ->
       form_error(Meta, E, ?MODULE, {wrong_number_of_args_for_clause, "one argument", Kind, Key});
-    ([_] = Args, E) ->
-      head(Args, E);
-    (_, E) ->
+    ([_] = Args, S, E) ->
+      head(Args, S, E);
+    (_, _, E) ->
       form_error(Meta, E, ?MODULE, {wrong_number_of_args_for_clause, "one argument", Kind, Key})
   end.
 
@@ -327,25 +326,27 @@ expand_head(Meta, Kind, Key) ->
 %% considering we have at maximum one entry.
 expand_one(Meta, Kind, Key, Fun) ->
   fun
-    ([_] = Args, E) ->
-      Fun(Args, E);
-    (_, E) ->
+    ([_] = Args, S, E) ->
+      Fun(Args, S, E);
+    (_, _, E) ->
       form_error(Meta, E, ?MODULE, {wrong_number_of_args_for_clause, "one argument", Kind, Key})
   end.
 
 %% Expands all -> pairs in a given key but do not keep the overall vars.
-expand_clauses(Meta, Kind, Fun, Clauses, E) ->
+expand_clauses(Meta, Kind, Fun, Clauses, S, E) ->
   NewKind = origin(Meta, Kind),
-  expand_clauses_origin(Meta, NewKind, Fun, Clauses, E).
+  expand_clauses_origin(Meta, NewKind, Fun, Clauses, S, E).
 
-expand_clauses_origin(Meta, Kind, Fun, {Key, [_ | _] = Clauses}, E) ->
-  Transformer = fun(Clause, Acc) ->
-    {EClause, EAcc} = clause(Meta, {Kind, Key}, Fun, Clause, elixir_env:reset_unused_vars(Acc)),
-    {EClause, elixir_env:merge_and_check_unused_vars(Acc, EAcc)}
+expand_clauses_origin(Meta, Kind, Fun, {Key, [_ | _] = Clauses}, S, E) ->
+  Transformer = fun(Clause, SA) ->
+    {EClause, SAcc, EAcc} =
+      clause(Meta, {Kind, Key}, Fun, Clause, elixir_env:reset_unused_vars(SA), E),
+
+    {EClause, elixir_env:merge_and_check_unused_vars(SAcc, SA, EAcc)}
   end,
-  {Values, EE} = lists:mapfoldl(Transformer, E, Clauses),
-  {{Key, Values}, EE};
-expand_clauses_origin(Meta, Kind, _Fun, {Key, _}, E) ->
+  {Values, SE} = lists:mapfoldl(Transformer, S, Clauses),
+  {{Key, Values}, SE};
+expand_clauses_origin(Meta, Kind, _Fun, {Key, _}, _, E) ->
   form_error(Meta, E, ?MODULE, {bad_or_missing_clauses, {Kind, Key}}).
 
 assert_at_most_once(_Kind, [], _Count, _Fun) -> ok;

lib/elixir/src/elixir_compiler.erl

@@ -41,27 +41,25 @@ file_to_path(File, Dest, Callback) when is_binary(File), is_binary(Dest) ->
 %% more efficient strategy depending on the code snippet.
 
 eval_forms(Forms, Args, E) ->
-  case (?key(E, module) == nil) andalso allows_fast_compilation(Forms) of
-    true  ->
-      {Result, _Binding, EE} = elixir:eval_forms(Forms, [], E),
-      {Result, EE};
-    false ->
-      compile(Forms, Args, E)
+  case (?key(E, module) == nil) andalso allows_fast_compilation(Forms) andalso
+        (not elixir_config:is_bootstrap()) of
+    true  -> fast_compile(Forms, E);
+    false -> compile(Forms, Args, E)
   end.
 
 compile(Quoted, ArgsList, E) ->
-  Args = list_to_tuple(ArgsList),
-  {Expanded, EE} = elixir_expand:expand(Quoted, E),
-  elixir_env:check_unused_vars(EE),
+  {Expanded, SE, EE} = elixir_expand:expand(Quoted, elixir_env:env_to_ex(E), E),
+  elixir_env:check_unused_vars(SE, EE),
 
   {Module, Fun, Purgeable} =
-    elixir_erl_compiler:spawn(fun spawned_compile/2, [Expanded, E]),
+    elixir_erl_compiler:spawn(fun() -> spawned_compile(Expanded, E) end),
 
+  Args = list_to_tuple(ArgsList),
   {dispatch(Module, Fun, Args, Purgeable), EE}.
 
 spawned_compile(ExExprs, #{line := Line, file := File} = E) ->
-  {Vars, S} = elixir_env:env_to_scope(E),
-  {ErlExprs, _} = elixir_erl_pass:translate(ExExprs, S),
+  {Vars, S} = elixir_env:env_to_erl(E),
+  {ErlExprs, _} = elixir_erl_pass:translate(ExExprs, erl_anno:new(Line), S),
 
   Module = retrieve_compiler_module(),
   Fun  = code_fun(?key(E, module)),
@@ -108,16 +106,41 @@ is_purgeable(Module, Binary) ->
 
 allows_fast_compilation({'__block__', _, Exprs}) ->
   lists:all(fun allows_fast_compilation/1, Exprs);
-allows_fast_compilation({defmodule, _, _}) ->
+allows_fast_compilation({defmodule, _, [_, [{do, _}]]}) ->
   true;
 allows_fast_compilation(_) ->
   false.
 
+fast_compile({'__block__', _, Exprs}, E) ->
+  lists:foldl(fun(Expr, _) -> fast_compile(Expr, E) end, nil, Exprs);
+fast_compile({defmodule, Meta, [Mod, [{do, TailBlock}]]}, NoLineE) ->
+  E = NoLineE#{line := ?line(Meta)},
+
+  Block = {'__block__', Meta, [
+    {'=', Meta, [{result, Meta, ?MODULE}, TailBlock]},
+    {{'.', Meta, [elixir_utils, noop]}, Meta, []},
+    {result, Meta, ?MODULE}
+  ]},
+
+  Expanded = case Mod of
+    {'__aliases__', _, _} ->
+      case elixir_aliases:expand_or_concat(Mod, E) of
+        Receiver when is_atom(Receiver) -> Receiver;
+        _ -> 'Elixir.Macro':expand(Mod, E)
+      end;
+
+    _ ->
+      'Elixir.Macro':expand(Mod, E)
+  end,
+
+  ContextModules = [Expanded | ?key(E, context_modules)],
+  elixir_module:compile(Expanded, Block, [], E#{context_modules := ContextModules}).
+
 %% Bootstrapper
 
 bootstrap() ->
   {ok, _} = application:ensure_all_started(elixir),
-  elixir_config:put(bootstrap, true),
+  elixir_config:static(#{bootstrap => true}),
   elixir_config:put(docs, false),
   elixir_config:put(relative_paths, false),
   elixir_config:put(ignore_module_conflict, true),
@@ -125,7 +148,6 @@ bootstrap() ->
   elixir_config:put(parser_options, []),
   {Init, Main} = bootstrap_files(),
   [bootstrap_file(File) || File <- [<<"lib/elixir/lib/kernel.ex">> | Init]],
-  elixir_config:put(bootstrap, true),
   elixir_config:put(docs, true),
   [bootstrap_file(File) || File <- [<<"lib/elixir/lib/kernel.ex">> | Main]].
 
@@ -179,6 +201,8 @@ bootstrap_files() ->
      <<"lib/elixir/lib/access.ex">>,
      <<"lib/elixir/lib/io.ex">>,
      <<"lib/elixir/lib/system.ex">>,
+     <<"lib/elixir/lib/code/formatter.ex">>,
+     <<"lib/elixir/lib/code/normalizer.ex">>,
      <<"lib/elixir/lib/kernel/cli.ex">>,
      <<"lib/elixir/lib/kernel/error_handler.ex">>,
      <<"lib/elixir/lib/kernel/parallel_compiler.ex">>,
@@ -186,7 +210,7 @@ bootstrap_files() ->
     ]
   }.
 
-binary_to_path({ModuleName, _ModuleMap, Binary}, CompilePath) ->
+binary_to_path({{ModuleName, Binary}, _Info}, CompilePath) ->
   Path = filename:join(CompilePath, atom_to_list(ModuleName) ++ ".beam"),
   case file:write_file(Path, Binary) of
     ok -> Path;