Release v1.6.3

The :timed_out message was not cancelled properly when compilation failed in ParallelCompiler. This meant the timeout message would be delivered even after compilation completed. This could be problematic when invoking compilation programmatically via e.g. Mix.Task.run("compile", ["--return-errors"]) since it means that the calling process, depending on the implemenation, might crash unexpectedly or get its inbox filled with messages.

The fix simply calls the cancel_waiting_timer when a compilation error has ocurred in the same way it is called in other similar cases.

Signed-off-by: José Valim <jose.valim@plataformatec.com.br>

.formatter.exs

@@ -12,6 +12,10 @@
     assert_same: 2,
 
     # Errors tests
-    assert_eval_raise: 3
+    assert_eval_raise: 3,
+
+    # Mix tests
+    in_fixture: 2,
+    in_tmp: 2
   ]
 ]

.travis.yml

@@ -1,39 +1,29 @@
-language: bash
+language: erlang
 sudo: false
 
-env:
-  global:
-    - ELIXIR_ASSERT_TIMEOUT=2000
-  matrix:
-    - OTP_RELEASE=OTP-19.0
-    - OTP_RELEASE=OTP-19.1
-    - OTP_RELEASE=OTP-19.2
-    - OTP_RELEASE=OTP-19.3
-    - OTP_RELEASE=OTP-20.0
-    - OTP_RELEASE=OTP-20.1
-    - OTP_RELEASE=OTP-20.2
-    - OTP_RELEASE=OTP-20.3
-    - OTP_RELEASE=OTP-21.0
-    - OTP_RELEASE=maint
-    - OTP_RELEASE=master
-
 matrix:
-  fast_finish: true
-  allow_failures:
-    - env: OTP_RELEASE=maint
-    - env: OTP_RELEASE=master
+  include:
+    - os: linux
+      otp_release: 19.0
+    - os: linux
+      otp_release: 19.1
+    - os: linux
+      otp_release: 19.2
+    - os: linux
+      otp_release: 19.3
+    - os: linux
+      otp_release: 20.0
+    - os: linux
+      otp_release: 20.1
 
-install:
-  - wget -O otp.tar.gz https://repo.hex.pm/builds/otp/ubuntu-14.04/${OTP_RELEASE}.tar.gz
-  - mkdir -p otp
-  - tar zxf otp.tar.gz -C otp --strip-components=1
-  - otp/Install -minimal $(pwd)/otp
-  - PATH=$(pwd)/otp/bin:$PATH
+env:
+  - ELIXIR_ASSERT_TIMEOUT=2000
 
 script:
   - make compile
   - rm -rf .git
   - make test
+  - bin/elixir bin/mix format --dry-run --check-formatted
   - dialyzer -pa lib/elixir/ebin --build_plt --output_plt elixir.plt --apps lib/elixir/ebin/elixir.beam lib/elixir/ebin/Elixir.Kernel.beam
 
 notifications:

CHANGELOG.md

@@ -1,310 +1,335 @@
-# Changelog for Elixir v1.7
+# Changelog for Elixir v1.6
 
-Elixir v1.7 is the last release to support Erlang/OTP 19. We recommend everyone to migrate to Erlang/OTP 20+.
+## Code formatter
 
-## Documentation metadata
+The big feature in Elixir v1.6 is the addition of a code formatter and an accompanying `mix format` task that adds automatic formatting to your projects.
 
-Elixir v1.7 implements [EEP 48](http://erlang.org/eep/eeps/eep-0048.html). EEP 48 aims to bring documentation interoperability across all languages running on the Erlang VM. The documentation format proposed by EEP 48 also supports metadata, which is now fully exposed to Elixir developers:
+The goal of the formatter is to automate the styling of codebases into a unique and consistent layout used across teams and the whole community. Code is now easier to write, as you no longer need to concern yourself with formatting rules. Code is also easier to read, as you no longer need to convert the styles of other developers in your mind.
 
-```elixir
-@moduledoc "A brand new module"
-@moduledoc authors: ["Jane", "Mary"], since: "1.4.0"
-```
+The formatter also helps new developers to learn the language, by giving immediate feedback on code structure, and eases code reviews by allowing teams to focus on business rules and code quality, rather than code style.
 
-Passing metadata is supported on `@doc`, `@moduledoc` and `@typedoc`.
+To automatically format your codebase, you can run the new `mix format` task. A `.formatter.exs` file may be added to your project root for rudimentary formatter configuration. The mix task also supports flags for CI integration. For instance, you can make your build or a Pull Request fail if the code is not formatted accordingly. We also recommend developers to check their favorite editor and see if they already provide key bindings for `mix format`, allowing a file or a code snippet to be formatted without ceremony.
 
-To access the new documentation format, developers should use `Code.fetch_docs/1`. The old documentation format is no longer available and the old `Code.get_docs/2` function will return `nil` accordingly.
+The Elixir codebase itself has been already fully formatted and all further contributions are expected to contain formatted code. We recommend existing codebases to be formatted in steps. While the formatter will correctly handle long lines and complex expressions, refactoring the code by breaking those into variables or smaller functions as you format them will lead to overall cleaner and more readable codebases.
 
-Tools like IEx and ExDoc have been updated to leverage the new format and show relevant metadata to users. While Elixir allows any metadata to be given, those tools currently exhibit only `:deprecated` and `:since`. Other keys may be shown in the future.
+## Dynamic Supervisor
 
-## The `__STACKTRACE__` construct
+Supervisors in Elixir are responsible for starting, shutting down and restarting child process when things go wrong. Most of the interaction with supervisors happen with the Supervisor module and it contains three main strategies: `:one_for_one`, `:rest_for_one` and `:one_for_all`.
 
-Erlang/OTP 21.0 introduces a new way to retrieve the stacktrace that is lexically scoped and no longer relies on side-effects like `System.stacktrace/0` does. Before one would write:
+However, sometimes the children of a supervisor are not known upfront and are rather started dynamically. For example, if you are building a web server, you have each request beind handled by a separate supervised process. Those cases were handled in the Supervisor module under a special strategy called `:simple_one_for_one`.
 
-```elixir
-try do
-  ... something that may fail ...
-rescue
-  e ->
-    log(e, System.stacktrace())
-    reraise(e, System.stacktrace())
-end
-```
+Unfortunately, this special strategy changed the semantics of the supervisor in regards to initialization and shutdown. Plus some APIs expected different inputs or would be completely unavailable depending on the supervision strategy.
 
-In Elixir v1.7, this can be written as:
+Elixir v1.6 addresses this issue by introducing a new `DynamicSupervisor` module, which encapsulates the old `:simple_one_for_one` strategy and APIs in a proper module while allowing the documentation and API of the `Supervisor` module to focus on its main use cases. Having a separate `DynamicSupervisor` module also makes it simpler to add new features to the dynamic supervisor, such as the new `:max_children` option that limits the maximum number of children supervised dynamically.
 
-```elixir
-try do
-  ... something that may fail ...
-rescue
-  e ->
-    log(e, __STACKTRACE__)
-    reraise(e, __STACKTRACE__)
-end
-```
+## `@deprecated` and `@since` attributes
 
-This change may also yield performance improvements in the future, since the lexical scope allows us to track precisely when a stacktrace is used and we no longer need to keep references to stacktrace entries after the `try` construct finishes.
+This release also introduces two new attributes associated to function definitions: `@deprecated` and `@since`. The former marks if a function or macro is deprecated, the latter annotates the version the API was introduced:
 
-Other parts of the exception system have been improved. For example, more information is provided in certain occurrences of `ArgumentError`, `ArithmeticError` and `KeyError` messages.
+    @doc "Breaks a collection into chunks"
+    @since "1.0.0"
+    @deprecated "Use chunk_every/2 instead"
+    def chunk(collection, chunk_size) do
+      chunk_every(collection, chunk_size)
+    end
 
-## Erlang/OTP logger integration
+The `mix xref` task was also updated to warn if your project calls deprecated code. So if a definition is marked as `@deprecated` and a module invokes it, a warning will be emitted during compilation. This effectively provides libraries and frameworks a mechanism to deprecate code without causing multiple warnings to be printed in runtime and without impacting performance.
 
-Erlang/OTP 21 includes a new `:logger` module. Elixir v1.7 fully integrates with the new `:logger` and leverages its metadata system. The `Logger.Translator` mechanism has also been improved to export metadata, allowing custom Logger backends to leverage information such as:
+Note those attributes are not yet available to tools that generate documentation. Such functionality will be added in future releases as it requires changes to how Elixir stores documentation in BEAM files. We still recommend developers to properly annotate their APIs, as the information will then be already available when the tooling is updated.
 
-  * `:crash_reason` - a two-element tuple with the throw/error/exit reason as first argument and the stacktrace as second
+## defguard and defguardp
 
-  * `:initial_call` - the initial call that started the process
+Elixir provides the concepts of guards: expressions used alongside pattern matching to select a matching clause. Let's see an example straight from Elixir's home page:
 
-  * `:registered_name` - the process registered name as an atom
+    def serve_drinks(%User{age: age}) when age >= 21 do
+      # Code that serves drinks!
+    end
 
-We recommend Elixir libraries that previously hooked into Erlang's `:error_logger` to hook into `Logger` instead, in order to support all current and future Erlang/OTP versions.
+`%User{age: age}` is matching on a `User` struct with an age field and `when age >= 21` is the guard.
 
-## Other Logger improvements
+Since only a handful of constructs are [allowed in guards](https://hexdocs.pm/elixir/guards.html#content), if you were in a situation where you had to check the age to be more than or equal to 21 in multiple times, extracting the guard to a separate function would be [less than obvious and error prone](https://github.com/elixir-lang/elixir/issues/2469). To address those issues, this release introduces `defguard/1` and `defguardp/1`:
 
-Previously, Logger macros such as `debug`, `info`, and so on would always evaluate their arguments, even when nothing would be logged. From Elixir v1.7, the arguments are only evaluated when the message is logged.
+    defguard is_drinking_age(age) when age >= 21
 
-The Logger configuration system also accepts a new option called `:compile_time_purge_matching` that allows you to remove log calls with specific compile-time metadata. For example, to remove all logger calls from application `:foo` with level lower than `:info`, as well as remove all logger calls from `Bar.foo/3`, you can use the following configuration:
+    def serve_drinks(%User{age: age}) when is_drinking_age(age) do
+      # Code that serves drinks!
+    end
 
-```elixir
-config :logger,
-  compile_time_purge_matching: [
-    [application: :foo, level_lower_than: :info],
-    [module: Bar, function: "foo/3"]
-  ]
-```
+## IEx improvements
 
-## ExUnit improvements
+IEx also got its share of improvements. The new code formatter allows us to pretty print code snippets, types and specifications, improving the overall experience when exploring code through the terminal.
 
-ExUnit has also seen its own share of improvements. Assertions such as `assert some_fun(arg1, arg2, arg3)` will now include the value of each argument in the failure report:
+The autocomplete mechanism also got smarter, being able to provide context autocompletion. For example, typing `t Enum.` and hitting TAB will autocomplete only the types in Enum (in contrast to all functions). Typing `b GenServer.` and hitting TAB will autocomplete only the behaviour callbacks.
 
-```
-  1) test function call arguments (TestOneOfEach)
-     lib/ex_unit/examples/one_of_each.exs:157
-     Expected truthy, got false
-     code: assert some_vars(1 + 2, 3 + 4)
-     arguments:
+Finally, the breakpoint functionality added in Elixir v1.5 has been improved to support pattern matching and guards. For example, to pattern match on a function call when the first argument is the atom `:foo`, you may do:
 
-         # 1
-         3
+    break! SomeFunction.call(:foo, _, _)
 
-         # 2
-         7
+## mix xref
 
-     stacktrace:
-       lib/ex_unit/examples/one_of_each.exs:158: (test)
-```
+`mix xref` is a task added in Elixir v1.3 which provides general information about how modules and files in an application depend on each other. This release brings many improvements to `xref`, extending the reach of the analysis and helping developers digest the vast amount of data it produces.
 
-Furthermore, failures in doctests are now colored and diffed.
+One of such additions is the `--include-siblings` option that can be given to all `xref` commands inside umbrella projects. For example, to find all of the callers of a given module or function in an umbrella:
 
-On the `mix test` side of things, there is a new `--failed` flag that runs all tests that failed the last time they ran. Finally, coverage reports generated with `mix test --cover` include a summary out of the box:
+    $ mix xref callers SomeModule --include-siblings
 
-```
-Generating cover results ...
+The `graph` command in `mix xref` now can also output general statistics about the graph. In [the hexpm project](https://github.com/hexpm/hexpm), you would get:
 
-Percentage | Module
------------|--------------------------
-   100.00% | Plug.Exception.Any
-   100.00% | Plug.Adapters.Cowboy2.Stream
-   100.00% | Collectable.Plug.Conn
-   100.00% | Plug.Crypto.KeyGenerator
-   100.00% | Plug.Parsers
-   100.00% | Plug.Head
-   100.00% | Plug.Router.Utils
-   100.00% | Plug.RequestId
-       ... | ...
------------|--------------------------
-    77.19% | Total
-```
+    $ mix xref graph --format stats
+    Tracked files: 129 (nodes)
+    Compile dependencies: 256 (edges)
+    Structs dependencies: 46 (edges)
+    Runtime dependencies: 266 (edges)
 
-## v1.7.4 (2018-10-24)
+    Top 10 files with most outgoing dependencies:
+      * test/support/factory.ex (18)
+      * lib/hexpm/accounts/user.ex (13)
+      * lib/hexpm/accounts/audit_log.ex (12)
+      * lib/hexpm/web/controllers/dashboard_controller.ex (12)
+      * lib/hexpm/repository/package.ex (12)
+      * lib/hexpm/repository/releases.ex (11)
+      * lib/hexpm/repository/release.ex (10)
+      * lib/hexpm/web/controllers/package_controller.ex (10)
+      * lib/mix/tasks/hexpm.stats.ex (9)
+      * lib/hexpm/repository/registry_builder.ex (9)
+
+    Top 10 files with most incoming dependencies:
+      * lib/hexpm/web/web.ex (84)
+      * lib/hexpm/web/router.ex (29)
+      * lib/hexpm/web/controllers/controller_helpers.ex (29)
+      * lib/hexpm/web/controllers/auth_helpers.ex (28)
+      * lib/hexpm/web/views/view_helpers.ex (27)
+      * lib/hexpm/web/views/icons.ex (27)
+      * lib/hexpm/web/endpoint.ex (23)
+      * lib/hexpm/ecto/changeset.ex (22)
+      * lib/hexpm/accounts/user.ex (19)
+      * lib/hexpm/repo.ex (19)
+
+`mix xref graph` also got the `--only-nodes` and `--label` options. The former asks Mix to only output file names (nodes) without the edges. The latter allows you to focus on certain relationships:
+
+      # To get all files that depend on lib/foo.ex
+      mix xref graph --sink lib/foo.ex --only-nodes
+
+      # To get all files that depend on lib/foo.ex at compile time
+      mix xref graph --label compile --sink lib/foo.ex --only-nodes
+
+      # To get all files lib/foo.ex depends on
+      mix xref graph --source lib/foo.ex --only-nodes
+
+      # To limit statistics only to compile time dependencies
+      mix xref graph --format stats --label compile
+
+Those improvements will help developers better understand the relationship between files and reveal potentially complex parts of their systems.
+
+Other improvements in Mix include better compiler diagnostics for editor integration, support for the `--slowest N` flag in `mix test` that shows the slowest tests in your suite, and a new `mix profile.eprof` task that provides time based profiling, complementing the existing `mix profile.cprof` (count based) and `mix profile.fprof` (flame based).
+
+## v1.6.3 (2018-03-09)
 
 ### 1. Enhancements
 
 #### Elixir
 
-  * [Kernel] Expand `left..right` at compile time in more cases, which leads to improved performance under different scenarios, especially on `x in left..right` expressions
-
-#### Mix
-
-  * [mix deps.loadpaths] Add `--no-load-deps` flag. This is useful for Rebar 3 compatibility
+  * [Code.Formatter] Support comments in the middle of pipelines, `when` and `|` expressions
 
 ### 2. Bug fixes
 
 #### Elixir
 
-  * [Calendar] Fix for converting from negative iso days on New Year in a leap year
-  * [Kernel] Ensure `@spec`, `@callback`, `@type` and friends can be read accordingly
-  * [Module] Avoid warnings when using Module.eval_quoted in the middle of existing definitions
+  * [Code.Formatter] Consider commas when breaking groups
+  * [Code.Formatter] Ensure proper precedence between `&` and operators
+  * [Code.Formatter] Consider `.formatter.exs` when formatting stdin
+
+#### Logger
+
+  * [Logger.Translator] Ensure logger doesn't crash when reporting named `DynamicSupervisor`
+
+## v1.6.2 (2018-02-28)
+
+### 1. Enhancements
 
 #### Mix
 
-  * [mix archive.build] Unload previous archive versions before building
-  * [mix format] Expand paths so mix format `path\for\windows.ex` works
-  * [mix test] Ensure that `--cover` displays correct coverage in an umbrella app
+  * [mix compile.erlang] Teach Mix erlang compiler alternative spelling for `-behavior` declaration
+  * [mix format] Support the `:subdirectories` configuration that points to other directories with their own `.formatter.exs` file. This is useful in umbrella applications. `mix new --umbrella` has also been changed to use this new configuration by default
+  * [mix format] Include the current environment for missing dependency errors
 
-## v1.7.3 (2018-08-24)
-
-### 1. Bug fixes
-
-#### ExUnit
-
-  * [ExUnit.Assertions] Do not attempt to expand `try/1` as it is a special form
-
-#### Mix
-
-  * [mix compile.app] Do not include applications with `runtime: false` as a runtime dependency for applications coming from Hex
-
-## v1.7.2 (2018-08-05)
-
-### 1. Bug fixes
+### 2. Bug fixes
 
 #### Elixir
 
-  * [DateTime] Take negative years into account in `DateTime.from_iso8601/1`
-  * [Kernel] Do not emit warnings for repeated docs over different clauses due to false positives
+  * [Code.Formatter] Ensure `->` does not exceed line length
+  * [DynamicSupervisor] Properly tag error reports generated by dynamic supervisors so they can be properly translated by `Logger`
+  * [DynamicSupervisor] Consider extra arguments during child restart
+  * [Kernel] Ensure arguments given to a guard defined with `defguard` are evaluated in the correct order
+  * [Module] Do not remove docs for previous function declaration when `@impl true` is used
+  * [Supervisor] Ensure `use Supervisor` properly adds the `@behaviour Supervisor` annotation
 
 #### Mix
 
-  * [mix compile] Properly mark top-level dependencies as optional and as runtime. This fixes a bug where Mix attempted to start optional dependencies of a package when those optional dependencies were not available
-  * [mix compile] Avoid deadlock when a config has a timestamp later than current time
-  * [mix help] Show task and alias help when both are available
-  * [mix test] Do not fail suite if there are no test files
+  * [Mix.Shell] Bring back `Mix.Shell.cmd/2` - this arity was defined via a default argument that was accidentally removed
 
-## v1.7.1 (2018-07-26)
-
-### 1. Bug fixes
-
-#### Elixir
-
-  * [Calendar] Work-around a Dialyzer bug that causes it to loop for a long time, potentially indefinitely
-
-## v1.7.0 (2018-07-25)
+## v1.6.1 (2018-01-29)
 
 ### 1. Enhancements
 
 #### Elixir
 
-  * [Calendar.ISO] Support negative dates in `Calendar.ISO`
-  * [Calendar] Add `Calendar.months_in_year/1` callback
-  * [Code] Add `Code.compile_file/2` that compiles files without leaving footprints on the system
-  * [Code] Add `Code.purge_compiler_modules/0` that purges any compiler module left behind. This is useful for live systems dynamically compiling code
-  * [Code] Add `Code.fetch_docs/1` that returns docs in the [EEP 48](http://erlang.org/eep/eeps/eep-0048.html) format
-  * [Date] Add `Date.months_in_year/1` function
-  * [DynamicSupervisor] Use the name of the `DynamicSupervisor` as the ID whenever possible
-  * [Exception] Provide "did you mean" suggestions on KeyError
-  * [Exception] Provide more information on ArithmeticError on Erlang/OTP 21+
-  * [Function] Add `Function` module with `capture/3`, `info/1` and `info/2` functions
-  * [GenServer] Support the new `handle_continue/2` callback on Erlang/OTP 21+
-  * [IO.ANSI] Add cursor movement to `IO.ANSI`
-  * [Kernel] Support adding arbitrary documentation metadata by passing a keyword list to `@doc`, `@moduledoc` and `@typedoc`
-  * [Kernel] Introduce `__STACKTRACE__` to retrieve the current stacktrace inside `catch`/`rescue` (this will be a requirement for Erlang/OTP 21+)
-  * [Kernel] Raise on unsafe variables in order to allow us to better track unused variables
-  * [Kernel] Warn when using `length` to check if a list is not empty on guards
-  * [Kernel] Add hints on mismatched `do`/`end` and others pairs
-  * [Kernel] Warn when comparing structs using the `>`, `<`, `>=` and `<=` operators
-  * [Kernel] Warn on unsupported nested comparisons such as `x < y < z`
-  * [Kernel] Warn if redefining documentation across clauses of the same definition
-  * [Kernel] Warn on unnecessary quotes around atoms, keywords and calls
-  * [Macro] Add `Macro.special_form?/2` and `Macro.operator?/2` that returns `true` if the given name/arity is a special form or operator respectively
-  * [Macro.Env] Add `Macro.Env.vars/1` and `Macro.Env.has_var?/2` that gives access to environment data without accessing private fields
-  * [Regex] Include endianness in the regex version. This allows regexes to be recompiled when an archive is installed in a system with a different endianness
-  * [Registry] Add `Registry.count/1` and `Registry.count_match/4`
-  * [String] Update to Unicode 11
-  * [StringIO] Add `StringIO.open/3`
-  * [System] Use ISO 8601 in `System.build_info/0`
+  * [DynamicSupervisor] Implement `child_spec/1` for DynamicSupervisor
+  * [Kernel] Raise better error messages on invalid map syntax
+
+### 2. Bug fixes
+
+#### Elixir
+
+  * [Code.Formatter] Only rearrange `not in` operator if explicitly opted-in
+  * [Code.Formatter] Ensure `do` blocks do not exceed line length on calls with a single argument
+  * [Collectable] Support bitstrings in Collectable and for-comprehensions (regression in v1.6.0)
+  * [GenServer] Do not override user own `@opts` attribute
+  * [Enum] Reintroduce zipping of any enumerable of enumerables in `Enum.zip/1` (regression in v1.6.0)
+  * [Macro] Reorder kw blocks in `Macro.to_string/1` to avoid warnings
+  * [Protocol] Fix protocol consolidation when some chunks may be missing
+  * [Stream] Reintroduce zipping of any enumerable of enumerables in `Stream.zip/1` (regression in v1.6.0)
+  * [Supervisor] Do not override user own `@opts` attribute
+  * [Supervisor] Add `@spec` to second clause of `start_link/2`
 
 #### ExUnit
 
-  * [ExUnit.Assertion] Print the arguments in error reports when asserting on a function call. For example, if `assert is_list(arg)` fails, the argument will be shown in the report
-  * [ExUnit.Diff] Improve diffing of lists when one list is a subset of the other
-  * [ExUnit.DocTest] Show colored diffs on failed doctests
-  * [ExUnit.Formatter] Excluded tests, via the `--exclude` and `--only` flags, are now shown as "Excluded" in reports. Tests skipped via `@tag :skip` are now exclusively shown as "Skipped" and in yellow
+  * [ExUnit.Case] Reintroduce `:case` in ExUnit setup/setup_all/test context
+
+## v1.6.0 (2018-01-17)
+
+### 1. Enhancements
+
+#### EEx
+
+  * [EEx] Allow markers `/` and `|` to be used in a custom EEx engine
+
+#### Elixir
+
+  * [Calendar] Add truncate to `Time`, `DateTime` and `NaiveDateTime` to facilitate microsecond precision pruning
+  * [Code] Add `format_string!/2` and `format_file!/2` for automatic code formatting
+  * [Code] Support column annotations in quoted expressions with `columns: true` in `Code.string_to_quoted/2`
+  * [DynamicSupervisor] Add `DynamicSupervisor` designed to manage children that are added and removed dynamically
+  * [Exception] Make `Exception.blame/3` extensible by adding an optional `blame/2` callback to exceptions
+  * [Exception] Improve the printing of guards on blamed exceptions
+  * [Enumerable] Add `Enumerable.slice/1` and optimize many `Enum` operations with the new protocol. This allows data-structures with index-based random access to provide a non-linear implementation
+  * [Inspect] Show UTF-8 BOM on inspected strings
+  * [Inspect.Algebra] Add `:strict` and `:flex` breaks - this gives more control over the document fitting
+  * [Inspect.Algebra] Allow a group to inherit the parent group break
+  * [Inspect.Algebra] Add `force_unfit/1` and `next_break_fits/2` which give more control over document fitting
+  * [Inspect.Algebra] Add `collapse_lines/1` for collapsing multiple lines to a maximum value
+  * [Inspect.Algebra] Allow `nest/2` to be `:reset` or be set to the current `:cursor` position
+  * [Kernel] Prefix variables with V when emitting Erlang code. This improves the integration with tools such as Erlang code formatters and the GUI debugger
+  * [Kernel] Warn on the use of `length(x) == 0` in guards
+  * [Kernel] Warn if `catch` comes before `rescue` in try
+  * [Kernel] Warn if heredoc is outdented compared to its closing quotes
+  * [Kernel] Add `defguard/1` and `defguardp/1` to make it easier to build guard-safe macros
+  * [Kernel.ParallelCompiler] Add `compile/2`, `compile_to_path/3` and `require/2` which provide detailed information about warnings and errors
+  * [Kernel.SpecialForms] Support the `uniq: true` flag in `for` comprehensions
+  * [Module] Introduce `@deprecated` and `@since` attributes
+  * [Module] Emit conflicting behaviour warnings if the same behaviour is given more than once
+  * [List] Rearrange equals and inserts for shorter diff scripts in `List.myers_difference/2`
+  * [Record] Allow `:macros` and `:includes` to be given to `Record.extract/2`
+  * [Stream] Add `Stream.intersperse/2`
+  * [String] Update to Unicode 10
+  * [String] Allow passing empty string `match` to `String.replace/4`
+  * [String] Support context and language sensitive operations in `String.upcase/2` and `String.downcase/2`. Currently only the `:greek` context is supported
+  * [String] Support `:ascii` conversion in `String.upcase/2` and `String.downcase/2`
+  * [Time] Add `Time.add/3`
+
+#### ExUnit
+
+  * [ExUnit.Assertions] Perform inclusive checks in `assert_in_delta`
+  * [ExUnit.Callbacks] Add `ExUnit.Callbacks.start_supervised!/2`
+  * [ExUnit.Case] Generate a random seed per test based on the test suite seed
 
 #### IEx
 
-  * [IEx.Helpers] Add `use_if_available/2`
-  * [IEx.Helpers] Allow `force: true` option in `recompile/1`
-  * [IEx.Helpers] Add `:allocators` pane to `runtime_info/1`
-  * [IEx.Helpers] Show documentation metadata in `h/1` helpers
+  * [IEx.Autocomplete] Provide contextual autocompletion: `t Enum.` will autocomplete types, `b Enum` will autocomplete callbacks
+  * [IEx.CLI] Provide hints for developers when a bad host name is given to `--remsh`
+  * [IEx.Helpers] Automatically include specs when showing documentation for functions/macros
+  * [IEx.Helpers] Improve formatting of behaviours and typespecs by using the formatter
+  * [IEx.Helpers] Allow pattern matching and guard expressions when on `IEx.break!`
 
 #### Logger
 
-  * [Logger] Ensure nil metadata is always pruned
-  * [Logger] Only evaluate Logger macro arguments when the message will be logged
-  * [Logger] Add `:compile_time_purge_matching` to purge logger calls that match certain compile time metadata, such as module names and application names
-  * [Logger] Log to `:stderr` if a backend fails and there are no other backends
-  * [Logger] Allow translators to return custom metadata
-  * [Logger] Return `:crash_reason`, `:initial_call` and `:registered_name` as metadata in crash reports coming from Erlang/OTP
+  * [Logger] Add `:discard_threshold` to Logger to help with message queue overflow
 
 #### Mix
 
-  * [mix archive.install] Add support for the Hex organization via `--organization`
-  * [mix archive.uninstall] Support `--force` flag
-  * [mix compile] Improve support for external build tools such as `rebar`
-  * [mix deps] Include `override: true` in rebar dependencies to make the behaviour closer to how rebar3 works (although diverged deps are still marked as diverged)
-  * [mix escript.install] Add support for the Hex organization via `--organization`
-  * [mix escript.uninstall] Support `--force` flag
-  * [mix help] Also list aliases
-  * [mix local] Use ipv6 with auto fallback to ipv4 when downloading data
-  * [mix profile] Allow all profiling tasks to run programatically
-  * [mix test] Add `--failed` option that only runs previously failed tests
-  * [mix test] Print coverage summary by default when the `--cover` flag is given
-  * [Mix.Project] Add `Mix.Project.clear_deps_cache/0`
-  * [Mix.Project] Add `Mix.Project.config_mtime/0` that caches the config mtime values to avoid filesystem access
+  * [mix app.start] Add `--preload-modules` to `mix app.start`
+  * [mix archive.build] Allow `mix archive.build` to bundle dot files via an option
+  * [mix compile] Define a behavior for Mix compiler tasks and return diagnostics from compiler tasks
+  * [mix compile] Track struct dependencies between files and recompile them only if the struct changes
+  * [mix deps] Support `:system_env` option when specifying dependencies
+  * [mix format] Add a `mix format` task that formats the given files (or the files specified in a `.formatter.exs` file)
+  * [mix profile.eprof] Add a new task for time-based profiling with eprof
+  * [mix test] Run all functions in a describe block by giving the `file:line` the describe block starts
+  * [mix test] Report the top N slowest tests with the `--slowest N` flag
+  * [mix test] Report the number of doctests and tests separately
+  * [mix xref] Support `--include-siblings` in reports for umbrella support
+  * [mix xref] Add `mix xref graph --format stats`
+  * [mix xref] Add `--only-nodes` and `--label` filters to mix xref graph
+  * [mix xref] Add `mix xref deprecated` that shows the callsite of deprecated functions
 
 ### 2. Bug fixes
 
 #### Elixir
 
-  * [IO.ANSI.Docs] Fix table column alignment when converting docs to ANSI escapes
-  * [Code] Ensure `string_to_quoted` returns error tuples instead of raising in certain constructs
-  * [Code.Formatter] Consistently format keyword lists in function calls with and without parens
-  * [Code.Formatter] Do not break after `->` when there are only comments and one-line clauses
-  * [File] Allow the `:trim_bom` option to be used with `:encoding`
-  * [Kernel] Raise on unsafe variables as some of the code emitted with unsafe variables would not correctly propagate variables or would disable tail call optimization semantics
-  * [Kernel] Do not crash on dynamic sizes in binary generators with collectable into in comprehensions
-  * [Kernel] Do not crash on literals with non-unary size in binary generators with collectable into in comprehensions
-  * [Task] Improve error reports and exit reasons for failed tasks on Erlang/OTP 20+
-
-#### ExUnit
-
-  * [ExUnit.Case] Raise proper error if `@tag` and `@moduletag` are used before `use ExUnit.Case`
-  * [ExUnit.Case] Raise proper error if `@describetag` is used outside of `describe/2` blocks
-  * [ExUnit.DocTest] Emit proper assertion error on doctests with invalid UTF-8
+  * [CLI] Support path with spaces as argument to elixir.bat
+  * [Inspect] Properly handle minus signal for non-decimal negative integers
+  * [Integer] Do not raise on non-integer values in `is_odd`/`is_even`
+  * [Kernel] Solve a precedence issue between `&` and `|`, such as `[&Foo.bar/1 | &Baz.bat/2]`
+  * [Kernel] Do not load dynamic Elixir modules as `:in_memory` as this value is not officially supported by the code server. Instead, use an empty list, which is the same value used by Erlang.
+  * [Kernel] Validate variable struct name is atom when used in pattern matching
+  * [Kernel] No longer generate documentation for `defdelegate` functions automatically to avoid overriding previously specified `@doc`
+  * [Macro] Fix `Macro.to_string/2` for tuple calls, such as `alias Foo.{Bar, Baz}`
+  * [MapSet] Return valid MapSet when unioning a legacy MapSet
+  * [Regex] Return a leading empty space when splitting on empty pattern. This makes the `split` operation consistent with the other operations in the `Regex` module
+  * [Stream] Ensure `Stream.chunk_while/4` does not emit more elements than necessary when halted
+  * [String] Return a leading empty space when splitting on empty string. This makes the `split` operation consistent with the other operations in the `String` module
+  * [URI] Preserve empty fragments in `URI.parse/1`
 
 #### Mix
 
-  * [mix archive.install] Fetch optional dependencies when installing an archive from Git/Hex
-  * [mix compile] Properly track config files in umbrella projects and recompile when any relevant umbrella configuration changes
-  * [mix deps] Ensure the same dependency from different SCMs are tagged as diverged when those SCMs are remote and non-remote
-  * [mix deps] Ensure we re-run dependency resolution when overriding a skipped dep in umbrella
-  * [mix deps.compile] Perform clean builds for dependencies on outdated locks to avoid old modules from affecting future compilation
-  * [mix escript.install] Fetch optional dependencies when installing an escript from Git/Hex
+  * [mix app.start] Improve the quality of reports if app fails to boot
+  * [mix cmd] Allow `mix cmd` to be invoked multiple times without marking it as executed
+  * [mix deps] Ensure optional dependencies in umbrella applications are loaded
+  * [mix deps.update] Ensure transitive new non-Hex dependencies are also fetched when a repo is updated
+  * [mix xref] Take compile dependencies with higher priority than runtime ones when building a graph
+  * [mix xref] Handle external files for xref callers and warnings
 
-### 3. Soft-deprecations (no warnings emitted)
+### 3. Soft deprecations (no warnings emitted)
 
 #### Elixir
 
-  * [Code] Deprecate `Code.load_file/2` in favor of `Code.compile_file/2`
-  * [Code] Deprecate `Code.loaded_files/0` in favor of `Code.required_files/0`
-  * [Code] Deprecate `Code.unload_files/1` in favor of `Code.unrequire_files/1`
+  * [GenServer] Warn if `init/1` is not defined in `GenServer`. This brings GenServer closer to the implementation in OTP and aligns all behaviours to require the `init/1` callback
+  * [Inspect.Algebra] `surround/3` and `surround_many/6` are deprecated in favor of `container_doc/6`
+  * [Kernel] Specifying map types with variable keys without defining the type as required/optional is deprecated
+  * [Kernel.ParallelCompiler] `files/2` and `files_to_path/3` are deprecated in favor of `compile/2` and `compile_to_path/3`
+  * [Kernel.ParallelRequire] `files/2` is deprecated in favor of `Kernel.ParallelCompiler.require/2`
+  * [Supervisor] The `:simple_one_for_one` strategy is deprecated in favor of `DynamicSupervisor`
+  * [Supervisor] Passing a list of args to `Supervisor.start_child/2` is deprecated in favor of `DynamicSupervisor`
+  * [Task.Supervisor] Passing `:restart` and `:shutdown` to `Task.Supervisor.start_link/2` is deprecated (it should be passed on start child instead)
 
-#### Logger
+#### ExUnit
 
-  * [Logger] `compile_time_purge_level` is deprecated in favor of `compile_time_purge_matching`
+  * [ExUnit.Formatter] `:case_started` and `:case_finished` events are deprecated in favor of `:module_started` and `:module_finished`
 
-### 4. Hard-deprecations
+#### Mix
+
+  * [Mix.Compilers.Erlang] Returning `{:ok, val} | :error` from custom Erlang compilers is deprecated in favor of `{:ok, val, warnings} | {:error, errors, warnings}`
+
+### 4. Deprecations
 
 #### Elixir
 
-  * [Code] `Code.get_docs/2` is deprecated in favor of `Code.fetch_docs/1`
-  * [Enum] `Enum.chunk/2/3/4` is deprecated in favor of `Enum.chunk_every/2/3/4` - notice `chunk_every` does not discard incomplete chunks by default
-  * [GenServer] Warn if `super` is used in any of the GenServer callbacks
-  * [Kernel] `not left in right` is ambiguous and is deprecated in favor of `left not in right`
-  * [Kernel] Warn on confusing operator sequences, such as `1+++1` meaning `1 ++ +1` or `........` meaning `... .. ...`
-  * [OptionParser] Deprecate dynamic option parser mode that depended on atoms to be previously loaded and therefore behaved inconsistently
-  * [Stream] `Stream.chunk/2/3/4` is deprecated in favor of `Stream.chunk_every/2/3/4` - notice `chunk_every` does not discard incomplete chunks by default
+  * [Enum] `Enum.partition/2` is deprecated in favor of `Enum.split_with/2`
+  * [Keyword] `Keyword.replace/3` is deprecated in favor of `Keyword.fetch/2` and `Keyword.put/3`
+  * [Map] `Map.replace/3` is deprecated in favor of `Map.fetch/2` and `Map.put/3`
+  * [Macro] `Macro.unescape_tokens/1` and `Macro.unescape_tokens/2` are deprecated in favor of `Enum.map/2`
+  * [Range] Deprecate `Range.range?/1` in favor of pattern matching on `_ .. _`
 
-## v1.6
+## v1.5
 
-The CHANGELOG for v1.6 releases can be found [in the v1.6 branch](https://github.com/elixir-lang/elixir/blob/v1.6/CHANGELOG.md).
+The CHANGELOG for v1.5 releases can be found [in the v1.5 branch](https://github.com/elixir-lang/elixir/blob/v1.5/CHANGELOG.md).

ISSUE_TEMPLATE.md

@@ -7,7 +7,7 @@
 
 ### Environment
 
-* Elixir & Erlang/OTP versions (elixir --version): 
+* Elixir & Erlang versions (elixir --version): 
 * Operating system: 
 
 ### Current behavior

Makefile

@@ -1,10 +1,10 @@
+REBAR ?= "$(CURDIR)/rebar"
 PREFIX ?= /usr/local
 SHARE_PREFIX ?= $(PREFIX)/share
-CANONICAL := v1.7/
+CANONICAL := v1.6/
 ELIXIRC := bin/elixirc --verbose --ignore-module-conflict
 ERLC := erlc -I lib/elixir/include
 ERL := erl -I lib/elixir/include -noshell -pa lib/elixir/ebin
-GENERATE_APP := $(CURDIR)/lib/elixir/generate_app.escript
 VERSION := $(strip $(shell cat VERSION))
 Q := @
 LIBDIR := lib
@@ -16,7 +16,7 @@ INSTALL_PROGRAM = $(INSTALL) -m755
 GIT_REVISION = $(strip $(shell git rev-parse HEAD 2> /dev/null ))
 GIT_TAG = $(strip $(shell head="$(call GIT_REVISION)"; git tag --points-at $$head 2> /dev/null | tail -1) )
 
-.PHONY: install compile erlang elixir unicode app build_plt clean_plt dialyze test clean clean_residual_files install_man clean_man docs Docs.zip Precompiled.zip zips
+.PHONY: install compile erlang elixir build_plt clean_plt dialyze test clean clean_residual_files install_man clean_man docs Docs.zip Precompiled.zip zips
 .NOTPARALLEL: compile
 
 #==> Functions
@@ -24,7 +24,7 @@ GIT_TAG = $(strip $(shell head="$(call GIT_REVISION)"; git tag --points-at $$hea
 define CHECK_ERLANG_RELEASE
 	erl -noshell -eval '{V,_} = string:to_integer(erlang:system_info(otp_release)), io:fwrite("~s", [is_integer(V) and (V >= 19)])' -s erlang halt | grep -q '^true'; \
 		if [ $$? != 0 ]; then \
-		  echo "At least Erlang/OTP 19.0 is required to build Elixir"; \
+		  echo "At least Erlang 19.0 is required to build Elixir"; \
 		  exit 1; \
 		fi
 endef
@@ -51,30 +51,25 @@ endef
 
 #==> Compilation tasks
 
-APP := lib/elixir/ebin/elixir.app
-PARSER := lib/elixir/src/elixir_parser.erl
-KERNEL := lib/elixir/ebin/Elixir.Kernel.beam
-UNICODE := lib/elixir/ebin/Elixir.String.Unicode.beam
+KERNEL:=lib/elixir/ebin/Elixir.Kernel.beam
+UNICODE:=lib/elixir/ebin/Elixir.String.Unicode.beam
 
 default: compile
 
-compile: erlang $(APP) elixir
+compile: erlang elixir
 
-erlang: $(PARSER)
-	$(Q) if [ ! -f $(APP) ]; then $(call CHECK_ERLANG_RELEASE); fi
-	$(Q) cd lib/elixir && mkdir -p ebin && erl -make
-
-$(PARSER): lib/elixir/src/elixir_parser.yrl
-	$(Q) erlc -o $@ +'{verbose,true}' +'{report,true}' $<
+erlang:
+	$(Q) cd lib/elixir && $(REBAR) compile
 
 # Since Mix depends on EEx and EEx depends on Mix,
 # we first compile EEx without the .app file,
-# then Mix and then compile EEx fully
+# then mix and then compile EEx fully
 elixir: stdlib lib/eex/ebin/Elixir.EEx.beam mix ex_unit logger eex iex
 
 stdlib: $(KERNEL) VERSION
 $(KERNEL): lib/elixir/lib/*.ex lib/elixir/lib/*/*.ex lib/elixir/lib/*/*/*.ex
 	$(Q) if [ ! -f $(KERNEL) ]; then \
+	  $(call CHECK_ERLANG_RELEASE); \
 		echo "==> bootstrap (compile)"; \
 		$(ERL) -s elixir_compiler bootstrap -s erlang halt; \
 	fi
@@ -82,11 +77,8 @@ $(KERNEL): lib/elixir/lib/*.ex lib/elixir/lib/*/*.ex lib/elixir/lib/*/*/*.ex
 	$(Q) cd lib/elixir && ../../$(ELIXIRC) "lib/kernel.ex" -o ebin;
 	$(Q) cd lib/elixir && ../../$(ELIXIRC) "lib/**/*.ex" -o ebin;
 	$(Q) $(MAKE) unicode
-	$(Q) $(MAKE) app
-
-app: $(APP)
-$(APP): lib/elixir/src/elixir.app.src lib/elixir/ebin VERSION $(GENERATE_APP)
-	$(Q) $(GENERATE_APP) $< $@ $(VERSION)
+	$(Q) rm -f lib/elixir/ebin/elixir.app
+	$(Q) cd lib/elixir && $(REBAR) compile
 
 unicode: $(UNICODE)
 $(UNICODE): lib/elixir/unicode/*
@@ -117,9 +109,9 @@ install: compile
 	$(MAKE) install_man
 
 clean:
+	cd lib/elixir && $(REBAR) clean
 	rm -rf ebin
 	rm -rf lib/*/ebin
-	rm -rf $(PARSER)
 	$(Q) $(MAKE) clean_residual_files
 
 clean_elixir:
@@ -192,18 +184,10 @@ Precompiled.zip: build_man compile
 	@ echo "Precompiled file created $(CURDIR)/Precompiled-v$(VERSION).zip"
 
 zips: Precompiled.zip Docs.zip
-	@ echo ""
-	@ echo "## Checksums"
-	@ echo ""
-	@ shasum -a 1 < Precompiled-v$(VERSION).zip | sed -e "s/-//" | xargs echo "  * Precompiled.zip SHA1:"
-	@ shasum -a 512 < Precompiled-v$(VERSION).zip | sed -e "s/-//" | xargs echo "  * Precompiled.zip SHA512:"
-	@ shasum -a 1 < Docs-v$(VERSION).zip | sed -e "s/-//" | xargs echo "  * Docs.zip SHA1:"
-	@ shasum -a 512 < Docs-v$(VERSION).zip | sed -e "s/-//" | xargs echo "  * Docs.zip SHA512:"
-	@ echo ""
 
 #==> Test tasks
 
-test: test_formatted test_erlang test_elixir
+test: test_erlang test_elixir
 
 test_windows: test test_taskkill
 
@@ -215,9 +199,6 @@ TEST_ERL = lib/elixir/test/erlang
 TEST_EBIN = lib/elixir/test/ebin
 TEST_ERLS = $(addprefix $(TEST_EBIN)/, $(addsuffix .beam, $(basename $(notdir $(wildcard $(TEST_ERL)/*.erl)))))
 
-test_formatted: compile
-	bin/elixir bin/mix format --check-formatted
-
 test_erlang: compile $(TEST_ERLS)
 	@ echo "==> elixir (eunit)"
 	$(Q) $(ERL) -pa $(TEST_EBIN) -s test_helper test;

README.md

@@ -29,8 +29,8 @@ If Elixir fails to build (specifically when pulling in a new version via
 If tests pass, you are ready to move on to the [Getting Started guide][1]
 or to try Interactive Elixir by running `bin/iex` in your terminal.
 
-However, if tests fail, it is likely you have an outdated Erlang/OTP version
-(Elixir requires Erlang/OTP 19.0 or later). You can check your Erlang/OTP version
+However, if tests fail, it is likely you have an outdated Erlang version
+(Elixir requires Erlang 19.0 or later). You can check your Erlang version
 by calling `erl` in the command line. You will see some information as follows:
 
     Erlang/OTP 19 [erts-8.0] [smp:2:2] [async-threads:10] [kernel-poll:false]
@@ -86,7 +86,7 @@ also run tests for a specific framework `make test_#{NAME}`, for example,
 `make test_ex_unit`. If you just changed something in the Elixir's standard
 library, you can run only that portion through `make test_stdlib`.
 
-If you are changing just one file, you can choose to compile and run tests only
+In case you are changing a single file, you can compile and run tests only
 for that particular file for fast development cycles. For example, if you
 are changing the String module, you can compile it and run its tests as:
 
@@ -142,7 +142,7 @@ rather manage all changes yourself, you can disable "Allow edits from maintainer
 feature when submitting your pull request.
 
 The Elixir team may optionally assign someone to review a pull request.
-If someone is assigned, they must explicitly approve the code before
+In case someone is assigned, they must explicitly approve the code before
 another team member can merge it.
 
 When the review finishes, your pull request will be squashed and merged

RELEASE.md

@@ -1,41 +1,37 @@
 # Release process
 
-## Shipping a new version
+## All releases
+
+This document simply outlines the release process:
 
 1. Ensure you are running on the oldest supported Erlang version
 
-2. Update version in /VERSION
+2. Remove all `-dev` extension from versions (see below for all files)
 
-3. Ensure /CHANGELOG.md is updated, versioned and add the current date
+3. Ensure CHANGELOG is updated and add current date
 
-4. Update "Compatibility and Deprecations" if a new OTP version is supported
+4. Update "Compatibility and Deprecations" if a new OTP version is supported. If a new `vMAJOR.MINOR`, replace "master" with "vVERSION" in the "Deprecations" section
 
-5. Commit changes above with title "Release vVERSION" and generate a new tag
+5. If a new `vMAJOR.MINOR`, create a new branch "vMAJOR.MINOR" and set `CANONICAL=` in Makefile
 
-6. Run `make clean test` to ensure all tests pass from scratch and the CI is green
+6. Add an entry for the new version to the OTP compatibility table in the "Compatibility and Deprecations" page
 
-7. Recompile an existing project (for example, Ecto) to ensure manifests can be upgraded
+7. Commit changes above with title "Release vVERSION" and generate new tag
 
-8. Push branch and the new tag
+8. Run `make clean test` to ensure all tests pass from scratch and the CI is green
 
-9. Publish new zips with `make zips`, upload `Precompiled.zip` and `Docs.zip` to GitHub Releases, and include SHAs+CHANGELOG
+9. Recompile an existing project (for example, Ecto) to ensure manifests can be upgraded
 
-10. Add the release to `elixir.csv` and `_data/elixir-versions.yml` files in `elixir-lang/elixir-lang.github.com`
+10. Push branch and the new tag
 
-## Creating a new vMAJOR.MINOR branch
+11. Publish new zips with `make zips`, upload `Precompiled.zip` and `Docs.zip` to GitHub Releases
 
-### In the new branch
+12. Add the release to `elixir.csv` and `_data/elixir-versions.yml` files in `elixir-lang/elixir-lang.github.com`
 
-1. Set `CANONICAL=` in /Makefile
+13. After a new `vMAJOR.MINOR`, move back to master, bump versions, start new CHANGELOG, add `-dev` back and commit "Start vMAJOR.MINOR+1"
 
-2. Update **all** tables in "Compatibility and Deprecations"
+## Places where version is mentioned
 
-3. Commit "Prepare vMAJOR.MINOR for release"
-
-### Back in master
-
-1. Bump /VERSION file
-
-2. Start new /CHANGELOG.md
-
-3. Commit "Start vMAJOR.MINOR+1"
+* VERSION
+* CHANGELOG.md
+* lib/elixir/src/elixir.app.src

VERSION

@@ -1 +1 @@
-1.7.4
+1.6.3

bin/elixir

@@ -117,7 +117,11 @@ if [ "$OS" = "Windows_NT" ] && [ $USE_WERL ]; then
 fi
 
 if [ -z "$ERL_PATH" ]; then
-  ERL_PATH="$ERL_EXEC"
+  if [ -f "$SCRIPT_PATH/../releases/RELEASES" ] && [ -f "$SCRIPT_PATH/erl" ]; then
+    ERL_PATH="$SCRIPT_PATH"/"$ERL_EXEC"
+  else
+    ERL_PATH="$ERL_EXEC"
+  fi
 fi
 
 exec "$ERL_PATH" -pa "$SCRIPT_PATH"/../lib/*/ebin $ELIXIR_ERL_OPTIONS $ERL -extra "$@"

lib/eex/lib/eex.ex

@@ -1,7 +1,6 @@
 defmodule EEx.SyntaxError do
   defexception [:message, :file, :line]
 
-  @impl true
   def message(exception) do
     "#{exception.file}:#{exception.line}: #{exception.message}"
   end
@@ -12,7 +11,7 @@ defmodule EEx do
   EEx stands for Embedded Elixir. It allows you to embed
   Elixir code inside a string in a robust way.
 
-      iex> EEx.eval_string("foo <%= bar %>", bar: "baz")
+      iex> EEx.eval_string "foo <%= bar %>", [bar: "baz"]
       "foo baz"
 
   ## API
@@ -84,7 +83,7 @@ defmodule EEx do
   An example is the `@` macro which allows easy data access
   in a template:
 
-      iex> EEx.eval_string("<%= @foo %>", assigns: [foo: 1])
+      iex> EEx.eval_string "<%= @foo %>", assigns: [foo: 1]
       "1"
 
   In other words, `<%= @foo %>` translates to:
@@ -187,7 +186,7 @@ defmodule EEx do
 
   ## Examples
 
-      iex> EEx.eval_string("foo <%= bar %>", bar: "baz")
+      iex> EEx.eval_string "foo <%= bar %>", [bar: "baz"]
       "foo baz"
 
   """

lib/eex/test/eex_test.exs

@@ -4,7 +4,8 @@ require EEx
 
 defmodule EExTest.Compiled do
   def before_compile do
-    {__ENV__.line, hd(tl(get_stacktrace()))}
+    fill_in_stacktrace()
+    {__ENV__.line, hd(tl(System.stacktrace()))}
   end
 
   EEx.function_from_string(:def, :string_sample, "<%= a + b %>", [:a, :b])
@@ -18,19 +19,21 @@ defmodule EExTest.Compiled do
   def file_sample(arg), do: private_file_sample(arg)
 
   def after_compile do
-    {__ENV__.line, hd(tl(get_stacktrace()))}
+    fill_in_stacktrace()
+    {__ENV__.line, hd(tl(System.stacktrace()))}
   end
 
   @file "unknown"
   def unknown do
-    {__ENV__.line, hd(tl(get_stacktrace()))}
+    fill_in_stacktrace()
+    {__ENV__.line, hd(tl(System.stacktrace()))}
   end
 
-  defp get_stacktrace do
+  defp fill_in_stacktrace do
     try do
       :erlang.error("failed")
-    rescue
-      _ -> __STACKTRACE__
+    catch
+      :error, _ -> System.stacktrace()
     end
   end
 end
@@ -444,13 +447,13 @@ defmodule EExTest do
       file = to_charlist(Path.relative_to_cwd(__ENV__.file))
 
       assert EExTest.Compiled.before_compile() ==
-               {7, {EExTest.Compiled, :before_compile, 0, [file: file, line: 7]}}
+               {8, {EExTest.Compiled, :before_compile, 0, [file: file, line: 7]}}
 
       assert EExTest.Compiled.after_compile() ==
-               {21, {EExTest.Compiled, :after_compile, 0, [file: file, line: 21]}}
+               {23, {EExTest.Compiled, :after_compile, 0, [file: file, line: 22]}}
 
       assert EExTest.Compiled.unknown() ==
-               {26, {EExTest.Compiled, :unknown, 0, [file: 'unknown', line: 26]}}
+               {29, {EExTest.Compiled, :unknown, 0, [file: 'unknown', line: 28]}}
     end
   end
 

lib/elixir/docs.exs

@@ -14,7 +14,6 @@
       DateTime,
       Exception,
       Float,
-      Function,
       Integer,
       NaiveDateTime,
       Record,
@@ -23,8 +22,9 @@
       Time,
       Tuple,
       URI,
-      Version
+      Version,
     ],
+
     "Collections & Enumerables": [
       Access,
       Date.Range,
@@ -34,8 +34,9 @@
       Map,
       MapSet,
       Range,
-      Stream
+      Stream,
     ],
+
     "IO & System": [
       File,
       File.Stat,
@@ -47,15 +48,17 @@
       Path,
       Port,
       StringIO,
-      System
+      System,
     ],
+
     "Modules & Code": [
       Code,
       Kernel.ParallelCompiler,
       Macro,
       Macro.Env,
-      Module
+      Module,
     ],
+
     "Processes & Applications": [
       Agent,
       Application,
@@ -66,9 +69,10 @@
       Registry,
       Supervisor,
       Task,
-      Task.Supervisor
+      Task.Supervisor,
     ],
-    Protocols: [
+
+    "Protocols": [
       Collectable,
       Enumerable,
       Inspect,
@@ -76,9 +80,10 @@
       Inspect.Opts,
       List.Chars,
       Protocol,
-      String.Chars
+      String.Chars,
     ],
-    Deprecated: [
+
+    "Deprecated": [
       Behaviour,
       Dict,
       GenEvent,
@@ -86,6 +91,6 @@
       HashSet,
       Set,
       Supervisor.Spec
-    ]
+    ],
   ]
 ]

lib/elixir/generate_app.escript

@@ -1,13 +0,0 @@
-#!/usr/bin/env escript
-%% -*- erlang -*-
-
-main([Source, Target, Version]) ->
-  {ok, [{application, Name, Props0}]} = file:consult(Source),
-  Ebin = filename:dirname(Target),
-  Files = filelib:wildcard(filename:join(Ebin, "*.beam")),
-  Mods = [list_to_atom(filename:basename(F, ".beam")) || F <- Files],
-  Props1 = lists:keyreplace(modules, 1, Props0, {modules, Mods}),
-  Props = lists:keyreplace(vsn, 1, Props1, {vsn, Version}),
-  AppDef = io_lib:format("~tp.~n", [{application, Name, Props}]),
-  ok = file:write_file(Target, AppDef),
-  io:format("Generated ~ts.app~n", [Name]).

lib/elixir/lib/access.ex

@@ -1,53 +1,27 @@
 defmodule Access do
   @moduledoc """
-  Key-based access to data structures.
+  Key-based access to data structures using the `data[key]` syntax.
 
-  Elixir supports three main key-value constructs: keywords,
-  maps, and structs. It also supports two mechanisms to access those keys:
-  by brackets (via `data[key]`) and by dot-syntax (via `data.field`).
+  Elixir provides two syntaxes for accessing values. `user[:name]`
+  is used by dynamic structures, like maps and keywords, while
+  `user.name` is used by structs. The main difference is that
+  `user[:name]` won't raise if the key `:name` is missing but
+  `user.name` will raise if there is no `:name` key.
 
-  In the next section we will briefly recap the key-value constructs and then
-  discuss the access mechanisms.
+  Besides the cases above, this module provides convenience
+  functions for accessing other structures, like `at/1` for
+  lists and `elem/1` for tuples. Those functions can be used
+  by the nested update functions in `Kernel`, such as
+  `Kernel.get_in/2`, `Kernel.put_in/3`, `Kernel.update_in/3`,
+  `Kernel.get_and_update_in/3` and friends.
 
-  ## Key-value constructs
+  ## Dynamic lookups
 
-  Elixir provides three main key-value constructs, summarized below:
-
-    * keyword lists - they are lists of two-element tuples where
-      the first element is an atom. Commonly written in the
-      `[key: value]` syntax, they support only atom keys. Keyword
-      lists are used almost exclusively to pass options to functions
-      and macros. They keep the user ordering and allow duplicate
-      keys. See the `Keyword` module.
-
-    * maps - they are the "go to" key-value data structure in Elixir.
-      They are capable of supporting billions of keys of any type. They are
-      written using the `%{key => value}` syntax and also support the
-      `%{key: value}` syntax when the keys are atoms. They do not
-      have any specified ordering and do not allow duplicate keys.
-      See the `Map` module.
-
-    * structs - they are named maps with a pre-determined set of keys.
-      They are defined with `defstruct/1` and written using the
-      `%StructName{key: value}` syntax.
-
-  ## Key-based accessors
-
-  Elixir provides two mechanisms to access data structures by key,
-  described next.
-
-  ### Bracket-based access
-
-  The `data[key]` syntax is used to access data structures with a
-  dynamic number of keys, such as keywords and maps. The key can
-  be of any type. The bracket-based access syntax returns `nil`
-  if the key does not exist:
+  Out of the box, `Access` works with `Keyword` and `Map`:
 
       iex> keywords = [a: 1, b: 2]
       iex> keywords[:a]
       1
-      iex> keywords[:c]
-      nil
 
       iex> map = %{a: 1, b: 2}
       iex> map[:a]
@@ -57,91 +31,110 @@ defmodule Access do
       iex> star_ratings[1.5]
       "★☆"
 
+  Note that the dynamic lookup syntax (`term[key]`) roughly translates to
+  `Access.get(term, key, nil)`.
+
+  `Access` can be combined with `Kernel.put_in/3` to put a value
+  in a given key:
+
+      iex> map = %{a: 1, b: 2}
+      iex> put_in map[:a], 3
+      %{a: 3, b: 2}
+
   This syntax is very convenient as it can be nested arbitrarily:
 
       iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
-      iex> put_in(users["john"][:age], 28)
+      iex> put_in users["john"][:age], 28
       %{"john" => %{age: 28}, "meg" => %{age: 23}}
 
-  Furthermore, the bracket-based access syntax transparently ignores
-  `nil` values. When trying to access anything on a `nil` value, `nil`
-  is returned:
+  Furthermore, `Access` transparently ignores `nil` values:
 
       iex> keywords = [a: 1, b: 2]
       iex> keywords[:c][:unknown]
       nil
 
-      iex> nil[:a]
-      nil
+  Since `Access` is a behaviour, it can be implemented for key-value
+  data structures. The implementation should be added to the
+  module that defines the struct being accessed. `Access` requires the
+  key comparison to be implemented using the `===` operator.
 
-  Internally, `data[key]` translates  to `Access.get(term, key, nil)`.
-  Developers interested in implementing their own key-value data
-  structures can implement the `Access` behaviour to provide the
-  bracket-based access syntax. `Access` requires the key comparison
-  to be implemented using the `===/2` operator.
+  ## Static lookups
 
-  ### Dot-based syntax
+  The `Access` syntax (`data[key]`) cannot be used to access fields in
+  structs, since structs do not implement the `Access` behaviour by
+  default. It is also a design decision: the dynamic access lookup
+  is meant to be used for dynamic key-value structures, like maps
+  and keywords, and not by static ones like structs (where fields are
+  known and not dynamic).
 
-  The `data.field` syntax is used exclusively to access atom fields
-  in maps and structs. If the accessed field does not exist, an error is
-  raised. This is a deliberate decision: since all of the
-  fields in a struct are pre-determined, structs support only the
-  dot-based syntax and not the access one.
-
-  Imagine a struct named `User` with a `:name` field. The following would raise:
+  Therefore Elixir provides a static lookup for struct fields and for atom
+  fields in maps. Imagine a struct named `User` with a `:name` field.
+  The following would raise:
 
       user = %User{name: "John"}
       user[:name]
       # ** (UndefinedFunctionError) undefined function User.fetch/2 (User does not implement the Access behaviour)
 
-  Instead we should use the `user.name` syntax to access fields:
+  Structs instead use the `user.name` syntax to access fields:
 
       user.name
       #=> "John"
 
+  The same `user.name` syntax can also be used by `Kernel.put_in/2`
+  for updating structs fields:
+
+      put_in user.name, "Mary"
+      #=> %User{name: "Mary"}
+
   Differently from `user[:name]`, `user.name` is not extensible via
   a behaviour and is restricted only to structs and atom keys in maps.
 
-  ### Summing up
+  As mentioned above, this works for atom keys in maps as well. Refer to the
+  `Map` module for more information on this.
 
-  The bracket-based syntax, `user[:name]`, is used by dynamic structures,
-  is extensible and returns nil on misisng keys.
+  Summing up:
 
-  The dot-based syntax, `user.name`, is used exclusively to access atom
-  keys in maps and structs, and it raises on missing keys.
+    * `user[:name]` is used by dynamic structures, is extensible and
+      does not raise on missing keys
+    * `user.name` is used by static structures, it is not extensible
+      and it will raise on missing keys
 
-  ## Nested data structures
+  ## Accessors
 
-  Both key-based access syntaxes can be used with the nested update
-  functions and macros in `Kernel`, such as `Kernel.get_in/2`, `Kernel.put_in/3`,
-  `Kernel.update_in/3`, `Kernel.pop_in/2`, and `Kernel.get_and_update_in/3`.
+  While Elixir provides built-in syntax only for traversing dynamic
+  and static key-value structures, this module provides convenience
+  functions for traversing other structures, like tuples and lists,
+  to be used alongside `Kernel.put_in/2` in others.
 
-  For example, to update a map inside another map:
-
-     iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
-     iex> put_in(users["john"].age, 28)
-     %{"john" => %{age: 28}, "meg" => %{age: 23}}
-
-  This module provides convenience functions for traversing other
-  structures, like tuples and lists. These functions can be used
-  in all the `Access`-related functions and macros in `Kernel`.
-
-  For instance, given a user map with the `:name` and `:languages` keys,
-  here is how to deeply traverse the map and convert all language names
-  to uppercase:
+  For instance, given a user map with `:name` and `:languages` keys, here is how
+  to deeply traverse the map and convert all language names to uppercase:
 
       iex> languages = [
       ...>   %{name: "elixir", type: :functional},
       ...>   %{name: "c", type: :procedural},
       ...> ]
       iex> user = %{name: "john", languages: languages}
-      iex> update_in(user, [:languages, Access.all(), :name], &String.upcase/1)
+      iex> update_in user, [:languages, Access.all(), :name], &String.upcase/1
       %{name: "john",
         languages: [%{name: "ELIXIR", type: :functional},
                     %{name: "C", type: :procedural}]}
 
   See the functions `key/1`, `key!/1`, `elem/1`, and `all/0` for some of the
   available accessors.
+
+  ## Implementing the Access behaviour for custom data structures
+
+  In order to be able to use the `Access` behaviour with custom data structures
+  (which have to be structs), such structures have to implement the `Access`
+  behaviour. For example, for a `User` struct, this would have to be done:
+
+      defmodule User do
+        defstruct [:name, :email]
+
+        @behaviour Access
+        # Implementation of the Access callbacks...
+      end
+
   """
 
   @type container :: keyword | struct | map
@@ -181,6 +174,28 @@ defmodule Access do
   """
   @callback fetch(term :: t, key) :: {:ok, value} | :error
 
+  @doc """
+  Invoked in order to access the value stored under `key` in the given term `term`,
+  defaulting to `default` if not present.
+
+  This function should return the value under `key` in `term` if there's
+  such key, otherwise `default`.
+
+  For most data structures, this can be implemented using `fetch/2` internally;
+  for example:
+
+      def get(structure, key, default) do
+        case fetch(structure, key) do
+          {:ok, value} -> value
+          :error       -> default
+        end
+      end
+
+  See the `Map.get/3` and `Keyword.get/3` implementations for examples of
+  how to implement this callback.
+  """
+  @callback get(term :: t, key, default :: value) :: value
+
   @doc """
   Invoked in order to access the value under `key` and update it at the same time.
 
@@ -190,12 +205,9 @@ defmodule Access do
 
   If the passed function returns `{get_value, update_value}`,
   the return value of this callback should be `{get_value, new_data}`, where:
-
-    * `get_value` is the retrieved value (which can be operated on before being returned)
-
-    * `update_value` is the new value to be stored under `key`
-
-    * `new_data` is `data` after updating the value of `key` with `update_value`.
+  - `get_value` is the retrieved value (which can be operated on before being returned)
+  - `update_value` is the new value to be stored under `key`
+  - `new_data` is `data` after updating the value of `key` with `update_value`.
 
   If the passed function returns `:pop`, the return value of this callback
   must be `{value, new_data}` where `value` is the value under `key`
@@ -223,8 +235,10 @@ defmodule Access do
 
   defmacrop raise_undefined_behaviour(exception, module, top) do
     quote do
+      stacktrace = System.stacktrace()
+
       exception =
-        case __STACKTRACE__ do
+        case stacktrace do
           [unquote(top) | _] ->
             reason = "#{inspect(unquote(module))} does not implement the Access behaviour"
             %{unquote(exception) | reason: reason}
@@ -233,7 +247,7 @@ defmodule Access do
             unquote(exception)
         end
 
-      reraise exception, __STACKTRACE__
+      reraise exception, stacktrace
     end
   end
 
@@ -243,15 +257,6 @@ defmodule Access do
 
   Returns `{:ok, value}` where `value` is the value under `key` if there is such
   a key, or `:error` if `key` is not found.
-
-  ## Examples
-
-      iex> Access.fetch(%{name: "meg", age: 26}, :name)
-      {:ok, "meg"}
-
-      iex> Access.fetch([ordered: true, on_timeout: :exit], :timeout)
-      :error
-
   """
   @spec fetch(container, term) :: {:ok, term} | :error
   @spec fetch(nil_container, any) :: :error
@@ -293,26 +298,11 @@ defmodule Access do
 
   Returns the value under `key` if there is such a key, or `default` if `key` is
   not found.
-
-  ## Examples
-
-      iex> Access.get(%{name: "john"}, :name, "default name")
-      "john"
-      iex> Access.get(%{name: "john"}, :age, 25)
-      25
-
-      iex> Access.get([ordered: true], :timeout)
-      nil
-
   """
   @spec get(container, term, term) :: term
   @spec get(nil_container, any, default) :: default when default: var
   def get(container, key, default \\ nil)
 
-  # Reimplementing the same logic as Access.fetch/2 here is done for performance, since
-  # this is called a lot and calling fetch/2 means introducing some overhead (like
-  # building the "{:ok, _}" tuple and deconstructing it back right away).
-
   def get(%module{} = container, key, default) do
     try do
       module.fetch(container, key)
@@ -446,8 +436,8 @@ defmodule Access do
   The returned function uses the default value if the key does not exist.
   This can be used to specify defaults and safely traverse missing keys:
 
-      iex> get_in(%{}, [Access.key(:user, %{name: "meg"}), Access.key(:name)])
-      "meg"
+      iex> get_in(%{}, [Access.key(:user, %{}), Access.key(:name)])
+      nil
 
   Such is also useful when using update functions, allowing us to introduce
   values as we traverse the data structure for updates:
@@ -460,8 +450,8 @@ defmodule Access do
       iex> map = %{user: %{name: "john"}}
       iex> get_in(map, [Access.key(:unknown, %{}), Access.key(:name, "john")])
       "john"
-      iex> get_and_update_in(map, [Access.key(:user), Access.key(:name)], fn prev ->
-      ...>   {prev, String.upcase(prev)}
+      iex> get_and_update_in(map, [Access.key(:user), Access.key(:name)], fn
+      ...>   prev -> {prev, String.upcase(prev)}
       ...> end)
       {"john", %{user: %{name: "JOHN"}}}
       iex> pop_in(map, [Access.key(:user), Access.key(:name)])
@@ -498,15 +488,15 @@ defmodule Access do
   The returned function is typically passed as an accessor to `Kernel.get_in/2`,
   `Kernel.get_and_update_in/3`, and friends.
 
-  Similar to `key/2`, but the returned function raises if the key does not exist.
+  The returned function raises if the key does not exist.
 
   ## Examples
 
       iex> map = %{user: %{name: "john"}}
       iex> get_in(map, [Access.key!(:user), Access.key!(:name)])
       "john"
-      iex> get_and_update_in(map, [Access.key!(:user), Access.key!(:name)], fn prev ->
-      ...>   {prev, String.upcase(prev)}
+      iex> get_and_update_in(map, [Access.key!(:user), Access.key!(:name)], fn
+      ...>   prev -> {prev, String.upcase(prev)}
       ...> end)
       {"john", %{user: %{name: "JOHN"}}}
       iex> pop_in(map, [Access.key!(:user), Access.key!(:name)])
@@ -547,16 +537,13 @@ defmodule Access do
 
   The returned function raises if `index` is out of bounds.
 
-  Note that popping elements out of tuples is not possible and raises an
-  error.
-
   ## Examples
 
       iex> map = %{user: {"john", 27}}
       iex> get_in(map, [:user, Access.elem(0)])
       "john"
-      iex> get_and_update_in(map, [:user, Access.elem(0)], fn prev ->
-      ...>   {prev, String.upcase(prev)}
+      iex> get_and_update_in(map, [:user, Access.elem(0)], fn
+      ...>   prev -> {prev, String.upcase(prev)}
       ...> end)
       {"john", %{user: {"JOHN", 27}}}
       iex> pop_in(map, [:user, Access.elem(0)])
@@ -569,7 +556,7 @@ defmodule Access do
 
   """
   @spec elem(non_neg_integer) :: access_fun(data :: tuple, get_value :: term)
-  def elem(index) when is_integer(index) and index >= 0 do
+  def elem(index) when is_integer(index) do
     pos = index + 1
 
     fn
@@ -600,8 +587,8 @@ defmodule Access do
       iex> list = [%{name: "john"}, %{name: "mary"}]
       iex> get_in(list, [Access.all(), :name])
       ["john", "mary"]
-      iex> get_and_update_in(list, [Access.all(), :name], fn prev ->
-      ...>   {prev, String.upcase(prev)}
+      iex> get_and_update_in(list, [Access.all(), :name], fn
+      ...>   prev -> {prev, String.upcase(prev)}
       ...> end)
       {["john", "mary"], [%{name: "JOHN"}, %{name: "MARY"}]}
       iex> pop_in(list, [Access.all(), :name])
@@ -611,8 +598,8 @@ defmodule Access do
   numbers and multiplying odd numbers by 2:
 
       iex> require Integer
-      iex> get_and_update_in([1, 2, 3, 4, 5], [Access.all], fn num ->
-      ...>   if Integer.is_even(num), do: :pop, else: {num, num * 2}
+      iex> get_and_update_in([1, 2, 3, 4, 5], [Access.all], fn
+      ...>   num -> if Integer.is_even(num), do: :pop, else: {num, num * 2}
       ...> end)
       {[1, 2, 3, 4, 5], [2, 6, 10]}
 
@@ -661,8 +648,8 @@ defmodule Access do
       iex> list = [%{name: "john"}, %{name: "mary"}]
       iex> get_in(list, [Access.at(1), :name])
       "mary"
-      iex> get_and_update_in(list, [Access.at(0), :name], fn prev ->
-      ...>   {prev, String.upcase(prev)}
+      iex> get_and_update_in(list, [Access.at(0), :name], fn
+      ...>   prev -> {prev, String.upcase(prev)}
       ...> end)
       {"john", [%{name: "JOHN"}, %{name: "mary"}]}
 
@@ -680,8 +667,8 @@ defmodule Access do
       iex> list = [%{name: "john"}, %{name: "mary"}]
       iex> get_in(list, [Access.at(10), :name])
       nil
-      iex> get_and_update_in(list, [Access.at(10), :name], fn prev ->
-      ...>   {prev, String.upcase(prev)}
+      iex> get_and_update_in(list, [Access.at(10), :name], fn
+      ...>   prev -> {prev, String.upcase(prev)}
       ...> end)
       {nil, [%{name: "john"}, %{name: "mary"}]}
 
@@ -736,11 +723,11 @@ defmodule Access do
 
   ## Examples
 
-      iex> list = [%{name: "john", salary: 10}, %{name: "francine", salary: 30}]
+      iex> list = [%{name: "john", salary: 10},  %{name: "francine", salary: 30}]
       iex> get_in(list, [Access.filter(&(&1.salary > 20)), :name])
       ["francine"]
-      iex> get_and_update_in(list, [Access.filter(&(&1.salary <= 20)), :name], fn prev ->
-      ...>   {prev, String.upcase(prev)}
+      iex> get_and_update_in(list, [Access.filter(&(&1.salary <= 20)), :name], fn
+      ...>   prev -> {prev, String.upcase(prev)}
       ...> end)
       {["john"], [%{name: "JOHN", salary: 10}, %{name: "francine", salary: 30}]}
 
@@ -758,8 +745,8 @@ defmodule Access do
       iex> list = [%{name: "john", salary: 10}, %{name: "francine", salary: 30}]
       iex> get_in(list, [Access.filter(&(&1.salary >= 50)), :name])
       []
-      iex> get_and_update_in(list, [Access.filter(&(&1.salary >= 50)), :name], fn prev ->
-      ...>   {prev, String.upcase(prev)}
+      iex> get_and_update_in(list, [Access.filter(&(&1.salary >= 50)), :name], fn
+      ...>   prev -> {prev, String.upcase(prev)}
       ...> end)
       {[], [%{name: "john", salary: 10}, %{name: "francine", salary: 30}]}
 
@@ -772,9 +759,7 @@ defmodule Access do
 
       iex> get_in(%{}, [Access.filter(fn a -> a == 10 end)])
       ** (RuntimeError) Access.filter/1 expected a list, got: %{}
-
   """
-  @doc since: "1.6.0"
   @spec filter((term -> boolean)) :: access_fun(data :: list, get_value :: list)
   def filter(func) when is_function(func) do
     fn op, data, next -> filter(op, data, func, next) end

lib/elixir/lib/agent.ex

@@ -77,7 +77,7 @@ defmodule Agent do
   defined module to be put under a supervision tree. The generated
   `child_spec/1` can be customized with the following options:
 
-    * `:id` - the child specification identifier, defaults to the current module
+    * `:id` - the child specification id, defaults to the current module
     * `:start` - how to start the child process (defaults to calling `__MODULE__.start_link/1`)
     * `:restart` - when the child should be restarted, defaults to `:permanent`
     * `:shutdown` - how to shut down the child
@@ -144,7 +144,7 @@ defmodule Agent do
 
   See `Supervisor`.
   """
-  @doc since: "1.5.0"
+  @since "1.5.0"
   def child_spec(arg) do
     %{
       id: Agent,

lib/elixir/lib/agent/server.ex

@@ -23,10 +23,18 @@ defmodule Agent.Server do
     {:reply, :ok, run(fun, [state])}
   end
 
+  def handle_call(msg, from, state) do
+    super(msg, from, state)
+  end
+
   def handle_cast({:cast, fun}, state) do
     {:noreply, run(fun, [state])}
   end
 
+  def handle_cast(msg, state) do
+    super(msg, state)
+  end
+
   def code_change(_old, state, fun) do
     {:ok, run(fun, [state])}
   end
@@ -37,8 +45,8 @@ defmodule Agent.Server do
   end
 
   defp get_initial_call(fun) when is_function(fun, 0) do
-    {:module, module} = Function.info(fun, :module)
-    {:name, name} = Function.info(fun, :name)
+    {:module, module} = :erlang.fun_info(fun, :module)
+    {:name, name} = :erlang.fun_info(fun, :name)
     {module, name, 0}
   end
 

lib/elixir/lib/application.ex

@@ -2,87 +2,61 @@ defmodule Application do
   @moduledoc """
   A module for working with applications and defining application callbacks.
 
-  Applications are the idiomatic way to package software in Erlang/OTP. To get
-  the idea, they are similar to the "library" concept common in other
-  programming languages, but with some additional characteristics.
+  In Elixir (actually, in Erlang/OTP), an application is a component
+  implementing some specific functionality, that can be started and stopped
+  as a unit, and which can be re-used in other systems.
 
-  An application is a component implementing some specific functionality, with a
-  standardized directory structure, configuration, and lifecycle. Applications
-  are *loaded*, *started*, and *stopped*.
+  Applications are defined with an application file named `APP.app` where
+  `APP` is the application name, usually in `underscore_case`. The application
+  file must reside in the same `ebin` directory as the compiled modules of the
+  application. In Elixir, the Mix build tool is responsible for compiling your
+  source code and generating your application `.app` file. You can learn more
+  about the generation of `.app` files by typing `mix help compile.app`.
 
-  ## The application resource file
+  Once your application is compiled, running your system is a matter of starting
+  your current application and its dependencies. Differently from other languages,
+  Elixir does not have a `main` procedure that is responsible for starting your
+  system. Instead, you start one or more applications, each with their own
+  initialization and termination logic.
 
-  Applications are specified in their [*resource
-  file*](http://erlang.org/doc/man/app.html), which is a file called `APP.app`,
-  where `APP` is the application name. For example, the application resource
-  file of the OTP application `ex_unit` is called `ex_unit.app`.
+  Applications also provide an "application environment", which provides one
+  mechanism for configuring long running applications. We will learn more about
+  the tooling, start and shutdown and the application environment in the next
+  sections.
 
-  You'll find the resource file of an application in its `ebin` directory, it is
-  generated automatically by Mix. Some of its keys are taken from the keyword
-  lists returned by the `project/0` and `application/0` functions defined in
-  `mix.exs`, and others are generated by Mix itself.
+  ## Start and shutdown
 
-  You can learn more about the generation of application resource files in the
-  documentation of `Mix.Tasks.Compile.App`, available as well by running `mix
-  help compile.app`.
+  Starting an application is done via the "application module callback", which
+  is a module that defines the `start/2` function. The `start/2` function should
+  then start a supervisor, which is often called as the top-level supervisor, since
+  it sits at the root of a potentially long supervision tree. When the system is
+  shutting down, all applications shut down their top-level supervisor, which
+  terminates children in the opposite order they are started.
 
-  ## The application environment
+  Shutting down a live system cleanly can be done by calling `System.stop/1`.
+  It will shut down all applications in the opposite order they are started.
+  Each application will then shutdown its top-level supervisor, if one is
+  available, [which then shuts down its children](Supervisor.html#module-start-and-shutdown).
 
-  The key `env` of an application resource file has a list of tuples that map
-  atoms to terms, and its contents are known as the application *environment*.
-  Note that this environment is unrelated to the operating system environment.
+  From Erlang/OTP 19.1, a SIGTERM from the operating system will automatically
+  translate to `System.stop/0`. Erlang/OTP 20 gives user more explicit control
+  over OS signals via the `:os.set_signal/2` function.
 
-  By default, the environment of an application is an empty list. In a Mix
-  project you can set that key in `application/0`:
+  ### Application module callback
 
-      def application do
-        [env: [redis_host: "localhost"]]
-      end
+  An application may start and stop a supervision tree when it boots via
+  the application module callback.
 
-  and the generated application resource file is going to have it included.
-
-  The environment is available after loading the application, which is a process
-  explained later:
-
-      Application.load(:APP_NAME)
-      #=> :ok
-
-      Application.get_env(:APP_NAME, :redis_host)
-      #=> "localhost"
-
-  In Mix projects, the environment of the application and its dependencies can
-  be overridden via the `config/config.exs` file. If you start the application
-  with Mix, that configuration is available at compile time, and at runtime too,
-  but take into account it is not included in the generated application resource
-  file, and it is not available if you start the application without Mix.
-
-  For example, someone using your application can override its `:redis_host`
-  environment variable as follows:
-
-      config :APP_NAME, redis_host: "redis.local"
-
-  The function `put_env/3` allows dynamic configuration of the application
-  environment, but as a rule of thumb each application is responsible for its
-  own environment. Please do not use the functions in this module for directly
-  accessing or modifying the environment of other applications.
-
-  The application environment can be overriden via the `-config` option of
-  `erl`, as well as command-line flags, as we are going to see below.
-
-  ## The application callback module
-
-  The `mod` key of an application resource file configures an application
-  callback module and start argument:
+  The first step is to pass the module callback in the application definition
+  in the `mix.exs` file:
 
       def application do
         [mod: {MyApp, []}]
       end
 
-  This key is optional, only needed for applications that start a supervision tree.
-
-  The `MyApp` module given to `:mod` needs to implement the `Application` behaviour.
-  This can be done by putting `use Application` in that module and implementing the
-  `c:start/2` callback, for example:
+  Our application now requires the `MyApp` module to provide an application
+  callback. This can be done by invoking `use Application` in that module and
+  defining a `start/2` callback, for example:
 
       defmodule MyApp do
         use Application
@@ -93,14 +67,17 @@ defmodule Application do
         end
       end
 
-  The `c:start/2` callback has to spawn and link a supervisor and return `{:ok,
-  pid}` or `{:ok, pid, state}`, where `pid` is the PID of the supervisor, and
-  `state` is an optional application state. `args` is the second element of the
-  tuple given to the `:mod` option.
+  `start/2` typically returns `{:ok, pid}` or `{:ok, pid, state}` where
+  `pid` identifies the supervision tree and `state` is the application state.
+  `args` is the second element of the tuple given to the `:mod` option.
 
-  The `type` argument passed to `c:start/2` is usually `:normal` unless in a
+  The `type` argument passed to `start/2` is usually `:normal` unless in a
   distributed setup where application takeovers and failovers are configured.
-  Distributed applications are beyond the scope of this documentation.
+  Distributed applications is beyond the scope of this documentation. For those
+  interested on the topic, please access the OTP documentation:
+
+    * [`:application` module](http://www.erlang.org/doc/man/application.html)
+    * [Applications – OTP Design Principles](http://www.erlang.org/doc/design_principles/applications.html)
 
   When an application is shutting down, its `c:stop/1` callback is called after
   the supervision tree has been stopped by the runtime. This callback allows the
@@ -116,90 +93,11 @@ defmodule Application do
   tree is terminated. Its argument is the state returned by `c:start/2`, if it did,
   or `[]` otherwise, and its return value is passed to `c:stop/1`.
 
-  ## The application lifecycle
-
-  ### Loading applications
-
-  Applications are *loaded*, which means that the runtime finds and processes
-  their resource files:
-
-      Application.load(:ex_unit)
-      #=> :ok
-
-  If an application has included applications, they are also loaded. And the
-  procedure recurses if they in turn have included applications. Included
-  applications are unrelated to applications in Mix umbrella projects, they are
-  an Erlang/OTP concept that has to do with coordinated starts.
-
-  When an application is loaded, the environment specified in its resource file
-  is merged with any overrides from config files passed to `erl` via the
-  `-config` option. It is worth highlighting that releases pass `sys.config`
-  this way. The resulting environment can still be overridden again via specific
-  `-Application` flags passed to `erl`.
-
-  Loading an application *does not* load its modules.
-
-  In practice, you rarely load applications by hand because that is part of the
-  start process, explained next.
-
-  ### Starting applications
-
-  Applications are also *started*:
-
-      Application.start(:ex_unit)
-      #=> :ok
-
-  Once your application is compiled, running your system is a matter of starting
-  your current application and its dependencies. Differently from other languages,
-  Elixir does not have a `main` procedure that is responsible for starting your
-  system. Instead, you start one or more applications, each with their own
-  initialization and termination logic.
-
-  When an application is started, the runtime loads it if it hasn't been loaded
-  yet (in the technical sense described above). Then, it checks if the
-  dependencies listed in the `applications` key of the resource file are already
-  started. Having at least one dependency not started is an error condition, but
-  when you start an application with `mix run`, Mix takes care of starting all
-  the dependencies for you, so in practice you don't need to worry about it
-  unless you are starting applications manually with the API provided by this
-  module.
-
-  If the application does not have a callback module configured, starting is
-  done at this point. Otherwise, its `c:start/2` callback if invoked. The PID of
-  the top-level supervisor returned by this function is stored by the runtime
-  for later use, and the returned application state is saved too, if any.
-
-  ### Stopping applications
-
-  Started applications are, finally, *stopped*:
-
-      Application.stop(:ex_unit)
-      #=> :ok
-
-  Stopping an application without a callback module is defined, but except for
-  some system tracing, it is in practice a no-op.
-
-  Stopping an application with a callback module has three steps:
-
-  1. If present, invoke the optional callback `c:prep_stop/1`.
-  2. Terminate the top-level supervisor.
-  3. Invoke the required callback `c:stop/1`.
-
-  The arguments passed to the callbacks are related to the state optionally
-  returned by `c:start/2`, and are documented in the section about the callback
-  module above.
-
-  It is important to highlight that step 2 is a blocking one. Termination of a
-  supervisor triggers a recursive chain of children terminations, therefore
-  orderly shutting down all descendant processes. The `c:stop/1` callback is
-  invoked only after termination of the whole supervision tree.
-
-  Shutting down a live system cleanly can be done by calling `System.stop/1`. It
-  will shut down every application in the opposite order they had been started.
-
-  From Erlang/OTP 19.1, a SIGTERM from the operating system will automatically
-  translate to `System.stop/0`. Erlang/OTP 20 gives user more explicit control
-  over OS signals via the `:os.set_signal/2` function.
+  An application without a supervision tree doesn't define an application
+  module callback in the application definition in `mix.exs` file. Even though
+  there is no module with application callbacks such as `start/2` and
+  `stop/1`, the application can be started and stopped the same way as an
+  application with a supervision tree.
 
   ## Tooling
 
@@ -220,14 +118,41 @@ defmodule Application do
   when tools must be shared between developers and not as deployment options.
   See `mix help archive.build` and `mix help escript.build` for more detail.
 
-  ## Further information
+  ## Application environment
 
-  For further details on applications please check the documentation of the
-  [`application`](http://www.erlang.org/doc/man/application.html) Erlang module,
-  and the
-  [Applications](http://www.erlang.org/doc/design_principles/applications.html)
-  section of the [OTP Design Principles User's
-  Guide](http://erlang.org/doc/design_principles/users_guide.html).
+  Once an application is started, OTP provides an application environment
+  that can be used to configure the application.
+
+  Assuming you are inside a Mix project, you can edit the `application/0`
+  function in the `mix.exs` file to the following:
+
+      def application do
+        [env: [hello: :world]]
+      end
+
+  In the application function, we can define the default environment values
+  for our application. By starting your application with `iex -S mix`, you
+  can access the default value:
+
+      Application.get_env(:APP_NAME, :hello)
+      #=> :world
+
+  Applications and dependencies in Mix projects are typically configured
+  via the `config/config.exs` file. For example, someone using your
+  application can configure the `:hello` key as follows:
+
+      config :APP_NAME, hello: :brand_new_world
+
+  Keep in mind configuration files are only useful to configure static
+  values. For example, if you need to configure your applications based
+  on the system environment, the file system or on database entries,
+  then those configurations are better placed at runtime. For example,
+  one may configure applications dynamically via `put_env/3`.
+
+  Keep in mind that each application is responsible for its environment.
+  Do not use the functions in this module for directly accessing or modifying
+  the environment of other applications (as it may lead to inconsistent
+  data in the application environment).
   """
 
   @doc """
@@ -326,8 +251,7 @@ defmodule Application do
   @type key :: atom
   @type value :: term
   @type state :: term
-  @type start_type :: :normal | {:takeover, node} | {:failover, node}
-  @type restart_type :: :permanent | :transient | :temporary
+  @type start_type :: :permanent | :transient | :temporary
 
   @application_keys [
     :description,
@@ -404,41 +328,6 @@ defmodule Application do
 
   If the configuration parameter does not exist, the function returns the
   `default` value.
-
-  ## Examples
-
-  `get_env/3` is commonly used to read the configuration of your OTP applications.
-  Since Mix configurations are commonly used to configure applications, we will use
-  this as a point of illustration.
-
-  Consider a new application `:my_app`. `:my_app` contains a database engine which
-  supports a pool of databases. The database engine needs to know the configuration for
-  each of those databases, and that configuration is supplied by key-value pairs in
-  environment of `:my_app`.
-
-      config :my_app, Databases.RepoOne,
-        # A database configuration
-        ip: "localhost"
-        port: 5433
-
-      config :my_app, Databases.RepoTwo,
-        # Another database configuration (for the same OTP app)
-        ip: "localhost"
-        port: 20717
-
-      config :my_app, my_app_databases: [Databases.RepoOne, Databases.RepoTwo]
-
-  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.
-
-  **Important:** if you are writing a library to be used by other developers,
-  it is generally recommended to avoid the application environment, as the
-  application environment is effectively a global storage. For more information,
-  read our [library guidelines](/library-guidelines.html).
   """
   @spec get_env(app, key, value) :: value
   def get_env(app, key, default \\ nil) do
@@ -532,7 +421,7 @@ defmodule Application do
       :ok = Application.ensure_started(:my_test_dep)
 
   """
-  @spec ensure_started(app, restart_type) :: :ok | {:error, term}
+  @spec ensure_started(app, start_type) :: :ok | {:error, term}
   def ensure_started(app, type \\ :temporary) when is_atom(app) do
     :application.ensure_started(app, type)
   end
@@ -544,7 +433,7 @@ defmodule Application do
   `:applications` in the `.app` file in case they were not previously
   started.
   """
-  @spec ensure_all_started(app, restart_type) :: {:ok, [app]} | {:error, {app, term}}
+  @spec ensure_all_started(app, start_type) :: {:ok, [app]} | {:error, {app, term}}
   def ensure_all_started(app, type \\ :temporary) when is_atom(app) do
     :application.ensure_all_started(app, type)
   end
@@ -583,7 +472,7 @@ defmodule Application do
   Note also that the `:transient` type is of little practical use, since when a
   supervision tree terminates, the reason is set to `:shutdown`, not `:normal`.
   """
-  @spec start(app, restart_type) :: :ok | {:error, term}
+  @spec start(app, start_type) :: :ok | {:error, term}
   def start(app, type \\ :temporary) when is_atom(app) do
     :application.start(app, type)
   end
@@ -657,26 +546,8 @@ defmodule Application do
 
   @doc """
   Returns the given path inside `app_dir/1`.
-
-  If `path` is a string, then it will be used as the path inside `app_dir/1`. If
-  `path` is a list of strings, it will be joined (see `Path.join/1`) and the result
-  will be used as the path inside `app_dir/1`.
-
-  ## Examples
-
-      File.mkdir_p!("foo/ebin")
-      Code.prepend_path("foo/ebin")
-
-      Application.app_dir(:foo, "my_path")
-      #=> "foo/my_path"
-
-      Application.app_dir(:foo, ["my", "nested", "path"])
-      #=> "foo/my/nested/path"
-
   """
   @spec app_dir(app, String.t() | [String.t()]) :: String.t()
-  def app_dir(app, path)
-
   def app_dir(app, path) when is_binary(path) do
     Path.join(app_dir(app), path)
   end
@@ -688,7 +559,7 @@ defmodule Application do
   @doc """
   Returns a list with information about the applications which are currently running.
   """
-  @spec started_applications(timeout) :: [{app, description :: charlist(), vsn :: charlist()}]
+  @spec started_applications(timeout) :: [tuple]
   def started_applications(timeout \\ 5000) do
     :application.which_applications(timeout)
   end
@@ -696,7 +567,7 @@ defmodule Application do
   @doc """
   Returns a list with information about the applications which have been loaded.
   """
-  @spec loaded_applications :: [{app, description :: charlist(), vsn :: charlist()}]
+  @spec loaded_applications :: [tuple]
   def loaded_applications do
     :application.loaded_applications()
   end

lib/elixir/lib/atom.ex

@@ -38,8 +38,8 @@ defmodule Atom do
   end
 
   # TODO: Remove by 2.0
+  # (hard-deprecated in elixir_dispatch)
   @doc false
-  @deprecated "Use Atom.to_charlist/1 instead"
   @spec to_char_list(atom) :: charlist
   def to_char_list(atom), do: Atom.to_charlist(atom)
 end

lib/elixir/lib/base.ex

@@ -184,19 +184,16 @@ defmodule Base do
   end
 
   defp decode_char_clauses(alphabet, :mixed) when length(alphabet) == 32 do
-    clauses =
-      alphabet
-      |> Stream.with_index()
-      |> Enum.flat_map(fn {encoding, value} = pair ->
-        if encoding in ?A..?Z do
-          [pair, {encoding - ?A + ?a, value}]
-        else
-          [pair]
-        end
-      end)
-      |> decode_clauses()
-
-    clauses ++ bad_digit_clause()
+    alphabet
+    |> Stream.with_index()
+    |> Enum.flat_map(fn {encoding, value} = pair ->
+      if encoding in ?A..?Z do
+        [pair, {encoding - ?A + ?a, value}]
+      else
+        [pair]
+      end
+    end)
+    |> decode_clauses()
   end
 
   defp decode_mixed_clauses(first, second) do

lib/elixir/lib/behaviour.ex

@@ -1,19 +1,15 @@
 defmodule Behaviour do
   @moduledoc """
-  Mechanism for handling behaviours.
+  WARNING: this module is deprecated.
 
-  This module is deprecated. Instead of `defcallback/1` and
-  `defmacrocallback/1`, the `@callback` and `@macrocallback`
-  module attributes can be used (respectively). See the
-  documentation for `Module` for more information on these
-  attributes.
+  Instead of `defcallback/1` and `defmacrocallback/1`, the `@callback` and
+  `@macrocallback` module attributes can be used (respectively). See the
+  documentation for `Module` for more information on these attributes.
 
   Instead of `MyModule.__behaviour__(:callbacks)`,
   `MyModule.behaviour_info(:callbacks)` can be used.
   """
 
-  @moduledoc deprecated: "Use @callback and @macrocallback attributes instead"
-
   @doc """
   Defines a function callback according to the given type specification.
   """
@@ -101,20 +97,14 @@ defmodule Behaviour do
       end
 
       def __behaviour__(:docs) do
-        {:docs_v1, _, :elixir, _, _, _, docs} = Code.fetch_docs(__MODULE__)
-
-        for {{kind, name, arity}, line, _, doc, _} <- docs, kind in [:callback, :macrocallback] do
+        for {tuple, line, kind, docs} <- Code.get_docs(__MODULE__, :callback_docs) do
           case kind do
-            :callback -> {{name, arity}, line, :def, __behaviour__doc_value(doc)}
-            :macrocallback -> {{name, arity}, line, :defmacro, __behaviour__doc_value(doc)}
+            :callback -> {tuple, line, :def, docs}
+            :macrocallback -> {tuple, line, :defmacro, docs}
           end
         end
       end
 
-      defp __behaviour__doc_value(:none), do: nil
-      defp __behaviour__doc_value(:hidden), do: false
-      defp __behaviour__doc_value(%{"en" => doc}), do: doc
-
       import unquote(__MODULE__)
     end
   end

lib/elixir/lib/bitwise.ex

@@ -6,9 +6,9 @@ defmodule Bitwise do
   operators. For example:
 
       iex> use Bitwise
-      iex> bnot(1) # named
+      iex> bnot 1   # named
       -2
-      iex> 1 &&& 1 # operator
+      iex> 1 &&& 1  # operator
       1
 
   If you prefer to use only operators or skip them, you can
@@ -29,10 +29,7 @@ defmodule Bitwise do
   All bitwise macros can be used in guards:
 
       iex> use Bitwise
-      iex> odd? = fn
-      ...>   int when band(int, 1) == 1 -> true
-      ...>   _ -> false
-      ...> end
+      iex> odd? = fn int when band(int, 1) == 1 -> true; _ -> false end
       iex> odd?.(1)
       true
 

lib/elixir/lib/calendar.ex

@@ -118,12 +118,7 @@ defmodule Calendar do
   @callback days_in_month(year, month) :: day
 
   @doc """
-  Returns how many months there are in the given year.
-  """
-  @callback months_in_year(year) :: month
-
-  @doc """
-  Returns `true` if the given year is a leap year.
+  Returns true if the given year is a leap year.
 
   A leap year is a year of a longer length than normal. The exact meaning
   is up to the calendar. A calendar must return `false` if it does not support
@@ -170,24 +165,24 @@ defmodule Calendar do
   @callback time_to_string(hour, minute, second, microsecond) :: String.t()
 
   @doc """
-  Converts the given datetime (without time zone) into the `t:iso_days/0` format.
+  Converts the given datetime (with time zone) into the `t:iso_days` format.
   """
   @callback naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond) ::
               iso_days
 
   @doc """
-  Converts `t:iso_days/0` to the Calendar's datetime format.
+  Converts `t:iso_days` to the Calendar's datetime format.
   """
   @callback naive_datetime_from_iso_days(iso_days) ::
               {year, month, day, hour, minute, second, microsecond}
 
   @doc """
-  Converts the given time to the `t:day_fraction/0` format.
+  Converts the given time to the `t:day_fraction` format.
   """
   @callback time_to_day_fraction(hour, minute, second, microsecond) :: day_fraction
 
   @doc """
-  Converts `t:day_fraction/0` to the Calendar's time format.
+  Converts `t:day_fraction` to the Calendar's time format.
   """
   @callback time_from_day_fraction(day_fraction) :: {hour, minute, second, microsecond}
 
@@ -234,7 +229,6 @@ defmodule Calendar do
   between them. If they are compatible, this means that we can also convert
   dates as well as naive datetimes between them.
   """
-  @doc since: "1.5.0"
   @spec compatible_calendars?(Calendar.calendar(), Calendar.calendar()) :: boolean
   def compatible_calendars?(calendar, calendar), do: true
 
@@ -247,7 +241,6 @@ defmodule Calendar do
   Returns a microsecond tuple truncated to a given precision (`:microsecond`,
   `:millisecond` or `:second`).
   """
-  @doc since: "1.6.0"
   @spec truncate(Calendar.microsecond(), :microsecond | :millisecond | :second) ::
           Calendar.microsecond()
   def truncate(microsecond_tuple, :microsecond), do: microsecond_tuple

lib/elixir/lib/calendar/date.ex

@@ -3,8 +3,8 @@ defmodule Date do
   A Date struct and functions.
 
   The Date struct contains the fields year, month, day and calendar.
-  New dates can be built with the `new/3` function or using the
-  [`~D`](`Kernel.sigil_D/2`) sigil:
+  New dates can be built with the `new/3` function or using the `~D`
+  sigil:
 
       iex> ~D[2000-01-01]
       ~D[2000-01-01]
@@ -29,7 +29,7 @@ defmodule Date do
 
   ## Comparing dates
 
-  Comparisons in Elixir using `==/2`, `>/2`, `</2` and similar are structural
+  Comparisons in Elixir using `==`, `>`, `<` and similar are structural
   and based on the `Date` struct fields. For proper comparison between
   dates, use the `compare/2` function.
 
@@ -85,9 +85,8 @@ defmodule Date do
       true
       iex> Enum.reduce(range, 0, fn _date, acc -> acc - 1 end)
       -366
-
   """
-  @doc since: "1.5.0"
+
   @spec range(Date.t(), Date.t()) :: Date.Range.t()
   def range(%Date{calendar: calendar} = first, %Date{calendar: calendar} = last) do
     {first_days, _} = to_iso_days(first)
@@ -115,7 +114,6 @@ defmodule Date do
       true
 
   """
-  @doc since: "1.4.0"
   @spec utc_today(Calendar.calendar()) :: t
   def utc_today(calendar \\ Calendar.ISO)
 
@@ -131,7 +129,7 @@ defmodule Date do
   end
 
   @doc """
-  Returns `true` if the year in the given `date` is a leap year.
+  Returns true if the year in the given `date` is a leap year.
 
   ## Examples
 
@@ -147,7 +145,6 @@ defmodule Date do
       true
 
   """
-  @doc since: "1.4.0"
   @spec leap_year?(Calendar.date()) :: boolean()
   def leap_year?(date)
 
@@ -168,7 +165,6 @@ defmodule Date do
       29
 
   """
-  @doc since: "1.4.0"
   @spec days_in_month(Calendar.date()) :: Calendar.day()
   def days_in_month(date)
 
@@ -176,23 +172,6 @@ defmodule Date do
     calendar.days_in_month(year, month)
   end
 
-  @doc """
-  Returns the number of months in the given `date` year.
-
-  ## Example
-
-      iex> Date.months_in_year(~D[1900-01-13])
-      12
-
-  """
-  @doc since: "1.7.0"
-  @spec months_in_year(Calendar.date()) :: Calendar.month()
-  def months_in_year(date)
-
-  def months_in_year(%{calendar: calendar, year: year}) do
-    calendar.months_in_year(year)
-  end
-
   @doc """
   Builds a new ISO date.
 
@@ -233,8 +212,6 @@ defmodule Date do
       "2000-02-28"
       iex> Date.to_string(~N[2000-02-28 01:23:45])
       "2000-02-28"
-      iex> Date.to_string(~D[-0100-12-15])
-      "-0100-12-15"
 
   """
   @spec to_string(Calendar.date()) :: String.t()
@@ -263,31 +240,20 @@ defmodule Date do
   @spec from_iso8601(String.t(), Calendar.calendar()) :: {:ok, t} | {:error, atom}
   def from_iso8601(string, calendar \\ Calendar.ISO)
 
-  def from_iso8601(<<?-, rest::binary>>, calendar) do
-    with {:ok, %{year: year} = date} <- raw_from_iso8601(rest, calendar) do
-      {:ok, %{date | year: -year}}
-    end
-  end
-
-  def from_iso8601(<<rest::binary>>, calendar) do
-    raw_from_iso8601(rest, calendar)
-  end
-
-  [match_date, guard_date, read_date] = Calendar.ISO.__match_date__()
-
-  defp raw_from_iso8601(string, calendar) do
-    with unquote(match_date) <- string,
-         true <- unquote(guard_date) do
-      {year, month, day} = unquote(read_date)
-
-      with {:ok, date} <- new(year, month, day, Calendar.ISO) do
-        convert(date, calendar)
-      end
+  def from_iso8601(<<year::4-bytes, ?-, month::2-bytes, ?-, day::2-bytes>>, calendar) do
+    with {year, ""} <- Integer.parse(year),
+         {month, ""} <- Integer.parse(month),
+         {day, ""} <- Integer.parse(day) do
+      with {:ok, date} <- new(year, month, day, Calendar.ISO), do: convert(date, calendar)
     else
       _ -> {:error, :invalid_format}
     end
   end
 
+  def from_iso8601(<<_::binary>>, _calendar) do
+    {:error, :invalid_format}
+  end
+
   @doc """
   Parses the extended "Dates" format described by
   [ISO 8601:2004](https://en.wikipedia.org/wiki/ISO_8601).
@@ -300,7 +266,6 @@ defmodule Date do
       ~D[2015-01-23]
       iex> Date.from_iso8601!("2015:01:23")
       ** (ArgumentError) cannot parse "2015:01:23" as date, reason: :invalid_format
-
   """
   @spec from_iso8601!(String.t(), Calendar.calendar()) :: t
   def from_iso8601!(string, calendar \\ Calendar.ISO) do
@@ -337,19 +302,11 @@ defmodule Date do
 
   """
   @spec to_iso8601(Calendar.date(), :extended | :basic) :: String.t()
-  def to_iso8601(date, format \\ :extended)
-
-  def to_iso8601(%{calendar: Calendar.ISO} = date, format) when format in [:basic, :extended] do
-    %{year: year, month: month, day: day} = date
+  def to_iso8601(date, format \\ :extended) when format in [:basic, :extended] do
+    %{year: year, month: month, day: day} = convert!(date, Calendar.ISO)
     Calendar.ISO.date_to_iso8601(year, month, day, format)
   end
 
-  def to_iso8601(%{calendar: _} = date, format) when format in [:basic, :extended] do
-    date
-    |> convert!(Calendar.ISO)
-    |> to_iso8601()
-  end
-
   @doc """
   Converts the given `date` to an Erlang date tuple.
 
@@ -440,7 +397,6 @@ defmodule Date do
       :eq
 
   """
-  @doc since: "1.4.0"
   @spec compare(Calendar.date(), Calendar.date()) :: :lt | :eq | :gt
   def compare(%{calendar: calendar} = date1, %{calendar: calendar} = date2) do
     %{year: year1, month: month1, day: day1} = date1
@@ -488,7 +444,6 @@ defmodule Date do
       {:ok, %Date{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1}}
 
   """
-  @doc since: "1.5.0"
   @spec convert(Calendar.date(), Calendar.calendar()) ::
           {:ok, t} | {:error, :incompatible_calendars}
   def convert(%{calendar: calendar, year: year, month: month, day: day}, calendar) do
@@ -522,7 +477,6 @@ defmodule Date do
       %Date{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1}
 
   """
-  @doc since: "1.5.0"
   @spec convert!(Calendar.date(), Calendar.calendar()) :: t
   def convert!(date, calendar) do
     case convert(date, calendar) do
@@ -548,13 +502,11 @@ defmodule Date do
       ~D[2000-01-01]
       iex> Date.add(~D[2000-01-01], 2)
       ~D[2000-01-03]
+
       iex> Date.add(~N[2000-01-01 09:00:00], 2)
       ~D[2000-01-03]
-      iex> Date.add(~D[-0010-01-01], -2)
-      ~D[-0011-12-30]
 
   """
-  @doc since: "1.5.0"
   @spec add(Calendar.date(), integer()) :: t
   def add(%{calendar: calendar} = date, days) do
     {iso_days, fraction} = to_iso_days(date)
@@ -574,13 +526,11 @@ defmodule Date do
       2
       iex> Date.diff(~D[2000-01-01], ~D[2000-01-03])
       -2
-      iex> Date.diff(~D[0000-01-02], ~D[-0001-12-30])
-      3
+
       iex> Date.diff(~D[2000-01-01], ~N[2000-01-03 09:00:00])
       -2
 
   """
-  @doc since: "1.5.0"
   @spec diff(Calendar.date(), Calendar.date()) :: integer
   def diff(%{calendar: Calendar.ISO} = date1, %{calendar: Calendar.ISO} = date2) do
     %{year: year1, month: month1, day: day1} = date1
@@ -634,11 +584,8 @@ defmodule Date do
       2
       iex> Date.day_of_week(~N[2016-11-01 01:23:45])
       2
-      iex> Date.day_of_week(~D[-0015-10-30])
-      3
 
   """
-  @doc since: "1.4.0"
   @spec day_of_week(Calendar.date()) :: non_neg_integer()
   def day_of_week(date)
 

lib/elixir/lib/calendar/date_range.ex

@@ -15,12 +15,10 @@ defmodule Date.Range do
   @type t :: %__MODULE__{
           first: Date.t(),
           last: Date.t(),
-          first_in_iso_days: iso_days(),
-          last_in_iso_days: iso_days()
+          first_in_iso_days: Calendar.iso_days(),
+          last_in_iso_days: Calendar.iso_days()
         }
 
-  @typep iso_days() :: Calendar.iso_days()
-
   defstruct [:first, :last, :first_in_iso_days, :last_in_iso_days]
 
   defimpl Enumerable do

lib/elixir/lib/calendar/datetime.ex

@@ -8,7 +8,7 @@ defmodule DateTime do
   well as the zone abbreviation field used exclusively
   for formatting purposes.
 
-  Remember, comparisons in Elixir using `==/2`, `>/2`, `</2` and friends
+  Remember, comparisons in Elixir using `==`, `>`, `<` and friends
   are structural and based on the DateTime struct fields. For proper
   comparison between datetimes, use the `compare/2` function.
 
@@ -17,7 +17,7 @@ defmodule DateTime do
   Such functions expect `t:Calendar.datetime/0` in their typespecs
   (instead of `t:t/0`).
 
-  Developers should avoid creating the `DateTime` struct directly
+  Developers should avoid creating the DateTime struct directly
   and instead rely on the functions provided by this module as
   well as the ones in 3rd party calendar libraries.
 
@@ -25,12 +25,12 @@ defmodule DateTime do
 
   You will notice this module only contains conversion
   functions as well as functions that work on UTC. This
-  is because a proper `DateTime` implementation requires a
-  time zone database which currently is not provided as part
+  is because a proper DateTime implementation requires a
+  TimeZone database which currently is not provided as part
   of Elixir.
 
   Such may be addressed in upcoming versions, meanwhile,
-  use 3rd party packages to provide `DateTime` building and
+  use 3rd party packages to provide DateTime building and
   similar functionality with time zone backing.
   """
 
@@ -96,17 +96,17 @@ defmodule DateTime do
 
   ## Examples
 
-      iex> {:ok, datetime} = DateTime.from_unix(1_464_096_368)
+      iex> {:ok, datetime} = DateTime.from_unix(1464096368)
       iex> datetime
       #DateTime<2016-05-24 13:26:08Z>
 
-      iex> {:ok, datetime} = DateTime.from_unix(1_432_560_368_868_569, :microsecond)
+      iex> {:ok, datetime} = DateTime.from_unix(1432560368868569, :microsecond)
       iex> datetime
       #DateTime<2015-05-25 13:26:08.868569Z>
 
   The unit can also be an integer as in `t:System.time_unit/0`:
 
-      iex> {:ok, datetime} = DateTime.from_unix(143_256_036_886_856, 1024)
+      iex> {:ok, datetime} = DateTime.from_unix(143256036886856, 1024)
       iex> datetime
       #DateTime<6403-03-17 07:05:22.320Z>
 
@@ -155,10 +155,10 @@ defmodule DateTime do
       iex> DateTime.from_unix!(0)
       #DateTime<1970-01-01 00:00:00Z>
 
-      iex> DateTime.from_unix!(1_464_096_368)
+      iex> DateTime.from_unix!(1464096368)
       #DateTime<2016-05-24 13:26:08Z>
 
-      iex> DateTime.from_unix!(1_432_560_368_868_569, :microsecond)
+      iex> DateTime.from_unix!(1432560368868569, :microsecond)
       #DateTime<2015-05-25 13:26:08.868569Z>
 
   """
@@ -186,7 +186,6 @@ defmodule DateTime do
       #DateTime<2016-05-24 13:26:08.003Z>
 
   """
-  @doc since: "1.4.0"
   @spec from_naive(NaiveDateTime.t(), Calendar.time_zone()) :: {:ok, t}
   def from_naive(naive_datetime, time_zone)
 
@@ -232,7 +231,6 @@ defmodule DateTime do
       #DateTime<2016-05-24 13:26:08.003Z>
 
   """
-  @doc since: "1.4.0"
   @spec from_naive!(NaiveDateTime.t(), Calendar.time_zone()) :: t
   def from_naive!(naive_datetime, time_zone) do
     case from_naive(naive_datetime, time_zone) do
@@ -256,7 +254,7 @@ defmodule DateTime do
 
   ## Examples
 
-      iex> 1_464_096_368 |> DateTime.from_unix!() |> DateTime.to_unix()
+      iex> 1464096368 |> DateTime.from_unix!() |> DateTime.to_unix()
       1464096368
 
       iex> dt = %DateTime{calendar: Calendar.ISO, day: 20, hour: 18, microsecond: {273806, 6},
@@ -416,8 +414,12 @@ defmodule DateTime do
   @spec to_iso8601(Calendar.datetime(), :extended | :basic) :: String.t()
   def to_iso8601(datetime, format \\ :extended)
 
-  def to_iso8601(%{calendar: Calendar.ISO} = datetime, format)
-      when format in [:extended, :basic] do
+  def to_iso8601(_, format) when format not in [:extended, :basic] do
+    raise ArgumentError,
+          "DateTime.to_iso8601/2 expects format to be :extended or :basic, got: #{inspect(format)}"
+  end
+
+  def to_iso8601(%{calendar: Calendar.ISO} = datetime, format) do
     %{
       year: year,
       month: month,
@@ -448,7 +450,7 @@ defmodule DateTime do
     )
   end
 
-  def to_iso8601(%{calendar: _} = datetime, format) when format in [:extended, :basic] do
+  def to_iso8601(%{calendar: _} = datetime, format) do
     datetime
     |> convert!(Calendar.ISO)
     |> to_iso8601(format)
@@ -485,14 +487,6 @@ defmodule DateTime do
       iex> datetime
       #DateTime<2015-01-23 21:20:07.123Z>
 
-      iex> {:ok, datetime, 0} = DateTime.from_iso8601("-2015-01-23T23:50:07Z")
-      iex> datetime
-      #DateTime<-2015-01-23 23:50:07Z>
-
-      iex> {:ok, datetime, 9000} = DateTime.from_iso8601("-2015-01-23T23:50:07,123+02:30")
-      iex> datetime
-      #DateTime<-2015-01-23 21:20:07.123Z>
-
       iex> DateTime.from_iso8601("2015-01-23P23:50:07")
       {:error, :invalid_format}
       iex> DateTime.from_iso8601("2015-01-23 23:50:07A")
@@ -510,79 +504,50 @@ defmodule DateTime do
       {:error, :invalid_format}
 
   """
-  @doc since: "1.4.0"
   @spec from_iso8601(String.t(), Calendar.calendar()) ::
           {:ok, t, Calendar.utc_offset()} | {:error, atom}
-  def from_iso8601(string, calendar \\ Calendar.ISO)
-
-  def from_iso8601(<<?-, rest::binary>>, calendar) do
-    raw_from_iso8601(rest, calendar, true)
-  end
-
-  def from_iso8601(<<rest::binary>>, calendar) do
-    raw_from_iso8601(rest, calendar, false)
-  end
-
-  @sep [?\s, ?T]
-  [match_date, guard_date, read_date] = Calendar.ISO.__match_date__()
-  [match_time, guard_time, read_time] = Calendar.ISO.__match_time__()
-
-  defp raw_from_iso8601(string, calendar, is_negative_datetime) do
-    with <<unquote(match_date), sep, unquote(match_time), rest::binary>> <- string,
-         true <- unquote(guard_date) and sep in @sep and unquote(guard_time),
+  def from_iso8601(string, calendar \\ Calendar.ISO) when is_binary(string) do
+    with <<year::4-bytes, ?-, month::2-bytes, ?-, day::2-bytes, sep, rest::binary>> <- string,
+         true <- sep in [?\s, ?T],
+         <<hour::2-bytes, ?:, min::2-bytes, ?:, sec::2-bytes, rest::binary>> <- rest,
+         {year, ""} <- Integer.parse(year),
+         {month, ""} <- Integer.parse(month),
+         {day, ""} <- Integer.parse(day),
+         {hour, ""} <- Integer.parse(hour),
+         {minute, ""} <- Integer.parse(min),
+         {second, ""} <- Integer.parse(sec),
          {microsecond, rest} <- Calendar.ISO.parse_microsecond(rest),
-         {offset, ""} <- Calendar.ISO.parse_offset(rest) do
-      {year, month, day} = unquote(read_date)
-      {hour, minute, second} = unquote(read_time)
-      year = if is_negative_datetime, do: -year, else: year
+         {:ok, date} <- Date.new(year, month, day),
+         {:ok, time} <- Time.new(hour, minute, second, microsecond),
+         {:ok, offset} <- parse_offset(rest) do
+      %{year: year, month: month, day: day} = date
+      %{hour: hour, minute: minute, second: second, microsecond: microsecond} = time
+      {_, precision} = microsecond
 
-      cond do
-        not calendar.valid_date?(year, month, day) ->
-          {:error, :invalid_date}
+      datetime =
+        Calendar.ISO.naive_datetime_to_iso_days(
+          year,
+          month,
+          day,
+          hour,
+          minute,
+          second,
+          microsecond
+        )
+        |> apply_tz_offset(offset)
+        |> from_iso_days("Etc/UTC", "UTC", 0, 0, calendar, precision)
 
-        not calendar.valid_time?(hour, minute, second, microsecond) ->
-          {:error, :invalid_time}
-
-        offset == 0 ->
-          datetime = %DateTime{
-            calendar: calendar,
-            year: year,
-            month: month,
-            day: day,
-            hour: hour,
-            minute: minute,
-            second: second,
-            microsecond: microsecond,
-            std_offset: 0,
-            utc_offset: 0,
-            zone_abbr: "UTC",
-            time_zone: "Etc/UTC"
-          }
-
-          {:ok, datetime, 0}
-
-        is_nil(offset) ->
-          {:error, :missing_offset}
-
-        true ->
-          {_, precision} = microsecond
-
-          datetime =
-            Calendar.ISO.naive_datetime_to_iso_days(
-              year,
-              month,
-              day,
-              hour,
-              minute,
-              second,
-              microsecond
-            )
-            |> apply_tz_offset(offset)
-            |> from_iso_days("Etc/UTC", "UTC", 0, 0, calendar, precision)
-
-          {:ok, %{datetime | microsecond: microsecond}, offset}
-      end
+      {:ok, %{datetime | microsecond: microsecond}, offset}
     else
+      {:error, reason} -> {:error, reason}
+      _ -> {:error, :invalid_format}
+    end
+  end
+
+  defp parse_offset(rest) do
+    case Calendar.ISO.parse_offset(rest) do
+      {offset, ""} when is_integer(offset) -> {:ok, offset}
+      {nil, ""} -> {:error, :missing_offset}
       _ -> {:error, :invalid_format}
     end
   end
@@ -610,12 +575,6 @@ defmodule DateTime do
       iex> DateTime.to_string(dt)
       "2000-02-29 23:00:07-04:00 AMT America/Manaus"
 
-      iex> dt = %DateTime{year: -100, month: 12, day: 19, zone_abbr: "CET",
-      ...>                hour: 3, minute: 20, second: 31, microsecond: {0, 0},
-      ...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Stockholm"}
-      iex> DateTime.to_string(dt)
-      "-0100-12-19 03:20:31+01:00 CET Europe/Stockholm"
-
   """
   @spec to_string(Calendar.datetime()) :: String.t()
   def to_string(%{calendar: calendar} = datetime) do
@@ -670,7 +629,6 @@ defmodule DateTime do
       :gt
 
   """
-  @doc since: "1.4.0"
   @spec compare(Calendar.datetime(), Calendar.datetime()) :: :lt | :eq | :gt
   def compare(
         %{calendar: _, utc_offset: utc_offset1, std_offset: std_offset1} = datetime1,
@@ -702,8 +660,6 @@ defmodule DateTime do
 
   The answer can be returned in any `unit` available from `t:System.time_unit/0`.
 
-  Leap seconds are not taken into account.
-
   This function returns the difference in seconds where seconds are measured
   according to `Calendar.ISO`.
 
@@ -721,7 +677,6 @@ defmodule DateTime do
       -18000
 
   """
-  @doc since: "1.5.0"
   @spec diff(Calendar.datetime(), Calendar.datetime()) :: integer()
   def diff(
         %{utc_offset: utc_offset1, std_offset: std_offset1} = datetime1,
@@ -761,7 +716,6 @@ defmodule DateTime do
       #DateTime<2017-11-07 11:45:18+01:00 CET Europe/Paris>
 
   """
-  @doc since: "1.6.0"
   @spec truncate(t(), :microsecond | :millisecond | :second) :: t()
   def truncate(%DateTime{microsecond: microsecond} = datetime, precision) do
     %{datetime | microsecond: Calendar.truncate(microsecond, precision)}
@@ -790,7 +744,6 @@ defmodule DateTime do
                       zone_abbr: "AMT"}}
 
   """
-  @doc since: "1.5.0"
   @spec convert(Calendar.datetime(), Calendar.calendar()) ::
           {:ok, t} | {:error, :incompatible_calendars}
 
@@ -865,7 +818,6 @@ defmodule DateTime do
                 zone_abbr: "AMT"}
 
   """
-  @doc since: "1.5.0"
   @spec convert!(Calendar.datetime(), Calendar.calendar()) :: t | no_return
   def convert!(datetime, calendar) do
     case convert(datetime, calendar) do

lib/elixir/lib/calendar/iso.ex

@@ -16,11 +16,11 @@ defmodule Calendar.ISO do
   @behaviour Calendar
 
   @unix_epoch 62_167_219_200
-  unix_start = (315_537_897_600 + @unix_epoch) * -1_000_000
-  unix_end = 315_569_519_999_999_999 - @unix_epoch * 1_000_000
-  @unix_range_microseconds unix_start..unix_end
+  @unix_start 1_000_000 * -@unix_epoch
+  @unix_end 315_569_519_999_999_999 - @unix_epoch * 1_000_000
+  @unix_range_microseconds @unix_start..@unix_end
 
-  @type year :: -9999..9999
+  @type year :: 0..9999
   @type month :: 1..12
   @type day :: 1..31
 
@@ -28,50 +28,14 @@ defmodule Calendar.ISO do
   @seconds_per_hour 60 * 60
   # Note that this does _not_ handle leap seconds.
   @seconds_per_day 24 * 60 * 60
-  @last_second_of_the_day @seconds_per_day - 1
   @microseconds_per_second 1_000_000
   @parts_per_day @seconds_per_day * @microseconds_per_second
 
   @days_per_nonleap_year 365
   @days_per_leap_year 366
 
-  @months_in_year 12
-
-  @doc false
-  def __match_date__ do
-    quote do
-      [
-        <<y1, y2, y3, y4, ?-, m1, m2, ?-, d1, d2>>,
-        y1 >= ?0 and y1 <= ?9 and y2 >= ?0 and y2 <= ?9 and y3 >= ?0 and y3 <= ?9 and y4 >= ?0 and
-          y4 <= ?9 and m1 >= ?0 and m1 <= ?9 and m2 >= ?0 and m2 <= ?9 and d1 >= ?0 and d1 <= ?9 and
-          d2 >= ?0 and d2 <= ?9,
-        {
-          (y1 - ?0) * 1000 + (y2 - ?0) * 100 + (y3 - ?0) * 10 + (y4 - ?0),
-          (m1 - ?0) * 10 + (m2 - ?0),
-          (d1 - ?0) * 10 + (d2 - ?0)
-        }
-      ]
-    end
-  end
-
-  @doc false
-  def __match_time__ do
-    quote do
-      [
-        <<h1, h2, ?:, i1, i2, ?:, s1, s2>>,
-        h1 >= ?0 and h1 <= ?9 and h2 >= ?0 and h2 <= ?9 and i1 >= ?0 and i1 <= ?9 and i2 >= ?0 and
-          i2 <= ?9 and s1 >= ?0 and s1 <= ?9 and s2 >= ?0 and s2 <= ?9,
-        {
-          (h1 - ?0) * 10 + (h2 - ?0),
-          (i1 - ?0) * 10 + (i2 - ?0),
-          (s1 - ?0) * 10 + (s2 - ?0)
-        }
-      ]
-    end
-  end
-
   @doc """
-  Returns the `t:Calendar.iso_days/0` format of the specified date.
+  Returns the `t:Calendar.iso_days` format of the specified date.
 
   ## Examples
 
@@ -81,11 +45,8 @@ defmodule Calendar.ISO do
       {730485, {43200000000, 86400000000}}
       iex> Calendar.ISO.naive_datetime_to_iso_days(2000, 1, 1, 13, 0, 0, {0, 6})
       {730485, {46800000000, 86400000000}}
-      iex> Calendar.ISO.naive_datetime_to_iso_days(-1, 1, 1, 0, 0, 0, {0, 6})
-      {-365, {0, 86400000000}}
 
   """
-  @doc since: "1.5.0"
   @impl true
   @spec naive_datetime_to_iso_days(
           Calendar.year(),
@@ -101,21 +62,18 @@ defmodule Calendar.ISO do
   end
 
   @doc """
-  Converts the `t:Calendar.iso_days/0` format to the datetime format specified by this calendar.
+  Converts the `t:Calendar.iso_days` format to the datetime format specified by this calendar.
 
   ## Examples
 
       iex> Calendar.ISO.naive_datetime_from_iso_days({0, {0, 86400}})
       {0, 1, 1, 0, 0, 0, {0, 6}}
-      iex> Calendar.ISO.naive_datetime_from_iso_days({730_485, {0, 86400}})
+      iex> Calendar.ISO.naive_datetime_from_iso_days({730485, {0, 86400}})
       {2000, 1, 1, 0, 0, 0, {0, 6}}
-      iex> Calendar.ISO.naive_datetime_from_iso_days({730_485, {43200, 86400}})
+      iex> Calendar.ISO.naive_datetime_from_iso_days({730485, {43200, 86400}})
       {2000, 1, 1, 12, 0, 0, {0, 6}}
-      iex> Calendar.ISO.naive_datetime_from_iso_days({-365, {0, 86400000000}})
-      {-1, 1, 1, 0, 0, 0, {0, 6}}
 
   """
-  @doc since: "1.5.0"
   @spec naive_datetime_from_iso_days(Calendar.iso_days()) :: {
           Calendar.year(),
           Calendar.month(),
@@ -143,7 +101,6 @@ defmodule Calendar.ISO do
       {45296000123, 86400000000}
 
   """
-  @doc since: "1.5.0"
   @impl true
   @spec time_to_day_fraction(
           Calendar.hour(),
@@ -165,13 +122,12 @@ defmodule Calendar.ISO do
 
   ## Examples
 
-      iex> Calendar.ISO.time_from_day_fraction({1, 2})
+      iex> Calendar.ISO.time_from_day_fraction({1,2})
       {12, 0, 0, {0, 6}}
-      iex> Calendar.ISO.time_from_day_fraction({13, 24})
+      iex> Calendar.ISO.time_from_day_fraction({13,24})
       {13, 0, 0, {0, 6}}
 
   """
-  @doc since: "1.5.0"
   @impl true
   @spec time_from_day_fraction(Calendar.day_fraction()) ::
           {Calendar.hour(), Calendar.minute(), Calendar.second(), Calendar.microsecond()}
@@ -190,7 +146,6 @@ defmodule Calendar.ISO do
 
   # Converts year, month, day to count of days since 0000-01-01.
   @doc false
-  @doc since: "1.5.0"
   def date_to_iso_days(0, 1, 1) do
     0
   end
@@ -199,7 +154,7 @@ defmodule Calendar.ISO do
     719_528
   end
 
-  def date_to_iso_days(year, month, day) when year in -9999..9999 do
+  def date_to_iso_days(year, month, day) when year in 0..9999 do
     true = day <= days_in_month(year, month)
 
     days_in_previous_years(year) + days_before_month(month) + leap_day_offset(year, month) + day -
@@ -208,7 +163,7 @@ defmodule Calendar.ISO do
 
   # Converts count of days since 0000-01-01 to {year, month, day} tuple.
   @doc false
-  def date_from_iso_days(days) when days in -3_652_059..3_652_424 do
+  def date_from_iso_days(days) when days in 0..3_652_424 do
     {year, day_of_year} = days_to_year(days)
     extra_day = if leap_year?(year), do: 1, else: 0
     {month, day_in_month} = year_day_to_year_date(extra_day, day_of_year)
@@ -217,13 +172,8 @@ defmodule Calendar.ISO do
 
   defp div_mod(int1, int2) do
     div = div(int1, int2)
-    rem = int1 - div * int2
-
-    if rem >= 0 do
-      {div, rem}
-    else
-      {div - 1, rem + int2}
-    end
+    mod = int1 - div * int2
+    {div, mod}
   end
 
   @doc """
@@ -243,8 +193,6 @@ defmodule Calendar.ISO do
       29
       iex> Calendar.ISO.days_in_month(2004, 4)
       30
-      iex> Calendar.ISO.days_in_month(-1, 5)
-      31
 
   """
   @spec days_in_month(year, month) :: 28..31
@@ -258,22 +206,6 @@ defmodule Calendar.ISO do
   def days_in_month(_, month) when month in [4, 6, 9, 11], do: 30
   def days_in_month(_, month) when month in 1..12, do: 31
 
-  @doc """
-  Returns how many months there are in the given year.
-
-  ## Example
-
-      iex> Calendar.ISO.months_in_year(2004)
-      12
-
-  """
-  @doc since: "1.7.0"
-  @impl true
-  @spec months_in_year(year) :: 12
-  def months_in_year(_year) do
-    @months_in_year
-  end
-
   @doc """
   Returns if the given year is a leap year.
 
@@ -287,14 +219,12 @@ defmodule Calendar.ISO do
       true
       iex> Calendar.ISO.leap_year?(1900)
       false
-      iex> Calendar.ISO.leap_year?(-4)
-      true
 
   """
   @spec leap_year?(year) :: boolean()
   @impl true
-  def leap_year?(year) when is_integer(year) do
-    rem(year, 4) === 0 and (rem(year, 100) !== 0 or rem(year, 400) === 0)
+  def leap_year?(year) when is_integer(year) and year >= 0 do
+    rem(year, 4) === 0 and (rem(year, 100) > 0 or rem(year, 400) === 0)
   end
 
   @doc """
@@ -306,21 +236,18 @@ defmodule Calendar.ISO do
 
       iex> Calendar.ISO.day_of_week(2016, 10, 31)
       1
-      iex> Calendar.ISO.day_of_week(2016, 11, 1)
+      iex> Calendar.ISO.day_of_week(2016, 11, 01)
       2
-      iex> Calendar.ISO.day_of_week(2016, 11, 2)
+      iex> Calendar.ISO.day_of_week(2016, 11, 02)
       3
-      iex> Calendar.ISO.day_of_week(2016, 11, 3)
+      iex> Calendar.ISO.day_of_week(2016, 11, 03)
       4
-      iex> Calendar.ISO.day_of_week(2016, 11, 4)
+      iex> Calendar.ISO.day_of_week(2016, 11, 04)
       5
-      iex> Calendar.ISO.day_of_week(2016, 11, 5)
+      iex> Calendar.ISO.day_of_week(2016, 11, 05)
       6
-      iex> Calendar.ISO.day_of_week(2016, 11, 6)
+      iex> Calendar.ISO.day_of_week(2016, 11, 06)
       7
-      iex> Calendar.ISO.day_of_week(-99, 1, 31)
-      4
-
   """
   @spec day_of_week(year, month, day) :: 1..7
   @impl true
@@ -331,23 +258,7 @@ defmodule Calendar.ISO do
 
   @doc """
   Converts the given time into a string.
-
-  ## Examples
-
-      iex> Calendar.ISO.time_to_string(2, 2, 2, {2, 6})
-      "02:02:02.000002"
-      iex> Calendar.ISO.time_to_string(2, 2, 2, {2, 2})
-      "02:02:02.00"
-      iex> Calendar.ISO.time_to_string(2, 2, 2, {2, 0})
-      "02:02:02"
-
   """
-  @spec time_to_string(
-          Calendar.hour(),
-          Calendar.minute(),
-          Calendar.second(),
-          Calendar.microsecond()
-        ) :: String.t()
   @impl true
   def time_to_string(hour, minute, second, microsecond) do
     time_to_string(hour, minute, second, microsecond, :extended)
@@ -372,18 +283,7 @@ defmodule Calendar.ISO do
 
   @doc """
   Converts the given date into a string.
-
-  ## Examples
-
-      iex> Calendar.ISO.date_to_string(2015, 2, 28)
-      "2015-02-28"
-      iex> Calendar.ISO.date_to_string(2017, 8, 1)
-      "2017-08-01"
-      iex> Calendar.ISO.date_to_string(-99, 1, 31)
-      "-0099-01-31"
-
   """
-  @spec date_to_string(year, month, day) :: String.t()
   @impl true
   def date_to_string(year, month, day) do
     date_to_string(year, month, day, :extended)
@@ -399,58 +299,16 @@ defmodule Calendar.ISO do
 
   @doc """
   Converts the datetime (without time zone) into a string.
-
-  ## Examples
-
-      iex> Calendar.ISO.naive_datetime_to_string(2015, 2, 28, 1, 2, 3, {4, 6})
-      "2015-02-28 01:02:03.000004"
-      iex> Calendar.ISO.naive_datetime_to_string(2017, 8, 1, 1, 2, 3, {4, 5})
-      "2017-08-01 01:02:03.00000"
-
   """
   @impl true
-  @spec naive_datetime_to_string(
-          year,
-          month,
-          day,
-          Calendar.hour(),
-          Calendar.minute(),
-          Calendar.second(),
-          Calendar.microsecond()
-        ) :: String.t()
   def naive_datetime_to_string(year, month, day, hour, minute, second, microsecond) do
     date_to_string(year, month, day) <> " " <> time_to_string(hour, minute, second, microsecond)
   end
 
   @doc """
-  Converts the datetime (with time zone) into a string.
-
-  ## Examples
-
-      iex> Calendar.ISO.datetime_to_string(2017, 8, 1, 1, 2, 3, {4, 5}, "Europe/Berlin", "CET", 3600, 0)
-      "2017-08-01 01:02:03.00000+01:00 CET Europe/Berlin"
-      iex> Calendar.ISO.datetime_to_string(2017, 8, 1, 1, 2, 3, {4, 5}, "Europe/Berlin", "CDT", 3600, 3600)
-      "2017-08-01 01:02:03.00000+02:00 CDT Europe/Berlin"
-      iex> Calendar.ISO.datetime_to_string(2015, 2, 28, 1, 2, 3, {4, 5}, "America/Los_Angeles", "PST", -28800, 0)
-      "2015-02-28 01:02:03.00000-08:00 PST America/Los_Angeles"
-      iex> Calendar.ISO.datetime_to_string(2015, 2, 28, 1, 2, 3, {4, 5}, "America/Los_Angeles", "PDT", -28800, 3600)
-      "2015-02-28 01:02:03.00000-07:00 PDT America/Los_Angeles"
-
+  Convers the datetime (with time zone) into a string.
   """
   @impl true
-  @spec datetime_to_string(
-          year,
-          month,
-          day,
-          Calendar.hour(),
-          Calendar.minute(),
-          Calendar.second(),
-          Calendar.microsecond(),
-          Calendar.time_zone(),
-          Calendar.zone_abbr(),
-          Calendar.utc_offset(),
-          Calendar.std_offset()
-        ) :: String.t()
   def datetime_to_string(
         year,
         month,
@@ -471,59 +329,18 @@ defmodule Calendar.ISO do
       zone_to_string(utc_offset, std_offset, zone_abbr, time_zone)
   end
 
-  @doc """
-  Determines if the date given is valid according to the proleptic Gregorian calendar.
-
-  ## Examples
-
-      iex> Calendar.ISO.valid_date?(2015, 2, 28)
-      true
-      iex> Calendar.ISO.valid_date?(2015, 2, 30)
-      false
-      iex> Calendar.ISO.valid_date?(-1, 12, 31)
-      true
-      iex> Calendar.ISO.valid_date?(-1, 12, 32)
-      false
-
-  """
-  @doc since: "1.5.0"
   @impl true
-  @spec valid_date?(year, month, day) :: boolean
   def valid_date?(year, month, day) do
-    month in 1..12 and year in -9999..9999 and
-      (is_integer(day) and day >= 1 and day <= days_in_month(year, month))
+    month in 1..12 and year in 0..9999 and day in 1..days_in_month(year, month)
   end
 
-  @doc """
-  Determines if the date given is valid according to the proleptic Gregorian calendar.
-  Note that leap seconds are considered valid, but the use of 24:00:00 as the
-  zero hour of the day is considered invalid.
-
-  ## Examples
-
-      iex> Calendar.ISO.valid_time?(10, 50, 25, {3006, 6})
-      true
-      iex> Calendar.ISO.valid_time?(23, 59, 60, {0, 0})
-      true
-      iex> Calendar.ISO.valid_time?(24, 0, 0, {0, 0})
-      false
-
-  """
-  @doc since: "1.5.0"
   @impl true
-  @spec valid_time?(Calendar.hour(), Calendar.minute(), Calendar.secon(), Calendar.microsecond()) ::
-          boolean
   def valid_time?(hour, minute, second, {microsecond, precision}) do
     hour in 0..23 and minute in 0..59 and second in 0..60 and microsecond in 0..999_999 and
       precision in 0..6
   end
 
-  @doc """
-  See `c:Calendar.day_rollover_relative_to_midlight_utc/0` for documentation.
-  """
-  @doc since: "1.5.0"
   @impl true
-  @spec day_rollover_relative_to_midnight_utc() :: {0, 1}
   def day_rollover_relative_to_midnight_utc() do
     {0, 1}
   end
@@ -553,15 +370,11 @@ defmodule Calendar.ISO do
   defp sign(total) when total < 0, do: "-"
   defp sign(_), do: "+"
 
-  defp zero_pad(val, count) when val >= 0 do
+  defp zero_pad(val, count) do
     num = Integer.to_string(val)
     :binary.copy("0", count - byte_size(num)) <> num
   end
 
-  defp zero_pad(val, count) do
-    "-" <> zero_pad(-val, count)
-  end
-
   ## Helpers
 
   @doc false
@@ -591,7 +404,6 @@ defmodule Calendar.ISO do
     do: precision_for_unit(div(number, 10), precision + 1)
 
   @doc false
-  @doc since: "1.5.0"
   def date_to_iso8601(year, month, day, format \\ :extended) do
     date_to_string(year, month, day, format)
   end
@@ -696,7 +508,6 @@ defmodule Calendar.ISO do
   end
 
   @doc false
-  @doc since: "1.5.0"
   def iso_days_to_unit({days, {parts, ppd}}, unit) do
     day_microseconds = days * @parts_per_day
     microseconds = div(parts * @parts_per_day, ppd)
@@ -704,7 +515,6 @@ defmodule Calendar.ISO do
   end
 
   @doc false
-  @doc since: "1.5.0"
   def add_day_fraction_to_iso_days({days, {parts, ppd}}, add, ppd) do
     normalize_iso_days(days, parts + add, ppd)
   end
@@ -751,30 +561,13 @@ defmodule Calendar.ISO do
     if leap_year?(year), do: 1, else: 0
   end
 
-  defp days_to_year(days) when days < 0 do
-    year_estimate = -div(-days, @days_per_nonleap_year) - 1
-
-    {year, days_before_year} =
-      days_to_year(year_estimate, days, days_to_end_of_epoch(year_estimate))
-
-    leap_year_pad = if leap_year?(year), do: 1, else: 0
-    {year, leap_year_pad + @days_per_nonleap_year + days - days_before_year}
-  end
-
   defp days_to_year(days) do
-    year_estimate = div(days, @days_per_nonleap_year)
-
-    {year, days_before_year} =
-      days_to_year(year_estimate, days, days_in_previous_years(year_estimate))
-
+    year = Integer.floor_div(days, @days_per_nonleap_year)
+    {year, days_before_year} = days_to_year(year, days, days_in_previous_years(year))
     {year, days - days_before_year}
   end
 
-  defp days_to_year(year, days1, days2) when year < 0 and days1 >= days2 do
-    days_to_year(year + 1, days1, days_to_end_of_epoch(year + 1))
-  end
-
-  defp days_to_year(year, days1, days2) when year >= 0 and days1 < days2 do
+  defp days_to_year(year, days1, days2) when days1 < days2 do
     days_to_year(year - 1, days1, days_in_previous_years(year - 1))
   end
 
@@ -782,13 +575,6 @@ defmodule Calendar.ISO do
     {year, days2}
   end
 
-  defp days_to_end_of_epoch(year) when year < 0 do
-    previous_year = year + 1
-
-    div(previous_year, 4) - div(previous_year, 100) + div(previous_year, 400) +
-      previous_year * @days_per_nonleap_year
-  end
-
   defp days_in_previous_years(0), do: 0
 
   defp days_in_previous_years(year) do
@@ -856,7 +642,7 @@ defmodule Calendar.ISO do
     {date, time}
   end
 
-  defp seconds_to_time(seconds) when seconds in 0..@last_second_of_the_day do
+  defp seconds_to_time(seconds) when seconds in 0..(@seconds_per_day - 1) do
     {hour, rest_seconds} = div_mod(seconds, @seconds_per_hour)
     {minute, second} = div_mod(rest_seconds, @seconds_per_minute)
 

lib/elixir/lib/calendar/naive_datetime.ex

@@ -4,8 +4,7 @@ defmodule NaiveDateTime do
 
   The NaiveDateTime struct contains the fields year, month, day, hour,
   minute, second, microsecond and calendar. New naive datetimes can be
-  built with the `new/2` and `new/8` functions or using the
-  [`~N`](`Kernel.sigil_N/2`) sigil:
+  built with the `new/2` and `new/7` functions or using the `~N` sigil:
 
       iex> ~N[2000-01-01 23:00:07]
       ~N[2000-01-01 23:00:07]
@@ -28,18 +27,18 @@ defmodule NaiveDateTime do
   `NaiveDateTime` is not validated against a time zone, such errors
   would go unnoticed.
 
-  The functions of this module work with the `NaiveDateTime` struct as well
+  The functions on this module work with the `NaiveDateTime` struct as well
   as any struct that contains the same fields as the `NaiveDateTime` struct,
   such as `DateTime`. Such functions expect
   `t:Calendar.naive_datetime/0` in their typespecs (instead of `t:t/0`).
 
   Developers should avoid creating the NaiveDateTime structs directly
-  and instead, rely on the functions provided by this module as well
+  and instead rely on the functions provided by this module as well
   as the ones in 3rd party calendar libraries.
 
   ## Comparing naive date times
 
-  Comparisons in Elixir using `==/2`, `>/2`, `</2` and similar are structural
+  Comparisons in Elixir using `==`, `>`, `<` and similar are structural
   and based on the `NaiveDateTime` struct fields. For proper comparison
   between naive datetimes, use the `compare/2` function.
 
@@ -53,7 +52,7 @@ defmodule NaiveDateTime do
       iex> NaiveDateTime.diff(~N[2010-04-17 14:00:00], ~N[1970-01-01 00:00:00])
       1271512800
 
-      iex> NaiveDateTime.add(~N[1970-01-01 00:00:00], 1_271_512_800)
+      iex> NaiveDateTime.add(~N[1970-01-01 00:00:00], 1271512800)
       ~N[2010-04-17 14:00:00]
 
   Those functions are optimized to deal with common epochs, such
@@ -96,7 +95,6 @@ defmodule NaiveDateTime do
       true
 
   """
-  @doc since: "1.4.0"
   @spec utc_now(Calendar.calendar()) :: t
   def utc_now(calendar \\ Calendar.ISO)
 
@@ -157,9 +155,6 @@ defmodule NaiveDateTime do
       iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 59, 1_000_000)
       {:error, :invalid_time}
 
-      iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 59, {0, 1}, Calendar.ISO)
-      {:ok, ~N[2000-01-01 23:59:59.0]}
-
   """
   @spec new(
           Calendar.year(),
@@ -171,35 +166,10 @@ defmodule NaiveDateTime do
           Calendar.microsecond(),
           Calendar.calendar()
         ) :: {:ok, t} | {:error, atom}
-  def new(year, month, day, hour, minute, second, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)
-
-  def new(year, month, day, hour, minute, second, microsecond, calendar)
-      when is_integer(microsecond) do
-    new(year, month, day, hour, minute, second, {microsecond, 6}, calendar)
-  end
-
-  def new(year, month, day, hour, minute, second, microsecond, calendar) do
-    cond do
-      not calendar.valid_date?(year, month, day) ->
-        {:error, :invalid_date}
-
-      not calendar.valid_time?(hour, minute, second, microsecond) ->
-        {:error, :invalid_time}
-
-      true ->
-        naive_datetime = %NaiveDateTime{
-          calendar: calendar,
-          year: year,
-          month: month,
-          day: day,
-          hour: hour,
-          minute: minute,
-          second: second,
-          microsecond: microsecond
-        }
-
-        {:ok, naive_datetime}
-    end
+  def new(year, month, day, hour, minute, second, microsecond \\ {0, 0}, calendar \\ Calendar.ISO) do
+    with {:ok, date} <- Date.new(year, month, day, calendar),
+         {:ok, time} <- Time.new(hour, minute, second, microsecond, calendar),
+         do: new(date, time)
   end
 
   @doc """
@@ -236,7 +206,7 @@ defmodule NaiveDateTime do
   Adds a specified amount of time to a `NaiveDateTime`.
 
   Accepts an `integer` in any `unit` available from `t:System.time_unit/0`.
-  Negative values will move backwards in time.
+  Negative values will be move backwards in time.
 
   This operation is only possible if both calendars are convertible to `Calendar.ISO`.
 
@@ -260,15 +230,14 @@ defmodule NaiveDateTime do
 
       # changes below the precision will not be visible
       iex> hidden = NaiveDateTime.add(~N[2014-10-02 00:29:10], 21, :millisecond)
-      iex> hidden.microsecond # ~N[2014-10-02 00:29:10]
+      iex> hidden.microsecond  # ~N[2014-10-02 00:29:10]
       {21000, 0}
 
       # from Gregorian seconds
-      iex> NaiveDateTime.add(~N[0000-01-01 00:00:00], 63_579_428_950)
+      iex> NaiveDateTime.add(~N[0000-01-01 00:00:00], 63579428950)
       ~N[2014-10-02 00:29:10]
 
   """
-  @doc since: "1.4.0"
   @spec add(t, integer, System.time_unit()) :: t
   def add(%NaiveDateTime{} = naive_datetime, integer, unit \\ :second)
       when is_integer(integer) do
@@ -299,36 +268,29 @@ defmodule NaiveDateTime do
       21
       iex> NaiveDateTime.diff(~N[2014-10-02 00:29:10], ~N[2014-10-02 00:29:12])
       -2
-      iex> NaiveDateTime.diff(~N[-0001-10-02 00:29:10], ~N[-0001-10-02 00:29:12])
-      -2
 
       # to Gregorian seconds
       iex> NaiveDateTime.diff(~N[2014-10-02 00:29:10], ~N[0000-01-01 00:00:00])
       63579428950
 
   """
-  @doc since: "1.4.0"
   @spec diff(t, t, System.time_unit()) :: integer
-  def diff(
-        %NaiveDateTime{} = naive_datetime1,
-        %NaiveDateTime{} = naive_datetime2,
-        unit \\ :second
-      ) do
-    if not Calendar.compatible_calendars?(naive_datetime1.calendar, naive_datetime2.calendar) do
+  def diff(%NaiveDateTime{} = ndatetime1, %NaiveDateTime{} = ndatetime2, unit \\ :second) do
+    if not Calendar.compatible_calendars?(ndatetime1.calendar, ndatetime2.calendar) do
       raise ArgumentError,
-            "cannot calculate the difference between #{inspect(naive_datetime1)} and " <>
-              "#{inspect(naive_datetime2)} because their calendars are not compatible " <>
+            "cannot calculate the difference between #{inspect(ndatetime1)} and " <>
+              "#{inspect(ndatetime2)} because their calendars are not compatible " <>
               "and thus the result would be ambiguous"
     end
 
-    units1 = naive_datetime1 |> to_iso_days() |> Calendar.ISO.iso_days_to_unit(unit)
-    units2 = naive_datetime2 |> to_iso_days() |> Calendar.ISO.iso_days_to_unit(unit)
+    units1 = ndatetime1 |> to_iso_days() |> Calendar.ISO.iso_days_to_unit(unit)
+    units2 = ndatetime2 |> to_iso_days() |> Calendar.ISO.iso_days_to_unit(unit)
     units1 - units2
   end
 
   @doc """
   Returns the given naive datetime with the microsecond field truncated to the
-  given precision (`:microsecond`, `:millisecond` or `:second`).
+  given precision (`:microsecond`, `millisecond` or `:second`).
 
   ## Examples
 
@@ -342,10 +304,9 @@ defmodule NaiveDateTime do
       ~N[2017-11-06 00:23:51]
 
   """
-  @doc since: "1.6.0"
   @spec truncate(t(), :microsecond | :millisecond | :second) :: t()
-  def truncate(%NaiveDateTime{microsecond: microsecond} = naive_datetime, precision) do
-    %{naive_datetime | microsecond: Calendar.truncate(microsecond, precision)}
+  def truncate(%NaiveDateTime{microsecond: microsecond} = ndatetime, precision) do
+    %{ndatetime | microsecond: Calendar.truncate(microsecond, precision)}
   end
 
   @doc """
@@ -405,8 +366,6 @@ defmodule NaiveDateTime do
       "2000-02-28 23:00:13"
       iex> NaiveDateTime.to_string(~N[2000-02-28 23:00:13.001])
       "2000-02-28 23:00:13.001"
-      iex> NaiveDateTime.to_string(~N[-0100-12-15 03:20:31])
-      "-0100-12-15 03:20:31"
 
   This function can also be used to convert a DateTime to a string without
   the time zone information:
@@ -437,7 +396,7 @@ defmodule NaiveDateTime do
   Parses the extended "Date and time of day" format described by
   [ISO 8601:2004](https://en.wikipedia.org/wiki/ISO_8601).
 
-  Time zone offset may be included in the string but they will be
+  Timezone offset may be included in the string but they will be
   simply discarded as such information is not included in naive date
   times.
 
@@ -493,33 +452,20 @@ defmodule NaiveDateTime do
 
   """
   @spec from_iso8601(String.t(), Calendar.calendar()) :: {:ok, t} | {:error, atom}
-  def from_iso8601(string, calendar \\ Calendar.ISO)
-
-  def from_iso8601(<<?-, rest::binary>>, calendar) do
-    with {:ok, %{year: year} = naive_datetime} <- raw_from_iso8601(rest, calendar) do
-      {:ok, %{naive_datetime | year: -year}}
-    end
-  end
-
-  def from_iso8601(<<rest::binary>>, calendar) do
-    raw_from_iso8601(rest, calendar)
-  end
-
-  @sep [?\s, ?T]
-  [match_date, guard_date, read_date] = Calendar.ISO.__match_date__()
-  [match_time, guard_time, read_time] = Calendar.ISO.__match_time__()
-
-  defp raw_from_iso8601(string, calendar) do
-    with <<unquote(match_date), sep, unquote(match_time), rest::binary>> <- string,
-         true <- unquote(guard_date) and sep in @sep and unquote(guard_time),
+  def from_iso8601(string, calendar \\ Calendar.ISO) when is_binary(string) do
+    with <<year::4-bytes, ?-, month::2-bytes, ?-, day::2-bytes, sep, rest::binary>> <- string,
+         true <- sep in [?\s, ?T],
+         <<hour::2-bytes, ?:, min::2-bytes, ?:, sec::2-bytes, rest::binary>> <- rest,
+         {year, ""} <- Integer.parse(year),
+         {month, ""} <- Integer.parse(month),
+         {day, ""} <- Integer.parse(day),
+         {hour, ""} <- Integer.parse(hour),
+         {min, ""} <- Integer.parse(min),
+         {sec, ""} <- Integer.parse(sec),
          {microsec, rest} <- Calendar.ISO.parse_microsecond(rest),
          {_offset, ""} <- Calendar.ISO.parse_offset(rest) do
-      {year, month, day} = unquote(read_date)
-      {hour, min, sec} = unquote(read_time)
-
-      with {:ok, utc_date} <- new(year, month, day, hour, min, sec, microsec, Calendar.ISO) do
-        convert(utc_date, calendar)
-      end
+      with {:ok, utc_date} <- new(year, month, day, hour, min, sec, microsec, Calendar.ISO),
+           do: convert(utc_date, calendar)
     else
       _ -> {:error, :invalid_format}
     end
@@ -617,6 +563,12 @@ defmodule NaiveDateTime do
     |> to_iso8601(format)
   end
 
+  def to_iso8601(_date, format) do
+    raise ArgumentError,
+          "NaiveDateTime.to_iso8601/2 expects format to be :extended or :basic, " <>
+            "got: #{inspect(format)}"
+  end
+
   @doc """
   Converts a `NaiveDateTime` struct to an Erlang datetime tuple.
 
@@ -662,7 +614,7 @@ defmodule NaiveDateTime do
       {:ok, ~N[2000-01-01 13:30:15.005]}
       iex> NaiveDateTime.from_erl({{2000, 13, 1}, {13, 30, 15}})
       {:error, :invalid_date}
-      iex> NaiveDateTime.from_erl({{2000, 13, 1}, {13, 30, 15}})
+      iex> NaiveDateTime.from_erl({{2000, 13, 1},{13, 30, 15}})
       {:error, :invalid_date}
 
   """
@@ -732,7 +684,6 @@ defmodule NaiveDateTime do
       :lt
 
   """
-  @doc since: "1.4.0"
   @spec compare(Calendar.naive_datetime(), Calendar.naive_datetime()) :: :lt | :eq | :gt
   def compare(%{calendar: calendar1} = naive_datetime1, %{calendar: calendar2} = naive_datetime2) do
     if Calendar.compatible_calendars?(calendar1, calendar2) do
@@ -769,7 +720,6 @@ defmodule NaiveDateTime do
                            hour: 13, minute: 30, second: 15, microsecond: {0, 0}}}
 
   """
-  @doc since: "1.5.0"
   @spec convert(Calendar.naive_datetime(), Calendar.calendar()) ::
           {:ok, t} | {:error, :incompatible_calendars}
 
@@ -831,7 +781,6 @@ defmodule NaiveDateTime do
                      hour: 13, minute: 30, second: 15, microsecond: {0, 0}}
 
   """
-  @doc since: "1.5.0"
   @spec convert!(Calendar.naive_datetime(), Calendar.calendar()) :: t
   def convert!(naive_datetime, calendar) do
     case convert(naive_datetime, calendar) do

lib/elixir/lib/calendar/time.ex

@@ -3,8 +3,8 @@ defmodule Time do
   A Time struct and functions.
 
   The Time struct contains the fields hour, minute, second and microseconds.
-  New times can be built with the `new/4` function or using the
-  [`~T`](`Kernel.sigil_T/2`) sigil:
+  New times can be built with the `new/4` function or using the `~T`
+  sigil:
 
       iex> ~T[23:00:07.001]
       ~T[23:00:07.001]
@@ -29,7 +29,7 @@ defmodule Time do
 
   ## Comparing times
 
-  Comparisons in Elixir using `==/2`, `>/2`, `</2` and similar are structural
+  Comparisons in Elixir using `==`, `>`, `<` and similar are structural
   and based on the `Time` struct fields. For proper comparison between
   times, use the `compare/2` function.
   """
@@ -55,7 +55,6 @@ defmodule Time do
       true
 
   """
-  @doc since: "1.4.0"
   @spec utc_now(Calendar.calendar()) :: t
   def utc_now(calendar \\ Calendar.ISO) do
     {:ok, _, time, microsecond} = Calendar.ISO.from_unix(:os.system_time(), :native)
@@ -177,7 +176,7 @@ defmodule Time do
   Parses the extended "Local time" format described by
   [ISO 8601:2004](https://en.wikipedia.org/wiki/ISO_8601).
 
-  Time zone offset may be included in the string but they will be
+  Timezone offset may be included in the string but they will be
   simply discarded as such information is not included in times.
 
   As specified in the standard, the separator "T" may be omitted if
@@ -217,31 +216,27 @@ defmodule Time do
   @spec from_iso8601(String.t(), Calendar.calendar()) :: {:ok, t} | {:error, atom}
   def from_iso8601(string, calendar \\ Calendar.ISO)
 
-  def from_iso8601(<<?T, rest::binary>>, calendar) do
-    raw_from_iso8601(rest, calendar)
+  def from_iso8601(<<?T, h, rest::binary>>, calendar) when h in ?0..?9 do
+    from_iso8601(<<h, rest::binary>>, calendar)
   end
 
-  def from_iso8601(<<rest::binary>>, calendar) do
-    raw_from_iso8601(rest, calendar)
-  end
-
-  [match_time, guard_time, read_time] = Calendar.ISO.__match_time__()
-
-  defp raw_from_iso8601(string, calendar) do
-    with <<unquote(match_time), rest::binary>> <- string,
-         true <- unquote(guard_time),
+  def from_iso8601(<<hour::2-bytes, ?:, min::2-bytes, ?:, sec::2-bytes, rest::binary>>, calendar) do
+    with {hour, ""} <- Integer.parse(hour),
+         {min, ""} <- Integer.parse(min),
+         {sec, ""} <- Integer.parse(sec),
          {microsec, rest} <- Calendar.ISO.parse_microsecond(rest),
          {_offset, ""} <- Calendar.ISO.parse_offset(rest) do
-      {hour, min, sec} = unquote(read_time)
-
-      with {:ok, utc_time} <- new(hour, min, sec, microsec, Calendar.ISO) do
-        convert(utc_time, calendar)
-      end
+      with {:ok, utc_time} <- new(hour, min, sec, microsec, Calendar.ISO),
+           do: convert(utc_time, calendar)
     else
       _ -> {:error, :invalid_format}
     end
   end
 
+  def from_iso8601(<<_::binary>>, _calendar) do
+    {:error, :invalid_format}
+  end
+
   @doc """
   Parses the extended "Local time" format described by
   [ISO 8601:2004](https://en.wikipedia.org/wiki/ISO_8601).
@@ -256,7 +251,6 @@ defmodule Time do
       ~T[23:50:07.123]
       iex> Time.from_iso8601!("2015:01:23 23-50-07")
       ** (ArgumentError) cannot parse "2015:01:23 23-50-07" as time, reason: :invalid_format
-
   """
   @spec from_iso8601!(String.t(), Calendar.calendar()) :: t
   def from_iso8601!(string, calendar \\ Calendar.ISO) do
@@ -293,25 +287,17 @@ defmodule Time do
 
   """
   @spec to_iso8601(Calendar.time(), :extended | :basic) :: String.t()
-  def to_iso8601(time, format \\ :extended)
-
-  def to_iso8601(%{calendar: Calendar.ISO} = time, format) when format in [:extended, :basic] do
+  def to_iso8601(time, format \\ :extended) when format in [:extended, :basic] do
     %{
       hour: hour,
       minute: minute,
       second: second,
       microsecond: microsecond
-    } = time
+    } = convert!(time, Calendar.ISO)
 
     Calendar.ISO.time_to_iso8601(hour, minute, second, microsecond, format)
   end
 
-  def to_iso8601(%{calendar: _} = time, format) when format in [:extended, :basic] do
-    time
-    |> convert!(Calendar.ISO)
-    |> to_iso8601(format)
-  end
-
   @doc """
   Converts given `time` to an Erlang time tuple.
 
@@ -393,7 +379,7 @@ defmodule Time do
       ~T[17:30:00.000000]
       iex> Time.add(~T[11:00:00.005], 2400)
       ~T[11:40:00.005000]
-      iex> Time.add(~T[00:00:00], 86_399_999, :millisecond)
+      iex> Time.add(~T[00:00:00], 86399999, :millisecond)
       ~T[23:59:59.999000]
       iex> Time.add(~T[17:10:05], 86400)
       ~T[17:10:05.000000]
@@ -401,7 +387,6 @@ defmodule Time do
       ~T[22:59:00.000000]
 
   """
-  @doc since: "1.6.0"
   @spec add(Calendar.time(), integer, System.time_unit()) :: t
   def add(%{calendar: calendar} = time, number, unit \\ :second) when is_integer(number) do
     number = System.convert_time_unit(number, unit, :microsecond)
@@ -448,7 +433,6 @@ defmodule Time do
       :gt
 
   """
-  @doc since: "1.4.0"
   @spec compare(Calendar.time(), Calendar.time()) :: :lt | :eq | :gt
   def compare(%{calendar: calendar} = time1, %{calendar: calendar} = time2) do
     %{hour: hour1, minute: minute1, second: second1, microsecond: {microsecond1, _}} = time1
@@ -488,7 +472,6 @@ defmodule Time do
       {:ok, %Time{calendar: Calendar.Holocene, hour: 13, minute: 30, second: 15, microsecond: {0, 0}}}
 
   """
-  @doc since: "1.5.0"
   @spec convert(Calendar.time(), Calendar.calendar()) :: {:ok, t} | {:error, atom}
 
   # Keep it multiline for proper function clause errors.
@@ -544,7 +527,6 @@ defmodule Time do
       %Time{calendar: Calendar.Holocene, hour: 13, minute: 30, second: 15, microsecond: {0, 0}}
 
   """
-  @doc since: "1.5.0"
   @spec convert!(Calendar.time(), Calendar.calendar()) :: t
   def convert!(time, calendar) do
     case convert(time, calendar) do
@@ -559,7 +541,7 @@ defmodule Time do
   end
 
   @doc """
-  Returns the difference between two times, considering only the hour, minute,
+  Returns the difference between two times, considering only the hour, minute
   second and microsecond.
 
   As with the `compare/2` function both `Time` structs and other structures
@@ -586,7 +568,7 @@ defmodule Time do
 
       # Two `NaiveDateTime` structs could have big differences in the date
       # but only the time part is considered.
-      iex> Time.diff(~N[2017-01-01 00:29:12], ~N[1900-02-03 00:29:10])
+      iex> Time.diff(~N[2017-01-01 00:29:12], (~N[1900-02-03 00:29:10]))
       2
 
       iex> Time.diff(~T[00:29:12], ~T[00:29:10], :microsecond)
@@ -595,7 +577,6 @@ defmodule Time do
       -2_000_000
 
   """
-  @doc since: "1.5.0"
   @spec diff(Calendar.time(), Calendar.time(), System.time_unit()) :: integer
   def diff(time1, time2, unit \\ :second) do
     fraction1 = to_day_fraction(time1)
@@ -621,7 +602,6 @@ defmodule Time do
       ~T[01:01:01]
 
   """
-  @doc since: "1.6.0"
   @spec truncate(t(), :microsecond | :millisecond | :second) :: t()
   def truncate(%Time{microsecond: microsecond} = time, precision) do
     %{time | microsecond: Calendar.truncate(microsecond, precision)}

lib/elixir/lib/code.ex

@@ -5,55 +5,25 @@ defmodule Code do
   This module complements Erlang's [`:code` module](http://www.erlang.org/doc/man/code.html)
   to add behaviour which is specific to Elixir. Almost all of the functions in this module
   have global side effects on the behaviour of Elixir.
-
-  ## Working with files
-
-  This module contains three functions for compiling and evaluating files.
-  Here is a summary of them and their behaviour:
-
-    * `require_file/2` - compiles a file and tracks its name. It does not
-      compile the file again if it has been previously required.
-
-    * `compile_file/2` - compiles a file without tracking its name. Compiles the
-      file multiple times when invoked multiple times.
-
-    * `eval_file/2` - evaluates the file contents without tracking its name. It
-      returns the result of the last expression in the file, instead of the modules
-      defined in it.
-
-  In a nutshell, the first must be used when you want to keep track of the files
-  handled by the system, to avoid the same file from being compiled multiple
-  times. This is common in scripts.
-
-  `compile_file/2` must be used when you are interested in the modules defined in a
-  file, without tracking. `eval_file/2` should be used when you are intested on
-  the result of evaluating the file rather than the modules it defines.
   """
 
   @doc """
-  Lists all required files.
+  Lists all loaded files.
 
   ## Examples
 
       Code.require_file("../eex/test/eex_test.exs")
-      List.first(Code.required_files()) =~ "eex_test.exs"
+      List.first(Code.loaded_files()) =~ "eex_test.exs"
       #=> true
 
   """
-  @doc since: "1.7.0"
-  @spec required_files() :: [binary]
-  def required_files do
-    :elixir_code_server.call(:required)
-  end
-
-  # TODO: Deprecate me on 1.9
-  @doc false
+  @spec loaded_files() :: [binary]
   def loaded_files do
-    required_files()
+    :elixir_code_server.call(:loaded)
   end
 
   @doc """
-  Removes files from the required files list.
+  Removes files from the loaded files list.
 
   The modules defined in the file are not removed;
   calling this function only removes them from the list,
@@ -61,27 +31,17 @@ defmodule Code do
 
   ## Examples
 
-      # Require EEx test code
-      Code.require_file("../eex/test/eex_test.exs")
+      # Load EEx test code, unload file, check for functions still available
+      Code.load_file("../eex/test/eex_test.exs")
 
-      # Now unrequire all files
-      Code.unrequire_files(Code.required_files())
-
-      # Notice modules are still available
+      Code.unload_files(Code.loaded_files())
       function_exported?(EExTest.Compiled, :before_compile, 0)
       #=> true
 
   """
-  @doc since: "1.7.0"
-  @spec unrequire_files([binary]) :: :ok
-  def unrequire_files(files) do
-    :elixir_code_server.cast({:unrequire_files, files})
-  end
-
-  # TODO: Deprecate me on 1.9
-  @doc false
+  @spec unload_files([binary]) :: :ok
   def unload_files(files) do
-    unrequire_files(files)
+    :elixir_code_server.cast({:unload_files, files})
   end
 
   @doc """
@@ -248,10 +208,7 @@ defmodule Code do
     * `:line` - the line the string starts, used for error reporting
 
     * `:line_length` - the line length to aim for when formatting
-      the document. Defaults to 98. Note this value is used as
-      reference but it is not enforced by the formatter as sometimes
-      user intervention is required. See "Running the formatter"
-      section
+      the document. Defaults to 98.
 
     * `:locals_without_parens` - a keyword list of name and arity
       pairs that should be kept without parens whenever possible.
@@ -286,104 +243,6 @@ defmodule Code do
   based on the name, this behaviour should be configurable, such as the
   `:locals_without_parens` option.
 
-  ## Running the formatter
-
-  The formatter attempts to fit the most it can on a single line and
-  introduces line breaks wherever possible when it cannot.
-
-  In some cases, this may lead to undesired formatting. Therefore, **some
-  code generated by the formatter may not be aesthetically pleasing and
-  may require explicit intervention from the developer**. That's why we
-  do not recommend to run the formatter blindly in an existing codebase.
-  Instead you should format and sanity check each formatted file.
-
-  Let's see some examples. The code below:
-
-      "this is a very long string ... #{inspect(some_value)}"
-
-  may be formatted as:
-
-      "this is a very long string ... #{
-        inspect(some_value)
-      }"
-
-  This happens because the only place the formatter can introduce a
-  new line without changing the code semantics is in the interpolation.
-  In those scenarios, we recommend developers to directly adjust the
-  code. Here we can use the binary concatenation operator `<>/2`:
-
-      "this is a very long string " <>
-        "... #{inspect(some_value)}"
-
-  The string concatenation makes the code fit on a single line and also
-  gives more options to the formatter.
-
-  A similar example is when the formatter breaks a function definition
-  over multiple clauses:
-
-      def my_function(
-        %User{name: name, age: age, ...},
-        arg1,
-        arg2
-      ) do
-        ...
-      end
-
-  While the code above is completely valid, you may prefer to match on
-  the struct variables inside the function body in order to keep the
-  definition on a single line:
-
-      def my_function(%User{} = user, arg1, arg2) do
-        %{name: name, age: age, ...} = user
-        ...
-      end
-
-  In some situations, you can use the fact the formatter does not generate
-  elegant code as a hint for refactoring. Take this code:
-
-      def board?(board_id, %User{} = user, available_permissions, required_permissions) do
-        Tracker.OrganizationMembers.user_in_organization?(user.id, board.organization_id) and
-          required_permissions == Enum.to_list(MapSet.intersection(MapSet.new(required_permissions), MapSet.new(available_permissions)))
-      end
-
-  The code above has very long lines and running the formatter is not going
-  to address this issue. In fact, the formatter may make it more obvious that
-  you have complex expressions:
-
-      def board?(board_id, %User{} = user, available_permissions, required_permissions) do
-        Tracker.OrganizationMembers.user_in_organization?(user.id, board.organization_id) and
-          required_permissions ==
-            Enum.to_list(
-              MapSet.intersection(
-                MapSet.new(required_permissions),
-                MapSet.new(available_permissions)
-              )
-            )
-      end
-
-  Take such cases as a suggestion that your code should be refactored:
-
-      def board?(board_id, %User{} = user, available_permissions, required_permissions) do
-        Tracker.OrganizationMembers.user_in_organization?(user.id, board.organization_id) and
-          matching_permissions?(required_permissions, available_permissions)
-      end
-
-      defp matching_permissions?(required_permissions, available_permissions) do
-        intersection =
-          required_permissions
-          |> MapSet.new()
-          |> MapSet.intersection(MapSet.new(available_permissions))
-          |> Enum.to_list()
-
-        required_permissions == intersection
-      end
-
-  To sum it up: since the formatter cannot change the semantics of your
-  code, sometimes it is necessary to tweak or refactor the code to get
-  optimal formatting. To help better understand how to control the formatter,
-  we describe in the next sections the cases where the formatter keeps the
-  user encoding and how to control multiline expressions.
-
   ## Keeping user's formatting
 
   The formatter respects the input format in some cases. Those are
@@ -416,6 +275,53 @@ defmodule Code do
   rules in the future. The goal of documenting them is to provide better
   understanding on what to expect from the formatter.
 
+  ## Adjusting formatted output
+
+  The formatter attempts to the fit the most it can on a single line.
+  When the code does not fit a single line, the formatter introduces
+  line breaks in the code.
+
+  In some rare situations, this may lead to undesired formatting.
+  For example, the code below:
+
+      "this is a very long string ... #{inspect(some_value)}"
+
+  may be formatted as:
+
+      "this is a very long string ... #{
+        inspect(some_value)
+      }"
+
+  This happens because the only place the formatter can introduce a
+  new line without changing the code semantics is in the interpolation.
+  In those scenarios, we recommend developers to directly adjust the
+  code. Here we can use the binary concatenation operator `<>`:
+
+      "this is a very long string " <>
+        "... #{inspect(some_value)}"
+
+  The string concatenation makes the code fit on a single line and also
+  gives more options to the formatter.
+
+  A similar example is when the formatter breaks a function definition
+  over multiple clauses:
+
+      def my_function(
+        %User{name: name, age: age, ...},
+        arg1,
+        arg2
+      ) do
+
+  While the code above is completely valid, you may prefer to match on
+  the struct variables inside the function body in order to keep the
+  definition on a single line:
+
+      def my_function(%User{} = user, arg1, arg2) do
+        %{name: name, age: age, ...} = user
+
+  Since the formatter cannot change the semantics of your code,
+  sometimes it is necessary to tweak the code to get optimal formatting.
+
   ### Multi-line lists, maps, tuples, etc
 
   You can force lists, tuples, bitstrings, maps, structs and function
@@ -437,14 +343,14 @@ defmodule Code do
 
       [foo, bar]
 
-  You can also force function calls and keywords to be rendered on multiple
-  lines by having each entry on its own line:
+  You can also force keywords to be rendered on multiple lines by
+  having each entry on its own line:
 
       defstruct name: nil,
                 age: 0
 
   The code above will be kept with one keyword entry per line by the
-  formatter. To avoid that, just squash everything into a single line.
+  formatter. To avoid that, just keep everything on a single line.
 
   ### Parens and no parens in function calls
 
@@ -453,8 +359,7 @@ defmodule Code do
 
     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)
+       call is also listed under `:locals_without_parens`
 
   The choice of parens and no parens also affects indentation. When a
   function call with parens doesn't fit on the same line, the formatter
@@ -482,7 +387,7 @@ defmodule Code do
         # code
       end)
 
-      some_function_without_parens %{
+      some_funtion_without_parens %{
         foo: :bar,
         baz: :bat
       }
@@ -496,7 +401,7 @@ defmodule Code do
   The formatter also extracts all trailing comments to their previous line.
   For example, the code below
 
-      hello #world
+      hello # world
 
   will be rewritten to
 
@@ -531,7 +436,6 @@ defmodule Code do
   user formatting). In such cases, the code formatter will always format to
   the latter.
   """
-  @doc since: "1.6.0"
   @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)
@@ -545,7 +449,6 @@ defmodule Code do
   See `format_string!/2` for more information on code formatting and
   available options.
   """
-  @doc since: "1.6.0"
   @spec format_file!(binary, keyword) :: iodata
   def format_file!(file, opts \\ []) when is_binary(file) and is_list(opts) do
     string = File.read!(file)
@@ -650,10 +553,6 @@ defmodule Code do
       when non-existing atoms are found by the tokenizer.
       Defaults to `false`.
 
-    * `:warn_on_unnecessary_quotes` - when `false`, does not warn
-      when atoms, keywords or calls have unnecessary quotes on
-      them. Defaults to `true`.
-
   ## `Macro.to_string/2`
 
   The opposite of converting a string to its quoted form is
@@ -666,12 +565,8 @@ defmodule Code do
     file = Keyword.get(opts, :file, "nofile")
     line = Keyword.get(opts, :line, 1)
 
-    case :elixir.string_to_tokens(to_charlist(string), line, file, opts) do
-      {:ok, tokens} ->
-        :elixir.tokens_to_quoted(tokens, file, opts)
-
-      {:error, _error_msg} = error ->
-        error
+    with {:ok, tokens} <- :elixir.string_to_tokens(to_charlist(string), line, file, opts) do
+      :elixir.tokens_to_quoted(tokens, file, opts)
     end
   end
 
@@ -697,8 +592,8 @@ defmodule Code do
 
   Accepts `relative_to` as an argument to tell where the file is located.
 
-  While `require_file/2` and `compile_file/2` returns the loaded modules and their
-  bytecode, `eval_file/2` simply evaluates the file contents and returns the
+  While `load_file/2` loads a file and returns the loaded modules and their
+  byte code, `eval_file/2` simply evaluates the file contents and returns the
   evaluation result and its bindings (exactly the same return value as `eval_string/3`).
   """
   @spec eval_file(binary, nil | binary) :: {term, binding :: list}
@@ -707,13 +602,32 @@ defmodule Code do
     eval_string(File.read!(file), [], file: file, line: 1)
   end
 
-  # TODO: Deprecate me on 1.9
-  @doc false
+  @doc """
+  Loads the given file.
+
+  Accepts `relative_to` as an argument to tell where the file is located.
+  If the file was already required/loaded, loads it again.
+
+  It returns a list of tuples `{ModuleName, bytecode}`, one tuple for
+  each module defined in the file.
+
+  Notice that if `load_file/2` is invoked by different processes concurrently,
+  the target file will be loaded concurrently many times. Check `require_file/2`
+  if you don't want a file to be loaded concurrently.
+
+  ## Examples
+
+      modules = Code.load_file("eex_test.exs", "../eex/test")
+      List.first(modules)
+      #=> {EExTest.Compiled, <<70, 79, 82, 49, ...>>}
+
+  """
+  @spec load_file(binary, nil | binary) :: [{module, binary}]
   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)
-    :elixir_code_server.cast({:required, file})
+    :elixir_code_server.cast({:loaded, file})
     loaded
   end
 
@@ -721,51 +635,47 @@ defmodule Code do
   Requires the given `file`.
 
   Accepts `relative_to` as an argument to tell where the file is located.
-  If the file was already required, `require_file/2` doesn't do anything and
-  returns `nil`.
+  The return value is the same as that of `load_file/2`. If the file was already
+  required or loaded, `require_file/2` doesn't do anything and returns `nil`.
 
   Notice that if `require_file/2` is invoked by different processes concurrently,
   the first process to invoke `require_file/2` acquires a lock and the remaining
-  ones will block until the file is available. This means that if `require_file/2`
-  is called more than once with a given file, that file will be compiled only once.
-  The first process to call `require_file/2` will get the list of loaded modules,
-  others will get `nil`.
+  ones will block until the file is available. This means that if `require_file/2` is called
+  more than one times with a given file, that file will be loaded only once. The first process to
+  call `require_file/2` will get the list of loaded modules, others will get `nil`.
 
-  See `compile_file/2` if you would like to compile a file without tracking its
-  filenames. Finally, if you would like to get the result of evaluating file rather
-  than the modules defined in it, see `eval_file/2`.
+  Check `load_file/2` if you want to load a file multiple times. See also `unload_files/1`.
 
   ## Examples
 
-  If the file has not been required, it returns the list of modules:
+  If the code is already loaded, it returns `nil`:
+
+      Code.require_file("eex_test.exs", "../eex/test")
+      #=> nil
+
+  If the code is not loaded yet, it returns the same as `load_file/2`:
 
       modules = Code.require_file("eex_test.exs", "../eex/test")
       List.first(modules)
       #=> {EExTest.Compiled, <<70, 79, 82, 49, ...>>}
 
-  If the code has been required, it returns `nil`:
-
-      Code.require_file("eex_test.exs", "../eex/test")
-      #=> nil
-
   """
   @spec require_file(binary, nil | binary) :: [{module, binary}] | nil
   def require_file(file, relative_to \\ nil) when is_binary(file) do
     file = find_file(file, relative_to)
 
-    # TODO: Simply block until :required or :proceed once load_file is removed in 2.0
     case :elixir_code_server.call({:acquire, file}) do
-      :required ->
+      :loaded ->
         nil
 
       {:queued, ref} ->
         receive do
-          {:elixir_code_server, ^ref, :required} -> nil
+          {:elixir_code_server, ^ref, :loaded} -> nil
         end
 
       :proceed ->
         loaded = :elixir_compiler.file(file)
-        :elixir_code_server.cast({:required, file})
+        :elixir_code_server.cast({:loaded, file})
         loaded
     end
   end
@@ -794,7 +704,7 @@ defmodule Code do
 
   ## Examples
 
-      iex> Code.available_compiler_options()
+      iex> Code.available_compiler_options
       [:docs, :debug_info, :ignore_module_conflict, :relative_paths, :warnings_as_errors]
 
   """
@@ -803,27 +713,6 @@ defmodule Code do
     [:docs, :debug_info, :ignore_module_conflict, :relative_paths, :warnings_as_errors]
   end
 
-  @doc """
-  Purge compiler modules.
-
-  The compiler utilizes temporary modules to compile code. For example,
-  `elixir_compiler_1`, `elixir_compiler_2`, etc. In case the compiled code
-  stores references to anonymous functions or similar, the Elixir compiler
-  may be unable to reclaim those modules, keeping an unecessary amount of
-  code in memory and eventually leading to modules such as `elixir_compiler_12345`.
-
-  This function purges all modules currently kept by the compiler, allowing
-  old compiler module names to be resued. If there are any processes running
-  any code from such modules, they will be terminated too.
-
-  It returns `{:ok, number_of_modules_purged}`.
-  """
-  @doc since: "1.7.0"
-  @spec purge_compiler_modules() :: {:ok, non_neg_integer()}
-  def purge_compiler_modules() do
-    :elixir_code_server.call(:purge_compiler_modules)
-  end
-
   @doc """
   Sets compilation options.
 
@@ -885,11 +774,7 @@ defmodule Code do
   given as second argument which will be used for reporting warnings
   and errors.
 
-  **Warning**: `string` can be any Elixir code and code can be executed with
-  the same privileges as the Erlang VM: this means that such code could
-  compromise the machine (for example by executing system commands).
-  Don't use `compile_string/2` with untrusted input (such as strings coming
-  from the network).
+  For compiling many files at once, check `Kernel.ParallelCompiler.compile/2`.
   """
   @spec compile_string(List.Chars.t(), binary) :: [{module, binary}]
   def compile_string(string, file \\ "nofile") when is_binary(file) do
@@ -909,25 +794,6 @@ defmodule Code do
     :elixir_compiler.quoted(quoted, file)
   end
 
-  @doc """
-  Compiles the given file.
-
-  Accepts `relative_to` as an argument to tell where the file is located.
-
-  Returns a list of tuples where the first element is the module name and
-  the second one is its bytecode (as a binary). Opposite to `require_file/2`,
-  it does not track the filename of the compiled file.
-
-  If you would like to get the result of evaluating file rather than the
-  modules defined in it, see `eval_file/2`.
-
-  For compiling many files concurrently, see `Kernel.ParallelCompiler.compile/2`.
-  """
-  @spec compile_file(binary, nil | binary) :: [{module, binary}]
-  def compile_file(file, relative_to \\ nil) when is_binary(file) do
-    :elixir_compiler.file(find_file(file, relative_to))
-  end
-
   @doc """
   Ensures the given module is loaded.
 
@@ -1054,79 +920,88 @@ defmodule Code do
   When given a path to a `.beam` file, it will load the docs directly from that
   file.
 
-  It returns the term stored in the documentation chunk in the format defined by
-  [EEP 48](http://erlang.org/eep/eeps/eep-0048.html) or `{:error, reason}` if
-  the chunk is not available.
+  The return value depends on the `kind` value:
+
+    * `:moduledoc` - tuple `{line, doc}` where `line` is the line on
+      which the module definition starts and `doc` is the string
+      attached to the module using the `@moduledoc` attribute,
+      `false` if `@moduledoc false` was used, or `nil` if no `@moduledoc`
+      was used.
+
+    * `:docs` - list of all docstrings attached to functions and macros
+      using the `@doc` attribute. Each tuple has the form
+      `{{name, arity}, line, kind, arguments, doc}`. `doc` can be either a
+      string, `false` if `@doc false` was used, or `nil` if no doc was used.
+
+    * `:callback_docs` - list of all docstrings attached to
+      `@callbacks` using the `@doc` attribute. Each tuple has the form
+      `{{name, arity}, line, kind, doc}`. `doc` can be either a string or
+      `nil` if no `@doc` was set.
+
+    * `:type_docs` - list of all docstrings attached to `@type` callbacks
+      using the `@typedoc` attribute. Each tuple has the form
+      `{{name, arity}, line, kind, doc}`. `doc` can be either a string or
+      `nil` if no `@typedoc` was used.
+
+    * `:all` - a keyword list with `:docs`, `:moduledoc`, `:callback_docs`,
+      and `:type_docs`.
+
+  If the module cannot be found, it returns `nil`.
 
   ## Examples
 
       # Module documentation of an existing module
-      iex> {:docs_v1, _, :elixir, _, %{"en" => module_doc}, _, _} = Code.fetch_docs(Atom)
-      iex> module_doc |> String.split("\n") |> Enum.at(0)
+      iex> {_line, text} = Code.get_docs(Atom, :moduledoc)
+      iex> text |> String.split("\n") |> Enum.at(0)
       "Convenience functions for working with atoms."
 
       # A module that doesn't exist
-      iex> Code.fetch_docs(ModuleNotGood)
-      {:error, :module_not_found}
+      iex> Code.get_docs(ModuleNotGood, :all)
+      nil
 
   """
-  @doc since: "1.7.0"
-  @spec fetch_docs(module | String.t()) ::
-          {:docs_v1, anno, beam_language, format, module_doc :: doc, metadata,
-           docs :: [{{kind, name, arity}, anno, signature, doc, metadata}]}
-          | {:error, :module_not_found | :chunk_not_found | {:invalid_chunk, binary}}
-          | future_formats
-        when anno: :erl_anno.anno(),
-             beam_language: atom,
-             format: binary,
-             doc: %{binary => binary} | :none | :hidden,
-             kind: atom,
-             name: atom,
-             signature: [binary],
-             metadata: map,
-             future_formats: term
-  def fetch_docs(module) when is_atom(module) do
+  @doc_kinds [:docs, :moduledoc, :callback_docs, :type_docs, :all]
+
+  @spec get_docs(module, :moduledoc) :: {line :: pos_integer, doc :: false | binary} | nil
+  @spec get_docs(module, :docs) :: [{function, line, kind, list, doc}] | nil
+        when function: {atom, arity}, line: pos_integer, kind: atom, doc: nil | false | binary
+  @spec get_docs(module, :callback_docs) :: [{callback, line, kind, doc}] | nil
+        when callback: {atom, arity}, line: pos_integer, kind: atom, doc: nil | false | binary
+  @spec get_docs(module, :type_docs) :: [{type, line, kind, doc}] | nil
+        when type: {atom, arity}, line: pos_integer, kind: atom, doc: nil | false | binary
+  @spec get_docs(module, :all) :: keyword | nil
+  def get_docs(module, kind)
+
+  def get_docs(module, kind) when is_atom(module) and kind in @doc_kinds do
     case :code.get_object_code(module) do
-      {_module, bin, _beam_path} -> do_fetch_docs(bin)
-      :error -> {:error, :module_not_found}
+      {_module, bin, _beam_path} -> do_get_docs(bin, kind)
+      :error -> nil
     end
   end
 
-  def fetch_docs(binpath) when is_binary(binpath) do
-    do_fetch_docs(String.to_charlist(binpath))
+  def get_docs(binpath, kind) when is_binary(binpath) and kind in @doc_kinds do
+    do_get_docs(String.to_charlist(binpath), kind)
   end
 
-  @docs_chunk 'Docs'
+  @docs_chunk 'ExDc'
 
-  defp do_fetch_docs(bin_or_path) do
+  defp do_get_docs(bin_or_path, kind) do
     case :beam_lib.chunks(bin_or_path, [@docs_chunk]) do
       {:ok, {_module, [{@docs_chunk, bin}]}} ->
-        try do
-          :erlang.binary_to_term(bin)
-        rescue
-          _ -> {:error, {:invalid_chunk, bin}}
-        end
+        lookup_docs(:erlang.binary_to_term(bin), kind)
 
       {:error, :beam_lib, {:missing_chunk, _, @docs_chunk}} ->
-        {:error, :chunk_not_found}
+        nil
     end
   end
 
-  @doc ~S"""
-  Deprecated function to retrieve old documentation format.
+  defp lookup_docs({:elixir_docs_v1, docs}, kind), do: do_lookup_docs(docs, kind)
 
-  Elixir v1.7 adopts [EEP 48](http://erlang.org/eep/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`.
-  Use `Code.fetch_docs/1` instead.
-  """
-  @doc deprecated:
-         "Code.get_docs/2 always returns nil as its outdated documentation is no longer stored on BEAM files. Use Code.fetch_docs/1 instead"
-  @spec get_docs(module, :moduledoc | :docs | :callback_docs | :type_docs | :all) :: nil
-  def get_docs(_module, _kind) do
-    nil
-  end
+  # unsupported chunk version
+  defp lookup_docs(_, _), do: nil
+
+  defp do_lookup_docs(docs, :all), do: docs
+  defp do_lookup_docs(docs, kind), do: Keyword.get(docs, kind)
 
   ## Helpers
 

lib/elixir/lib/code/formatter.ex

@@ -194,7 +194,7 @@ defmodule Code.Formatter do
 
   Returns `{:ok, doc}` or `{:error, parser_error}`.
 
-  See `Code.format_string!/2` for the list of options.
+  See `format!/2` for the list of options.
   """
   def to_algebra(string, opts \\ []) when is_binary(string) and is_list(opts) do
     file = Keyword.get(opts, :file, "nofile")
@@ -202,12 +202,7 @@ defmodule Code.Formatter do
     charlist = String.to_charlist(string)
 
     Process.put(:code_formatter_comments, [])
-
-    tokenizer_options = [
-      unescape: false,
-      preserve_comments: &preserve_comments/5,
-      warn_on_unnecessary_quotes: false
-    ]
+    tokenizer_options = [unescape: false, preserve_comments: &preserve_comments/5]
 
     with {:ok, tokens} <- :elixir.string_to_tokens(charlist, line, file, tokenizer_options),
          {:ok, forms} <- :elixir.tokens_to_quoted(tokens, file, formatter_metadata: true) do
@@ -229,7 +224,7 @@ defmodule Code.Formatter do
 
   Raises if the `string` cannot be parsed.
 
-  See `Code.format_string!/2` for the list of options.
+  See `format!/2` for the list of options.
   """
   def to_algebra!(string, opts \\ []) do
     case to_algebra(string, opts) do
@@ -259,7 +254,6 @@ defmodule Code.Formatter do
       |> Keyword.get(:locals_without_parens, [])
       |> MapSet.new()
       |> MapSet.union(@locals_without_parens)
-      |> MapSet.to_list()
 
     %{
       locals_without_parens: locals_without_parens,
@@ -425,11 +419,11 @@ defmodule Code.Formatter do
   # {}
   # {1, 2}
   defp quoted_to_algebra({:{}, meta, args}, _context, state) do
-    tuple_to_algebra(meta, args, :flex_break, state)
+    tuple_to_algebra(meta, args, :flex_glue, state)
   end
 
   defp quoted_to_algebra({:__block__, meta, [{left, right}]}, _context, state) do
-    tuple_to_algebra(meta, [left, right], :flex_break, state)
+    tuple_to_algebra(meta, [left, right], :flex_glue, state)
   end
 
   defp quoted_to_algebra({:__block__, meta, [list]}, _context, state) when is_list(list) do
@@ -518,7 +512,7 @@ defmodule Code.Formatter do
   defp quoted_to_algebra({:not, meta, [{:in, _, [left, right]} = arg]}, context, state) do
     %{rename_deprecated_at: since} = state
 
-    # TODO: Remove since check on Elixir v2.0 and the OP arrangement is removed.
+    # TODO: Remove since check on Elixir v2.0 and the OP arrengement is removed.
     if meta[:operator] == :"not in" || (since && Version.match?(since, "~> 1.5")) do
       binary_op_to_algebra(:in, "not in", meta, left, right, context, state)
     else
@@ -527,7 +521,7 @@ defmodule Code.Formatter do
   end
 
   defp quoted_to_algebra({:fn, meta, [_ | _] = clauses}, _context, state) do
-    anon_fun_to_algebra(clauses, line(meta), end_line(meta), state, eol?(meta))
+    anon_fun_to_algebra(clauses, line(meta), end_line(meta), state)
   end
 
   defp quoted_to_algebra({fun, meta, args}, context, state) when is_atom(fun) and is_list(args) do
@@ -560,16 +554,7 @@ defmodule Code.Formatter do
         {left, state} =
           case left_arg do
             {:__block__, _, [atom]} when is_atom(atom) ->
-              key =
-                case Code.Identifier.classify(atom) do
-                  type when type in [:callable_local, :callable_operator, :not_callable] ->
-                    IO.iodata_to_binary([Atom.to_string(atom), ?:])
-
-                  _ ->
-                    IO.iodata_to_binary([?", Atom.to_string(atom), ?", ?:])
-                end
-
-              {string(key), state}
+              {atom |> Code.Identifier.inspect_as_key() |> string(), state}
 
             {{:., _, [:erlang, :binary_to_atom]}, _, [{:<<>>, _, entries}, :utf8]} ->
               interpolation_to_algebra(entries, @double_quote, state, "\"", "\":")
@@ -716,21 +701,14 @@ defmodule Code.Formatter do
         {concat(op_string, doc), @empty, newlines, state}
     end
 
-    {doc, state} =
-      operand_to_algebra_with_comments(
-        operands,
-        meta,
-        min_line,
-        max_line,
-        state,
-        operand_to_algebra
-      )
-
-    if keyword?(right_arg) and context in [:parens_arg, :no_parens_arg] do
-      {wrap_in_parens(doc), state}
-    else
-      {doc, state}
-    end
+    operand_to_algebra_with_comments(
+      operands,
+      meta,
+      min_line,
+      max_line,
+      state,
+      operand_to_algebra
+    )
   end
 
   defp binary_op_to_algebra(op, _, meta, left_arg, right_arg, context, state, _nesting)
@@ -972,7 +950,7 @@ defmodule Code.Formatter do
   # expression.{arguments}
   defp remote_to_algebra({{:., _, [target, :{}]}, meta, args}, _context, state) do
     {target_doc, state} = remote_target_to_algebra(target, state)
-    {call_doc, state} = tuple_to_algebra(meta, args, :break, state)
+    {call_doc, state} = tuple_to_algebra(meta, args, :glue, state)
     {concat(concat(target_doc, "."), call_doc), state}
   end
 
@@ -1057,8 +1035,6 @@ defmodule Code.Formatter do
   # We can only rename functions in the same module because
   # introducing a new module may wrong due to aliases.
   defp deprecated(Enum, :partition, 2), do: {"split_with", "~> 1.4"}
-  defp deprecated(Code, :unload_files, 2), do: {"unrequire_files", "~> 1.7"}
-  defp deprecated(Code, :loaded_files, 2), do: {"required_files", "~> 1.7"}
   defp deprecated(_, _, _), do: :error
 
   defp remote_target_to_algebra({:fn, _, [_ | _]} = quoted, state) do
@@ -1101,7 +1077,7 @@ defmodule Code.Formatter do
   #
   defp call_args_to_algebra([], meta, _context, _parens, _list_to_keyword?, state) do
     {args_doc, _join, state} =
-      args_to_algebra_with_comments([], meta, false, :none, :break, state, &{&1, &2})
+      args_to_algebra_with_comments([], meta, false, :none, :glue, state, &{&1, &2})
 
     {{surround("(", args_doc, ")"), state}, false}
   end
@@ -1135,6 +1111,7 @@ defmodule Code.Formatter do
 
   defp call_args_to_algebra_no_blocks(meta, args, skip_parens?, list_to_keyword?, extra, state) do
     {left, right} = split_last(args)
+    generators_count = count_generators(args)
     {keyword?, right} = last_arg_to_keyword(right, list_to_keyword?)
 
     context =
@@ -1144,110 +1121,76 @@ defmodule Code.Formatter do
         if skip_parens?, do: :no_parens_arg, else: :parens_arg
       end
 
-    args = if keyword?, do: left ++ right, else: left ++ [right]
-    many_eol? = match?([_, _ | _], args) and Keyword.get(meta, :eol, false)
-    no_generators? = no_generators?(args)
+    if left != [] and keyword? and skip_parens? and generators_count == 0 do
+      call_args_to_algebra_with_no_parens_keywords(meta, left, right, context, extra, state)
+    else
+      next_break_fits? = next_break_fits?(right, state)
+      last_arg_mode = if next_break_fits?, do: :next_break_fits, else: :none
+      force_keyword? = keyword? and force_keyword?(right)
+      non_empty_eol? = left != [] and not next_break_fits? and Keyword.get(meta, :eol, false)
+      join = if generators_count > 1 or force_keyword? or non_empty_eol?, do: :line, else: :glue
+      args = if keyword?, do: left ++ right, else: left ++ [right]
+
+      {args_doc, _join, state} =
+        args_to_algebra_with_comments(
+          args,
+          meta,
+          skip_parens?,
+          last_arg_mode,
+          join,
+          state,
+          &quoted_to_algebra(&1, context, &2)
+        )
+
+      # If we have a single argument, then we won't have an option to break
+      # before the "extra" part, so we ungroup it and build it later.
+      args_doc = ungroup_if_group(args_doc)
+
+      doc =
+        if skip_parens? do
+          " "
+          |> concat(nest(args_doc, :cursor, :break))
+          |> concat(extra)
+          |> group()
+        else
+          glue("(", "", args_doc)
+          |> nest(2, :break)
+          |> glue("", ")")
+          |> concat(extra)
+          |> group()
+        end
+
+      if next_break_fits? do
+        {next_break_fits(doc, :disabled), state}
+      else
+        {doc, state}
+      end
+    end
+  end
+
+  defp call_args_to_algebra_with_no_parens_keywords(meta, left, right, context, extra, state) do
     to_algebra_fun = &quoted_to_algebra(&1, context, &2)
 
-    {args_doc, next_break_fits?, state} =
-      if left != [] and keyword? and no_generators? do
-        join = if force_args?(left) or many_eol?, do: :line, else: :break
+    {left_doc, _join, state} =
+      args_to_algebra_with_comments(left, meta, true, :force_comma, :glue, state, to_algebra_fun)
 
-        {left_doc, _join, state} =
-          args_to_algebra_with_comments(
-            left,
-            Keyword.delete(meta, :end_line),
-            skip_parens?,
-            :force_comma,
-            join,
-            state,
-            to_algebra_fun
-          )
+    {right_doc, _join, state} =
+      args_to_algebra_with_comments(right, meta, false, :none, :glue, state, to_algebra_fun)
 
-        join = if force_args?(right) or force_args?(args) or many_eol?, do: :line, else: :break
-
-        {right_doc, _join, state} =
-          args_to_algebra_with_comments(right, meta, false, :none, join, state, to_algebra_fun)
-
-        right_doc = apply(Inspect.Algebra, join, []) |> concat(right_doc)
-
-        args_doc =
-          if skip_parens? do
-            left_doc
-            |> concat(next_break_fits(group(right_doc, :inherit), :enabled))
-            |> nest(:cursor, :break)
-          else
-            right_doc =
-              right_doc
-              |> nest(2, :break)
-              |> concat(break(""))
-              |> group(:inherit)
-              |> next_break_fits(:enabled)
-
-            concat(nest(left_doc, 2, :break), right_doc)
-          end
-
-        {args_doc, true, state}
-      else
-        join = if force_args?(args) or many_eol?, do: :line, else: :break
-        next_break_fits? = join == :break and next_break_fits?(right, state)
-        last_arg_mode = if next_break_fits?, do: :next_break_fits, else: :none
-
-        {args_doc, _join, state} =
-          args_to_algebra_with_comments(
-            args,
-            meta,
-            skip_parens?,
-            last_arg_mode,
-            join,
-            state,
-            to_algebra_fun
-          )
-
-        # If we have a single argument, then we won't have an option to break
-        # before the "extra" part, so we ungroup it and build it later.
-        args_doc = ungroup_if_group(args_doc)
-
-        args_doc =
-          if skip_parens? do
-            nest(args_doc, :cursor, :break)
-          else
-            nest(args_doc, 2, :break) |> concat(break(""))
-          end
-
-        {args_doc, next_break_fits?, state}
-      end
+    right_doc = break() |> concat(right_doc) |> force_keyword(right) |> group(:inherit)
 
     doc =
-      cond do
-        left != [] and keyword? and skip_parens? and no_generators? ->
-          " "
-          |> concat(args_doc)
-          |> nest(2)
-          |> concat(extra)
-          |> group()
+      with_next_break_fits(true, right_doc, fn right_doc ->
+        args_doc = concat(left_doc, right_doc)
 
-        skip_parens? ->
-          " "
-          |> concat(args_doc)
-          |> concat(extra)
-          |> group()
+        " "
+        |> concat(nest(args_doc, :cursor, :break))
+        |> nest(2)
+        |> concat(extra)
+        |> group()
+      end)
 
-        true ->
-          "("
-          |> concat(break(""))
-          |> nest(2, :break)
-          |> concat(args_doc)
-          |> concat(")")
-          |> concat(extra)
-          |> group()
-      end
-
-    if next_break_fits? do
-      {next_break_fits(doc, :disabled), state}
-    else
-      {doc, state}
-    end
+    {doc, state}
   end
 
   defp local_without_parens?(fun, args, %{locals_without_parens: locals_without_parens}) do
@@ -1259,8 +1202,8 @@ defmodule Code.Formatter do
       end)
   end
 
-  defp no_generators?(args) do
-    not Enum.any?(args, &match?({:<-, _, [_, _]}, &1))
+  defp count_generators(args) do
+    Enum.count(args, &match?({:<-, _, [_, _]}, &1))
   end
 
   defp do_end_blocks([{{:__block__, meta, [:do]}, _} | _] = blocks) do
@@ -1372,7 +1315,7 @@ defmodule Code.Formatter do
 
   defp bitstring_to_algebra(meta, args, state) do
     last = length(args) - 1
-    join = if Keyword.get(meta, :eol, false), do: :line, else: :flex_break
+    join = if Keyword.get(meta, :eol, false), do: :line, else: :flex_glue
     to_algebra_fun = &bitstring_segment_to_algebra(&1, &2, last)
 
     {args_doc, join, state} =
@@ -1380,7 +1323,7 @@ defmodule Code.Formatter do
       |> Enum.with_index()
       |> args_to_algebra_with_comments(meta, false, :none, join, state, to_algebra_fun)
 
-    if join == :flex_break do
+    if join == :flex_glue do
       {"<<" |> concat(args_doc) |> nest(2) |> concat(">>") |> group(), state}
     else
       {surround("<<", args_doc, ">>"), state}
@@ -1396,17 +1339,8 @@ defmodule Code.Formatter do
   defp bitstring_segment_to_algebra({{:::, _, [segment, spec]}, i}, state, last) do
     {doc, state} = quoted_to_algebra(segment, :parens_arg, state)
     {spec, state} = bitstring_spec_to_algebra(spec, state)
-
-    spec = wrap_in_parens_if_inspected_atom(spec)
-    spec = if i == last, do: bitstring_wrap_parens(spec, i, last), else: spec
-
-    doc =
-      doc
-      |> bitstring_wrap_parens(i, -1)
-      |> concat("::")
-      |> concat(spec)
-
-    {doc, state}
+    doc = concat(concat(doc, "::"), wrap_in_parens_if_inspected_atom(spec))
+    {bitstring_wrap_parens(doc, i, last), state}
   end
 
   defp bitstring_segment_to_algebra({segment, i}, state, last) do
@@ -1424,23 +1358,25 @@ defmodule Code.Formatter do
     quoted_to_algebra_with_parens_if_operator(spec, :parens_arg, state)
   end
 
-  defp bitstring_wrap_parens(doc, i, last) when i == 0 or i == last do
-    string = format_to_string(doc)
+  defp bitstring_wrap_parens(doc, i, last) do
+    if i == 0 or i == last do
+      string = format_to_string(doc)
 
-    if (i == 0 and String.starts_with?(string, ["~", "<<"])) or
-         (i == last and String.ends_with?(string, [">>"])) do
-      wrap_in_parens(doc)
+      if (i == 0 and String.starts_with?(string, "<<")) or
+           (i == last and String.ends_with?(string, ">>")) do
+        wrap_in_parens(doc)
+      else
+        doc
+      end
     else
       doc
     end
   end
 
-  defp bitstring_wrap_parens(doc, _, _), do: doc
-
   ## Literals
 
   defp list_to_algebra(meta, args, state) do
-    join = if Keyword.get(meta, :eol, false), do: :line, else: :break
+    join = if Keyword.get(meta, :eol, false), do: :line, else: :glue
     fun = &quoted_to_algebra(&1, :parens_arg, &2)
 
     {args_doc, _join, state} =
@@ -1450,7 +1386,7 @@ defmodule Code.Formatter do
   end
 
   defp map_to_algebra(meta, name_doc, [{:|, _, [left, right]}], state) do
-    join = if Keyword.get(meta, :eol, false), do: :line, else: :break
+    join = if Keyword.get(meta, :eol, false), do: :line, else: :glue
     fun = &quoted_to_algebra(&1, :parens_arg, &2)
     {left_doc, state} = fun.(left, state)
 
@@ -1467,7 +1403,7 @@ defmodule Code.Formatter do
   end
 
   defp map_to_algebra(meta, name_doc, args, state) do
-    join = if Keyword.get(meta, :eol, false), do: :line, else: :break
+    join = if Keyword.get(meta, :eol, false), do: :line, else: :glue
     fun = &quoted_to_algebra(&1, :parens_arg, &2)
 
     {args_doc, _join, state} =
@@ -1484,7 +1420,7 @@ defmodule Code.Formatter do
     {args_doc, join, state} =
       args_to_algebra_with_comments(args, meta, false, :none, join, state, fun)
 
-    if join == :flex_break do
+    if join == :flex_glue do
       {"{" |> concat(args_doc) |> nest(1) |> concat("}") |> group(), state}
     else
       {surround("{", args_doc, "}"), state}
@@ -1632,24 +1568,18 @@ defmodule Code.Formatter do
       join == :line or comments? ->
         {args_docs |> Enum.reduce(&line(&2, &1)) |> force_unfit(), :line, state}
 
-      join == :break ->
-        {args_docs |> Enum.reduce(&glue(&2, &1)), :break, state}
+      join == :glue ->
+        {args_docs |> Enum.reduce(&glue(&2, &1)), :glue, state}
 
-      join == :flex_break ->
-        {args_docs |> Enum.reduce(&flex_glue(&2, &1)), :flex_break, state}
+      join == :flex_glue ->
+        {args_docs |> Enum.reduce(&flex_glue(&2, &1)), :flex_glue, state}
     end
   end
 
   ## Anonymous functions
 
   # fn -> block end
-  defp anon_fun_to_algebra(
-         [{:->, meta, [[], body]}] = clauses,
-         _min_line,
-         max_line,
-         state,
-         _multi_clauses_style
-       ) do
+  defp anon_fun_to_algebra([{:->, meta, [[], body]}] = clauses, _min_line, max_line, state) do
     min_line = line(meta)
     {body_doc, state} = block_to_algebra(body, min_line, max_line, state)
 
@@ -1668,13 +1598,7 @@ defmodule Code.Formatter do
   # fn x ->
   #   y
   # end
-  defp anon_fun_to_algebra(
-         [{:->, meta, [args, body]}] = clauses,
-         _min_line,
-         max_line,
-         state,
-         false = _multi_clauses_style
-       ) do
+  defp anon_fun_to_algebra([{:->, meta, [args, body]}] = clauses, _min_line, max_line, state) do
     min_line = line(meta)
     {args_doc, state} = clause_args_to_algebra(args, min_line, state)
     {body_doc, state} = block_to_algebra(body, min_line, max_line, state)
@@ -1704,7 +1628,7 @@ defmodule Code.Formatter do
   #   args2 ->
   #     block2
   # end
-  defp anon_fun_to_algebra(clauses, min_line, max_line, state, _multi_clauses_style) do
+  defp anon_fun_to_algebra(clauses, min_line, max_line, state) do
     {clauses_doc, state} = clauses_to_algebra(clauses, min_line, max_line, state)
     {"fn" |> line(clauses_doc) |> nest(2) |> line("end") |> force_unfit(), state}
   end
@@ -1827,19 +1751,13 @@ defmodule Code.Formatter do
   end
 
   defp clause_args_to_algebra(args, min_line, state) do
-    arg_to_algebra = fn arg, _args, newlines, state ->
-      {doc, state} = clause_args_to_algebra(arg, state)
-      {doc, @empty, newlines, state}
-    end
+    meta = [line: min_line]
+    fun = &clause_args_to_algebra/2
 
-    {args_docs, comments?, state} =
-      quoted_to_algebra_with_comments([args], [], min_line, @min_line, 1, state, arg_to_algebra)
+    {args_docs, _join, state} =
+      args_to_algebra_with_comments([args], meta, false, :none, :glue, state, fun)
 
-    if comments? do
-      {Enum.reduce(args_docs, &line(&2, &1)), state}
-    else
-      {Enum.reduce(args_docs, &glue(&2, &1)), state}
-    end
+    {args_docs, state}
   end
 
   # fn a, b, c when d -> e end
@@ -2154,32 +2072,26 @@ defmodule Code.Formatter do
     {false, arg}
   end
 
-  defp force_args?(args) do
-    match?([_, _ | _], args) and force_args?(args, MapSet.new())
+  defp force_keyword?(keyword) do
+    match?([{_, _}, _ | _], keyword) and force_keyword?(keyword, MapSet.new())
   end
 
-  defp force_args?([[arg | _] | args], lines) do
-    force_args?([arg | args], lines)
-  end
+  defp force_keyword?([{{_, meta, _}, _} | keyword], lines) do
+    line = line(meta)
 
-  defp force_args?([arg | args], lines) do
-    line =
-      case arg do
-        {{_, meta, _}, _} -> line(meta)
-        {_, meta, _} -> line(meta)
-      end
-
-    if MapSet.member?(lines, line) do
+    if line in lines do
       false
     else
-      force_args?(args, MapSet.put(lines, line))
+      force_keyword?(keyword, MapSet.put(lines, line))
     end
   end
 
-  defp force_args?([], _lines), do: true
+  defp force_keyword?([], _lines) do
+    true
+  end
 
   defp force_keyword(doc, arg) do
-    if force_args?(arg), do: force_unfit(doc), else: doc
+    if force_keyword?(arg), do: force_unfit(doc), else: doc
   end
 
   defp keyword?([{key, _} | list]) do
@@ -2202,10 +2114,6 @@ defmodule Code.Formatter do
     false
   end
 
-  defp eol?(meta) do
-    Keyword.get(meta, :eol, false)
-  end
-
   defp line(meta) do
     Keyword.get(meta, :line, @max_line)
   end

lib/elixir/lib/code/identifier.ex

@@ -55,22 +55,22 @@ defmodule Code.Identifier do
   @doc """
   Classifies the given atom into one of the following categories:
 
-    * `:alias` - a valid Elixir alias, like `Foo`, `Foo.Bar` and so on
+    * :alias - a valid Elixir alias, like Foo, Foo.Bar and so on
 
-    * `:callable_local` - an atom that can be used as a local call;
-      this category includes identifiers like `:foo`
+    * :callable_local - an atom that can be used as a local call;
+      this category includes identifiers like :foo
 
-    * `:callable_operators` - all callable operators, such as `:<>`. Note
+    * :callable_operators - all callable operators, such as `:<>`. Note
       operators such as `:..` are not callable because of ambiguity
 
-    * `:not_callable` - an atom that cannot be used as a function call after the
-      `.` operator (for example, `:<<>>` is not callable because `Foo.<<>>` is a
-      syntax error); this category includes atoms like `:Foo`, since they are
+    * :not_callable - an atom that cannot be used as a function call after the
+      . operator (for example, :<<>> is not callable because Foo.<<>> is a
+      syntax error); this category includes atoms like :Foo, since they are
       valid identifiers but they need quotes to be used in function calls
-      (`Foo."Bar"`)
+      (Foo."Bar")
 
-    * `:other` - any other atom (these are usually escaped when inspected, like
-      `:"foo and bar"`)
+    * :other - any other atom (these are usually escaped when inspected, like
+      :"foo and bar")
 
   """
   def classify(atom) when is_atom(atom) do

lib/elixir/lib/code/typespec.ex

@@ -1,430 +0,0 @@
-defmodule Code.Typespec do
-  @moduledoc false
-
-  @doc """
-  Converts a spec clause back to Elixir quoted expression.
-  """
-  @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]})
-      when is_atom(name) do
-    meta = [line: line]
-    body = {name, meta, Enum.map(args, &typespec_to_quoted/1)}
-
-    vars =
-      for type_expr <- args ++ [result],
-          var <- collect_vars(type_expr),
-          uniq: true,
-          do: {var, {:var, meta, nil}}
-
-    spec = {:::, meta, [body, typespec_to_quoted(result)]}
-
-    if vars == [] do
-      spec
-    else
-      {:when, meta, [spec, vars]}
-    end
-  end
-
-  def spec_to_quoted(name, {:type, line, :fun, []}) when is_atom(name) do
-    {:::, [line: line], [{name, [line: line], []}, quote(do: term)]}
-  end
-
-  def spec_to_quoted(name, {:type, line, :bounded_fun, [type, constrs]}) when is_atom(name) do
-    {:type, _, :fun, [{:type, _, :product, args}, result]} = type
-
-    guards =
-      for {:type, _, :constraint, [{:atom, _, :is_subtype}, [{:var, _, var}, type]]} <- constrs do
-        {erl_to_ex_var(var), typespec_to_quoted(type)}
-      end
-
-    meta = [line: line]
-    ignore_vars = Keyword.keys(guards)
-
-    vars =
-      for type_expr <- args ++ [result],
-          var <- collect_vars(type_expr),
-          var not in ignore_vars,
-          uniq: true,
-          do: {var, {:var, meta, nil}}
-
-    args = for arg <- args, do: typespec_to_quoted(arg)
-
-    when_args = [
-      {:::, meta, [{name, [line: line], args}, typespec_to_quoted(result)]},
-      guards ++ vars
-    ]
-
-    {:when, meta, when_args}
-  end
-
-  @doc """
-  Converts a type clause back to Elixir AST.
-  """
-  def type_to_quoted(type)
-
-  def type_to_quoted({{:record, record}, fields, args}) when is_atom(record) do
-    fields = for field <- fields, do: typespec_to_quoted(field)
-    args = for arg <- args, do: typespec_to_quoted(arg)
-    type = {:{}, [], [record | fields]}
-    quote(do: unquote(record)(unquote_splicing(args)) :: unquote(type))
-  end
-
-  def type_to_quoted({name, type, args}) when is_atom(name) do
-    args = for arg <- args, do: typespec_to_quoted(arg)
-    quote(do: unquote(name)(unquote_splicing(args)) :: unquote(typespec_to_quoted(type)))
-  end
-
-  @doc """
-  Returns all types available from the module's BEAM code.
-
-  The result is returned as a list of tuples where the first
-  element is the type (`:typep`, `:type` and `:opaque`).
-
-  The module must have a corresponding BEAM file which can be
-  located by the runtime system. The types will be in the Erlang
-  Abstract Format.
-  """
-  @spec fetch_types(module | binary) :: {:ok, [tuple]} | :error
-  def fetch_types(module) when is_atom(module) or is_binary(module) do
-    case typespecs_abstract_code(module) do
-      {:ok, abstract_code} ->
-        exported_types = for {:attribute, _, :export_type, types} <- abstract_code, do: types
-        exported_types = List.flatten(exported_types)
-
-        types =
-          for {:attribute, _, kind, {name, _, args} = type} <- abstract_code,
-              kind in [:opaque, :type] do
-            cond do
-              kind == :opaque -> {:opaque, type}
-              {name, length(args)} in exported_types -> {:type, type}
-              true -> {:typep, type}
-            end
-          end
-
-        {:ok, types}
-
-      _ ->
-        :error
-    end
-  end
-
-  @doc """
-  Returns all specs available from the module's BEAM code.
-
-  The result is returned as a list of tuples where the first
-  element is spec name and arity and the second is the spec.
-
-  The module must have a corresponding BEAM file which can be
-  located by the runtime system. The types will be in the Erlang
-  Abstract Format.
-  """
-  @spec fetch_specs(module) :: {:ok, [tuple]} | :error
-  def fetch_specs(module) when is_atom(module) or is_binary(module) do
-    case typespecs_abstract_code(module) do
-      {:ok, abstract_code} ->
-        {:ok, for({:attribute, _, :spec, value} <- abstract_code, do: value)}
-
-      :error ->
-        :error
-    end
-  end
-
-  @doc """
-  Returns all callbacks available from the module's BEAM code.
-
-  The result is returned as a list of tuples where the first
-  element is spec name and arity and the second is the spec.
-
-  The module must have a corresponding BEAM file
-  which can be located by the runtime system. The types will be
-  in the Erlang Abstract Format.
-  """
-  @spec fetch_callbacks(module) :: {:ok, [tuple]} | :error
-  def fetch_callbacks(module) when is_atom(module) or is_binary(module) do
-    case typespecs_abstract_code(module) do
-      {:ok, abstract_code} ->
-        {:ok, for({:attribute, _, :callback, value} <- abstract_code, do: value)}
-
-      :error ->
-        :error
-    end
-  end
-
-  # TODO: Do not rely on abstract_code when OTP 20+ support is dropped (v1.8).
-  # We should then be able to simplify this code and use `with`.
-  defp typespecs_abstract_code(module) do
-    case get_module_and_beam(module) do
-      {module, binary} ->
-        case :beam_lib.chunks(binary, [:debug_info]) do
-          {:ok, {_, [debug_info: {:debug_info_v1, backend, data}]}} ->
-            case data do
-              {:elixir_v1, %{}, specs} ->
-                # Fast path to avoid translation to Erlang from Elixir.
-                {:ok, specs}
-
-              _ ->
-                case backend.debug_info(:erlang_v1, module, data, []) do
-                  {:ok, abstract_code} -> {:ok, abstract_code}
-                  _ -> :error
-                end
-            end
-
-          _ ->
-            case :beam_lib.chunks(binary, [:abstract_code]) do
-              {:ok, {_, [{:abstract_code, {_raw_abstract_v1, abstract_code}}]}} ->
-                {:ok, abstract_code}
-
-              _ ->
-                :error
-            end
-        end
-
-      :error ->
-        :error
-    end
-  end
-
-  defp get_module_and_beam(module) when is_atom(module) do
-    case :code.get_object_code(module) do
-      {^module, beam, _filename} -> {module, beam}
-      :error -> :error
-    end
-  end
-
-  defp get_module_and_beam(beam) when is_binary(beam) do
-    case :beam_lib.info(beam) do
-      [_ | _] = info -> {info[:module], beam}
-      _ -> :error
-    end
-  end
-
-  ## To AST conversion
-
-  defp collect_vars({:ann_type, _line, args}) when is_list(args) do
-    []
-  end
-
-  defp collect_vars({:type, _line, _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
-    Enum.flat_map(args, &collect_vars/1)
-  end
-
-  defp collect_vars({:typed_record_field, _line, type}) do
-    collect_vars(type)
-  end
-
-  defp collect_vars({:paren_type, _line, [type]}) do
-    collect_vars(type)
-  end
-
-  defp collect_vars({:var, _line, var}) do
-    [erl_to_ex_var(var)]
-  end
-
-  defp collect_vars(_) do
-    []
-  end
-
-  defp typespec_to_quoted({:user_type, line, name, args}) do
-    typespec_to_quoted({:type, line, name, args})
-  end
-
-  defp typespec_to_quoted({:type, line, :tuple, :any}) do
-    {:tuple, [line: line], []}
-  end
-
-  defp typespec_to_quoted({:type, line, :tuple, args}) do
-    args = for arg <- args, do: typespec_to_quoted(arg)
-    {:{}, [line: line], args}
-  end
-
-  defp typespec_to_quoted({:type, _line, :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], []}
-  end
-
-  defp typespec_to_quoted({:type, _line, :list, [arg]}) do
-    [typespec_to_quoted(arg)]
-  end
-
-  defp typespec_to_quoted({:type, line, :nonempty_list, []}) do
-    [{:..., [line: line], nil}]
-  end
-
-  defp typespec_to_quoted({:type, line, :nonempty_list, [arg]}) do
-    [typespec_to_quoted(arg), {:..., [line: line], nil}]
-  end
-
-  defp typespec_to_quoted({:type, line, :map, :any}) do
-    {:map, [line: line], []}
-  end
-
-  defp typespec_to_quoted({:type, line, :map, fields}) do
-    fields =
-      Enum.map(fields, fn
-        {:type, _, :map_field_assoc, :any} ->
-          {{:optional, [], [{:any, [], []}]}, {:any, [], []}}
-
-        {:type, _, :map_field_exact, [{:atom, _, k}, v]} ->
-          {k, typespec_to_quoted(v)}
-
-        {:type, _, :map_field_exact, [k, v]} ->
-          {{:required, [], [typespec_to_quoted(k)]}, typespec_to_quoted(v)}
-
-        {:type, _, :map_field_assoc, [k, v]} ->
-          {{:optional, [], [typespec_to_quoted(k)]}, typespec_to_quoted(v)}
-      end)
-
-    {struct, fields} = Keyword.pop(fields, :__struct__)
-    map = {:%{}, [line: line], fields}
-
-    if struct do
-      {:%, [line: line], [struct, map]}
-    else
-      map
-    end
-  end
-
-  defp typespec_to_quoted({:type, line, :binary, [arg1, arg2]}) do
-    [arg1, arg2] = for arg <- [arg1, arg2], do: typespec_to_quoted(arg)
-
-    case {typespec_to_quoted(arg1), typespec_to_quoted(arg2)} do
-      {arg1, 0} ->
-        quote(line: line, do: <<_::unquote(arg1)>>)
-
-      {0, arg2} ->
-        quote(line: line, do: <<_::_*unquote(arg2)>>)
-
-      {arg1, arg2} ->
-        quote(line: line, do: <<_::unquote(arg1), _::_*unquote(arg2)>>)
-    end
-  end
-
-  defp typespec_to_quoted({:type, line, :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)
-  end
-
-  defp typespec_to_quoted({:type, line, :fun, [{:type, _, :product, args}, result]}) do
-    args = for arg <- args, do: typespec_to_quoted(arg)
-    [{:->, [line: line], [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)]}]
-  end
-
-  defp typespec_to_quoted({:type, line, :fun, []}) do
-    typespec_to_quoted({:type, line, :fun, [{:type, line, :any}, {:type, line, :any, []}]})
-  end
-
-  defp typespec_to_quoted({:type, line, :range, [left, right]}) do
-    {:.., [line: line], [typespec_to_quoted(left), typespec_to_quoted(right)]}
-  end
-
-  defp typespec_to_quoted({:type, _line, nil, []}) do
-    []
-  end
-
-  defp typespec_to_quoted({:type, line, name, args}) do
-    args = for arg <- args, do: typespec_to_quoted(arg)
-    {name, [line: line], args}
-  end
-
-  defp typespec_to_quoted({:var, line, var}) do
-    {erl_to_ex_var(var), line, nil}
-  end
-
-  defp typespec_to_quoted({:op, line, op, arg}) do
-    {op, [line: line], [typespec_to_quoted(arg)]}
-  end
-
-  defp typespec_to_quoted({:remote_type, line, [mod, name, args]}) do
-    remote_type(line, mod, name, args)
-  end
-
-  defp typespec_to_quoted({:ann_type, line, [var, type]}) do
-    {:::, [line: line], [typespec_to_quoted(var), typespec_to_quoted(type)]}
-  end
-
-  defp typespec_to_quoted(
-         {:typed_record_field, {:record_field, line, {:atom, line1, name}}, type}
-       ) do
-    typespec_to_quoted({:ann_type, line, [{:var, line1, name}, type]})
-  end
-
-  defp typespec_to_quoted({:type, _, :any}) do
-    quote(do: ...)
-  end
-
-  defp typespec_to_quoted({:paren_type, _, [type]}) do
-    typespec_to_quoted(type)
-  end
-
-  defp typespec_to_quoted({type, _line, atom}) when is_atom(type) do
-    atom
-  end
-
-  defp typespec_to_quoted(other), do: other
-
-  ## Helpers
-
-  defp remote_type(line, {:atom, _, :elixir}, {:atom, _, :charlist}, []) do
-    typespec_to_quoted({:type, line, :charlist, []})
-  end
-
-  defp remote_type(line, {:atom, _, :elixir}, {:atom, _, :nonempty_charlist}, []) do
-    typespec_to_quoted({:type, line, :nonempty_charlist, []})
-  end
-
-  defp remote_type(line, {:atom, _, :elixir}, {:atom, _, :struct}, []) do
-    typespec_to_quoted({:type, line, :struct, []})
-  end
-
-  defp remote_type(line, {:atom, _, :elixir}, {:atom, _, :as_boolean}, [arg]) do
-    typespec_to_quoted({:type, line, :as_boolean, [arg]})
-  end
-
-  defp remote_type(line, {:atom, _, :elixir}, {:atom, _, :keyword}, args) do
-    typespec_to_quoted({:type, line, :keyword, args})
-  end
-
-  defp remote_type(line, 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}
-  end
-
-  defp erl_to_ex_var(var) do
-    case Atom.to_string(var) do
-      <<"_", c::utf8, rest::binary>> ->
-        String.to_atom("_#{String.downcase(<<c::utf8>>)}#{rest}")
-
-      <<c::utf8, rest::binary>> ->
-        String.to_atom("#{String.downcase(<<c::utf8>>)}#{rest}")
-    end
-  end
-
-  defp unpack_typespec_kw([{:type, _, :tuple, [{:atom, _, atom}, type]} | t], acc) do
-    unpack_typespec_kw(t, [{atom, typespec_to_quoted(type)} | acc])
-  end
-
-  defp unpack_typespec_kw([], acc) do
-    {:ok, Enum.reverse(acc)}
-  end
-
-  defp unpack_typespec_kw(_, _acc) do
-    :error
-  end
-end

lib/elixir/lib/collectable.ex

@@ -101,9 +101,6 @@ defimpl Collectable, for: BitString do
       acc, {:cont, x} when is_bitstring(x) ->
         <<IO.iodata_to_binary(acc)::bitstring, x::bitstring>>
 
-      acc, :done when is_bitstring(acc) ->
-        acc
-
       acc, :done ->
         IO.iodata_to_binary(acc)
 

lib/elixir/lib/dict.ex

@@ -1,6 +1,6 @@
 defmodule Dict do
   @moduledoc ~S"""
-  Generic API for dictionaries.
+  WARNING: this module is deprecated.
 
   If you need a general dictionary, use the `Map` module.
   If you need to manipulate keyword lists, use `Keyword`.
@@ -9,26 +9,18 @@ defmodule Dict do
   `new` function in the respective modules.
   """
 
-  @moduledoc deprecated: "Use Map or Keyword modules instead"
-
   @type key :: any
   @type value :: any
   @type t :: list | map
 
-  message =
-    "Use the Map module for working with maps or the Keyword module for working with keyword lists"
-
   # TODO: Remove by 2.0
+  # (hard-deprecated in elixir_dispatch)
 
-  @deprecated message
   defmacro __using__(_) do
     # Use this import to guarantee proper code expansion
     import Kernel, except: [size: 1]
 
     quote do
-      message = "Use maps and the Map module instead"
-
-      @deprecated message
       def get(dict, key, default \\ nil) do
         case fetch(dict, key) do
           {:ok, value} -> value
@@ -36,7 +28,6 @@ defmodule Dict do
         end
       end
 
-      @deprecated message
       def get_lazy(dict, key, fun) when is_function(fun, 0) do
         case fetch(dict, key) do
           {:ok, value} -> value
@@ -44,14 +35,12 @@ defmodule Dict do
         end
       end
 
-      @deprecated message
       def get_and_update(dict, key, fun) do
         current_value = get(dict, key)
         {get, new_value} = fun.(current_value)
         {get, put(dict, key, new_value)}
       end
 
-      @deprecated message
       def fetch!(dict, key) do
         case fetch(dict, key) do
           {:ok, value} -> value
@@ -59,12 +48,10 @@ defmodule Dict do
         end
       end
 
-      @deprecated message
       def has_key?(dict, key) do
         match?({:ok, _}, fetch(dict, key))
       end
 
-      @deprecated message
       def put_new(dict, key, value) do
         case has_key?(dict, key) do
           true -> dict
@@ -72,7 +59,6 @@ defmodule Dict do
         end
       end
 
-      @deprecated message
       def put_new_lazy(dict, key, fun) when is_function(fun, 0) do
         case has_key?(dict, key) do
           true -> dict
@@ -80,12 +66,10 @@ defmodule Dict do
         end
       end
 
-      @deprecated message
       def drop(dict, keys) do
         Enum.reduce(keys, dict, &delete(&2, &1))
       end
 
-      @deprecated message
       def take(dict, keys) do
         Enum.reduce(keys, new(), fn key, acc ->
           case fetch(dict, key) do
@@ -95,28 +79,24 @@ defmodule Dict do
         end)
       end
 
-      @deprecated message
       def to_list(dict) do
         reduce(dict, {:cont, []}, fn kv, acc -> {:cont, [kv | acc]} end)
         |> elem(1)
         |> :lists.reverse()
       end
 
-      @deprecated message
       def keys(dict) do
         reduce(dict, {:cont, []}, fn {k, _}, acc -> {:cont, [k | acc]} end)
         |> elem(1)
         |> :lists.reverse()
       end
 
-      @deprecated message
       def values(dict) do
         reduce(dict, {:cont, []}, fn {_, v}, acc -> {:cont, [v | acc]} end)
         |> elem(1)
         |> :lists.reverse()
       end
 
-      @deprecated message
       def equal?(dict1, dict2) do
         # Use this import to avoid conflicts in the user code
         import Kernel, except: [size: 1]
@@ -136,7 +116,6 @@ defmodule Dict do
         end
       end
 
-      @deprecated message
       def merge(dict1, dict2, fun \\ fn _k, _v1, v2 -> v2 end) do
         # Use this import to avoid conflicts in the user code
         import Kernel, except: [size: 1]
@@ -153,7 +132,6 @@ defmodule Dict do
         |> elem(1)
       end
 
-      @deprecated message
       def update(dict, key, initial, fun) do
         case fetch(dict, key) do
           {:ok, value} ->
@@ -164,7 +142,6 @@ defmodule Dict do
         end
       end
 
-      @deprecated message
       def update!(dict, key, fun) do
         case fetch(dict, key) do
           {:ok, value} ->
@@ -175,7 +152,6 @@ defmodule Dict do
         end
       end
 
-      @deprecated message
       def pop(dict, key, default \\ nil) do
         case fetch(dict, key) do
           {:ok, value} ->
@@ -186,7 +162,6 @@ defmodule Dict do
         end
       end
 
-      @deprecated message
       def pop_lazy(dict, key, fun) when is_function(fun, 0) do
         case fetch(dict, key) do
           {:ok, value} ->
@@ -197,7 +172,6 @@ defmodule Dict do
         end
       end
 
-      @deprecated message
       def split(dict, keys) do
         Enum.reduce(keys, {new(), dict}, fn key, {inc, exc} = acc ->
           case fetch(exc, key) do
@@ -246,85 +220,71 @@ defmodule Dict do
     end
   end
 
-  @deprecated message
   @spec keys(t) :: [key]
   def keys(dict) do
     target(dict).keys(dict)
   end
 
-  @deprecated message
   @spec values(t) :: [value]
   def values(dict) do
     target(dict).values(dict)
   end
 
-  @deprecated message
   @spec size(t) :: non_neg_integer
   def size(dict) do
     target(dict).size(dict)
   end
 
-  @deprecated message
   @spec has_key?(t, key) :: boolean
   def has_key?(dict, key) do
     target(dict).has_key?(dict, key)
   end
 
-  @deprecated message
   @spec get(t, key, value) :: value
   def get(dict, key, default \\ nil) do
     target(dict).get(dict, key, default)
   end
 
-  @deprecated message
   @spec get_lazy(t, key, (() -> value)) :: value
   def get_lazy(dict, key, fun) do
     target(dict).get_lazy(dict, key, fun)
   end
 
-  @deprecated message
   @spec get_and_update(t, key, (value -> {value, value})) :: {value, t}
   def get_and_update(dict, key, fun) do
     target(dict).get_and_update(dict, key, fun)
   end
 
-  @deprecated message
   @spec fetch(t, key) :: value
   def fetch(dict, key) do
     target(dict).fetch(dict, key)
   end
 
-  @deprecated message
   @spec fetch!(t, key) :: value | no_return
   def fetch!(dict, key) do
     target(dict).fetch!(dict, key)
   end
 
-  @deprecated message
   @spec put(t, key, value) :: t
   def put(dict, key, val) do
     target(dict).put(dict, key, val)
   end
 
-  @deprecated message
   @spec put_new(t, key, value) :: t
   def put_new(dict, key, val) do
     target(dict).put_new(dict, key, val)
   end
 
-  @deprecated message
   @spec put_new_lazy(t, key, (() -> value)) :: t
   def put_new_lazy(dict, key, fun) do
     target(dict).put_new_lazy(dict, key, fun)
   end
 
-  @deprecated message
   @spec delete(t, key) :: t
   def delete(dict, key) do
     target(dict).delete(dict, key)
   end
 
-  @deprecated message
   @spec merge(t, t) :: t
   def merge(dict1, dict2) do
     target1 = target(dict1)
@@ -337,7 +297,6 @@ defmodule Dict do
     end
   end
 
-  @deprecated message
   @spec merge(t, t, (key, value, value -> value)) :: t
   def merge(dict1, dict2, fun) do
     target1 = target(dict1)
@@ -357,55 +316,46 @@ defmodule Dict do
     |> elem(1)
   end
 
-  @deprecated message
   @spec pop(t, key, value) :: {value, t}
   def pop(dict, key, default \\ nil) do
     target(dict).pop(dict, key, default)
   end
 
-  @deprecated message
   @spec pop_lazy(t, key, (() -> value)) :: {value, t}
   def pop_lazy(dict, key, fun) do
     target(dict).pop_lazy(dict, key, fun)
   end
 
-  @deprecated message
   @spec update!(t, key, (value -> value)) :: t
   def update!(dict, key, fun) do
     target(dict).update!(dict, key, fun)
   end
 
-  @deprecated message
   @spec update(t, key, value, (value -> value)) :: t
   def update(dict, key, initial, fun) do
     target(dict).update(dict, key, initial, fun)
   end
 
-  @deprecated message
   @spec split(t, [key]) :: {t, t}
   def split(dict, keys) do
     target(dict).split(dict, keys)
   end
 
-  @deprecated message
   @spec drop(t, [key]) :: t
   def drop(dict, keys) do
     target(dict).drop(dict, keys)
   end
 
-  @deprecated message
   @spec take(t, [key]) :: t
   def take(dict, keys) do
     target(dict).take(dict, keys)
   end
 
-  @deprecated message
   @spec empty(t) :: t
   def empty(dict) do
     target(dict).empty(dict)
   end
 
-  @deprecated message
   @spec equal?(t, t) :: boolean
   def equal?(dict1, dict2) do
     target1 = target(dict1)
@@ -429,7 +379,6 @@ defmodule Dict do
     end
   end
 
-  @deprecated message
   @spec to_list(t) :: list
   def to_list(dict) do
     target(dict).to_list(dict)

lib/elixir/lib/dynamic_supervisor.ex

@@ -19,7 +19,7 @@ defmodule DynamicSupervisor do
         {DynamicSupervisor, strategy: :one_for_one, name: MyApp.DynamicSupervisor}
       ]
 
-      Supervisor.start_link(children, strategy: :one_for_one)
+      Supervisor.start_link(strategy: :one_for_one)
 
   The options given in the child specification are documented in `start_link/1`.
 
@@ -35,7 +35,7 @@ defmodule DynamicSupervisor do
       Agent.get(agent2, & &1)
       #=> %{}
 
-      DynamicSupervisor.count_children(MyApp.DynamicSupervisor)
+      DynamicSupervisor.count_children(sup)
       #=> %{active: 2, specs: 2, supervisors: 0, workers: 2}
 
   ## Module-based supervisors
@@ -51,7 +51,6 @@ defmodule DynamicSupervisor do
           DynamicSupervisor.start_link(__MODULE__, arg, name: __MODULE__)
         end
 
-        @impl true
         def init(_arg) do
           DynamicSupervisor.init(strategy: :one_for_one)
         end
@@ -85,7 +84,6 @@ defmodule DynamicSupervisor do
           Supervisor.start_child(__MODULE__, [foo, bar, baz])
         end
 
-        @impl true
         def init(initial_arg) do
           children = [
             # Or the deprecated: worker(MyWorker, [initial_arg])
@@ -112,7 +110,6 @@ defmodule DynamicSupervisor do
           DynamicSupervisor.start_child(__MODULE__, spec)
         end
 
-        @impl true
         def init(initial_arg) do
           DynamicSupervisor.init(
             strategy: :one_for_one,
@@ -137,14 +134,13 @@ defmodule DynamicSupervisor do
   """
   @callback init(args :: term) :: {:ok, sup_flags()} | :ignore
 
-  @typedoc "The supervisor flags returned on init"
-  @type sup_flags() :: %{
-          strategy: strategy(),
-          intensity: non_neg_integer(),
-          period: pos_integer(),
-          max_children: non_neg_integer() | :infinity,
-          extra_arguments: [term()]
-        }
+  @opaque sup_flags() :: %{
+            strategy: strategy(),
+            intensity: non_neg_integer(),
+            period: pos_integer(),
+            max_children: non_neg_integer() | :infinity,
+            extra_arguments: [term()]
+          }
 
   @typedoc "Option values used by the `start*` functions"
   @type option :: {:name, Supervisor.name()} | init_option()
@@ -163,13 +159,6 @@ defmodule DynamicSupervisor do
   @typedoc "Supported strategies"
   @type strategy :: :one_for_one
 
-  @typedoc "Return values of `start_child` functions"
-  @type on_start_child ::
-          {:ok, pid}
-          | {:ok, pid, info :: term}
-          | :ignore
-          | {:error, {:already_started, pid} | :max_children | term}
-
   defstruct [
     :args,
     :extra_arguments,
@@ -180,6 +169,7 @@ defmodule DynamicSupervisor do
     :max_restarts,
     :max_seconds,
     children: %{},
+    dynamic: 0,
     restarts: []
   ]
 
@@ -188,18 +178,11 @@ defmodule DynamicSupervisor do
 
   See `Supervisor`.
   """
-  @doc since: "1.6.1"
-  def child_spec(opts) when is_list(opts) do
-    id =
-      case Keyword.get(opts, :name, DynamicSupervisor) do
-        name when is_atom(name) -> name
-        {:global, name} -> name
-        {:via, _module, name} -> name
-      end
-
+  @since "1.6.1"
+  def child_spec(arg) do
     %{
-      id: id,
-      start: {DynamicSupervisor, :start_link, [opts]},
+      id: DynamicSupervisor,
+      start: {DynamicSupervisor, :start_link, [arg]},
       type: :supervisor
     }
   end
@@ -225,6 +208,9 @@ defmodule DynamicSupervisor do
       end
 
       defoverridable child_spec: 1
+
+      @doc false
+      def init(arg)
     end
   end
 
@@ -249,7 +235,6 @@ defmodule DynamicSupervisor do
   process and exits not only on crashes but also if the parent process exits
   with `:normal` reason.
   """
-  @doc since: "1.6.0"
   @spec start_link(options) :: Supervisor.on_start()
   def start_link(options) when is_list(options) do
     keys = [:extra_arguments, :max_children, :max_seconds, :max_restarts, :strategy]
@@ -275,7 +260,6 @@ defmodule DynamicSupervisor do
   name, the supported values are described in the "Name registration"
   section in the `GenServer` module docs.
   """
-  @doc since: "1.6.0"
   @spec start_link(module, term, GenServer.options()) :: Supervisor.on_start()
   def start_link(mod, args, opts \\ []) do
     GenServer.start_link(__MODULE__, {mod, args, opts[:name]}, opts)
@@ -284,9 +268,8 @@ defmodule DynamicSupervisor do
   @doc """
   Dynamically adds a child specification to `supervisor` and starts that child.
 
-  `child_spec` should be a valid child specification as detailed in the
-  "child_spec/1" section of the documentation for `Supervisor`. The child
-  process will be started as defined in the child specification.
+  `child_spec` should be a valid child specification. The child process will
+  be started as defined in the child specification.
 
   If the child process start function returns `{:ok, child}` or `{:ok, child,
   info}`, then child specification and PID are added to the supervisor and
@@ -304,9 +287,8 @@ defmodule DynamicSupervisor do
   of `:max_children` set on the supervisor initialization (see `init/1`), then
   this function returns `{:error, :max_children}`.
   """
-  @doc since: "1.6.0"
   @spec start_child(Supervisor.supervisor(), :supervisor.child_spec() | {module, term} | module) ::
-          on_start_child()
+          Supervisor.on_start_child()
   def start_child(supervisor, {_, _, _, _, _, _} = child_spec) do
     validate_and_start_child(supervisor, child_spec)
   end
@@ -378,12 +360,11 @@ defmodule DynamicSupervisor do
   end
 
   @doc """
-  Terminates the given child identified by `pid`.
+  Terminates the given child identified by child id.
 
   If successful, this function returns `:ok`. If there is no process with
   the given PID, this function returns `{:error, :not_found}`.
   """
-  @doc since: "1.6.0"
   @spec terminate_child(Supervisor.supervisor(), pid) :: :ok | {:error, :not_found}
   def terminate_child(supervisor, pid) when is_pid(pid) do
     call(supervisor, {:terminate_child, pid})
@@ -409,7 +390,6 @@ defmodule DynamicSupervisor do
     * `modules` - as defined in the child specification
 
   """
-  @doc since: "1.6.0"
   @spec which_children(Supervisor.supervisor()) :: [
           {:undefined, pid | :restarting, :worker | :supervisor, :supervisor.modules()}
         ]
@@ -422,7 +402,7 @@ defmodule DynamicSupervisor do
 
   The map contains the following keys:
 
-    * `:specs` - the number of children processes
+    * `:specs` - always 1 as dynamic supervisors have a single specification
 
     * `:active` - the count of all actively running child processes managed by
       this supervisor
@@ -434,7 +414,6 @@ defmodule DynamicSupervisor do
       is still alive
 
   """
-  @doc since: "1.6.0"
   @spec count_children(Supervisor.supervisor()) :: %{
           specs: non_neg_integer,
           active: non_neg_integer,
@@ -445,22 +424,6 @@ defmodule DynamicSupervisor do
     call(supervisor, :count_children) |> :maps.from_list()
   end
 
-  @doc """
-  Synchronously stops the given supervisor with the given `reason`.
-
-  It returns `:ok` if the supervisor terminates with the given
-  reason. If it terminates with another reason, the call exits.
-
-  This function keeps OTP semantics regarding error reporting.
-  If the reason is any other than `:normal`, `:shutdown` or
-  `{:shutdown, _}`, an error report is logged.
-  """
-  @doc since: "1.7.0"
-  @spec stop(Supervisor.supervisor(), reason :: term, timeout) :: :ok
-  def stop(supervisor, reason \\ :normal, timeout \\ :infinity) do
-    GenServer.stop(supervisor, reason, timeout)
-  end
-
   @doc """
   Receives a set of options that initializes a dynamic supervisor.
 
@@ -493,7 +456,7 @@ defmodule DynamicSupervisor do
 
     * `:max_children` - the maximum amount of children to be running
       under this supervisor at the same time. When `:max_children` is
-      exceeded, `start_child/2` returns `{:error, :max_children}`. Defaults
+      exceeded, `start_child/2` returns `{:error, :dynamic}`. Defaults
       to `:infinity`.
 
     * `:extra_arguments` - arguments that are prepended to the arguments
@@ -501,8 +464,7 @@ defmodule DynamicSupervisor do
       an empty list.
 
   """
-  @doc since: "1.6.0"
-  @spec init([init_option]) :: {:ok, sup_flags()}
+  @spec init([init_option]) :: {:ok, map()}
   def init(options) when is_list(options) do
     unless strategy = options[:strategy] do
       raise ArgumentError, "expected :strategy option to be given"
@@ -656,10 +618,10 @@ defmodule DynamicSupervisor do
   end
 
   def handle_call({:start_child, child}, _from, state) do
-    %{children: children, max_children: max_children} = state
+    %{dynamic: dynamic, max_children: max_children} = state
 
-    if map_size(children) < max_children do
-      handle_start_child(child, state)
+    if dynamic < max_children do
+      handle_start_child(child, %{state | dynamic: dynamic + 1})
     else
       {:reply, {:error, :max_children}, state}
     end
@@ -676,7 +638,7 @@ defmodule DynamicSupervisor do
         {:reply, reply, save_child(pid, mfa, restart, shutdown, type, modules, state)}
 
       _ ->
-        {:reply, reply, state}
+        {:reply, reply, update_in(state.dynamic, &(&1 - 1))}
     end
   end
 
@@ -685,7 +647,7 @@ defmodule DynamicSupervisor do
       apply(m, f, a)
     catch
       kind, reason ->
-        {:error, exit_reason(kind, reason, __STACKTRACE__)}
+        {:error, exit_reason(kind, reason, System.stacktrace())}
     else
       {:ok, pid, extra} when is_pid(pid) -> {:ok, pid, extra}
       {:ok, pid} when is_pid(pid) -> {:ok, pid}
@@ -695,13 +657,13 @@ defmodule DynamicSupervisor do
     end
   end
 
-  defp save_child(pid, mfa, restart, shutdown, type, modules, state) do
-    mfa = mfa_for_restart(mfa, restart)
-    put_in(state.children[pid], {mfa, restart, shutdown, type, modules})
+  defp save_child(pid, {m, f, _}, :temporary, shutdown, type, modules, state) do
+    put_in(state.children[pid], {{m, f, :undefined}, :temporary, shutdown, type, modules})
   end
 
-  defp mfa_for_restart({m, f, _}, :temporary), do: {m, f, :undefined}
-  defp mfa_for_restart(mfa, _), do: mfa
+  defp save_child(pid, mfa, restart, shutdown, type, modules, state) do
+    put_in(state.children[pid], {mfa, restart, shutdown, type, modules})
+  end
 
   defp exit_reason(:exit, reason, _), do: reason
   defp exit_reason(:error, reason, stack), do: {reason, stack}
@@ -919,8 +881,9 @@ defmodule DynamicSupervisor do
     {:ok, delete_child(pid, state)}
   end
 
-  defp delete_child(pid, %{children: children} = state) do
-    %{state | children: Map.delete(children, pid)}
+  defp delete_child(pid, state) do
+    %{children: children, dynamic: dynamic} = state
+    %{state | children: Map.delete(children, pid), dynamic: dynamic - 1}
   end
 
   defp restart_child(pid, child, state) do
@@ -944,6 +907,8 @@ defmodule DynamicSupervisor do
   defp add_restart(state) do
     %{max_seconds: max_seconds, max_restarts: max_restarts, restarts: restarts} = state
 
+    # The below is equivalent to 1 second. We avoid
+    # :second because of incompatibilties with OTP < 20
     now = :erlang.monotonic_time(1)
     restarts = add_restart([now | restarts], now, max_seconds)
     state = %{state | restarts: restarts}

lib/elixir/lib/enum.ex

@@ -131,10 +131,10 @@ defprotocol Enumerable do
 
   As an example, here is the implementation of `reduce` for lists:
 
-      def reduce(_list, {:halt, acc}, _fun), do: {:halted, acc}
-      def reduce(list, {:suspend, acc}, fun), do: {:suspended, acc, &reduce(list, &1, fun)}
-      def reduce([], {:cont, acc}, _fun), do: {:done, acc}
-      def reduce([head | tail], {:cont, acc}, fun), do: reduce(tail, fun.(head, acc), fun)
+      def reduce(_,       {:halt, acc}, _fun),   do: {:halted, acc}
+      def reduce(list,    {:suspend, acc}, fun), do: {:suspended, acc, &reduce(list, &1, fun)}
+      def reduce([],      {:cont, acc}, _fun),   do: {:done, acc}
+      def reduce([h | t], {:cont, acc}, fun),    do: reduce(t, fun.(h, acc), fun)
 
   """
   @spec reduce(t, acc, reducer) :: result
@@ -156,7 +156,7 @@ defprotocol Enumerable do
   Checks if an element exists within the enumerable.
 
   It should return `{:ok, boolean}` if you can check the membership of a
-  given element in the enumerable with `===/2` without traversing the whole
+  given element in the enumerable with `===` without traversing the whole
   enumerable.
 
   Otherwise it should return `{:error, __MODULE__}` and a default algorithm
@@ -197,51 +197,30 @@ defmodule Enum do
   import Kernel, except: [max: 2, min: 2]
 
   @moduledoc """
-  Provides a set of algorithms to work with enumerables.
+  Provides a set of algorithms that enumerate over enumerables according
+  to the `Enumerable` protocol.
 
-  In Elixir, an enumerable is any data type that implements the
-  `Enumerable` protocol. `List`s (`[1, 2, 3]`), `Map`s (`%{foo: 1, bar: 2}`)
-  and `Range`s (`1..3`) are common data types used as enumerables:
-
-      iex> Enum.map([1, 2, 3], fn x -> x * 2 end)
+      iex> Enum.map([1, 2, 3], fn(x) -> x * 2 end)
       [2, 4, 6]
 
-      iex> Enum.sum([1, 2, 3])
-      6
+  Some particular types, like maps, yield a specific format on enumeration.
+  For example, the argument is always a `{key, value}` tuple for maps:
 
-      iex> Enum.map(1..3, fn x -> x * 2 end)
-      [2, 4, 6]
-
-      iex> Enum.sum(1..3)
-      6
-
-      iex> map = %{"a" => 1, "b" => 2}
+      iex> map = %{a: 1, b: 2}
       iex> Enum.map(map, fn {k, v} -> {k, v * 2} end)
-      [{"a", 2}, {"b", 4}]
+      [a: 2, b: 4]
 
-  However, many other enumerables exist in the language, such as `MapSet`s
-  and the data type returned by `File.stream!/3` which allows a file to be
-  traversed as if it was an enumerable.
+  Note that the functions in the `Enum` module are eager: they always
+  start the enumeration of the given enumerable. The `Stream` module
+  allows lazy enumeration of enumerables and provides infinite streams.
 
-  The functions in this module work in linear time. This means that,
-  the larger the enumerable, the longer it will take to perform the desired
-  operation. This is expected on operations such as `Enum.map/2`. After all,
-  if we want to traverse every element on a list, the longer the list, the
-  more elements we need to traverse, and the longer it will take.
+  Since the majority of the functions in `Enum` enumerate the whole
+  enumerable and return a list as result, infinite streams need to
+  be carefully used with such functions, as they can potentially run
+  forever. For example:
 
-  This linear behaviour should also be expected on operations like `count/1`,
-  `member?/2`, `at/2` and similar. While Elixir does allow data types to
-  provide performant variants for such operations, you should not expect it
-  to always be available, since the `Enum` module is meant to work with a
-  large variety of data types and not all data types can provide optimized
-  behaviour.
+      Enum.each Stream.cycle([1, 2, 3]), &IO.puts(&1)
 
-  Finally, note the functions in the `Enum` module are eager: they will
-  traverse the enumerable as soon as they are invoked. This is particularly
-  dangerous when working with infinite enumerables. In such cases, you should
-  use the `Stream` module, which allows you to lazily express computations,
-  without traversing collections, and work with possibly infinite collections.
-  See the `Stream` module for examples and documentation.
   """
 
   @compile :inline_list_funcs
@@ -252,6 +231,7 @@ defmodule Enum do
   @type index :: integer
   @type default :: any
 
+  # Require Stream.Reducers and its callbacks
   require Stream.Reducers, as: R
 
   defmacrop skip(acc) do
@@ -273,16 +253,16 @@ defmodule Enum do
   end
 
   @doc """
-  Returns `true` if the given `fun` evaluates to true on all of the items in the enumerable.
+  Returns true if the given `fun` evaluates to true on all of the items in the enumerable.
 
   It stops the iteration at the first invocation that returns `false` or `nil`.
 
   ## Examples
 
-      iex> Enum.all?([2, 4, 6], fn x -> rem(x, 2) == 0 end)
+      iex> Enum.all?([2, 4, 6], fn(x) -> rem(x, 2) == 0 end)
       true
 
-      iex> Enum.all?([2, 3, 4], fn x -> rem(x, 2) == 0 end)
+      iex> Enum.all?([2, 3, 4], fn(x) -> rem(x, 2) == 0 end)
       false
 
   If no function is given, it defaults to checking if
@@ -311,16 +291,16 @@ defmodule Enum do
   end
 
   @doc """
-  Returns `true` if the given `fun` evaluates to true on any of the items in the enumerable.
+  Returns true if the given `fun` evaluates to true on any of the items in the enumerable.
 
-  It stops the iteration at the first invocation that returns a truthy value (neither `false` nor `nil`).
+  It stops the iteration at the first invocation that returns a truthy value (not `false` or `nil`).
 
   ## Examples
 
-      iex> Enum.any?([2, 4, 6], fn x -> rem(x, 2) == 1 end)
+      iex> Enum.any?([2, 4, 6], fn(x) -> rem(x, 2) == 1 end)
       false
 
-      iex> Enum.any?([2, 3, 4], fn x -> rem(x, 2) == 1 end)
+      iex> Enum.any?([2, 3, 4], fn(x) -> rem(x, 2) == 1 end)
       true
 
   If no function is given, it defaults to checking if at least one item
@@ -357,6 +337,10 @@ defmodule Enum do
   enumerated once and the `index` is counted from the end (e.g.
   `-1` finds the last element).
 
+  Note this operation takes linear time. In order to access
+  the element at index `index`, it will need to traverse `index`
+  previous elements.
+
   ## Examples
 
       iex> Enum.at([2, 4, 6], 0)
@@ -380,29 +364,19 @@ defmodule Enum do
     end
   end
 
-  # TODO: Remove by 2.0
+  # Deprecate on v1.7
   @doc false
-  @deprecated "Use Enum.chunk_every/2 instead"
   def chunk(enumerable, count), do: chunk(enumerable, count, count, nil)
 
-  # TODO: Remove by 2.0
+  # Deprecate on v1.7
   @doc false
-  @deprecated "Use Enum.chunk_every/3 instead"
-  def chunk(enum, n, step) do
-    chunk_every(enum, n, step, nil)
-  end
-
-  # TODO: Remove by 2.0
-  @doc false
-  @deprecated "Use Enum.chunk_every/4 instead"
-  def chunk(enumerable, count, step, leftover) do
+  def chunk(enumerable, count, step, leftover \\ nil) do
     chunk_every(enumerable, count, step, leftover || :discard)
   end
 
   @doc """
   Shortcut to `chunk_every(enumerable, count, count)`.
   """
-  @doc since: "1.5.0"
   @spec chunk_every(t, pos_integer) :: [list]
   def chunk_every(enumerable, count), do: chunk_every(enumerable, count, count, [])
 
@@ -442,7 +416,6 @@ defmodule Enum do
       [[1, 2], [4, 5]]
 
   """
-  @doc since: "1.5.0"
   @spec chunk_every(t, pos_integer, pos_integer, t | :discard) :: [list]
   def chunk_every(enumerable, count, step, leftover \\ [])
       when is_integer(count) and count > 0 and is_integer(step) and step > 0 do
@@ -464,11 +437,11 @@ defmodule Enum do
 
   ## Examples
 
-      iex> chunk_fun = fn item, acc ->
-      ...>   if rem(item, 2) == 0 do
-      ...>     {:cont, Enum.reverse([item | acc]), []}
+      iex> chunk_fun = fn i, acc ->
+      ...>   if rem(i, 2) == 0 do
+      ...>     {:cont, Enum.reverse([i | acc]), []}
       ...>   else
-      ...>     {:cont, [item | acc]}
+      ...>     {:cont, [i | acc]}
       ...>   end
       ...> end
       iex> after_fun = fn
@@ -479,7 +452,6 @@ defmodule Enum do
       [[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]]
 
   """
-  @doc since: "1.5.0"
   @spec chunk_while(
           t,
           acc,
@@ -594,7 +566,7 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.count([1, 2, 3, 4, 5], fn x -> rem(x, 2) == 0 end)
+      iex> Enum.count([1, 2, 3, 4, 5], fn(x) -> rem(x, 2) == 0 end)
       2
 
   """
@@ -609,7 +581,7 @@ defmodule Enum do
   Enumerates the `enumerable`, returning a list where all consecutive
   duplicated elements are collapsed to a single element.
 
-  Elements are compared using `===/2`.
+  Elements are compared using `===`.
 
   If you want to remove all duplicated elements, regardless of order,
   see `uniq/1`.
@@ -619,7 +591,7 @@ defmodule Enum do
       iex> Enum.dedup([1, 2, 3, 3, 2, 1])
       [1, 2, 3, 2, 1]
 
-      iex> Enum.dedup([1, 1, 2, 2.0, :three, :three])
+      iex> Enum.dedup([1, 1, 2, 2.0, :three, :"three"])
       [1, 2, 2.0, :three]
 
   """
@@ -733,7 +705,7 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.drop_while([1, 2, 3, 2, 1], fn x -> x < 3 end)
+      iex> Enum.drop_while([1, 2, 3, 2, 1], fn(x) -> x < 3 end)
       [3, 2, 1]
 
   """
@@ -815,6 +787,10 @@ defmodule Enum do
   enumerated once and the `index` is counted from the end (e.g.
   `-1` fetches the last element).
 
+  Note this operation takes linear time. In order to access
+  the element at index `index`, it will need to traverse `index`
+  previous elements.
+
   ## Examples
 
       iex> Enum.fetch([2, 4, 6], 0)
@@ -844,6 +820,9 @@ defmodule Enum do
   Raises `OutOfBoundsError` if the given `index` is outside the range of
   the enumerable.
 
+  Note this operation takes linear time. In order to access the element
+  at index `index`, it will need to traverse `index` previous elements.
+
   ## Examples
 
       iex> Enum.fetch!([2, 4, 6], 0)
@@ -869,11 +848,11 @@ defmodule Enum do
   for which `fun` returns a truthy value.
 
   See also `reject/2` which discards all elements where the
-  function a truthy value.
+  function returns true.
 
   ## Examples
 
-      iex> Enum.filter([1, 2, 3], fn x -> rem(x, 2) == 0 end)
+      iex> Enum.filter([1, 2, 3], fn(x) -> rem(x, 2) == 0 end)
       [2]
 
   Keep in mind that `filter` is not capable of filtering and
@@ -902,7 +881,7 @@ defmodule Enum do
 
   @doc false
   # TODO: Remove on 2.0
-  @deprecated "Use Enum.filter/2 + Enum.map/2 or for comprehensions instead"
+  # (hard-deprecated in elixir_dispatch)
   def filter_map(enumerable, filter, mapper) when is_list(enumerable) do
     for item <- enumerable, filter.(item), do: mapper.(item)
   end
@@ -919,13 +898,13 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.find([2, 4, 6], fn x -> rem(x, 2) == 1 end)
+      iex> Enum.find([2, 4, 6], fn(x) -> rem(x, 2) == 1 end)
       nil
 
-      iex> Enum.find([2, 4, 6], 0, fn x -> rem(x, 2) == 1 end)
+      iex> Enum.find([2, 4, 6], 0, fn(x) -> rem(x, 2) == 1 end)
       0
 
-      iex> Enum.find([2, 3, 4], fn x -> rem(x, 2) == 1 end)
+      iex> Enum.find([2, 3, 4], fn(x) -> rem(x, 2) == 1 end)
       3
 
   """
@@ -949,10 +928,10 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.find_index([2, 4, 6], fn x -> rem(x, 2) == 1 end)
+      iex> Enum.find_index([2, 4, 6], fn(x) -> rem(x, 2) == 1 end)
       nil
 
-      iex> Enum.find_index([2, 3, 4], fn x -> rem(x, 2) == 1 end)
+      iex> Enum.find_index([2, 3, 4], fn(x) -> rem(x, 2) == 1 end)
       1
 
   """
@@ -979,10 +958,10 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.find_value([2, 4, 6], fn x -> rem(x, 2) == 1 end)
+      iex> Enum.find_value([2, 4, 6], fn(x) -> rem(x, 2) == 1 end)
       nil
 
-      iex> Enum.find_value([2, 3, 4], fn x -> rem(x, 2) == 1 end)
+      iex> Enum.find_value([2, 3, 4], fn(x) -> rem(x, 2) == 1 end)
       true
 
       iex> Enum.find_value([1, 2, 3], "no bools!", &is_boolean/1)
@@ -1013,13 +992,13 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.flat_map([:a, :b, :c], fn x -> [x, x] end)
+      iex> Enum.flat_map([:a, :b, :c], fn(x) -> [x, x] end)
       [:a, :a, :b, :b, :c, :c]
 
-      iex> Enum.flat_map([{1, 3}, {4, 6}], fn {x, y} -> x..y end)
+      iex> Enum.flat_map([{1, 3}, {4, 6}], fn({x, y}) -> x..y end)
       [1, 2, 3, 4, 5, 6]
 
-      iex> Enum.flat_map([:a, :b, :c], fn x -> [[x]] end)
+      iex> Enum.flat_map([:a, :b, :c], fn(x) -> [[x]] end)
       [[:a], [:b], [:c]]
 
   """
@@ -1050,12 +1029,12 @@ defmodule Enum do
 
       iex> enumerable = 1..100
       iex> n = 3
-      iex> Enum.flat_map_reduce(enumerable, 0, fn x, acc ->
-      ...>   if acc < n, do: {[x], acc + 1}, else: {:halt, acc}
+      iex> Enum.flat_map_reduce(enumerable, 0, fn i, acc ->
+      ...>   if acc < n, do: {[i], acc + 1}, else: {:halt, acc}
       ...> end)
       {[1, 2, 3], 3}
 
-      iex> Enum.flat_map_reduce(1..5, 0, fn x, acc -> {[[x]], acc + x} end)
+      iex> Enum.flat_map_reduce(1..5, 0, fn(i, acc) -> {[[i]], acc + i} end)
       {[[1], [2], [3], [4], [5]], 15}
 
   """
@@ -1250,8 +1229,9 @@ defmodule Enum do
       reduce(enumerable, initial, callback)
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         fun.(initial, :halt)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     else
       acc -> fun.(acc, :done)
     end
@@ -1300,10 +1280,10 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.map([1, 2, 3], fn x -> x * 2 end)
+      iex> Enum.map([1, 2, 3], fn(x) -> x * 2 end)
       [2, 4, 6]
 
-      iex> Enum.map([a: 1, b: 2], fn {k, v} -> {k, -v} end)
+      iex> Enum.map([a: 1, b: 2], fn({k, v}) -> {k, -v} end)
       [a: -1, b: -2]
 
   """
@@ -1345,7 +1325,6 @@ defmodule Enum do
       [1001, 1002, 1003]
 
   """
-  @doc since: "1.4.0"
   @spec map_every(t, non_neg_integer, (element -> any)) :: list
   def map_every(enumerable, nth, fun)
 
@@ -1409,7 +1388,7 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.map_reduce([1, 2, 3], 0, fn x, acc -> {x * 2, x + acc} end)
+      iex> Enum.map_reduce([1, 2, 3], 0, fn(x, acc) -> {x * 2, x + acc} end)
       {[2, 4, 6], 6}
 
   """
@@ -1462,8 +1441,6 @@ defmodule Enum do
       iex> Enum.max_by([~D[2017-03-31], ~D[2017-04-01]], &Date.to_erl/1)
       ~D[2017-04-01]
 
-  For selecting a maximum value out of two consider using `Kernel.max/2`.
-
   """
   @spec max(t, (() -> empty_result)) :: element | empty_result | no_return when empty_result: any
   def max(enumerable, empty_fallback \\ fn -> raise Enum.EmptyError end) do
@@ -1482,7 +1459,7 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.max_by(["a", "aa", "aaa"], fn x -> String.length(x) end)
+      iex> Enum.max_by(["a", "aa", "aaa"], fn(x) -> String.length(x) end)
       "aaa"
 
       iex> Enum.max_by(["a", "aa", "aaa", "b", "bbb"], &String.length/1)
@@ -1511,7 +1488,7 @@ defmodule Enum do
   @doc """
   Checks if `element` exists within the enumerable.
 
-  Membership is tested with the match (`===/2`) operator.
+  Membership is tested with the match (`===`) operator.
 
   ## Examples
 
@@ -1582,8 +1559,6 @@ defmodule Enum do
       iex> Enum.min_by([~D[2017-03-31], ~D[2017-04-01]], &Date.to_erl/1)
       ~D[2017-03-31]
 
-  For selecting a minimal value out of two consider using `Kernel.min/2`.
-
   """
   @spec min(t, (() -> empty_result)) :: element | empty_result | no_return when empty_result: any
   def min(enumerable, empty_fallback \\ fn -> raise Enum.EmptyError end) do
@@ -1602,7 +1577,7 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.min_by(["a", "aa", "aaa"], fn x -> String.length(x) end)
+      iex> Enum.min_by(["a", "aa", "aaa"], fn(x) -> String.length(x) end)
       "a"
 
       iex> Enum.min_by(["a", "aa", "aaa", "b", "bbb"], &String.length/1)
@@ -1651,8 +1626,8 @@ defmodule Enum do
         when empty_result: any
   def min_max(enumerable, empty_fallback \\ fn -> raise Enum.EmptyError end)
 
-  def min_max(first..last, _empty_fallback) do
-    {Kernel.min(first, last), Kernel.max(first, last)}
+  def min_max(left..right, _empty_fallback) do
+    {Kernel.min(left, right), Kernel.max(left, right)}
   end
 
   def min_max(enumerable, empty_fallback) do
@@ -1680,7 +1655,7 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.min_max_by(["aaa", "bb", "c"], fn x -> String.length(x) end)
+      iex> Enum.min_max_by(["aaa", "bb", "c"], fn(x) -> String.length(x) end)
       {"c", "aaa"}
 
       iex> Enum.min_max_by(["aaa", "a", "bb", "c", "ccc"], &String.length/1)
@@ -1737,20 +1712,19 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.split_with([5, 4, 3, 2, 1, 0], fn x -> rem(x, 2) == 0 end)
+      iex> Enum.split_with([5, 4, 3, 2, 1, 0], fn(x) -> rem(x, 2) == 0 end)
       {[4, 2, 0], [5, 3, 1]}
 
-      iex> Enum.split_with(%{a: 1, b: -2, c: 1, d: -3}, fn {_k, v} -> v < 0 end)
+      iex> Enum.split_with(%{a: 1, b: -2, c: 1, d: -3}, fn({_k, v}) -> v < 0 end)
       {[b: -2, d: -3], [a: 1, c: 1]}
 
-      iex> Enum.split_with(%{a: 1, b: -2, c: 1, d: -3}, fn {_k, v} -> v > 50 end)
+      iex> Enum.split_with(%{a: 1, b: -2, c: 1, d: -3}, fn({_k, v}) -> v > 50 end)
       {[], [a: 1, b: -2, c: 1, d: -3]}
 
-      iex> Enum.split_with(%{}, fn {_k, v} -> v > 50 end)
+      iex> Enum.split_with(%{}, fn({_k, v}) -> v > 50 end)
       {[], []}
 
   """
-  @doc since: "1.4.0"
   @spec split_with(t, (element -> any)) :: {list, list}
   def split_with(enumerable, fun) do
     {acc1, acc2} =
@@ -1767,7 +1741,7 @@ defmodule Enum do
 
   @doc false
   # TODO: Remove on 2.0
-  @deprecated "Use Enum.split_with/2 instead"
+  # (hard-deprecated in elixir_dispatch)
   def partition(enumerable, fun) do
     split_with(enumerable, fun)
   end
@@ -1854,7 +1828,7 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.reduce([1, 2, 3, 4], fn x, acc -> x * acc end)
+      iex> Enum.reduce([1, 2, 3, 4], fn(x, acc) -> x * acc end)
       24
 
   """
@@ -1893,7 +1867,7 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.reduce([1, 2, 3], 0, fn x, acc -> x + acc end)
+      iex> Enum.reduce([1, 2, 3], 0, fn(x, acc) -> x + acc end)
       6
 
   ## Reduce as a building block
@@ -1934,7 +1908,7 @@ defmodule Enum do
   end
 
   def reduce(%_{} = enumerable, acc, fun) do
-    reduce_enumerable(enumerable, acc, fun)
+    Enumerable.reduce(enumerable, {:cont, acc}, fn x, acc -> {:cont, fun.(x, acc)} end) |> elem(1)
   end
 
   def reduce(%{} = enumerable, acc, fun) do
@@ -1942,7 +1916,7 @@ defmodule Enum do
   end
 
   def reduce(enumerable, acc, fun) do
-    reduce_enumerable(enumerable, acc, fun)
+    Enumerable.reduce(enumerable, {:cont, acc}, fn x, acc -> {:cont, fun.(x, acc)} end) |> elem(1)
   end
 
   @doc """
@@ -1957,8 +1931,8 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.reduce_while(1..100, 0, fn x, acc ->
-      ...>   if x < 3, do: {:cont, acc + x}, else: {:halt, acc}
+      iex> Enum.reduce_while(1..100, 0, fn i, acc ->
+      ...>   if i < 3, do: {:cont, acc + i}, else: {:halt, acc}
       ...> end)
       3
 
@@ -1969,14 +1943,14 @@ defmodule Enum do
   end
 
   @doc """
-  Returns a list of elements in `enumerable` excluding those for which the function `fun` returns
-  a truthy value.
+  Returns elements of `enumerable` for which the function `fun` returns
+  `false` or `nil`.
 
   See also `filter/2`.
 
   ## Examples
 
-      iex> Enum.reject([1, 2, 3], fn x -> rem(x, 2) == 0 end)
+      iex> Enum.reject([1, 2, 3], fn(x) -> rem(x, 2) == 0 end)
       [1, 3]
 
   """
@@ -2008,11 +1982,11 @@ defmodule Enum do
   def reverse(enumerable), do: reduce(enumerable, [], &[&1 | &2])
 
   @doc """
-  Reverses the elements in `enumerable`, appends the `tail`, and returns
+  Reverses the elements in `enumerable`, appends the tail, and returns
   it as a list.
 
   This is an optimization for
-  `enumerable |> Enum.reverse() |> Enum.concat(tail)`.
+  `Enum.concat(Enum.reverse(enumerable), tail)`.
 
   ## Examples
 
@@ -2158,7 +2132,6 @@ defmodule Enum do
       []
 
   """
-  @doc since: "1.6.0"
   @spec slice(t, Range.t()) :: list
   def slice(enumerable, first..last) do
     {count, fun} = slice_count_and_fun(enumerable)
@@ -2247,14 +2220,14 @@ defmodule Enum do
   The sorting algorithm will be stable as long as the given function
   returns `true` for values considered equal:
 
-      iex> Enum.sort(["some", "kind", "of", "monster"], &(byte_size(&1) <= byte_size(&2)))
+      iex> Enum.sort ["some", "kind", "of", "monster"], &(byte_size(&1) <= byte_size(&2))
       ["of", "some", "kind", "monster"]
 
   If the function does not return `true` for equal values, the sorting
   is not stable and the order of equal terms may be shuffled.
   For example:
 
-      iex> Enum.sort(["some", "kind", "of", "monster"], &(byte_size(&1) < byte_size(&2)))
+      iex> Enum.sort ["some", "kind", "of", "monster"], &(byte_size(&1) < byte_size(&2))
       ["of", "kind", "some", "monster"]
 
   """
@@ -2369,7 +2342,7 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.split_while([1, 2, 3, 4], fn x -> x < 3 end)
+      iex> Enum.split_while([1, 2, 3, 4], fn(x) -> x < 3 end)
       {[1, 2], [3, 4]}
 
   """
@@ -2575,7 +2548,7 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.take_while([1, 2, 3], fn x -> x < 3 end)
+      iex> Enum.take_while([1, 2, 3], fn(x) -> x < 3 end)
       [1, 2]
 
   """
@@ -2607,10 +2580,13 @@ defmodule Enum do
 
   """
   @spec to_list(t) :: [element]
-  def to_list(enumerable) when is_list(enumerable), do: enumerable
-  def to_list(%_{} = enumerable), do: reverse(enumerable) |> :lists.reverse()
-  def to_list(%{} = enumerable), do: Map.to_list(enumerable)
-  def to_list(enumerable), do: reverse(enumerable) |> :lists.reverse()
+  def to_list(enumerable) when is_list(enumerable) do
+    enumerable
+  end
+
+  def to_list(enumerable) do
+    reverse(enumerable) |> :lists.reverse()
+  end
 
   @doc """
   Enumerates the `enumerable`, removing all duplicated elements.
@@ -2628,7 +2604,7 @@ defmodule Enum do
 
   @doc false
   # TODO: Remove on 2.0
-  @deprecated "Use Enum.uniq_by/2 instead"
+  # (hard-deprecated in elixir_dispatch)
   def uniq(enumerable, fun) do
     uniq_by(enumerable, fun)
   end
@@ -2756,7 +2732,6 @@ defmodule Enum do
       [{1, :a}, {2, :b}, {3, :c}]
 
   """
-  @doc since: "1.4.0"
   @spec zip([t]) :: t
   @spec zip(t) :: t
 
@@ -2770,8 +2745,7 @@ defmodule Enum do
 
   ## Helpers
 
-  @compile {:inline,
-            aggregate: 3, entry_to_string: 1, reduce: 3, reduce_by: 3, reduce_enumerable: 3}
+  @compile {:inline, aggregate: 3, entry_to_string: 1, reduce: 3, reduce_by: 3}
 
   defp entry_to_string(entry) when is_binary(entry), do: entry
   defp entry_to_string(entry), do: String.Chars.to_string(entry)
@@ -2784,8 +2758,8 @@ defmodule Enum do
     empty.()
   end
 
-  defp aggregate(first..last, fun, _empty) do
-    fun.(first, last)
+  defp aggregate(left..right, fun, _empty) do
+    fun.(left, right)
   end
 
   defp aggregate(enumerable, fun, empty) do
@@ -2829,13 +2803,13 @@ defmodule Enum do
     lower_limit + :rand.uniform(upper_limit - lower_limit + 1) - 1
   end
 
-  # TODO: Remove me on Elixir v1.9
+  # TODO: Remove me on Elixir v1.8
   defp backwards_compatible_slice(args) do
     try do
       Enumerable.slice(args)
     catch
       :error, :undef ->
-        case __STACKTRACE__ do
+        case System.stacktrace() do
           [{module, :slice, [^args], _} | _] -> {:error, module}
           stack -> :erlang.raise(:error, :undef, stack)
         end
@@ -2975,10 +2949,6 @@ defmodule Enum do
     reduce_range_dec(first - 1, last, fun.(first, acc), fun)
   end
 
-  defp reduce_enumerable(enumerable, acc, fun) do
-    Enumerable.reduce(enumerable, {:cont, acc}, fn x, acc -> {:cont, fun.(x, acc)} end) |> elem(1)
-  end
-
   ## reject
 
   defp reject_list([head | tail], fun) do
@@ -3275,16 +3245,16 @@ defimpl Enumerable, for: List do
   def member?(_list, _value), do: {:error, __MODULE__}
   def slice(_list), do: {:error, __MODULE__}
 
-  def reduce(_list, {:halt, acc}, _fun), do: {:halted, acc}
+  def reduce(_, {:halt, acc}, _fun), do: {:halted, acc}
   def reduce(list, {:suspend, acc}, fun), do: {:suspended, acc, &reduce(list, &1, fun)}
   def reduce([], {:cont, acc}, _fun), do: {:done, acc}
-  def reduce([head | tail], {:cont, acc}, fun), do: reduce(tail, fun.(head, acc), fun)
+  def reduce([h | t], {:cont, acc}, fun), do: reduce(t, fun.(h, acc), fun)
 
   @doc false
   def slice([], _start, _count), do: []
   def slice(_list, _start, 0), do: []
   def slice([head | tail], 0, count), do: [head | slice(tail, 0, count - 1)]
-  def slice([_head | tail], start, count), do: slice(tail, start - 1, count)
+  def slice([_ | tail], start, count), do: slice(tail, start - 1, count)
 end
 
 defimpl Enumerable, for: Map do
@@ -3308,10 +3278,10 @@ defimpl Enumerable, for: Map do
     reduce_list(:maps.to_list(map), acc, fun)
   end
 
-  defp reduce_list(_list, {:halt, acc}, _fun), do: {:halted, acc}
+  defp reduce_list(_, {:halt, acc}, _fun), do: {:halted, acc}
   defp reduce_list(list, {:suspend, acc}, fun), do: {:suspended, acc, &reduce_list(list, &1, fun)}
   defp reduce_list([], {:cont, acc}, _fun), do: {:done, acc}
-  defp reduce_list([head | tail], {:cont, acc}, fun), do: reduce_list(tail, fun.(head, acc), fun)
+  defp reduce_list([h | t], {:cont, acc}, fun), do: reduce_list(t, fun.(h, acc), fun)
 end
 
 defimpl Enumerable, for: Function do

lib/elixir/lib/exception.ex

@@ -2,8 +2,10 @@ defmodule Exception do
   @moduledoc """
   Functions to format throw/catch/exit and exceptions.
 
-  Note that stacktraces in Elixir are only available inside
-  catch and rescue by using the `__STACKTRACE__/0` variable.
+  Note that stacktraces in Elixir are updated on throw,
+  errors and exits. For example, at any given moment,
+  `System.stacktrace/0` will return the stacktrace for the
+  last throw/error/exit that occurred in the current process.
 
   Do not rely on the particular format returned by the `format*`
   functions in this module. They may be changed in future releases
@@ -80,16 +82,31 @@ defmodule Exception do
   normalizes only `:error`, returning the untouched payload
   for others.
 
-  The third argument is the stacktrace which is used to enrich
-  a normalized error with more information. It is only used when
-  the kind is an error.
+  The third argument, a stacktrace, is optional. If it is
+  not supplied `System.stacktrace/0` will sometimes be used
+  to get additional information for the `kind` `:error`. If
+  the stacktrace is unknown and `System.stacktrace/0` would
+  not return the stacktrace corresponding to the exception
+  an empty stacktrace, `[]`, must be used.
   """
   @spec normalize(:error, any, stacktrace) :: t
   @spec normalize(non_error_kind, payload, stacktrace) :: payload when payload: var
-  def normalize(kind, payload, stacktrace \\ [])
-  def normalize(:error, %_{__exception__: true} = payload, _stacktrace), do: payload
-  def normalize(:error, payload, stacktrace), do: ErlangError.normalize(payload, stacktrace)
-  def normalize(_kind, payload, _stacktrace), do: payload
+
+  # Generating a stacktrace is expensive, default to nil
+  # to only fetch it when needed.
+  def normalize(kind, payload, stacktrace \\ nil)
+
+  def normalize(:error, exception, stacktrace) do
+    if exception?(exception) do
+      exception
+    else
+      ErlangError.normalize(exception, stacktrace)
+    end
+  end
+
+  def normalize(_kind, payload, _stacktrace) do
+    payload
+  end
 
   @doc """
   Normalizes and formats any throw/error/exit.
@@ -97,12 +114,15 @@ defmodule Exception do
   The message is formatted and displayed in the same
   format as used by Elixir's CLI.
 
-  The third argument is the stacktrace which is used to enrich
-  a normalized error with more information. It is only used when
-  the kind is an error.
+  The third argument, a stacktrace, is optional. If it is
+  not supplied `System.stacktrace/0` will sometimes be used
+  to get additional information for the `kind` `:error`. If
+  the stacktrace is unknown and `System.stacktrace/0` would
+  not return the stacktrace corresponding to the exception
+  an empty stacktrace, `[]`, must be used.
   """
-  @spec format_banner(kind, any, stacktrace) :: String.t()
-  def format_banner(kind, exception, stacktrace \\ [])
+  @spec format_banner(kind, any, stacktrace | nil) :: String.t()
+  def format_banner(kind, exception, stacktrace \\ nil)
 
   def format_banner(:error, exception, stacktrace) do
     exception = normalize(:error, exception, stacktrace)
@@ -127,17 +147,18 @@ defmodule Exception do
   It relies on `format_banner/3` and `format_stacktrace/1`
   to generate the final format.
 
-  If `kind` is `{:EXIT, pid}`, it does not generate a stacktrace,
-  as such exits are retrieved as messages without stacktraces.
+  Note that `{:EXIT, pid}` do not generate a stacktrace though
+  (as they are retrieved as messages without stacktraces).
   """
-  @spec format(kind, any, stacktrace) :: String.t()
-  def format(kind, payload, stacktrace \\ [])
+  @spec format(kind, any, stacktrace | nil) :: String.t()
+  def format(kind, payload, stacktrace \\ nil)
 
   def format({:EXIT, _} = kind, any, _) do
     format_banner(kind, any)
   end
 
   def format(kind, payload, stacktrace) do
+    stacktrace = stacktrace || System.stacktrace()
     message = format_banner(kind, payload, stacktrace)
 
     case stacktrace do
@@ -150,13 +171,12 @@ defmodule Exception do
   Attaches information to exceptions for extra debugging.
 
   This operation is potentially expensive, as it reads data
-  from the filesystem, parses beam files, evaluates code and
+  from the filesystem, parse beam files, evaluates code and
   so on.
 
   If the exception module implements the optional `c:blame/2`
-  callback, it will be invoked to perform the computation.
+  callbak, it will be invoked to perform the computation.
   """
-  @doc since: "1.5.0"
   @spec blame(:error, any, stacktrace) :: {t, stacktrace}
   @spec blame(non_error_kind, payload, stacktrace) :: {payload, stacktrace} when payload: var
   def blame(kind, error, stacktrace)
@@ -189,7 +209,6 @@ defmodule Exception do
   Note this functionality requires Erlang/OTP 20, otherwise `:error`
   is always returned.
   """
-  @doc since: "1.5.0"
   @spec blame_mfa(module, function, args :: [term]) ::
           {:ok, :def | :defp | :defmacro | :defmacrop, [{args :: [term], guards :: [term]}]}
           | :error
@@ -210,7 +229,7 @@ defmodule Exception do
          {_, kind, _, clauses} <- List.keyfind(defs, {function, arity}, 0) do
       clauses =
         for {meta, ex_args, guards, _block} <- clauses do
-          scope = :elixir_erl.scope(meta)
+          scope = :elixir_erl.definition_scope(meta, "nofile")
 
           {erl_args, scope} =
             :elixir_erl_clauses.match(&:elixir_erl_pass.translate_args/2, ex_args, scope)
@@ -369,8 +388,8 @@ defmodule Exception do
         format_exit_reason(reason)
     else
       mfa ->
-        # Assume tuple formattable as an mfa is an mfa,
-        # so exit was caused by failed mfa.
+        # Assume tuple formattable as an mfa is an mfa, so exit was caused by
+        # failed mfa.
         "exited in: " <>
           mfa <> joiner <> "** (EXIT) " <> format_exit(reason2, joiner <> <<"    ">>)
     end
@@ -594,13 +613,13 @@ defmodule Exception do
 
   ## Examples
 
-      iex> Exception.format_mfa(Foo, :bar, 1)
+      iex> Exception.format_mfa Foo, :bar, 1
       "Foo.bar/1"
 
-      iex> Exception.format_mfa(Foo, :bar, [])
+      iex> Exception.format_mfa Foo, :bar, []
       "Foo.bar()"
 
-      iex> Exception.format_mfa(nil, :bar, [])
+      iex> Exception.format_mfa nil, :bar, []
       "nil.bar()"
 
   Anonymous functions are reported as -func/arity-anonfn-count-,
@@ -673,86 +692,15 @@ end
 
 defmodule ArgumentError do
   defexception message: "argument error"
-
-  @impl true
-  def blame(
-        %{message: "argument error"} = exception,
-        [{:erlang, :apply, [module, function, args], _} | _] = stacktrace
-      ) do
-    message =
-      cond do
-        # 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. " <>
-            "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"
-
-        not is_atom(module) ->
-          "you attempted to apply a function on #{inspect(module)}. " <>
-            "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"
-      end
-
-    {%{exception | message: message}, stacktrace}
-  end
-
-  def blame(exception, stacktrace) do
-    {exception, stacktrace}
-  end
 end
 
 defmodule ArithmeticError do
   defexception message: "bad argument in arithmetic expression"
-
-  @unary_ops [:+, :-]
-  @binary_ops [:+, :-, :*, :/]
-  @binary_funs [:div, :rem]
-  @bitwise_binary_funs [:band, :bor, :bxor, :bsl, :bsr]
-
-  @impl true
-  def blame(%{message: message} = exception, [{:erlang, fun, args, _} | _] = stacktrace) do
-    message =
-      message <>
-        case {fun, args} do
-          {op, [a]} when op in @unary_ops ->
-            ": #{op}(#{inspect(a)})"
-
-          {op, [a, b]} when op in @binary_ops ->
-            ": #{inspect(a)} #{op} #{inspect(b)}"
-
-          {fun, [a, b]} when fun in @binary_funs ->
-            ": #{fun}(#{inspect(a)}, #{inspect(b)})"
-
-          {fun, [a, b]} when fun in @bitwise_binary_funs ->
-            ": Bitwise.#{fun}(#{inspect(a)}, #{inspect(b)})"
-
-          {:bnot, [a]} ->
-            ": Bitwise.bnot(#{inspect(a)})"
-
-          _ ->
-            ""
-        end
-
-    {%{exception | message: message}, stacktrace}
-  end
-
-  def blame(exception, stacktrace) do
-    {exception, stacktrace}
-  end
 end
 
 defmodule SystemLimitError do
   defexception []
 
-  @impl true
   def message(_) do
     "a system limit has been reached"
   end
@@ -761,7 +709,6 @@ end
 defmodule SyntaxError do
   defexception [:file, :line, description: "syntax error"]
 
-  @impl true
   def message(exception) do
     Exception.format_file_line(Path.relative_to_cwd(exception.file), exception.line) <>
       " " <> exception.description
@@ -771,7 +718,6 @@ end
 defmodule TokenMissingError do
   defexception [:file, :line, description: "expression is incomplete"]
 
-  @impl true
   def message(%{file: file, line: line, description: description}) do
     Exception.format_file_line(file && Path.relative_to_cwd(file), line) <> " " <> description
   end
@@ -780,7 +726,6 @@ end
 defmodule CompileError do
   defexception [:file, :line, description: "compile error"]
 
-  @impl true
   def message(%{file: file, line: line, description: description}) do
     Exception.format_file_line(file && Path.relative_to_cwd(file), line) <> " " <> description
   end
@@ -789,7 +734,6 @@ end
 defmodule BadFunctionError do
   defexception [:term]
 
-  @impl true
   def message(exception) do
     "expected a function, got: #{inspect(exception.term)}"
   end
@@ -798,7 +742,6 @@ end
 defmodule BadStructError do
   defexception [:struct, :term]
 
-  @impl true
   def message(exception) do
     "expected a struct named #{inspect(exception.struct)}, got: #{inspect(exception.term)}"
   end
@@ -807,7 +750,6 @@ end
 defmodule BadMapError do
   defexception [:term]
 
-  @impl true
   def message(exception) do
     "expected a map, got: #{inspect(exception.term)}"
   end
@@ -816,7 +758,6 @@ end
 defmodule BadBooleanError do
   defexception [:term, :operator]
 
-  @impl true
   def message(exception) do
     "expected a boolean on left-side of \"#{exception.operator}\", got: #{inspect(exception.term)}"
   end
@@ -825,7 +766,6 @@ end
 defmodule MatchError do
   defexception [:term]
 
-  @impl true
   def message(exception) do
     "no match of right hand side value: #{inspect(exception.term)}"
   end
@@ -834,7 +774,6 @@ end
 defmodule CaseClauseError do
   defexception [:term]
 
-  @impl true
   def message(exception) do
     "no case clause matching: #{inspect(exception.term)}"
   end
@@ -843,7 +782,6 @@ end
 defmodule WithClauseError do
   defexception [:term]
 
-  @impl true
   def message(exception) do
     "no with clause matching: #{inspect(exception.term)}"
   end
@@ -852,7 +790,6 @@ end
 defmodule CondClauseError do
   defexception []
 
-  @impl true
   def message(_exception) do
     "no cond clause evaluated to a true value"
   end
@@ -861,7 +798,6 @@ end
 defmodule TryClauseError do
   defexception [:term]
 
-  @impl true
   def message(exception) do
     "no try clause matching: #{inspect(exception.term)}"
   end
@@ -870,12 +806,11 @@ end
 defmodule BadArityError do
   defexception [:function, :args]
 
-  @impl true
   def message(exception) do
     fun = exception.function
     args = exception.args
     insp = Enum.map_join(args, ", ", &inspect/1)
-    {:arity, arity} = Function.info(fun, :arity)
+    {:arity, arity} = :erlang.fun_info(fun, :arity)
     "#{inspect(fun)} with arity #{arity} called with #{count(length(args), insp)}"
   end
 
@@ -885,80 +820,73 @@ defmodule BadArityError do
 end
 
 defmodule UndefinedFunctionError do
-  defexception [:module, :function, :arity, :reason, :message]
+  defexception [:module, :function, :arity, :reason, :exports]
 
-  @impl true
-  def message(%{message: nil} = exception) do
-    %{reason: reason, module: module, function: function, arity: arity} = exception
-    {message, _loaded?} = message(reason, module, function, arity)
-    message
-  end
-
-  def message(%{message: message}) do
-    message
-  end
-
-  defp message(nil, module, function, arity) do
+  def message(%{reason: nil, module: module, function: function, arity: arity} = e) do
     cond do
       is_nil(function) or is_nil(arity) ->
-        {"undefined function", false}
+        "undefined function"
 
-      is_nil(module) ->
-        formatted_fun = Exception.format_mfa(module, function, arity)
-        {"function #{formatted_fun} is undefined", false}
-
-      function_exported?(module, :module_info, 0) ->
-        message(:"function not exported", module, function, arity)
+      not is_nil(module) and :code.is_loaded(module) == false ->
+        message(%{e | reason: :"module could not be loaded"})
 
       true ->
-        message(:"module could not be loaded", module, function, arity)
+        message(%{e | reason: :"function not exported"})
     end
   end
 
-  defp message(:"module could not be loaded", module, function, arity) do
+  def message(%{
+        reason: :"module could not be loaded",
+        module: module,
+        function: function,
+        arity: arity
+      }) do
     formatted_fun = Exception.format_mfa(module, function, arity)
-    {"function #{formatted_fun} is undefined (module #{inspect(module)} is not available)", false}
+    "function #{formatted_fun} is undefined (module #{inspect(module)} is not available)"
   end
 
-  defp message(:"function not exported", module, function, arity) do
-    formatted_fun = Exception.format_mfa(module, function, arity)
-    {"function #{formatted_fun} is undefined or private", true}
+  def message(%{
+        reason: :"function not exported",
+        module: module,
+        function: function,
+        arity: arity
+      }) do
+    IO.iodata_to_binary(function_not_exported(module, function, arity, nil))
   end
 
-  defp message(reason, module, function, arity) do
-    formatted_fun = Exception.format_mfa(module, function, arity)
-    {"function #{formatted_fun} is undefined (#{reason})", false}
+  def message(%{
+        reason: :"function not available",
+        module: module,
+        function: function,
+        arity: arity
+      }) do
+    "nil." <> fa = Exception.format_mfa(nil, function, arity)
+
+    "function " <>
+      Exception.format_mfa(module, function, arity) <>
+      " is undefined (function #{fa} is not available)"
   end
 
-  @impl true
-  def blame(exception, stacktrace) do
-    %{reason: reason, module: module, function: function, arity: arity} = exception
-    {message, loaded?} = message(reason, module, function, arity)
-    message = message <> hint(module, function, arity, loaded?)
-    {%{exception | message: message}, stacktrace}
-  end
-
-  defp hint(nil, _function, 0, _loaded?) do
-    ". 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"
-  end
-
-  defp hint(module, function, arity, true) do
-    hint_for_loaded_module(module, function, arity, nil)
-  end
-
-  defp hint(_module, _function, _arity, _loaded?) do
-    ""
+  def message(%{reason: reason, module: module, function: function, arity: arity}) do
+    "function " <> Exception.format_mfa(module, function, arity) <> " is undefined (#{reason})"
   end
 
   @doc false
-  def hint_for_loaded_module(module, function, arity, exports) do
-    if macro_exported?(module, function, arity) do
-      ". However there is a macro with the same name and arity. " <>
-        "Be sure to require #{inspect(module)} if you intend to invoke this macro"
-    else
-      IO.iodata_to_binary(did_you_mean(module, function, exports))
-    end
+  def function_not_exported(module, function, arity, exports) do
+    suffix =
+      if macro_exported?(module, function, arity) do
+        ". However there is a macro with the same name and arity. " <>
+          "Be sure to require #{inspect(module)} if you intend to invoke this macro"
+      else
+        did_you_mean(module, function, exports)
+      end
+
+    [
+      "function ",
+      Exception.format_mfa(module, function, arity),
+      " is undefined or private",
+      suffix
+    ]
   end
 
   @function_threshold 0.77
@@ -1010,7 +938,6 @@ end
 defmodule FunctionClauseError do
   defexception [:module, :function, :arity, :kind, :args, :clauses]
 
-  @impl true
   def message(exception) do
     case exception do
       %{function: nil} ->
@@ -1023,7 +950,6 @@ defmodule FunctionClauseError do
     end
   end
 
-  @impl true
   def blame(%{module: module, function: function, arity: arity} = exception, stacktrace) do
     case stacktrace do
       [{^module, ^function, args, meta} | rest] when length(args) == arity ->
@@ -1103,7 +1029,6 @@ end
 defmodule Protocol.UndefinedError do
   defexception [:protocol, :value, description: ""]
 
-  @impl true
   def message(%{protocol: protocol, value: value, description: description}) do
     "protocol #{inspect(protocol)} not implemented for #{inspect(value)}" <>
       maybe_description(description) <> maybe_available(protocol)
@@ -1127,72 +1052,17 @@ defmodule Protocol.UndefinedError do
 end
 
 defmodule KeyError do
-  defexception [:key, :term, :message]
+  defexception [:key, :term]
 
-  @impl true
-  def message(exception = %{message: nil}), do: message(exception.key, exception.term)
-  def message(%{message: message}), do: message
+  def message(exception) do
+    msg = "key #{inspect(exception.key)} not found"
 
-  def message(key, term) do
-    message = "key #{inspect(key)} not found"
-
-    if term != nil do
-      message <> " in: #{inspect(term)}"
+    if exception.term != nil do
+      msg <> " in: #{inspect(exception.term)}"
     else
-      message
+      msg
     end
   end
-
-  @impl true
-  def blame(exception = %{term: nil}, stacktrace) do
-    message = message(exception.key, exception.term)
-    {%{exception | message: message}, stacktrace}
-  end
-
-  def blame(exception, stacktrace) do
-    %{term: term, key: key} = exception
-    message = message(key, term)
-
-    if is_atom(key) and (map_with_atom_keys_only?(term) or Keyword.keyword?(term)) do
-      hint = did_you_mean(key, available_keys(term))
-      message = message <> IO.iodata_to_binary(hint)
-      {%{exception | message: message}, stacktrace}
-    else
-      {%{exception | message: message}, stacktrace}
-    end
-  end
-
-  defp map_with_atom_keys_only?(term) do
-    is_map(term) and Enum.all?(Map.to_list(term), fn {k, _} -> is_atom(k) end)
-  end
-
-  defp available_keys(term) when is_map(term), do: Map.keys(term)
-  defp available_keys(term) when is_list(term), do: Keyword.keys(term)
-
-  @threshold 0.77
-  @max_suggestions 5
-  defp did_you_mean(missing_key, available_keys) do
-    stringified_key = Atom.to_string(missing_key)
-
-    suggestions =
-      for key <- available_keys,
-          distance = String.jaro_distance(stringified_key, Atom.to_string(key)),
-          distance >= @threshold,
-          do: {distance, key}
-
-    case suggestions do
-      [] -> []
-      suggestions -> [". Did you mean one of:\n\n" | format_suggestions(suggestions)]
-    end
-  end
-
-  defp format_suggestions(suggestions) do
-    suggestions
-    |> Enum.sort(&(elem(&1, 0) >= elem(&2, 0)))
-    |> Enum.take(@max_suggestions)
-    |> Enum.sort(&(elem(&1, 1) <= elem(&2, 1)))
-    |> Enum.map(fn {_, key} -> ["      * ", inspect(key), ?\n] end)
-  end
 end
 
 defmodule UnicodeConversionError do
@@ -1229,7 +1099,6 @@ end
 defmodule File.Error do
   defexception [:reason, :path, action: ""]
 
-  @impl true
   def message(%{action: action, reason: reason, path: path}) do
     formatted =
       case {action, reason} do
@@ -1247,7 +1116,6 @@ end
 defmodule File.CopyError do
   defexception [:reason, :source, :destination, on: "", action: ""]
 
-  @impl true
   def message(exception) do
     formatted = IO.iodata_to_binary(:file.format_error(exception.reason))
 
@@ -1265,7 +1133,6 @@ end
 defmodule File.LinkError do
   defexception [:reason, :existing, :new, action: ""]
 
-  @impl true
   def message(exception) do
     formatted = IO.iodata_to_binary(:file.format_error(exception.reason))
 
@@ -1277,7 +1144,6 @@ end
 defmodule ErlangError do
   defexception [:original]
 
-  @impl true
   def message(exception) do
     "Erlang error: #{inspect(exception.original)}"
   end
@@ -1325,12 +1191,11 @@ defmodule ErlangError do
 
   def normalize({:badkey, key}, stacktrace) do
     term =
-      case stacktrace do
+      case ensure_stacktrace(stacktrace) do
         [{Map, :get_and_update!, [map, _, _], _} | _] -> map
         [{Map, :update!, [map, _, _], _} | _] -> map
         [{:maps, :update, [_, _, map], _} | _] -> map
         [{:maps, :get, [_, map], _} | _] -> map
-        [{:erlang, :map_get, [_, map], _} | _] -> map
         _ -> nil
       end
 
@@ -1354,12 +1219,13 @@ defmodule ErlangError do
   end
 
   def normalize(:undef, stacktrace) do
+    stacktrace = ensure_stacktrace(stacktrace)
     {mod, fun, arity} = from_stacktrace(stacktrace)
     %UndefinedFunctionError{module: mod, function: fun, arity: arity}
   end
 
   def normalize(:function_clause, stacktrace) do
-    {mod, fun, arity} = from_stacktrace(stacktrace)
+    {mod, fun, arity} = from_stacktrace(ensure_stacktrace(stacktrace))
     %FunctionClauseError{module: mod, function: fun, arity: arity}
   end
 
@@ -1371,6 +1237,18 @@ defmodule ErlangError do
     %ErlangError{original: other}
   end
 
+  defp ensure_stacktrace(nil) do
+    try do
+      :erlang.get_stacktrace()
+    rescue
+      _ -> []
+    end
+  end
+
+  defp ensure_stacktrace(stacktrace) do
+    stacktrace
+  end
+
   defp from_stacktrace([{module, function, args, _} | _]) when is_list(args) do
     {module, function, length(args)}
   end

lib/elixir/lib/file.ex

@@ -90,13 +90,8 @@ defmodule File do
           | :read
           | :read_ahead
           | :sync
+          | :utf8
           | :write
-          | {:read_ahead, pos_integer}
-          | {:delayed_write, non_neg_integer, non_neg_integer}
-          | encoding_mode()
-
-  @type encoding_mode ::
-          :utf8
           | {
               :encoding,
               :latin1
@@ -107,11 +102,7 @@ defmodule File do
               | {:utf16, :big | :little}
               | {:utf32, :big | :little}
             }
-
-  @type stream_mode ::
-          encoding_mode()
-          | :trim_bom
-          | {:read_ahead, pos_integer | false}
+          | {:read_ahead, pos_integer}
           | {:delayed_write, non_neg_integer, non_neg_integer}
 
   @doc """
@@ -437,7 +428,6 @@ defmodule File do
     * `:enotsup` - symbolic links are not supported on the current platform
 
   """
-  @doc since: "1.5.0"
   @spec read_link(Path.t()) :: {:ok, binary} | {:error, posix}
   def read_link(path) do
     case path |> IO.chardata_to_string() |> :file.read_link() do
@@ -450,7 +440,6 @@ defmodule File do
   Same as `read_link/1` but returns the target directly or throws `File.Error` if an error is
   returned.
   """
-  @doc since: "1.5.0"
   @spec read_link!(Path.t()) :: binary | no_return
   def read_link!(path) do
     case read_link(path) do
@@ -536,8 +525,6 @@ defmodule File do
   If the operating system does not support hard links, returns
   `{:error, :enotsup}`.
   """
-  @doc since: "1.5.0"
-  @spec ln(Path.t(), Path.t()) :: :ok | {:error, posix}
   def ln(existing, new) do
     :file.make_link(IO.chardata_to_string(existing), IO.chardata_to_string(new))
   end
@@ -547,8 +534,6 @@ defmodule File do
 
   Returns `:ok` otherwise
   """
-  @doc since: "1.5.0"
-  @spec ln!(Path.t(), Path.t()) :: :ok | no_return
   def ln!(existing, new) do
     case ln(existing, new) do
       :ok ->
@@ -570,8 +555,6 @@ defmodule File do
   If the operating system does not support symlinks, returns
   `{:error, :enotsup}`.
   """
-  @doc since: "1.5.0"
-  @spec ln_s(Path.t(), Path.t()) :: :ok | {:error, posix}
   def ln_s(existing, new) do
     :file.make_symlink(IO.chardata_to_string(existing), IO.chardata_to_string(new))
   end
@@ -581,7 +564,6 @@ defmodule File do
 
   Returns `:ok` otherwise
   """
-  @spec ln_s!(Path.t(), Path.t()) :: :ok | no_return
   def ln_s!(existing, new) do
     case ln_s(existing, new) do
       :ok ->
@@ -663,7 +645,6 @@ defmodule File do
 
       # Rename directory "samples" to "tmp"
       File.rename "samples", "tmp"
-
   """
   @spec rename(Path.t(), Path.t()) :: :ok | {:error, posix}
   def rename(source, destination) do
@@ -1033,19 +1014,14 @@ defmodule File do
 
   @doc """
   Tries to delete the dir at `path`.
-
   Returns `:ok` if successful, or `{:error, reason}` if an error occurs.
-  It returns `{:error, :eexist}` if the directory is not empty.
 
   ## Examples
 
-      File.rmdir("tmp_dir")
+      File.rmdir('tmp_dir')
       #=> :ok
 
-      File.rmdir("non_empty_dir")
-      #=> {:error, :eexist}
-
-      File.rmdir("file.txt")
+      File.rmdir('file.txt')
       #=> {:error, :enotdir}
 
   """
@@ -1512,8 +1488,7 @@ defmodule File do
   in raw mode for performance reasons. Therefore, Elixir **will** open
   streams in `:raw` mode with the `:read_ahead` option unless an encoding
   is specified. This means any data streamed into the file must be
-  converted to `t:iodata/0` type. If you pass e.g. `[encoding: :utf8]`
-  or `[encoding: {:utf16, :little}]` in the modes parameter,
+  converted to `t:iodata/0` type. If you pass `[:utf8]` in the modes parameter,
   the underlying stream will use `IO.write/2` and the `String.Chars` protocol
   to convert the data. See `IO.binwrite/2` and `IO.write/2` .
 
@@ -1525,9 +1500,6 @@ defmodule File do
   If you pass `:trim_bom` in the modes parameter, the stream will
   trim UTF-8, UTF-16 and UTF-32 byte order marks when reading from file.
 
-  Note that this function does not try to discover the file encoding basing
-  on BOM.
-
   ## Examples
 
       # Read in 2048 byte chunks rather than lines
@@ -1538,7 +1510,6 @@ defmodule File do
   See `Stream.run/1` for an example of streaming into a file.
 
   """
-  @spec stream!(Path.t(), stream_mode, :line | pos_integer) :: File.Stream.t()
   def stream!(path, modes \\ [], line_or_bytes \\ :line) do
     modes = normalize_modes(modes, true)
     File.Stream.__build__(IO.chardata_to_string(path), modes, line_or_bytes)

lib/elixir/lib/file/stream.ex

@@ -22,10 +22,10 @@ defmodule File.Stream do
     modes =
       case raw do
         true ->
-          case :lists.keyfind(:read_ahead, 1, modes) do
-            {:read_ahead, false} -> [:raw | :lists.keydelete(:read_ahead, 1, modes)]
-            {:read_ahead, _} -> [:raw | modes]
-            false -> [:raw, :read_ahead | modes]
+          if :lists.keyfind(:read_ahead, 1, modes) == {:read_ahead, false} do
+            [:raw | modes]
+          else
+            [:raw, :read_ahead | modes]
           end
 
         false ->
@@ -77,7 +77,7 @@ defmodule File.Stream do
       start_fun = fn ->
         case :file.open(path, read_modes(modes)) do
           {:ok, device} ->
-            if :trim_bom in modes, do: trim_bom(device, raw) |> elem(0), else: device
+            if :trim_bom in modes, do: trim_bom(device), else: device
 
           {:error, reason} ->
             raise File.Error, reason: reason, action: "stream", path: path
@@ -106,24 +106,19 @@ defmodule File.Stream do
       end
     end
 
-    def count(%{path: path, line_or_bytes: bytes, raw: true, modes: modes}) do
+    def count(%{path: path, line_or_bytes: bytes}) do
       case File.stat(path) do
         {:ok, %{size: 0}} ->
           {:error, __MODULE__}
 
         {:ok, %{size: size}} ->
-          remainder = if rem(size, bytes) == 0, do: 0, else: 1
-          {:ok, div(size, bytes) + remainder - count_raw_bom(path, modes)}
+          {:ok, div(size, bytes) + if(rem(size, bytes) == 0, do: 0, else: 1)}
 
         {:error, reason} ->
           raise File.Error, reason: reason, action: "stream", path: path
       end
     end
 
-    def count(_stream) do
-      {:error, __MODULE__}
-    end
-
     def member?(_stream, _term) do
       {:error, __MODULE__}
     end
@@ -132,30 +127,10 @@ defmodule File.Stream do
       {:error, __MODULE__}
     end
 
-    defp count_raw_bom(path, modes) do
-      if :trim_bom in modes do
-        File.open!(path, read_modes(modes), &(&1 |> trim_bom(true) |> elem(1)))
-      else
-        0
-      end
-    end
-
-    defp trim_bom(device, true) do
-      bom_length = device |> IO.binread(4) |> bom_length()
-      {:ok, new_pos} = :file.position(device, bom_length)
-      {device, new_pos}
-    end
-
-    defp trim_bom(device, false) do
-      # Or we read the bom in the correct amount or it isn't there
-      case bom_length(IO.read(device, 1)) do
-        0 ->
-          {:ok, _} = :file.position(device, 0)
-          {device, 0}
-
-        _ ->
-          {device, 1}
-      end
+    defp trim_bom(device) do
+      header = IO.binread(device, 4)
+      {:ok, _new_pos} = :file.position(device, bom_length(header))
+      device
     end
 
     defp bom_length(<<239, 187, 191, _rest::binary>>), do: 3

lib/elixir/lib/float.ex

@@ -16,9 +16,7 @@ defmodule Float do
 
   There are some very well known problems with floating-point numbers
   and arithmetics due to the fact most decimal fractions cannot be
-  represented by a floating-point binary and most operations are not exact,
-  but operate on approximations. Those issues are not specific
-  to Elixir, they are a property of floating point representation itself.
+  represented by a floating-point binary.
 
   For example, the numbers 0.1 and 0.01 are two of them, what means the result
   of squaring 0.1 does not give 0.01 neither the closest representable. Here is
@@ -32,12 +30,6 @@ defmodule Float do
 
   There are also other known problems like flooring or rounding numbers. See
   `round/2` and `floor/2` for more details about them.
-
-  To learn more about floating-point arithmetic visit:
-
-    * [0.30000000000000004.com](http://0.30000000000000004.com/)
-    * [What Every Programmer Should Know About Floating-Point Arithmetic](http://floating-point-gui.de/)
-
   """
 
   import Bitwise
@@ -387,8 +379,6 @@ defmodule Float do
       {-16, 1}
 
   """
-  @doc since: "1.4.0"
-  @spec ratio(float) :: {pos_integer | neg_integer, pos_integer}
   def ratio(float) when is_float(float) do
     <<sign::1, exp::11, significant::52-bitstring>> = <<float::float>>
     {num, _, den} = decompose(significant)
@@ -473,21 +463,21 @@ defmodule Float do
     IO.iodata_to_binary(:io_lib_format.fwrite_g(float))
   end
 
-  @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use Float.to_charlist/1 instead"
+  # (hard-deprecated in elixir_dispatch)
+  @doc false
   def to_char_list(float), do: Float.to_charlist(float)
 
   @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use :erlang.float_to_list/2 instead"
+  # (hard-deprecated in elixir_dispatch)
   def to_char_list(float, options) do
     :erlang.float_to_list(float, expand_compact(options))
   end
 
   @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use :erlang.float_to_binary/2 instead"
+  # (hard-deprecated in elixir_dispatch)
   def to_string(float, options) do
     :erlang.float_to_binary(float, expand_compact(options))
   end

lib/elixir/lib/function.ex

@@ -1,137 +0,0 @@
-defmodule Function do
-  @moduledoc """
-  A set of functions for working with functions.
-
-  There are two types of captured functions: **external** and **local**.
-  External functions are functions residing in modules that are captured
-  with `&/1`, such as `&String.length/1`. Local functions are anonymous functions
-  defined with `fn/1` or with the capture operator `&/1` using `&1`, `&2`,
-  and so on as replacements.
-  """
-
-  @type information ::
-          :arity
-          | :env
-          | :index
-          | :module
-          | :name
-          | :new_index
-          | :new_uniq
-          | :pid
-          | :type
-          | :uniq
-
-  @doc """
-  Captures the given function.
-
-  Inlined by the compiler.
-
-  ## Examples
-
-      iex> Function.capture(String, :length, 1)
-      &String.length/1
-
-  """
-  @doc since: "1.7.0"
-  @spec capture(module, atom, arity) :: fun
-  def capture(module, function_name, arity) do
-    :erlang.make_fun(module, function_name, arity)
-  end
-
-  @doc """
-  Returns a keyword list with information about a function.
-
-  The returned keys (with the corresponding possible values) for
-  all types of functions (local and external) are the following:
-
-    * `:type` - `:local` (for anonymous functions) or `:external` (for
-      named functions).
-
-    * `:module` - an atom which is the module where the function is defined when
-    anonymous or the module which the function refers to when it's a named function.
-
-    * `:arity` - (integer) the number of arguments the function is to be called with.
-
-    * `:name` - (atom) the name of the function.
-
-    * `:env` - a list of the environment or free variables. For named
-      functions, the returned list is always empty.
-
-  When `fun` is an anonymous function (that is, the type is `:local`), the following
-  additional keys are returned:
-
-    * `:pid` - PID of the process that originally created the function.
-
-    * `:index` - (integer) an index into the module function table.
-
-    * `:new_index` - (integer) an index into the module function table.
-
-    * `:new_uniq` - (binary) a unique value for this function. It's
-      calculated from the compiled code for the entire module.
-
-    * `:uniq` - (integer) a unique value for this function. This integer is
-      calculated from the compiled code for the entire module.
-
-  **Note**: this function must be used only for debugging purposes.
-
-  Inlined by the compiler.
-
-  ## Examples
-
-      iex> fun = fn x -> x end
-      iex> info = Function.info(fun)
-      iex> Keyword.get(info, :arity)
-      1
-      iex> Keyword.get(info, :type)
-      :local
-
-      iex> fun = &String.length/1
-      iex> info = Function.info(fun)
-      iex> Keyword.get(info, :type)
-      :external
-      iex> Keyword.get(info, :name)
-      :length
-
-  """
-  @doc since: "1.7.0"
-  @spec info(fun) :: [{information, term}]
-  def info(fun), do: :erlang.fun_info(fun)
-
-  @doc """
-  Returns a specific information about the function.
-
-  The returned information is a two-element tuple in the shape of
-  `{info, value}`.
-
-  For any function, the information asked for can be any of the atoms
-  `:module`, `:name`, `:arity`, `:env`, or `:type`.
-
-  For anonymous functions, there is also information about any of the
-  atoms `:index`, `:new_index`, `:new_uniq`, `:uniq`, and `:pid`.
-  For a named function, the value of any of these items is always the
-  atom `:undefined`.
-
-  For more information on each of the possible returned values, see
-  `info/1`.
-
-  Inlined by the compiler.
-
-  ## Examples
-
-      iex> f = fn x -> x end
-      iex> Function.info(f, :arity)
-      {:arity, 1}
-      iex> Function.info(f, :type)
-      {:type, :local}
-
-      iex> fun = &String.length/1
-      iex> Function.info(fun, :name)
-      {:name, :length}
-      iex> Function.info(fun, :pid)
-      {:pid, :undefined}
-
-  """
-  @doc since: "1.7.0"
-  @spec info(fun, item) :: {item, term} when item: information
-  def info(fun, item), do: :erlang.fun_info(fun, item)
-end

lib/elixir/lib/gen_event.ex

@@ -4,7 +4,7 @@ defmodule GenEvent do
   # Functions from this module are deprecated in elixir_dispatch.
 
   @moduledoc """
-  A event manager with event handlers behaviour.
+  WARNING: this module is deprecated.
 
   If you are interested in implementing an event manager, please read the
   "Alternatives" section below. If you have to implement an event handler to
@@ -43,8 +43,6 @@ defmodule GenEvent do
   [`:gen_event`](http://erlang.org/doc/man/gen_event.html) Erlang module.
   """
 
-  @moduledoc deprecated: "Use Erlang/OTP's :gen_event module instead"
-
   @callback init(args :: term) ::
               {:ok, state}
               | {:ok, state, :hibernate}
@@ -85,9 +83,6 @@ defmodule GenEvent do
 
   @type handler :: atom | {atom, term}
 
-  message = "Use one of the alternatives described in the documentation for the GenEvent module"
-
-  @deprecated message
   @doc false
   defmacro __using__(_) do
     %{file: file, line: line} = __CALLER__
@@ -153,14 +148,12 @@ defmodule GenEvent do
   end
 
   @doc false
-  @deprecated message
   @spec start_link(options) :: on_start
   def start_link(options \\ []) when is_list(options) do
     do_start(:link, options)
   end
 
   @doc false
-  @deprecated message
   @spec start(options) :: on_start
   def start(options \\ []) when is_list(options) do
     do_start(:nolink, options)
@@ -184,7 +177,7 @@ defmodule GenEvent do
 
       other ->
         raise ArgumentError, """
-        expected :name option to be one of the following:
+        expected :name option to be one of:
 
           * nil
           * atom
@@ -197,28 +190,24 @@ defmodule GenEvent do
   end
 
   @doc false
-  @deprecated message
   @spec stream(manager, keyword) :: GenEvent.Stream.t()
   def stream(manager, options \\ []) do
     %GenEvent.Stream{manager: manager, timeout: Keyword.get(options, :timeout, :infinity)}
   end
 
   @doc false
-  @deprecated message
   @spec add_handler(manager, handler, term) :: :ok | {:error, term}
   def add_handler(manager, handler, args) do
     rpc(manager, {:add_handler, handler, args})
   end
 
   @doc false
-  @deprecated message
   @spec add_mon_handler(manager, handler, term) :: :ok | {:error, term}
   def add_mon_handler(manager, handler, args) do
     rpc(manager, {:add_mon_handler, handler, args, self()})
   end
 
   @doc false
-  @deprecated message
   @spec notify(manager, term) :: :ok
   def notify(manager, event)
 
@@ -249,21 +238,18 @@ defmodule GenEvent do
   end
 
   @doc false
-  @deprecated message
   @spec sync_notify(manager, term) :: :ok
   def sync_notify(manager, event) do
     rpc(manager, {:sync_notify, event})
   end
 
   @doc false
-  @deprecated message
   @spec ack_notify(manager, term) :: :ok
   def ack_notify(manager, event) do
     rpc(manager, {:ack_notify, event})
   end
 
   @doc false
-  @deprecated message
   @spec call(manager, handler, term, timeout) :: term | {:error, term}
   def call(manager, handler, request, timeout \\ 5000) do
     try do
@@ -277,35 +263,30 @@ defmodule GenEvent do
   end
 
   @doc false
-  @deprecated message
   @spec remove_handler(manager, handler, term) :: term | {:error, term}
   def remove_handler(manager, handler, args) do
     rpc(manager, {:delete_handler, handler, args})
   end
 
   @doc false
-  @deprecated message
   @spec swap_handler(manager, handler, term, handler, term) :: :ok | {:error, term}
   def swap_handler(manager, handler1, args1, handler2, args2) do
     rpc(manager, {:swap_handler, handler1, args1, handler2, args2})
   end
 
   @doc false
-  @deprecated message
   @spec swap_mon_handler(manager, handler, term, handler, term) :: :ok | {:error, term}
   def swap_mon_handler(manager, handler1, args1, handler2, args2) do
     rpc(manager, {:swap_mon_handler, handler1, args1, handler2, args2, self()})
   end
 
   @doc false
-  @deprecated message
   @spec which_handlers(manager) :: [handler]
   def which_handlers(manager) do
     rpc(manager, :which_handlers)
   end
 
   @doc false
-  @deprecated message
   @spec stop(manager, reason :: term, timeout) :: :ok
   def stop(manager, reason \\ :normal, timeout \\ :infinity) do
     :gen.stop(manager, reason, timeout)
@@ -848,7 +829,7 @@ defmodule GenEvent do
       apply(mod, fun, args)
     catch
       :throw, val -> {:ok, val}
-      :error, val -> {:error, {val, __STACKTRACE__}}
+      :error, val -> {:error, {val, System.stacktrace()}}
       :exit, val -> {:error, val}
     else
       res -> {:ok, res}

lib/elixir/lib/gen_server.ex

@@ -23,17 +23,10 @@ defmodule GenServer do
 
         # Callbacks
 
-        @impl true
-        def init(stack) do
-          {:ok, stack}
+        def handle_call(:pop, _from, [h | t]) do
+          {:reply, h, t}
         end
 
-        @impl true
-        def handle_call(:pop, _from, [head | tail]) do
-          {:reply, head, tail}
-        end
-
-        @impl true
         def handle_cast({:push, item}, state) do
           {:noreply, [item | state]}
         end
@@ -52,7 +45,7 @@ defmodule GenServer do
       GenServer.call(pid, :pop)
       #=> :world
 
-  We start our `Stack` by calling `start_link/2`, passing the module
+  We start our `Stack` by calling `start_link/3`, passing the module
   with the server implementation and its initial argument (a list
   representing the stack containing the item `:hello`). We can primarily
   interact with the server by sending two types of messages. **call**
@@ -63,64 +56,18 @@ defmodule GenServer do
   that must be handled by the `c:handle_call/3` callback in the GenServer.
   A `cast/2` message must be handled by `c:handle_cast/2`.
 
-  ## Client / Server APIs
-
-  Although in the example above we have used `GenServer.start_link/3` and
-  friends to directly start and communicate with the server, most of the
-  time we don't call the `GenServer` functions directly. Instead, we wrap
-  the calls in new functions representing the public API of the server.
-
-  Here is a better implementation of our Stack module:
-
-      defmodule Stack do
-        use GenServer
-
-        # Client
-
-        def start_link(default) when is_list(default) do
-          GenServer.start_link(__MODULE__, default)
-        end
-
-        def push(pid, item) do
-          GenServer.cast(pid, {:push, item})
-        end
-
-        def pop(pid) do
-          GenServer.call(pid, :pop)
-        end
-
-        # Server (callbacks)
-
-        @impl true
-        def init(stack) do
-          {:ok, stack}
-        end
-
-        @impl true
-        def handle_call(:pop, _from, [head | tail]) do
-          {:reply, head, tail}
-        end
-
-        @impl true
-        def handle_cast({:push, item}, state) do
-          {:noreply, [item | state]}
-        end
-      end
-
-  In practice, it is common to have both server and client functions in
-  the same module. If the server and/or client implementations are growing
-  complex, you may want to have them in different modules.
-
   ## use GenServer and callbacks
 
-  There are 7 callbacks to be implemented when you use a `GenServer`.
-  The only required callback is `init/1`.
+  There are 6 callbacks required to be implemented in a `GenServer`. By
+  adding `use GenServer` to your module, Elixir will automatically define
+  all 6 callbacks for you, leaving it up to you to implement the ones
+  you want to customize.
 
   `use GenServer` also defines a `child_spec/1` function, allowing the
   defined module to be put under a supervision tree. The generated
   `child_spec/1` can be customized with the following options:
 
-    * `:id` - the child specification identifier, defaults to the current module
+    * `:id` - the child specification id, defaults to the current module
     * `:start` - how to start the child process (defaults to calling `__MODULE__.start_link/1`)
     * `:restart` - when the child should be restarted, defaults to `:permanent`
     * `:shutdown` - how to shut down the child
@@ -131,7 +78,7 @@ defmodule GenServer do
 
   See the `Supervisor` docs for more information.
 
-  ## Name registration
+  ## Name Registration
 
   Both `start_link/3` and `start/3` support the `GenServer` to register
   a name on start via the `:name` option. Registered names are also
@@ -140,7 +87,7 @@ defmodule GenServer do
     * an atom - the GenServer is registered locally with the given name
       using `Process.register/2`.
 
-    * `{:global, term}` - the GenServer is registered globally with the given
+    * `{:global, term}`- the GenServer is registered globally with the given
       term using the functions in the [`:global` module](http://www.erlang.org/doc/man/global.html).
 
     * `{:via, module, term}` - the GenServer is registered with the given
@@ -161,30 +108,80 @@ defmodule GenServer do
       GenServer.call(MyStack, :pop) #=> :hello
 
   Once the server is started, the remaining functions in this module (`call/3`,
-  `cast/2`, and friends) will also accept an atom, or any `{:global, ...}` or
-  `{:via, ...}` tuples. In general, the following formats are supported:
+  `cast/2`, and friends) will also accept an atom, or any `:global` or `:via`
+  tuples. In general, the following formats are supported:
 
-    * a PID
-    * an atom if the server is locally registered
+    * a `pid`
+    * an `atom` if the server is locally registered
     * `{atom, node}` if the server is locally registered at another node
     * `{:global, term}` if the server is globally registered
     * `{:via, module, name}` if the server is registered through an alternative
       registry
 
   If there is an interest to register dynamic names locally, do not use
-  atoms, as atoms are never garbage-collected and therefore dynamically
-  generated atoms won't be garbage-collected. For such cases, you can
+  atoms, as atoms are never garbage collected and therefore dynamically
+  generated atoms won't be garbage collected. For such cases, you can
   set up your own local registry by using the `Registry` module.
 
+  ## Client / Server APIs
+
+  Although in the example above we have used `GenServer.start_link/3` and
+  friends to directly start and communicate with the server, most of the
+  time we don't call the `GenServer` functions directly. Instead, we wrap
+  the calls in new functions representing the public API of the server.
+
+  Here is a better implementation of our Stack module:
+
+      defmodule Stack do
+        use GenServer
+
+        # Client
+
+        def start_link(default) do
+          GenServer.start_link(__MODULE__, default)
+        end
+
+        def push(pid, item) do
+          GenServer.cast(pid, {:push, item})
+        end
+
+        def pop(pid) do
+          GenServer.call(pid, :pop)
+        end
+
+        # Server (callbacks)
+
+        def handle_call(:pop, _from, [h | t]) do
+          {:reply, h, t}
+        end
+
+        def handle_call(request, from, state) do
+          # Call the default implementation from GenServer
+          super(request, from, state)
+        end
+
+        def handle_cast({:push, item}, state) do
+          {:noreply, [item | state]}
+        end
+
+        def handle_cast(request, state) do
+          super(request, state)
+        end
+      end
+
+  In practice, it is common to have both server and client functions in
+  the same module. If the server and/or client implementations are growing
+  complex, you may want to have them in different modules.
+
   ## Receiving "regular" messages
 
   The goal of a `GenServer` is to abstract the "receive" loop for developers,
-  automatically handling system messages, supporting code change, synchronous
+  automatically handling system messages, support code change, synchronous
   calls and more. Therefore, you should never call your own "receive" inside
   the GenServer callbacks as doing so will cause the GenServer to misbehave.
 
   Besides the synchronous and asynchronous communication provided by `call/3`
-  and `cast/2`, "regular" messages sent by functions such as `Kernel.send/2`,
+  and `cast/2`, "regular" messages sent by functions such `Kernel.send/2`,
   `Process.send_after/4` and similar, can be handled inside the `c:handle_info/2`
   callback.
 
@@ -199,13 +196,11 @@ defmodule GenServer do
           GenServer.start_link(__MODULE__, %{})
         end
 
-        @impl true
         def init(state) do
           schedule_work() # Schedule work to be performed on start
           {:ok, state}
         end
 
-        @impl true
         def handle_info(:work, state) do
           # Do the desired work here
           schedule_work() # Reschedule once more
@@ -217,55 +212,13 @@ defmodule GenServer do
         end
       end
 
-  ## When (not) to use a GenServer
-
-  So far, we have learned that a `GenServer` can be used as a supervised process
-  that handles sync and async calls. It can also handle system messages, such as
-  periodic messages and monitoring events. GenServer processes may also be named.
-
-  A GenServer, or a process in general, must be used to model runtime characteristics
-  of your system. A GenServer must never be used for code organization purposes.
-
-  In Elixir, code organization is done by modules and functions, processes are not
-  necessary. For example, imagine you are implementing a calculator and you decide
-  to put all the calculator operations behind a GenServer:
-
-      def add(a, b) do
-        GenServer.call(__MODULE__, {:add, a, b})
-      end
-
-      def handle_call({:add, a, b}, _from, state) do
-        {:reply, a + b, state}
-      end
-
-      def handle_call({:subtract, a, b}, _from, state) do
-        {:reply, a - b, state}
-      end
-
-  This is an anti-pattern not only because it convolutes the calculator logic but
-  also because you put the calculator logic behind a single process that will
-  potentially become a bottleneck in your system, especially as the number of
-  calls grow. Instead just define the functions directly:
-
-      def add(a, b) do
-        a + b
-      end
-
-      def subtract(a, b) do
-        a - b
-      end
-
-  If you don't need a process, then you don't need a process. Use processes only to
-  model runtime properties, such as mutable state, concurrency and failures, never
-  for code organization.
-
   ## Debugging with the :sys module
 
   GenServers, as [special processes](http://erlang.org/doc/design_principles/spec_proc.html),
-  can be debugged using the [`:sys` module](http://www.erlang.org/doc/man/sys.html).
-  Through various hooks, this module allows developers to introspect the state of
-  the process and trace system events that happen during its execution, such as
-  received messages, sent replies and state changes.
+  can be debugged using the [`:sys` module](http://www.erlang.org/doc/man/sys.html). Through various hooks, this module
+  allows developers to introspect the state of the process and trace
+  system events that happen during its execution, such as received messages,
+  sent replies and state changes.
 
   Let's explore the basic functions from the
   [`:sys` module](http://www.erlang.org/doc/man/sys.html) used for debugging:
@@ -326,7 +279,7 @@ defmodule GenServer do
 
   ## Learn more
 
-  If you wish to find out more about GenServers, the Elixir Getting Started
+  If you wish to find out more about gen servers, the Elixir Getting Started
   guide provides a tutorial-like introduction. The documentation and links
   in Erlang can also provide extra insight.
 
@@ -334,7 +287,6 @@ defmodule GenServer do
     * [`:gen_server` module documentation](http://www.erlang.org/doc/man/gen_server.html)
     * [gen_server Behaviour – OTP Design Principles](http://www.erlang.org/doc/design_principles/gen_server_concepts.html)
     * [Clients and Servers – Learn You Some Erlang for Great Good!](http://learnyousomeerlang.com/clients-and-servers)
-
   """
 
   @doc """
@@ -350,24 +302,18 @@ defmodule GenServer do
   except `handle_info(:timeout, state)` will be called after `timeout`
   milliseconds if no messages are received within the timeout.
 
-  Returning `{:ok, state, :hibernate}` is similar to `{:ok, state}`
-  except the process is hibernated before entering the loop. See
+  Returning `{:ok, state, :hibernate}` is similar to
+  `{:ok, state}` except the process is hibernated before entering the loop. See
   `c:handle_call/3` for more information on hibernation.
 
-  Returning `{:ok, state, {:continue, continue}}` is similar to
-  `{:ok, state}` except that immediately after entering the loop
-  the `c:handle_continue/2` callback will be invoked with the value
-  `continue` as first argument.
-
-  Returning `:ignore` will cause `start_link/3` to return `:ignore` and
-  the process will exit normally without entering the loop or calling
-  `c:terminate/2`. If used when part of a supervision tree the parent
-  supervisor will not fail to start nor immediately try to restart the
-  `GenServer`. The remainder of the supervision tree will be started
-  and so the `GenServer` should not be required by other processes.
-  It can be started later with `Supervisor.restart_child/2` as the child
-  specification is saved in the parent supervisor. The main use cases for
-  this are:
+  Returning `:ignore` will cause `start_link/3` to return `:ignore` and the
+  process will exit normally without entering the loop or calling `c:terminate/2`.
+  If used when part of a supervision tree the parent supervisor will not fail
+  to start nor immediately try to restart the `GenServer`. The remainder of the
+  supervision tree will be (re)started and so the `GenServer` should not be
+  required by other processes. It can be started later with
+  `Supervisor.restart_child/2` as the child specification is saved in the parent
+  supervisor. The main use cases for this are:
 
     * The `GenServer` is disabled by configuration but might be enabled later.
     * An error occurred and it will be handled by a different mechanism than the
@@ -380,7 +326,7 @@ defmodule GenServer do
   """
   @callback init(args :: term) ::
               {:ok, state}
-              | {:ok, state, timeout | :hibernate | {:continue, term}}
+              | {:ok, state, timeout | :hibernate}
               | :ignore
               | {:stop, reason :: any}
             when state: any
@@ -407,10 +353,6 @@ defmodule GenServer do
   `GenServer` causes garbage collection and leaves a continuous heap that
   minimises the memory used by the process.
 
-  Returning `{:reply, reply, new_state, {:continue, continue}}` is similar to
-  `{:reply, reply, new_state}` except `c:handle_continue/2` will be invoked
-  immediately after with the value `continue` as first argument.
-
   Hibernating should not be used aggressively as too much time could be spent
   garbage collecting. Normally it should only be used when a message is not
   expected soon and minimising the memory of the process is shown to be
@@ -432,9 +374,9 @@ defmodule GenServer do
   process exits without replying as the caller will be blocking awaiting a
   reply.
 
-  Returning `{:noreply, new_state, timeout | :hibernate | {:continue, continue}}`
-  is similar to `{:noreply, new_state}` except a timeout, hibernation or continue
-  occurs as with a `:reply` tuple.
+  Returning `{:noreply, new_state, timeout | :hibernate}` is similar to
+  `{:noreply, new_state}` except a timeout or hibernation occurs as with a
+  `:reply` tuple.
 
   Returning `{:stop, reason, reply, new_state}` stops the loop and `c:terminate/2`
   is called with reason `reason` and state `new_state`. Then the `reply` is sent
@@ -443,14 +385,15 @@ defmodule GenServer do
   Returning `{:stop, reason, new_state}` is similar to
   `{:stop, reason, reply, new_state}` except a reply is not sent.
 
-  This callback is optional. If one is not implemented, the server will fail
-  if a call is performed against it.
+  If this callback is not implemented, the default implementation by
+  `use GenServer` will fail with a `RuntimeError` exception with a message:
+  attempted to call `GenServer` but no `handle_call/3` clause was provided.
   """
   @callback handle_call(request :: term, from, state :: term) ::
               {:reply, reply, new_state}
-              | {:reply, reply, new_state, timeout | :hibernate | {:continue, term}}
+              | {:reply, reply, new_state, timeout | :hibernate}
               | {:noreply, new_state}
-              | {:noreply, new_state, timeout | :hibernate, {:continue, term}}
+              | {:noreply, new_state, timeout | :hibernate}
               | {:stop, reason, reply, new_state}
               | {:stop, reason, new_state}
             when reply: term, new_state: term, reason: term
@@ -471,20 +414,17 @@ defmodule GenServer do
   `{:noreply, new_state}` except the process is hibernated before continuing the
   loop. See `c:handle_call/3` for more information.
 
-  Returning `{:noreply, new_state, {:continue, continue}}` is similar to
-  `{:noreply, new_state}` except `c:handle_continue/2` will be invoked
-  immediately after with the value `continue` as first argument.
-
   Returning `{:stop, reason, new_state}` stops the loop and `c:terminate/2` is
   called with the reason `reason` and state `new_state`. The process exits with
   reason `reason`.
 
-  This callback is optional. If one is not implemented, the server will fail
-  if a cast is performed against it.
+  If this callback is not implemented, the default implementation by
+  `use GenServer` will fail with a `RuntimeError` exception with a message:
+  attempted to call `GenServer` but no `handle_cast/2` clause was provided.
   """
   @callback handle_cast(request :: term, state :: term) ::
               {:noreply, new_state}
-              | {:noreply, new_state, timeout | :hibernate | {:continue, term}}
+              | {:noreply, new_state, timeout | :hibernate}
               | {:stop, reason :: term, new_state}
             when new_state: term
 
@@ -496,31 +436,12 @@ defmodule GenServer do
 
   Return values are the same as `c:handle_cast/2`.
 
-  This callback is optional. If one is not implemented, the received message
-  will be logged.
+  If this callback is not implemented, the default implementation by
+  `use GenServer` will return `{:noreply, state}`.
   """
   @callback handle_info(msg :: :timeout | term, state :: term) ::
               {:noreply, new_state}
-              | {:noreply, new_state, timeout | :hibernate | {:continue, term}}
-              | {:stop, reason :: term, new_state}
-            when new_state: term
-
-  @doc """
-  Invoked to handle `continue` instructions.
-
-  It is useful for performing work after initialization or for splitting the work
-  in a callback in multiple steps, updating the process state along the way.
-
-  Return values are the same as `c:handle_cast/2`.
-
-  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}
-              | {:noreply, new_state, timeout | :hibernate | {:continue, term}}
+              | {:noreply, new_state, timeout | :hibernate}
               | {:stop, reason :: term, new_state}
             when new_state: term
 
@@ -557,15 +478,12 @@ defmodule GenServer do
   Therefore it is not guaranteed that `c:terminate/2` is called when a `GenServer`
   exits. For such reasons, we usually recommend important clean-up rules to
   happen in separated processes either by use of monitoring or by links
-  themselves. There is no cleanup needed when the `GenServer` controls a `port` (e.g.
-  `:gen_tcp.socket`) or `t:File.io_device/0`, because these will be closed on
-  receiving a `GenServer`'s exit signal and do not need to be closed manually
-  in `c:terminate/2`.
+  themselves. For example if the `GenServer` controls a `port` (e.g.
+  `:gen_tcp.socket`) or `t:File.io_device/0`, they will be closed on receiving a
+  `GenServer`'s exit signal and do not need to be closed in `c:terminate/2`.
 
   If `reason` is not `:normal`, `:shutdown`, nor `{:shutdown, term}` an error is
   logged.
-
-  This callback is optional.
   """
   @callback terminate(reason, state :: term) :: term
             when reason: :normal | :shutdown | {:shutdown, term}
@@ -588,8 +506,6 @@ defmodule GenServer do
 
   If `c:code_change/3` raises the code change fails and the loop will continue
   with its previous state. Therefore this callback does not usually contain side effects.
-
-  This callback is optional.
   """
   @callback code_change(old_vsn, state :: term, extra :: term) ::
               {:ok, new_state :: term}
@@ -617,13 +533,7 @@ defmodule GenServer do
   @callback format_status(reason, pdict_and_state :: list) :: term
             when reason: :normal | :terminate
 
-  @optional_callbacks code_change: 3,
-                      terminate: 2,
-                      handle_info: 2,
-                      handle_cast: 2,
-                      handle_call: 3,
-                      format_status: 2,
-                      handle_continue: 2
+  @optional_callbacks format_status: 2
 
   @typedoc "Return values of `start*` functions"
   @type on_start :: {:ok, pid} | :ignore | {:error, {:already_started, pid} | term}
@@ -738,7 +648,7 @@ defmodule GenServer do
         {:ok, state}
       end
 
-      defoverridable code_change: 3, terminate: 2, handle_info: 2, handle_cast: 2, handle_call: 3
+      defoverridable GenServer
     end
   end
 
@@ -754,8 +664,8 @@ defmodule GenServer do
             {:ok, args}
           end
 
-      You can copy the implementation above or define your own that converts \
-      the arguments given to GenServer.start_link/3 to the server state.
+      But you want to define your own implementation that converts the \
+      arguments given to GenServer.start_link/3 to the server state
       """
 
       :elixir_errors.warn(env.line, env.file, message)
@@ -789,7 +699,7 @@ defmodule GenServer do
   ## Options
 
     * `:name` - used for name registration as described in the "Name
-      registration" section in the documentation for `GenServer`
+      registration" section of the module documentation
 
     * `:timeout` - if present, the server is allowed to spend the given number of
       milliseconds initializing or it will be terminated and the start function
@@ -843,7 +753,7 @@ defmodule GenServer do
 
       {other, _} ->
         raise ArgumentError, """
-        expected :name option to be one of the following:
+        expected :name option to be one of:
 
           * nil
           * atom

lib/elixir/lib/hash_dict.ex

@@ -1,13 +1,12 @@
 defmodule HashDict do
   @moduledoc """
-  Tuple-based HashDict implementation.
+  WARNING: this module is deprecated.
 
-  This module is deprecated. Use the `Map` module instead.
+  Use the `Map` module instead.
   """
 
-  @moduledoc deprecated: "Use Map instead"
-
   # TODO: Remove by 2.0
+  # (hard-deprecated in elixir_dispatch)
 
   use Dict
 
@@ -24,24 +23,19 @@ defmodule HashDict do
   @compile :inline_list_funcs
   @compile {:inline, key_hash: 1, key_mask: 1, key_shift: 1}
 
-  message = "Use maps and the Map module instead"
-
   @doc """
   Creates a new empty dict.
   """
   @spec new :: Dict.t()
-  @deprecated message
   def new do
     %HashDict{}
   end
 
-  @deprecated message
   def put(%HashDict{root: root, size: size}, key, value) do
     {root, counter} = do_put(root, key, value, key_hash(key))
     %HashDict{root: root, size: size + counter}
   end
 
-  @deprecated message
   def update!(%HashDict{root: root, size: size} = dict, key, fun) when is_function(fun, 1) do
     {root, counter} =
       do_update(root, key, fn -> raise KeyError, key: key, term: dict end, fun, key_hash(key))
@@ -49,18 +43,15 @@ defmodule HashDict do
     %HashDict{root: root, size: size + counter}
   end
 
-  @deprecated message
   def update(%HashDict{root: root, size: size}, key, initial, fun) when is_function(fun, 1) do
     {root, counter} = do_update(root, key, fn -> initial end, fun, key_hash(key))
     %HashDict{root: root, size: size + counter}
   end
 
-  @deprecated message
   def fetch(%HashDict{root: root}, key) do
     do_fetch(root, key, key_hash(key))
   end
 
-  @deprecated message
   def delete(dict, key) do
     case dict_delete(dict, key) do
       {dict, _value} -> dict
@@ -68,7 +59,6 @@ defmodule HashDict do
     end
   end
 
-  @deprecated message
   def pop(dict, key, default \\ nil) do
     case dict_delete(dict, key) do
       {dict, value} -> {value, dict}
@@ -76,13 +66,11 @@ defmodule HashDict do
     end
   end
 
-  @deprecated message
   def size(%HashDict{size: size}) do
     size
   end
 
   @doc false
-  @deprecated message
   def reduce(%HashDict{root: root}, acc, fun) do
     do_reduce(root, acc, fun, @node_size, fn
       {:suspend, acc} -> {:suspended, acc, &{:done, elem(&1, 1)}}

lib/elixir/lib/hash_set.ex

@@ -1,19 +1,18 @@
 defmodule HashSet do
   @moduledoc """
-  Tuple-based HashSet implementation.
+  WARNING: this module is deprecated.
 
-  This module is deprecated. Use the `MapSet` module instead.
+  Use the `MapSet` module instead.
   """
 
-  @moduledoc deprecated: "Use MapSet instead"
+  # TODO: Remove by 2.0
+  # (hard-deprecated in elixir_dispatch)
 
   @node_bitmap 0b111
   @node_shift 3
   @node_size 8
   @node_template :erlang.make_tuple(@node_size, [])
 
-  message = "Use the MapSet module instead"
-
   @opaque t :: %__MODULE__{size: non_neg_integer, root: term}
   @doc false
   defstruct size: 0, root: @node_template
@@ -22,40 +21,33 @@ defmodule HashSet do
   @compile :inline_list_funcs
   @compile {:inline, key_hash: 1, key_mask: 1, key_shift: 1}
 
-  @deprecated message
   @spec new :: Set.t()
   def new do
     %HashSet{}
   end
 
-  @deprecated message
   def union(%HashSet{size: size1} = set1, %HashSet{size: size2} = set2) when size1 <= size2 do
     set_fold(set1, set2, fn v, acc -> put(acc, v) end)
   end
 
-  @deprecated message
   def union(%HashSet{} = set1, %HashSet{} = set2) do
     set_fold(set2, set1, fn v, acc -> put(acc, v) end)
   end
 
-  @deprecated message
   def intersection(%HashSet{} = set1, %HashSet{} = set2) do
     set_fold(set1, %HashSet{}, fn v, acc ->
       if member?(set2, v), do: put(acc, v), else: acc
     end)
   end
 
-  @deprecated message
   def difference(%HashSet{} = set1, %HashSet{} = set2) do
     set_fold(set2, set1, fn v, acc -> delete(acc, v) end)
   end
 
-  @deprecated message
   def to_list(set) do
     set_fold(set, [], &[&1 | &2]) |> :lists.reverse()
   end
 
-  @deprecated message
   def equal?(%HashSet{size: size1} = set1, %HashSet{size: size2} = set2) do
     case size1 do
       ^size2 -> subset?(set1, set2)
@@ -63,7 +55,6 @@ defmodule HashSet do
     end
   end
 
-  @deprecated message
   def subset?(%HashSet{} = set1, %HashSet{} = set2) do
     reduce(set1, {:cont, true}, fn member, acc ->
       case member?(set2, member) do
@@ -74,7 +65,6 @@ defmodule HashSet do
     |> elem(1)
   end
 
-  @deprecated message
   def disjoint?(%HashSet{} = set1, %HashSet{} = set2) do
     reduce(set2, {:cont, true}, fn member, acc ->
       case member?(set1, member) do
@@ -85,18 +75,15 @@ defmodule HashSet do
     |> elem(1)
   end
 
-  @deprecated message
   def member?(%HashSet{root: root}, term) do
     do_member?(root, term, key_hash(term))
   end
 
-  @deprecated message
   def put(%HashSet{root: root, size: size}, term) do
     {root, counter} = do_put(root, term, key_hash(term))
     %HashSet{root: root, size: size + counter}
   end
 
-  @deprecated message
   def delete(%HashSet{root: root, size: size} = set, term) do
     case do_delete(root, term, key_hash(term)) do
       {:ok, root} -> %HashSet{root: root, size: size - 1}
@@ -113,7 +100,6 @@ defmodule HashSet do
     end)
   end
 
-  @deprecated message
   def size(%HashSet{size: size}) do
     size
   end

lib/elixir/lib/inspect.ex

@@ -5,17 +5,15 @@ alias Code.Identifier
 
 defprotocol Inspect do
   @moduledoc """
-  The `Inspect` protocol converts an Elixir data structure into an
-  algebra document.
-
-  This documentation refers to implementing the `Inspect` protocol
-  for your own data structures. To learn more about using inspect,
-  see `Kernel.inspect/2` and `IO.inspect/2`.
+  The `Inspect` protocol is responsible for converting any Elixir
+  data structure into an algebra document. This document is then
+  formatted, either in pretty printing format or a regular one.
 
   The `inspect/2` function receives the entity to be inspected
   followed by the inspecting options, represented by the struct
-  `Inspect.Opts`. Building of the algebra document is done with
-  `Inspect.Algebra`.
+  `Inspect.Opts`.
+
+  Inspection is done using the functions available in `Inspect.Algebra`.
 
   ## Examples
 
@@ -305,25 +303,26 @@ end
 
 defimpl Inspect, for: Function do
   def inspect(function, _opts) do
-    fun_info = Function.info(function)
+    fun_info = :erlang.fun_info(function)
     mod = fun_info[:module]
     name = fun_info[:name]
 
-    cond do
-      fun_info[:type] == :external and fun_info[:env] == [] ->
-        inspected_as_atom = Identifier.inspect_as_atom(mod)
-        inspected_as_function = Identifier.inspect_as_function(name)
-        "&#{inspected_as_atom}.#{inspected_as_function}/#{fun_info[:arity]}"
+    if fun_info[:type] == :external and fun_info[:env] == [] do
+      inspected_as_atom = Identifier.inspect_as_atom(mod)
+      inspected_as_function = Identifier.inspect_as_function(name)
+      "&#{inspected_as_atom}.#{inspected_as_function}/#{fun_info[:arity]}"
+    else
+      case Atom.to_charlist(mod) do
+        'elixir_compiler_' ++ _ ->
+          if function_exported?(mod, :__RELATIVE__, 0) do
+            "#Function<#{uniq(fun_info)} in file:#{mod.__RELATIVE__}>"
+          else
+            default_inspect(mod, fun_info)
+          end
 
-      match?('elixir_compiler_' ++ _, Atom.to_charlist(mod)) ->
-        if function_exported?(mod, :__RELATIVE__, 0) do
-          "#Function<#{uniq(fun_info)} in file:#{mod.__RELATIVE__}>"
-        else
+        _ ->
           default_inspect(mod, fun_info)
-        end
-
-      true ->
-        default_inspect(mod, fun_info)
+      end
     end
   end
 

lib/elixir/lib/inspect/algebra.ex

@@ -25,19 +25,16 @@ defmodule Inspect.Opts do
 
     * `:limit` - limits the number of items that are printed for tuples,
       bitstrings, maps, lists and any other collection of items. It does not
-      apply to strings nor charlists and defaults to 50. If you don't want to limit
-      the number of items to a particular number, use `:infinity`.
+      apply to strings nor charlists and defaults to 50.
 
     * `:printable_limit` - limits the number of bytes that are printed for strings
-      and char lists. Defaults to 4096. If you don't want to limit the number of items
-      to a particular number, use `:infinity`.
+      and char lists. Defaults to 4096.
 
     * `:pretty` - if set to `true` enables pretty printing, defaults to `false`.
 
     * `:width` - defaults to 80 characters, used when pretty is `true` or when
       printing to IO devices. Set to 0 to force each item to be printed on its
-      own line. If you don't want to limit the number of items to a particular
-      number, use `:infinity`.
+      own line.
 
     * `:base` - prints integers as `:binary`, `:octal`, `:decimal`, or `:hex`,
       defaults to `:decimal`. When inspecting binaries any `:base` other than
@@ -104,7 +101,7 @@ defmodule Inspect.Algebra do
   additions, like support for binary nodes and a break mode that
   maximises use of horizontal space.
 
-      iex> Inspect.Algebra.empty()
+      iex> Inspect.Algebra.empty
       :doc_nil
 
       iex> "foo"
@@ -113,7 +110,7 @@ defmodule Inspect.Algebra do
   With the functions in this module, we can concatenate different
   elements together and render them:
 
-      iex> doc = Inspect.Algebra.concat(Inspect.Algebra.empty(), "foo")
+      iex> doc = Inspect.Algebra.concat(Inspect.Algebra.empty, "foo")
       iex> Inspect.Algebra.format(doc, 80)
       ["foo"]
 
@@ -232,6 +229,19 @@ defmodule Inspect.Algebra do
     quote do: {:doc_color, unquote(doc), unquote(color)}
   end
 
+  defmacrop is_doc(doc) do
+    if Macro.Env.in_guard?(__CALLER__) do
+      do_is_doc(doc)
+    else
+      var = quote(do: doc)
+
+      quote do
+        unquote(var) = unquote(doc)
+        unquote(do_is_doc(var))
+      end
+    end
+  end
+
   @docs [
     :doc_string,
     :doc_cons,
@@ -244,9 +254,12 @@ defmodule Inspect.Algebra do
     :doc_collapse
   ]
 
-  defguard is_doc(doc)
-           when is_binary(doc) or doc in [:doc_nil, :doc_line] or
-                  (is_tuple(doc) and elem(doc, 0) in @docs)
+  defp do_is_doc(doc) do
+    quote do
+      is_binary(unquote(doc)) or unquote(doc) in [:doc_nil, :doc_line] or
+        (is_tuple(unquote(doc)) and elem(unquote(doc), 0) in unquote(@docs))
+    end
+  end
 
   # Elixir + Inspect.Opts conveniences
 
@@ -263,6 +276,8 @@ defmodule Inspect.Algebra do
         Inspect.inspect(struct, opts)
       rescue
         caught_exception ->
+          stacktrace = System.stacktrace()
+
           # Because we try to raise a nice error message in case
           # we can't inspect a struct, there is a chance the error
           # message itself relies on the struct being printed, so
@@ -287,7 +302,7 @@ defmodule Inspect.Algebra do
               if opts.safe do
                 Inspect.inspect(exception, opts)
               else
-                reraise(exception, __STACKTRACE__)
+                reraise(exception, stacktrace)
               end
             after
               Process.delete(:inspect_trap)
@@ -326,21 +341,20 @@ defmodule Inspect.Algebra do
 
       iex> doc = Inspect.Algebra.container_doc("[", Enum.to_list(1..5), "]",
       ...>         %Inspect.Opts{limit: :infinity}, fn i, _opts -> to_string(i) end)
-      iex> Inspect.Algebra.format(doc, 5) |> IO.iodata_to_binary()
+      iex> Inspect.Algebra.format(doc, 5) |> IO.iodata_to_binary
       "[1,\n 2,\n 3,\n 4,\n 5]"
 
       iex> doc = Inspect.Algebra.container_doc("[", Enum.to_list(1..5), "]",
       ...>         %Inspect.Opts{limit: 3}, fn i, _opts -> to_string(i) end)
-      iex> Inspect.Algebra.format(doc, 20) |> IO.iodata_to_binary()
+      iex> Inspect.Algebra.format(doc, 20) |> IO.iodata_to_binary
       "[1, 2, 3, ...]"
 
       iex> doc = Inspect.Algebra.container_doc("[", Enum.to_list(1..5), "]",
       ...>         %Inspect.Opts{limit: 3}, fn i, _opts -> to_string(i) end, separator: "!")
-      iex> Inspect.Algebra.format(doc, 20) |> IO.iodata_to_binary()
+      iex> Inspect.Algebra.format(doc, 20) |> IO.iodata_to_binary
       "[1! 2! 3! ...]"
 
   """
-  @doc since: "1.6.0"
   @spec container_doc(t, [any], t, Inspect.Opts.t(), (term, Inspect.Opts.t() -> t), keyword()) ::
           t
   def container_doc(left, collection, right, inspect, fun, opts \\ [])
@@ -433,7 +447,7 @@ defmodule Inspect.Algebra do
 
   ## Examples
 
-      iex> Inspect.Algebra.empty()
+      iex> Inspect.Algebra.empty
       :doc_nil
 
   """
@@ -468,7 +482,6 @@ defmodule Inspect.Algebra do
       ["olá", " ", "mundo"]
 
   """
-  @doc since: "1.6.0"
   @spec string(String.t()) :: doc_string
   def string(string) when is_binary(string) do
     doc_string(string, String.length(string))
@@ -507,7 +520,6 @@ defmodule Inspect.Algebra do
   @doc ~S"""
   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
   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
@@ -538,7 +550,7 @@ defmodule Inspect.Algebra do
       ["hello", "\n     ", "world"]
 
   """
-  @spec nest(t, non_neg_integer | :cursor | :reset, :always | :break) :: doc_nest
+  @spec nest(t, non_neg_integer) :: doc_nest
   def nest(doc, level, mode \\ :always)
 
   def nest(doc, :cursor, mode) when is_doc(doc) and mode in [:always, :break] do
@@ -592,7 +604,6 @@ defmodule Inspect.Algebra do
   Collapse any new lines and whitespace following this
   node, emitting up to `max` new lines.
   """
-  @doc since: "1.6.0"
   @spec collapse_lines(pos_integer) :: doc_collapse
   def collapse_lines(max) when is_integer(max) and max > 0 do
     doc_collapse(max)
@@ -639,8 +650,7 @@ defmodule Inspect.Algebra do
       })
 
   """
-  @doc since: "1.6.0"
-  @spec next_break_fits(t, :enabled | :disabled) :: doc_fits
+  @spec next_break_fits(t) :: doc_fits
   def next_break_fits(doc, mode \\ @next_break_fits)
       when is_doc(doc) and mode in [:enabled, :disabled] do
     doc_fits(doc, mode)
@@ -649,7 +659,6 @@ defmodule Inspect.Algebra do
   @doc """
   Forces the current group to be unfit.
   """
-  @doc since: "1.6.0"
   @spec force_unfit(t) :: doc_force
   def force_unfit(doc) when is_doc(doc) do
     doc_force(doc)
@@ -683,7 +692,6 @@ defmodule Inspect.Algebra do
   This function is used by `container_doc/4` and friends to the
   maximum number of entries on the same line.
   """
-  @doc since: "1.6.0"
   @spec flex_break(binary) :: doc_break
   def flex_break(string \\ " ") when is_binary(string) do
     doc_break(string, :flex)
@@ -696,7 +704,6 @@ defmodule Inspect.Algebra do
   This function is used by `container_doc/6` and friends
   to the maximum number of entries on the same line.
   """
-  @doc since: "1.6.0"
   @spec flex_glue(t, binary, t) :: t
   def flex_glue(doc1, break_string \\ " ", doc2) when is_binary(break_string) do
     concat(doc1, concat(flex_break(break_string), doc2))
@@ -757,7 +764,7 @@ defmodule Inspect.Algebra do
       ["Hello,", "\n", "A", "\n", "B"]
 
   """
-  @spec group(t, :self | :inherit) :: doc_group
+  @spec group(t) :: doc_group
   def group(doc, mode \\ :self) when is_doc(doc) do
     doc_group(doc, mode)
   end
@@ -782,18 +789,16 @@ defmodule Inspect.Algebra do
 
   ## Examples
 
-      iex> doc =
-      ...>   Inspect.Algebra.concat(
-      ...>     Inspect.Algebra.concat(
-      ...>       "Hughes",
-      ...>       Inspect.Algebra.line()
-      ...>     ), "Wadler"
-      ...>   )
-      iex> Inspect.Algebra.format(doc, 80)
-      ["Hughes", "\n", "Wadler"]
+    iex> doc = Inspect.Algebra.concat(
+    ...>   Inspect.Algebra.concat(
+    ...>     "Hughes",
+    ...>     Inspect.Algebra.line()
+    ...>   ), "Wadler"
+    ...> )
+    iex> Inspect.Algebra.format(doc, 80)
+    ["Hughes", "\n", "Wadler"]
 
   """
-  @doc since: "1.6.0"
   @spec line() :: t
   def line(), do: :doc_line
 

lib/elixir/lib/integer.ex

@@ -1,15 +1,6 @@
 defmodule Integer do
   @moduledoc """
   Functions for working with integers.
-
-  Some functions that work on integers are found in `Kernel`:
-
-    * `abs/2`
-    * `div/2`
-    * `max/2`
-    * `min/2`
-    * `rem/2`
-
   """
 
   import Bitwise
@@ -81,7 +72,6 @@ defmodule Integer do
       -2
 
   """
-  @doc since: "1.4.0"
   @spec mod(integer, neg_integer | pos_integer) :: integer
   def mod(dividend, divisor) do
     remainder = rem(dividend, divisor)
@@ -115,7 +105,6 @@ defmodule Integer do
       -50
 
   """
-  @doc since: "1.4.0"
   @spec floor_div(integer, neg_integer | pos_integer) :: integer
   def floor_div(dividend, divisor) do
     if dividend * divisor < 0 and rem(dividend, divisor) != 0 do
@@ -149,7 +138,10 @@ defmodule Integer do
     do_digits(integer, base, [])
   end
 
-  defp do_digits(integer, base, acc) when abs(integer) < base, do: [integer | acc]
+  defp do_digits(digit, base, []) when abs(digit) < base, do: [digit]
+  defp do_digits(digit, base, []) when digit == -base, do: [-1, 0]
+  defp do_digits(base, base, []), do: [1, 0]
+  defp do_digits(0, _base, acc), do: acc
 
   defp do_digits(integer, base, acc),
     do: do_digits(div(integer, base), base, [rem(integer, base) | acc])
@@ -177,6 +169,10 @@ defmodule Integer do
     do_undigits(digits, base, 0)
   end
 
+  defp do_undigits([], _base, 0), do: 0
+  defp do_undigits([digit], base, 0) when is_integer(digit) and digit < base, do: digit
+  defp do_undigits([1, 0], base, 0), do: base
+  defp do_undigits([0 | tail], base, 0), do: do_undigits(tail, base, 0)
   defp do_undigits([], _base, acc), do: acc
 
   defp do_undigits([digit | _], base, _) when is_integer(digit) and digit >= base,
@@ -196,7 +192,7 @@ defmodule Integer do
 
   Raises an error if `base` is less than 2 or more than 36.
 
-  If you want to convert a string-formatted integer directly to an integer,
+  If you want to convert a string-formatted integer directly to a integer,
   `String.to_integer/1` or `String.to_integer/2` can be used instead.
 
   ## Examples
@@ -311,7 +307,7 @@ defmodule Integer do
       iex> Integer.to_string(-100, 16)
       "-64"
 
-      iex> Integer.to_string(882_681_651, 36)
+      iex> Integer.to_string(882681651, 36)
       "ELIXIR"
 
   """
@@ -360,7 +356,7 @@ defmodule Integer do
       iex> Integer.to_charlist(-100, 16)
       '-64'
 
-      iex> Integer.to_charlist(882_681_651, 36)
+      iex> Integer.to_charlist(882681651, 36)
       'ELIXIR'
 
   """
@@ -398,7 +394,6 @@ defmodule Integer do
       0
 
   """
-  @doc since: "1.5.0"
   @spec gcd(0, 0) :: 0
   @spec gcd(integer, integer) :: pos_integer
   def gcd(integer1, integer2) when is_integer(integer1) and is_integer(integer2) do
@@ -410,12 +405,14 @@ defmodule Integer do
   defp gcd_positive(integer1, integer2), do: gcd_positive(integer2, rem(integer1, integer2))
 
   # TODO: Remove by 2.0
+  # (hard-deprecated in elixir_dispatch)
   @doc false
-  @deprecated "Use Integer.to_charlist/1 instead"
+  @spec to_char_list(integer) :: charlist
   def to_char_list(integer), do: Integer.to_charlist(integer)
 
   # TODO: Remove by 2.0
+  # (hard-deprecated in elixir_dispatch)
   @doc false
-  @deprecated "Use Integer.to_charlist/2 instead"
+  @spec to_char_list(integer, 2..36) :: charlist
   def to_char_list(integer, base), do: Integer.to_charlist(integer, base)
 end

lib/elixir/lib/io/ansi.ex

@@ -170,33 +170,6 @@ defmodule IO.ANSI do
   @doc "Sends cursor home."
   defsequence(:home, "", "H")
 
-  @doc """
-  Sends cursor to the absolute position specified by `line` and `column`.
-
-  Line `0` and column `0` would mean the top left corner.
-  """
-  @spec cursor(non_neg_integer, non_neg_integer) :: String.t()
-  def cursor(line, column)
-      when is_integer(line) and line >= 0 and is_integer(column) and column >= 0 do
-    "\e[#{line};#{column}H"
-  end
-
-  @doc "Sends cursor `lines` up."
-  @spec cursor_up(pos_integer) :: String.t()
-  def cursor_up(lines \\ 1) when is_integer(lines) and lines >= 1, do: "\e[#{lines}A"
-
-  @doc "Sends cursor `lines` down."
-  @spec cursor_down(pos_integer) :: String.t()
-  def cursor_down(lines \\ 1) when is_integer(lines) and lines >= 1, do: "\e[#{lines}B"
-
-  @doc "Sends cursor `columns` to the right."
-  @spec cursor_right(pos_integer) :: String.t()
-  def cursor_right(columns \\ 1) when is_integer(columns) and columns >= 1, do: "\e[#{columns}C"
-
-  @doc "Sends cursor `columns` to the left."
-  @spec cursor_left(pos_integer) :: String.t()
-  def cursor_left(columns \\ 1) when is_integer(columns) and columns >= 1, do: "\e[#{columns}D"
-
   @doc "Clears screen."
   defsequence(:clear, "2", "J")
 

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

@@ -7,15 +7,14 @@ defmodule IO.ANSI.Docs do
   @doc """
   The default options used by this module.
 
-  The supported keys are:
+  The supported values are:
 
     * `:enabled`           - toggles coloring on and off (true)
     * `:doc_bold`          - bold text (bright)
     * `:doc_code`          - code blocks (cyan)
     * `:doc_headings`      - h1, h2, h3, h4, h5, h6 headings (yellow)
-    * `:doc_metadata`      - documentation metadata keys (yellow)
     * `:doc_inline_code`   - inline code (cyan)
-    * `:doc_table_heading` - the style for table headings
+    * `:doc_table_heading` - style for table headings
     * `:doc_title`         - top level heading (reverse, yellow)
     * `:doc_underline`     - underlined text (underline)
     * `:width`             - the width to format the text (80)
@@ -23,14 +22,12 @@ defmodule IO.ANSI.Docs do
   Values for the color settings are strings with
   comma-separated ANSI values.
   """
-  @spec default_options() :: keyword
   def default_options do
     [
       enabled: true,
       doc_bold: [:bright],
       doc_code: [:cyan],
       doc_headings: [:yellow],
-      doc_metadata: [:yellow],
       doc_inline_code: [:cyan],
       doc_table_heading: [:reverse],
       doc_title: [:reverse, :yellow],
@@ -44,7 +41,6 @@ defmodule IO.ANSI.Docs do
 
   See `default_options/0` for docs on the supported options.
   """
-  @spec print_heading(String.t(), keyword) :: :ok
   def print_heading(heading, options \\ []) do
     IO.puts(IO.ANSI.reset())
     options = Keyword.merge(default_options(), options)
@@ -55,46 +51,12 @@ defmodule IO.ANSI.Docs do
     newline_after_block()
   end
 
-  @doc """
-  Prints documentation metadata (only `since` and `deprecated` for now).
-
-  See `default_options/0` for docs on the supported options.
-  """
-  @spec print_metadata(map, keyword) :: :ok
-  def print_metadata(metadata, options \\ []) when is_map(metadata) do
-    options = Keyword.merge(default_options(), options)
-    print_each_metadata(metadata, options) && IO.write("\n")
-  end
-
-  @metadata_filter [:deprecated, :since]
-
-  defp print_each_metadata(metadata, options) do
-    Enum.reduce(metadata, false, fn
-      {key, value}, _printed when is_binary(value) and key in @metadata_filter ->
-        label = metadata_label(key, options)
-        indent = String.duplicate(" ", length_without_escape(label, 0) + 1)
-        write_with_wrap([label | String.split(value, @spaces)], options[:width], indent, true)
-
-      _metadata, printed ->
-        printed
-    end)
-  end
-
-  defp metadata_label(key, options) do
-    if options[:enabled] do
-      "#{color(:doc_metadata, options)}#{key}:#{IO.ANSI.reset()}"
-    else
-      "#{key}:"
-    end
-  end
-
   @doc """
   Prints the documentation body.
 
   In addition to the printing string, takes a set of options
-  defined in `default_options/0`.
+  defined in `default_options/1`.
   """
-  @spec print(String.t(), keyword) :: :ok
   def print(doc, options \\ []) do
     options = Keyword.merge(default_options(), options)
 
@@ -424,22 +386,17 @@ defmodule IO.ANSI.Docs do
   end
 
   defp generate_table_cell({{{col, length}, width}, :center}) do
-    ansi_diff = byte_size(col) - length
-    width = width + ansi_diff
-
     col
     |> String.pad_leading(div(width, 2) - div(length, 2) + length)
     |> String.pad_trailing(width + 1 - rem(width, 2))
   end
 
-  defp generate_table_cell({{{col, length}, width}, :right}) do
-    ansi_diff = byte_size(col) - length
-    String.pad_leading(col, width + ansi_diff)
+  defp generate_table_cell({{{col, _length}, width}, :right}) do
+    String.pad_leading(col, width)
   end
 
-  defp generate_table_cell({{{col, length}, width}, :left}) do
-    ansi_diff = byte_size(col) - length
-    String.pad_trailing(col, width + ansi_diff)
+  defp generate_table_cell({{{col, _length}, width}, :left}) do
+    String.pad_trailing(col, width)
   end
 
   defp table_line?(line) do

lib/elixir/lib/io/stream.ex

@@ -1,7 +1,6 @@
 defmodule IO.StreamError do
   defexception [:reason, :message]
 
-  @impl true
   def exception(opts) do
     reason = opts[:reason]
     formatted = IO.iodata_to_binary(:file.format_error(reason))

lib/elixir/lib/kernel/cli.ex

@@ -116,9 +116,10 @@ defmodule Kernel.CLI do
             exit(reason)
 
           kind, reason ->
-            print_error(kind, reason, __STACKTRACE__)
+            stack = System.stacktrace()
+            print_error(kind, reason, stack)
             send(parent, {self(), {:shutdown, 1}})
-            exit(to_exit(kind, reason, __STACKTRACE__))
+            exit(to_exit(kind, reason, stack))
         else
           _ ->
             send(parent, {self(), res})
@@ -175,7 +176,7 @@ defmodule Kernel.CLI do
     "    " <> String.replace(string, "\n", "\n    ")
   end
 
-  @elixir_internals [:elixir, :elixir_aliases, :elixir_expand, :elixir_compiler, :elixir_module] ++
+  @elixir_internals [:elixir, :elixir_expand, :elixir_compiler, :elixir_module] ++
                       [:elixir_clauses, :elixir_lexical, :elixir_def, :elixir_map] ++
                       [:elixir_erl, :elixir_erl_clauses, :elixir_erl_pass, Kernel.ErrorHandler]
 

lib/elixir/lib/kernel/lexical_tracker.ex

@@ -23,19 +23,28 @@ defmodule Kernel.LexicalTracker do
     :gen_server.call(to_pid(arg), :remote_dispatches, @timeout)
   end
 
+  @doc """
+  Gets the destination the lexical scope is meant to
+  compile to.
+  """
+  def dest(arg) do
+    :gen_server.call(to_pid(arg), :dest, @timeout)
+  end
+
   defp to_pid(pid) when is_pid(pid), do: pid
 
   defp to_pid(mod) when is_atom(mod) do
-    {set, _} = :elixir_module.data_tables(mod)
-    :ets.lookup_element(set, {:elixir, :lexical_tracker}, 2)
+    table = :elixir_module.data_table(mod)
+    [{_, val}] = :ets.lookup(table, {:elixir, :lexical_tracker})
+    val
   end
 
   # Internal API
 
   # Starts the tracker and returns its PID.
   @doc false
-  def start_link() do
-    :gen_server.start_link(__MODULE__, :ok, [])
+  def start_link(dest) do
+    :gen_server.start_link(__MODULE__, dest, [])
   end
 
   @doc false
@@ -116,13 +125,14 @@ defmodule Kernel.LexicalTracker do
 
   # Callbacks
 
-  def init(:ok) do
+  def init(dest) do
     state = %{
       directives: %{},
       references: %{},
       compile: %{},
       runtime: %{},
       structs: %{},
+      dest: dest,
       cache: %{},
       file: nil
     }
@@ -149,6 +159,10 @@ defmodule Kernel.LexicalTracker do
     {:reply, {state.compile, state.runtime}, state}
   end
 
+  def handle_call(:dest, _from, state) do
+    {:reply, state.dest, state}
+  end
+
   def handle_call({:read_cache, key}, _from, %{cache: cache} = state) do
     {:reply, :maps.get(key, cache), state}
   end

lib/elixir/lib/kernel/parallel_compiler.ex

@@ -14,17 +14,14 @@ defmodule Kernel.ParallelCompiler do
   See `Task.async/1` for more information. The task spawned must be
   always awaited on by calling `Task.await/1`
   """
-  @doc since: "1.6.0"
   def async(fun) when is_function(fun) 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)
 
       Task.async(fn ->
         :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)
@@ -72,12 +69,10 @@ defmodule Kernel.ParallelCompiler do
       `dest`, use `compile_to_path/3` instead.
 
   """
-  @doc since: "1.6.0"
   def compile(files, options \\ []) when is_list(options) do
     spawn_workers(files, :compile, options)
   end
 
-  @doc since: "1.6.0"
   def compile_to_path(files, path, options \\ []) when is_binary(path) and is_list(options) do
     spawn_workers(files, {:compile, path}, options)
   end
@@ -102,7 +97,6 @@ defmodule Kernel.ParallelCompiler do
       the file, module and the module bytecode
 
   """
-  @doc since: "1.6.0"
   def require(files, options \\ []) when is_list(options) do
     spawn_workers(files, :require, options)
   end
@@ -126,7 +120,7 @@ defmodule Kernel.ParallelCompiler do
   end
 
   defp spawn_workers(files, output, options) do
-    {:module, _} = :code.ensure_loaded(Kernel.ErrorHandler)
+    true = Code.ensure_loaded?(Kernel.ErrorHandler)
     compiler_pid = self()
     :elixir_code_server.cast({:reset_warnings, compiler_pid})
     schedulers = max(:erlang.system_info(:schedulers_online), 2)
@@ -197,13 +191,11 @@ defmodule Kernel.ParallelCompiler do
               case output do
                 {:compile, path} ->
                   :erlang.process_flag(:error_handler, Kernel.ErrorHandler)
-                  :erlang.put(:elixir_compiler_dest, path)
-                  :elixir_compiler.file_to_path(Path.expand(file), path)
+                  :elixir_compiler.file_to_path(file, path)
 
                 :compile ->
                   :erlang.process_flag(:error_handler, Kernel.ErrorHandler)
-                  :erlang.put(:elixir_compiler_dest, dest)
-                  Code.compile_file(file)
+                  :elixir_compiler.file(file, dest)
 
                 :require ->
                   Code.require_file(file)
@@ -212,7 +204,7 @@ defmodule Kernel.ParallelCompiler do
             :ok
           catch
             kind, reason ->
-              {kind, reason, __STACKTRACE__}
+              {kind, reason, System.stacktrace()}
           end
 
         send(parent, {:file_done, self(), file, result})
@@ -238,33 +230,19 @@ defmodule Kernel.ParallelCompiler do
   end
 
   # Queued x, waiting for x: POSSIBLE ERROR! Release processes so we get the failures
-
-  # Single entry, just release it.
-  defp spawn_workers([], [_] = waiting, [_] = queued, result, warnings, state) do
-    [{_, _, ref, _, _}] = waiting
-    spawn_workers([{ref, :not_found}], waiting, queued, result, warnings, state)
-  end
-
-  # Multiple entries, try to release modules.
   defp spawn_workers([], waiting, queued, result, warnings, state)
        when length(waiting) == length(queued) 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 we only release modules because those can be rescued. A missing
-    # struct is a guaranteed compile error, so we never release it and treat
-    # it exclusively a missing entry/deadlock.
     pending =
       for {pid, _, _, _} <- queued,
           entry = waiting_on_without_definition(waiting, pid),
-          {kind, _, ref, on, _} = entry,
-          kind == :module,
+          {_, _, ref, on, _} = entry,
           do: {on, {ref, :not_found}}
 
     # Instead of releasing all files at once, we release them in groups
     # based on the module they are waiting on. We pick the module being
     # depended on with less edges, as it is the mostly likely source of
     # error (for example, someone made a typo). This may not always be
-    # true though. For example, if there is a macro injecting code into
+    # true though: for example, if there is a macro injecting code into
     # multiple modules and such code becomes faulty, now multiple modules
     # are waiting on the same module required by the faulty code. However,
     # since we need to pick something to be first, the one with fewer edges
@@ -418,8 +396,8 @@ defmodule Kernel.ParallelCompiler do
         {:current_stacktrace, stacktrace} = Process.info(pid, :current_stacktrace)
         Process.exit(pid, :kill)
 
-        {kind, ^pid, _, on, _} = List.keyfind(waiting, pid, 1)
-        description = "deadlocked waiting on #{kind} #{inspect(on)}"
+        {_kind, ^pid, _, on, _} = List.keyfind(waiting, pid, 1)
+        description = "deadlocked waiting on module #{inspect(on)}"
         error = CompileError.exception(description: description, file: nil, line: nil)
         print_error(file, :error, error, stacktrace)
 
@@ -441,10 +419,7 @@ defmodule Kernel.ParallelCompiler do
       IO.puts(["  ", String.pad_leading(file, max), " => " | inspect(mod)])
     end
 
-    IO.puts(
-      "\nEnsure there are no compile-time dependencies between those files " <>
-        "and that the modules they reference exist and are correctly named\n"
-    )
+    IO.puts("")
 
     for {file, _, description} <- deadlock, do: {Path.absname(file), nil, description}
   end

lib/elixir/lib/kernel/special_forms.ex

@@ -75,7 +75,7 @@ defmodule Kernel.SpecialForms do
   defmacro unquote(:%{})(args), do: error!([args])
 
   @doc """
-  Matches on or builds a struct.
+  Creates a struct.
 
   A struct is a tagged map that allows developers to provide
   default values for keys, tags to be used in polymorphic
@@ -96,25 +96,16 @@ defmodule Kernel.SpecialForms do
 
       %User{} == %{__struct__: User, name: "john", age: 27}
 
-  The struct fields can be given when building the struct:
+  A struct also validates that the given keys are part of the defined
+  struct. The example below will fail because there is no key
+  `:full_name` in the `User` struct:
 
-      %User{age: 31}
-      #=> %{__struct__: User, name: "john", age: 31}
-
-  Or also on pattern matching to extract values out:
-
-      %User{age: age} = user
+      %User{full_name: "john doe"}
 
   An update operation specific for structs is also available:
 
       %User{user | age: 28}
 
-  The advantage of structs is that they validate that the given
-  keys are part of the defined struct. The example below will fail
-  because there is no key `:full_name` in the `User` struct:
-
-      %User{full_name: "john doe"}
-
   The syntax above will guarantee the given keys are valid at
   compilation time and it will guarantee at runtime the given
   argument is a struct, failing with `BadStructError` otherwise.
@@ -125,24 +116,6 @@ defmodule Kernel.SpecialForms do
   can be used with protocols for polymorphic dispatch. Also
   see `Kernel.struct/2` and `Kernel.struct!/2` for examples on
   how to create and update structs dynamically.
-
-  ## Pattern matching on struct names
-
-  Besides allowing pattern matching on struct fields, such as:
-
-      %User{age: age} = user
-
-  Structs also allow pattern matching on the struct name:
-
-      %struct_name{} = user
-      struct_name #=> User
-
-  You can also assign the struct name to `_` when you want to
-  check if something is a struct but you are not interested in
-  its name:
-
-      %_{} = user
-
   """
   defmacro unquote(:%)(struct, map), do: error!([struct, map])
 
@@ -321,7 +294,7 @@ defmodule Kernel.SpecialForms do
 
   Or as a part of function definitions to pattern match:
 
-      defmodule ImageTyper do
+      defmodule ImageTyper
         @png_signature <<137::size(8), 80::size(8), 78::size(8), 71::size(8),
                          13::size(8), 10::size(8), 26::size(8), 10::size(8)>>
         @jpg_signature <<255::size(8), 216::size(8)>>
@@ -358,7 +331,7 @@ defmodule Kernel.SpecialForms do
 
   The dot may be used to invoke anonymous functions too:
 
-      iex> (fn n -> n end).(7)
+      iex> (fn(n) -> n end).(7)
       7
 
   in which case there is a function on the left hand side.
@@ -387,18 +360,21 @@ defmodule Kernel.SpecialForms do
       iex> Kernel.+(1, 2)
       3
 
-      iex> Kernel."+"(1, 2)
+      iex> Kernel."length"([1, 2, 3])
       3
 
-  Note that wrapping the function name in single- or double-quotes is always a
-  remote call. Therefore `Kernel."Foo"` will attempt to call the function "Foo"
-  and not return the alias `Kernel.Foo`. This is done by design as module names
-  are more strict than function names.
+      iex> Kernel.'+'(1, 2)
+      3
+
+  Note that `Kernel."FUNCTION_NAME"` will be treated as a remote call and not an alias.
+  This choice was done so every time single- or double-quotes are used, we have
+  a remote call regardless of the quote contents. This decision is also reflected
+  in the quoted expressions discussed below.
 
   When the dot is used to invoke an anonymous function there is only one
   operand, but it is still written using a postfix notation:
 
-      iex> negate = fn n -> -n end
+      iex> negate = fn(n) -> -n end
       iex> negate.(7)
       -7
 
@@ -422,7 +398,15 @@ defmodule Kernel.SpecialForms do
   with the name as first argument, some keyword list as metadata as second,
   and the list of arguments as third. In this case, the arguments are the
   alias `String` and the atom `:downcase`. The second argument in a remote call
-  is **always** an atom.
+  is **always** an atom regardless of the literal used in the call:
+
+      iex> quote do
+      ...>   String."downcase"("FOO")
+      ...> end
+      {{:., [], [{:__aliases__, [alias: false], [:String]}, :downcase]}, [], ["FOO"]}
+
+  The tuple containing `:.` is wrapped in another tuple, which actually
+  represents the function call, and has `"FOO"` as argument.
 
   In the case of calls to anonymous functions, the inner tuple with the dot
   special form has only one argument, reflecting the fact that the operator is
@@ -686,14 +670,6 @@ defmodule Kernel.SpecialForms do
   """
   defmacro __CALLER__, do: error!([])
 
-  @doc """
-  Returns the stacktrace for the curently handled exception.
-
-  It is available only in the `catch` and `rescue` clauses of `try/1`
-  expressions.
-  """
-  defmacro __STACKTRACE__, do: error!([])
-
   @doc """
   Accesses an already bound variable in match clauses. Also known as the pin operator.
 
@@ -880,7 +856,7 @@ defmodule Kernel.SpecialForms do
         end
       end
 
-  Now invoking `squared(my_number.())` as before will print the value just
+  Now invoking `square(my_number.())` as before will print the value just
   once.
 
   In fact, this pattern is so common that most of the times you will want
@@ -1352,7 +1328,7 @@ defmodule Kernel.SpecialForms do
       iex> for(x <- [1, 1, 2, 3], uniq: true, do: x * 2)
       [2, 4, 6]
 
-      iex> for(<<x <- "abcabc">>, uniq: true, into: "", do: <<x - 32>>)
+      iex> for(<<x <- "abcabc">>, uniq: true, into: "", do: <<x-32>>)
       "ABC"
 
   """
@@ -1365,9 +1341,8 @@ defmodule Kernel.SpecialForms do
 
       iex> opts = %{width: 10, height: 15}
       iex> with {:ok, width} <- Map.fetch(opts, :width),
-      ...>      {:ok, height} <- Map.fetch(opts, :height) do
-      ...>   {:ok, width * height}
-      ...> end
+      ...>      {:ok, height} <- Map.fetch(opts, :height),
+      ...>      do: {:ok, width * height}
       {:ok, 150}
 
   If all clauses match, the `do` block is executed, returning its result.
@@ -1375,17 +1350,15 @@ defmodule Kernel.SpecialForms do
 
       iex> opts = %{width: 10}
       iex> with {:ok, width} <- Map.fetch(opts, :width),
-      ...>      {:ok, height} <- Map.fetch(opts, :height) do
-      ...>   {:ok, width * height}
-      ...> end
+      ...>      {:ok, height} <- Map.fetch(opts, :height),
+      ...>      do: {:ok, width * height}
       :error
 
   Guards can be used in patterns as well:
 
       iex> users = %{"melany" => "guest", "bob" => :admin}
-      iex> with {:ok, role} when not is_binary(role) <- Map.fetch(users, "bob") do
-      ...>   {:ok, to_string(role)}
-      ...> end
+      iex> with {:ok, role} when not is_binary(role) <- Map.fetch(users, "bob"),
+      ...>      do: {:ok, to_string(role)}
       {:ok, "admin"}
 
   As in `for/1`, variables bound inside `with/1` won't leak;
@@ -1395,9 +1368,8 @@ defmodule Kernel.SpecialForms do
       iex> opts = %{width: 10, height: 15}
       iex> with {:ok, width} <- Map.fetch(opts, :width),
       ...>      double_width = width * 2,
-      ...>      {:ok, height} <- Map.fetch(opts, :height) do
-      ...>   {:ok, double_width * height}
-      ...> end
+      ...>      {:ok, height} <- Map.fetch(opts, :height),
+      ...>      do: {:ok, double_width * height}
       {:ok, 300}
       iex> width
       nil
@@ -1408,20 +1380,6 @@ defmodule Kernel.SpecialForms do
       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:
-
-      iex> opts = %{width: 10, height: 15}
-      iex> with(
-      ...>   {:ok, width} <- Map.fetch(opts, :width),
-      ...>   {:ok, height} <- Map.fetch(opts, :height)
-      ...> ) do
-      ...>   {:ok, width * height}
-      ...> end
-      {:ok, 150}
-
-  The choice between parens and no parens is a matter of preference.
-
   An `else` option can be given to modify what is being returned from
   `with` in the case of a failed match:
 
@@ -1725,9 +1683,7 @@ defmodule Kernel.SpecialForms do
   pattern matching (similar to the `case` special form).
 
   Note that calls inside `try/1` are not tail recursive since the VM
-  needs to keep the stacktrace in case an exception happens. To
-  retrieve the stacktrace, access `__STACKTRACE__/0` inside the `rescue`
-  or `catch` clause.
+  needs to keep the stacktrace in case an exception happens.
 
   ## `rescue` clauses
 
@@ -1997,10 +1953,10 @@ defmodule Kernel.SpecialForms do
   ## Examples
 
       receive do
-        {:selector, number, name} when is_integer(number) ->
-          name
-        name when is_atom(name) ->
-          name
+        {:selector, i, value} when is_integer(i) ->
+          value
+        value when is_atom(value) ->
+          value
         _ ->
           IO.puts :stderr, "Unexpected message received"
       end
@@ -2009,10 +1965,10 @@ defmodule Kernel.SpecialForms do
   received after the given timeout period, specified in milliseconds:
 
       receive do
-        {:selector, number, name} when is_integer(number) ->
-          name
-        name when is_atom(name) ->
-          name
+        {:selector, i, value} when is_integer(i) ->
+          value
+        value when is_atom(value) ->
+          value
         _ ->
           IO.puts :stderr, "Unexpected message received"
       after
@@ -2025,13 +1981,13 @@ defmodule Kernel.SpecialForms do
   one of the allowed values:
 
     * `:infinity` - the process should wait indefinitely for a matching
-      message, this is the same as not using the after clause
+      message, this is the same as not using a timeout
 
     * `0` - if there is no matching message in the mailbox, the timeout
       will occur immediately
 
-    * positive integer smaller than or equal to `4_294_967_295` (`0xFFFFFFFF`
-      in hexadecimal notation) - it should be possible to represent the timeout
+    * positive integer smaller than `4_294_967_295` (`0xFFFFFFFF`
+      in hex notation) - it should be possible to represent the timeout
       value as an unsigned 32-bit integer.
 
   ## Variables handling

lib/elixir/lib/kernel/utils.ex

@@ -125,8 +125,8 @@ defmodule Kernel.Utils do
     RuntimeError.exception(msg)
   end
 
-  def raise(module) when is_atom(module) do
-    module.exception([])
+  def raise(atom) when is_atom(atom) do
+    atom.exception([])
   end
 
   def raise(%_{__exception__: true} = exception) do
@@ -188,8 +188,7 @@ defmodule Kernel.Utils do
   @spec defguard([Macro.t()], Macro.t(), Macro.Env.t()) :: Macro.t()
   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, _scope} = :elixir_expand.expand(expr, %{env | context: :guard, vars: vars})
 
     quote do
       case Macro.Env.in_guard?(__CALLER__) do
@@ -201,8 +200,8 @@ defmodule Kernel.Utils do
 
   defp extract_refs_from_args(args) do
     Macro.postwalk(args, [], fn
-      {ref, meta, context} = var, acc when is_atom(ref) and is_atom(context) ->
-        {var, [{ref, var_context(meta, context)} | acc]}
+      {ref, _meta, context} = var, acc when is_atom(ref) and is_atom(context) ->
+        {var, [{ref, context} | acc]}
 
       node, acc ->
         {node, acc}
@@ -212,8 +211,8 @@ defmodule Kernel.Utils do
   # Finds every reference to `refs` in `guard` and wraps them in an unquote.
   defp unquote_every_ref(guard, refs) do
     Macro.postwalk(guard, fn
-      {ref, meta, context} = var when is_atom(ref) and is_atom(context) ->
-        case {ref, var_context(meta, context)} in refs do
+      {ref, _meta, context} = var when is_atom(ref) and is_atom(context) ->
+        case {ref, context} in refs do
           true -> literal_unquote(var)
           false -> var
         end
@@ -227,11 +226,9 @@ defmodule Kernel.Utils do
   defp unquote_refs_once(guard, refs) do
     {_, used_refs} =
       Macro.postwalk(guard, [], fn
-        {ref, meta, context} = var, acc when is_atom(ref) and is_atom(context) ->
-          pair = {ref, var_context(meta, context)}
-
-          case pair in refs and pair not in acc do
-            true -> {var, [pair | acc]}
+        {ref, _meta, context} = var, acc when is_atom(ref) and is_atom(context) ->
+          case {ref, context} in refs and {ref, context} not in acc do
+            true -> {var, [{ref, context} | acc]}
             false -> {var, acc}
           end
 
@@ -239,7 +236,7 @@ defmodule Kernel.Utils do
           {node, acc}
       end)
 
-    vars = for {ref, context} <- :lists.reverse(used_refs), do: context_to_var(ref, context)
+    vars = for {ref, context} <- :lists.reverse(used_refs), do: {ref, [], context}
     exprs = for var <- vars, do: literal_unquote(var)
 
     quote do
@@ -255,14 +252,4 @@ defmodule Kernel.Utils do
   defp literal_unquote(ast) do
     {:unquote, [], List.wrap(ast)}
   end
-
-  defp context_to_var(ref, ctx) when is_atom(ctx), do: {ref, [], ctx}
-  defp context_to_var(ref, ctx) when is_integer(ctx), do: {ref, [counter: ctx], nil}
-
-  defp var_context(meta, kind) do
-    case :lists.keyfind(:counter, 1, meta) do
-      {:counter, counter} -> counter
-      false -> kind
-    end
-  end
 end

lib/elixir/lib/keyword.ex

@@ -20,19 +20,10 @@ defmodule Keyword do
       iex> [{:active, :once}]
       [active: :once]
 
-  The two syntaxes are completely equivalent. If the keyword has foreign
-  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. Keywords are
-  always atoms and quotes should only be used to handle foreign characters.
-  In fact, if you attempt use quotes when not necessary, Elixir will warn.
-
-  Note that when keyword lists are passed as the last argument to a function,
-  if the short-hand syntax is used then the square brackets around the keyword list
-  can be omitted as well. For example, the following:
+  The two syntaxes are completely equivalent. Note that when keyword
+  lists are passed as the last argument to a function, if the short-hand
+  syntax is used then the square brackets around the keyword list can
+  be omitted as well. For example, the following:
 
       String.split("1-0", "-", trim: true, parts: 2)
 
@@ -142,7 +133,7 @@ defmodule Keyword do
 
   ## Examples
 
-      iex> Keyword.new([:a, :b], fn x -> {x, x} end)
+      iex> Keyword.new([:a, :b], fn(x) -> {x, x} end)
       [a: :a, b: :b]
 
   """
@@ -465,23 +456,19 @@ defmodule Keyword do
   """
   @spec delete(t, key, value) :: t
   def delete(keywords, key, value) when is_list(keywords) and is_atom(key) do
-    case :lists.keymember(key, 1, keywords) do
-      true -> delete_key_value(keywords, key, value)
-      _ -> keywords
-    end
+    delete_key_value(keywords, key, value, _deleted? = false)
+  catch
+    :not_deleted -> keywords
   end
 
-  defp delete_key_value([{key, value} | tail], key, value) do
-    delete_key_value(tail, key, value)
-  end
+  defp delete_key_value([{key, value} | rest], key, value, _deleted?),
+    do: delete_key_value(rest, key, value, true)
 
-  defp delete_key_value([{_, _} = pair | tail], key, value) do
-    [pair | delete_key_value(tail, key, value)]
-  end
+  defp delete_key_value([{_, _} = pair | rest], key, value, deleted?),
+    do: [pair | delete_key_value(rest, key, value, deleted?)]
 
-  defp delete_key_value([], _key, _value) do
-    []
-  end
+  defp delete_key_value([], _key, _value, _deleted? = true), do: []
+  defp delete_key_value([], _key, _value, _deleted? = false), do: throw(:not_deleted)
 
   @doc """
   Deletes the entries in the keyword list for a specific `key`.
@@ -503,23 +490,18 @@ defmodule Keyword do
   @spec delete(t, key) :: t
   @compile {:inline, delete: 2}
   def delete(keywords, key) when is_list(keywords) and is_atom(key) do
-    case :lists.keymember(key, 1, keywords) do
-      true -> delete_key(keywords, key)
-      _ -> keywords
-    end
+    delete_key(keywords, key, _deleted? = false)
+  catch
+    :not_deleted -> keywords
   end
 
-  defp delete_key([{key, _} | tail], key) do
-    delete_key(tail, key)
-  end
+  defp delete_key([{key, _} | rest], key, _deleted?), do: delete_key(rest, key, true)
 
-  defp delete_key([{_, _} = pair | tail], key) do
-    [pair | delete_key(tail, key)]
-  end
+  defp delete_key([{_, _} = pair | rest], key, deleted?),
+    do: [pair | delete_key(rest, key, deleted?)]
 
-  defp delete_key([], _key) do
-    []
-  end
+  defp delete_key([], _key, _deleted? = true), do: []
+  defp delete_key([], _key, _deleted? = false), do: throw(:not_deleted)
 
   @doc """
   Deletes the first entry in the keyword list for a specific `key`.
@@ -536,23 +518,14 @@ defmodule Keyword do
   """
   @spec delete_first(t, key) :: t
   def delete_first(keywords, key) when is_list(keywords) and is_atom(key) do
-    case :lists.keymember(key, 1, keywords) do
-      true -> delete_first_key(keywords, key)
-      _ -> keywords
-    end
+    delete_first_key(keywords, key)
+  catch
+    :not_deleted -> keywords
   end
 
-  defp delete_first_key([{key, _} | tail], key) do
-    tail
-  end
-
-  defp delete_first_key([{_, _} = pair | tail], key) do
-    [pair | delete_first_key(tail, key)]
-  end
-
-  defp delete_first_key([], _key) do
-    []
-  end
+  defp delete_first_key([{key, _} | rest], key), do: rest
+  defp delete_first_key([{_, _} = pair | rest], key), do: [pair | delete_first_key(rest, key)]
+  defp delete_first_key([], _key), do: throw(:not_deleted)
 
   @doc """
   Puts the given `value` under `key`.
@@ -625,7 +598,6 @@ defmodule Keyword do
   end
 
   @doc false
-  @deprecated "Use Keyword.fetch/2 + Keyword.put/3 instead"
   def replace(keywords, key, value) when is_list(keywords) and is_atom(key) do
     case :lists.keyfind(key, 1, keywords) do
       {^key, _} -> [{key, value} | delete(keywords, key)]
@@ -648,7 +620,6 @@ defmodule Keyword do
       ** (KeyError) key :b not found in: [a: 1]
 
   """
-  @doc since: "1.5.0"
   @spec replace!(t, key, value) :: t
   def replace!(keywords, key, value) when is_list(keywords) and is_atom(key) do
     case :lists.keyfind(key, 1, keywords) do
@@ -699,11 +670,6 @@ defmodule Keyword do
 
   """
   @spec merge(t, t) :: t
-  def merge(keywords1, keywords2)
-
-  def merge(keywords1, []), do: keywords1
-  def merge([], keywords2), do: keywords2
-
   def merge(keywords1, keywords2) when is_list(keywords1) and is_list(keywords2) do
     if keyword?(keywords2) do
       fun = fn
@@ -1046,7 +1012,7 @@ defmodule Keyword do
 
   @doc false
   # TODO: Remove on 2.0
-  @deprecated "Use Kernel.length/1 instead"
+  # (hard-deprecated in elixir_dispatch)
   def size(keyword) do
     length(keyword)
   end

lib/elixir/lib/list.ex

@@ -2,19 +2,6 @@ defmodule List do
   @moduledoc """
   Functions that work on (linked) lists.
 
-  Many of the functions provided for lists, which implement
-  the `Enumerable` protocol, are found in the `Enum` module.
-
-  Additionally, the following functions and operators for lists are
-  found in `Kernel`:
-
-    * `++/2`
-    * `--/2`
-    * `hd/1`
-    * `tl/1`
-    * `in/2`
-    * `length/1`
-
   Lists in Elixir are specified between square brackets:
 
       iex> [1, "two", 3, :four]
@@ -58,15 +45,17 @@ defmodule List do
   slower as the list grows in size (linear time):
 
       iex> list = [1, 2, 3]
-      iex> [0 | list] # fast
+      iex> [0 | list]   # fast
       [0, 1, 2, 3]
-      iex> list ++ [4] # slow
+      iex> list ++ [4]  # slow
       [1, 2, 3, 4]
 
-  Additonally, getting a list's length and accessing it by index are
-  linear time operations. Negative indexes are also supported but
-  they imply the list will be iterated twice, once to calculate the
-  proper index and another time to perform the operation.
+  The `Kernel` module contains many functions to manipulate lists
+  and that are allowed in guards. For example, `Kernel.hd/1` to
+  retrieve the head, `Kernel.tl/1` to fetch the tail and
+  `Kernel.length/1` for calculating the length. Keep in mind that,
+  similar to appending to a list, calculating the length needs to
+  traverse the whole list.
 
   ## Charlists
 
@@ -96,6 +85,19 @@ defmodule List do
 
   A list can be checked if it is made of printable ascii
   codepoints with `ascii_printable?/2`.
+
+  ## List and Enum modules
+
+  This module aims to provide operations that are specific
+  to lists, like conversion between data types, updates,
+  deletions and key lookups (for lists of tuples). For traversing
+  lists in general, developers should use the functions in the
+  `Enum` module that work across a variety of data types.
+
+  In both `Enum` and `List` modules, any kind of index access
+  on a list is linear. Negative indexes are also supported but
+  they imply the list will be iterated twice, one to calculate
+  the proper index and another to perform the operation.
   """
 
   @compile :inline_list_funcs
@@ -175,10 +177,10 @@ defmodule List do
 
   ## Examples
 
-      iex> List.foldl([5, 5], 10, fn x, acc -> x + acc end)
+      iex> List.foldl([5, 5], 10, fn(x, acc) -> x + acc end)
       20
 
-      iex> List.foldl([1, 2, 3, 4], 0, fn x, acc -> x - acc end)
+      iex> List.foldl([1, 2, 3, 4], 0, fn(x, acc) -> x - acc end)
       2
 
   """
@@ -193,7 +195,7 @@ defmodule List do
 
   ## Examples
 
-      iex> List.foldr([1, 2, 3, 4], 0, fn x, acc -> x - acc end)
+      iex> List.foldr([1, 2, 3, 4], 0, fn(x, acc) -> x - acc end)
       -2
 
   """
@@ -388,10 +390,10 @@ defmodule List do
   end
 
   @doc """
-  Wraps `term` in a list if this is not list.
+  Wraps the argument in a list.
 
-  If `term` is already a list, it returns the list.
-  If `term` is `nil`, it returns an empty list.
+  If the argument is already a list, returns the list.
+  If the argument is `nil`, returns an empty list.
 
   ## Examples
 
@@ -405,11 +407,7 @@ defmodule List do
       []
 
   """
-  @spec wrap(nil) :: []
-  @spec wrap(list) :: list when list: maybe_improper_list()
-  @spec wrap(term) :: nonempty_list(term) when term: any()
-  def wrap(term)
-
+  @spec wrap(list | any) :: list
   def wrap(list) when is_list(list) do
     list
   end
@@ -468,7 +466,6 @@ defmodule List do
       false
 
   """
-  @doc since: "1.6.0"
   def ascii_printable?(list, counter \\ :infinity)
 
   def ascii_printable?(_, 0) do
@@ -650,7 +647,6 @@ defmodule List do
       {3, [1, 2]}
 
   """
-  @doc since: "1.4.0"
   @spec pop_at(list, integer, any) :: {any, list}
   def pop_at(list, index, default \\ nil) when is_integer(index) do
     if index < 0 do
@@ -680,7 +676,6 @@ defmodule List do
       false
 
   """
-  @doc since: "1.5.0"
   @spec starts_with?(list, list) :: boolean
   @spec starts_with?(list, []) :: true
   @spec starts_with?([], nonempty_list) :: false
@@ -867,13 +862,16 @@ defmodule List do
       [eq: [1], del: [4], eq: [2, 3], ins: [4]]
 
   """
-  @doc since: "1.4.0"
-  @spec myers_difference(list, list) :: [{:eq | :ins | :del, list}]
+  @spec myers_difference(list, list) :: [{:eq | :ins | :del, list}] | nil
   def myers_difference(list1, list2) when is_list(list1) and is_list(list2) do
-    path = {0, list1, list2, []}
+    path = {0, 0, list1, list2, []}
     find_script(0, length(list1) + length(list2), [path])
   end
 
+  defp find_script(envelope, max, _paths) when envelope > max do
+    nil
+  end
+
   defp find_script(envelope, max, paths) do
     case each_diagonal(-envelope, envelope, paths, []) do
       {:done, edits} -> compact_reverse(edits, [])
@@ -919,34 +917,34 @@ defmodule List do
   end
 
   defp proceed_path(_diag, _limit, [path1, path2 | rest]) do
-    if elem(path1, 0) > elem(path2, 0) do
+    if elem(path1, 1) > elem(path2, 1) do
       {move_right(path1), [path2 | rest]}
     else
       {move_down(path2), [path2 | rest]}
     end
   end
 
-  defp move_right({y, list1, [elem | rest], edits}) do
-    {y, list1, rest, [{:ins, elem} | edits]}
+  defp move_right({x, y, list1, [elem | rest], edits}) do
+    {x + 1, y, list1, rest, [{:ins, elem} | edits]}
   end
 
-  defp move_right({y, list1, [], edits}) do
-    {y, list1, [], edits}
+  defp move_right({x, y, list1, [], edits}) do
+    {x + 1, y, list1, [], edits}
   end
 
-  defp move_down({y, [elem | rest], list2, edits}) do
-    {y + 1, rest, list2, [{:del, elem} | edits]}
+  defp move_down({x, y, [elem | rest], list2, edits}) do
+    {x, y + 1, rest, list2, [{:del, elem} | edits]}
   end
 
-  defp move_down({y, [], list2, edits}) do
-    {y + 1, [], list2, edits}
+  defp move_down({x, y, [], list2, edits}) do
+    {x, y + 1, [], list2, edits}
   end
 
-  defp follow_snake({y, [elem | rest1], [elem | rest2], edits}) do
-    follow_snake({y + 1, rest1, rest2, [{:eq, elem} | edits]})
+  defp follow_snake({x, y, [elem | rest1], [elem | rest2], edits}) do
+    follow_snake({x + 1, y + 1, rest1, rest2, [{:eq, elem} | edits]})
   end
 
-  defp follow_snake({_y, [], [], edits}) do
+  defp follow_snake({_x, _y, [], [], edits}) do
     {:done, edits}
   end
 

lib/elixir/lib/list/chars.ex

@@ -18,7 +18,7 @@ defprotocol List.Chars do
 
   @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use List.Chars.to_charlist/1 instead"
+  # (hard-deprecated in elixir_dispatch)
   Kernel.def to_char_list(term) do
     __MODULE__.to_charlist(term)
   end

lib/elixir/lib/macro.ex

@@ -127,10 +127,6 @@ defmodule Macro do
     raise ArgumentError, bad_pipe(expr, call_args)
   end
 
-  def pipe(expr, {:<<>>, _, _} = call_args, _integer) do
-    raise ArgumentError, bad_pipe(expr, call_args)
-  end
-
   # {:fn, _, _} is what we get when we pipe into an anonymous function without
   # calling it, e.g., `:foo |> (fn x -> x end)`.
   def pipe(expr, {:fn, _, _}, _integer) do
@@ -201,7 +197,6 @@ defmodule Macro do
       [{:var1, [], __MODULE__}, {:var2, [], __MODULE__}]
 
   """
-  @doc since: "1.5.0"
   def generate_arguments(0, _), do: []
 
   def generate_arguments(amount, context)
@@ -356,7 +351,12 @@ defmodule Macro do
   def decompose_call(_), do: :error
 
   @doc """
-  Recursively escapes a value so it can be inserted into a syntax tree.
+  Recursively escapes a value so it can be inserted
+  into a syntax tree.
+
+  One may pass `unquote: true` to `escape/2`
+  which leaves `unquote/1` statements unescaped, effectively
+  unquoting the contents on escape.
 
   ## Examples
 
@@ -369,57 +369,10 @@ defmodule Macro do
       iex> Macro.escape({:unquote, [], [1]}, unquote: true)
       1
 
-  ## Options
-
-    * `:unquote` - when true, this function leaves `unquote/1` and
-      `unquote_splicing/1` statements unescaped, effectively unquoting
-      the contents on escape. This option is useful only when escaping
-      ASTs which may have quoted fragments in them. Defaults to false.
-
-    * `: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.
-      
-      As an example, `ExUnit` stores the AST of every assertion, so when
-      an assertion fails we can show code snippets to users. Without this
-      option, each time the test module is compiled, we get a different
-      MD5 of the module byte code, 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.
-
-  ## Comparison to `Kernel.quote/2`
-
-  The `escape/2` function is sometimes confused with `Kernel.SpecialForms.quote/2`,
-  because the above examples behave the same with both. The key difference is
-  best illustrated when the value to escape is stored in a variable.
-
-      iex> Macro.escape({:a, :b, :c})
-      {:{}, [], [:a, :b, :c]}
-      iex> quote do: {:a, :b, :c}
-      {:{}, [], [:a, :b, :c]}
-
-      iex> value = {:a, :b, :c}
-      iex> Macro.escape(value)
-      {:{}, [], [:a, :b, :c]}
-
-      iex> quote do: value
-      {:value, [], __MODULE__}
-
-      iex> value = {:a, :b, :c}
-      iex> quote do: unquote(value)
-      {:a, :b, :c}
-
-  `escape/2` is used to escape *values* (either directly passed or variable
-  bound), while `Kernel.SpecialForms.quote/2` produces syntax trees for
-  expressions.
   """
   @spec escape(term, keyword) :: Macro.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
-    elem(:elixir_quote.escape(expr, kind, unquote), 0)
+    elem(:elixir_quote.escape(expr, Keyword.get(opts, :unquote, false)), 0)
   end
 
   @doc """
@@ -463,8 +416,8 @@ defmodule Macro do
   defp find_invalid(bin) when is_binary(bin), do: nil
 
   defp find_invalid(fun) when is_function(fun) do
-    unless Function.info(fun, :env) == {:env, []} and
-             Function.info(fun, :type) == {:type, :external} do
+    unless :erlang.fun_info(fun, :env) == {:env, []} and
+             :erlang.fun_info(fun, :type) == {:type, :external} do
       {:error, fun}
     end
   end
@@ -547,21 +500,13 @@ defmodule Macro do
   end
 
   @doc false
-  @deprecated "Traverse over the arguments using Enum.map/2 instead"
   def unescape_tokens(tokens) do
-    case :elixir_interpolation.unescape_tokens(tokens) do
-      {:ok, unescaped_tokens} -> unescaped_tokens
-      {:error, reason} -> raise ArgumentError, to_string(reason)
-    end
+    :elixir_interpolation.unescape_tokens(tokens)
   end
 
   @doc false
-  @deprecated "Traverse over the arguments using Enum.map/2 instead"
   def unescape_tokens(tokens, map) do
-    case :elixir_interpolation.unescape_tokens(tokens, map) do
-      {:ok, unescaped_tokens} -> unescaped_tokens
-      {:error, reason} -> raise ArgumentError, to_string(reason)
-    end
+    :elixir_interpolation.unescape_tokens(tokens, map)
   end
 
   @doc """
@@ -774,13 +719,7 @@ defmodule Macro do
   end
 
   # All other structures
-  def to_string(other, fun) do
-    fun.(other, inspect_no_limit(other))
-  end
-
-  defp inspect_no_limit(value) do
-    Kernel.inspect(value, limit: :infinity, printable_limit: :infinity)
-  end
+  def to_string(other, fun), do: fun.(other, inspect(other, []))
 
   defp bitpart_to_string({:::, _, [left, right]} = ast, fun) do
     result =
@@ -834,15 +773,15 @@ defmodule Macro do
           "\#{" <> to_string(arg, fun) <> "}"
 
         binary when is_binary(binary) ->
-          binary = inspect_no_limit(binary)
-          binary_part(binary, 1, byte_size(binary) - 2)
+          binary = inspect(binary, [])
+          :binary.part(binary, 1, byte_size(binary) - 2)
       end)
 
     <<?", parts::binary, ?">>
   end
 
   defp module_to_string(atom, _fun) when is_atom(atom) do
-    inspect_no_limit(atom)
+    inspect(atom, [])
   end
 
   defp module_to_string({:&, _, [val]} = expr, fun) when not is_integer(val) do
@@ -900,25 +839,11 @@ defmodule Macro do
     :error
   end
 
-  defp sigil_call({sigil, _, [{:<<>>, _, _} = parts, args]} = ast, fun)
+  defp sigil_call({sigil, _, [{:<<>>, _, _} = bin, args]} = ast, fun)
        when is_atom(sigil) and is_list(args) do
     case Atom.to_string(sigil) do
-      <<"sigil_", name>> when name >= ?A and name <= ?Z ->
-        {:<<>>, _, [binary]} = parts
-
-        formatted =
-          if :binary.last(binary) == ?\n do
-            binary = String.replace(binary, ~s["""], ~s["\\""])
-            <<?~, name, ~s["""\n], binary::binary, ~s["""], sigil_args(args, fun)::binary>>
-          else
-            {left, right} = select_sigil_container(binary)
-            <<?~, name, left, binary::binary, right, sigil_args(args, fun)::binary>>
-          end
-
-        {:ok, fun.(ast, formatted)}
-
-      <<"sigil_", name>> when name >= ?a and name <= ?z ->
-        {:ok, fun.(ast, "~" <> <<name>> <> interpolate(parts, fun) <> sigil_args(args, fun))}
+      <<"sigil_", name>> ->
+        {:ok, fun.(ast, "~" <> <<name>> <> interpolate(bin, fun) <> sigil_args(args, fun))}
 
       _ ->
         :error
@@ -929,18 +854,6 @@ defmodule Macro do
     :error
   end
 
-  defp select_sigil_container(binary) do
-    cond do
-      :binary.match(binary, ["\""]) == :nomatch -> {?", ?"}
-      :binary.match(binary, ["\'"]) == :nomatch -> {?', ?'}
-      :binary.match(binary, ["(", ")"]) == :nomatch -> {?(, ?)}
-      :binary.match(binary, ["[", "]"]) == :nomatch -> {?[, ?]}
-      :binary.match(binary, ["{", "}"]) == :nomatch -> {?{, ?}}
-      :binary.match(binary, ["<", ">"]) == :nomatch -> {?<, ?>}
-      true -> {?/, ?/}
-    end
-  end
-
   defp sigil_args([], _fun), do: ""
   defp sigil_args(args, fun), do: fun.(args, List.to_string(args))
 
@@ -1039,9 +952,8 @@ defmodule Macro do
   end
 
   defp map_list_to_string(list, fun) do
-    Enum.map_join(list, ", ", fn
-      {key, value} -> to_string(key, fun) <> " => " <> to_string(value, fun)
-      other -> to_string(other, fun)
+    Enum.map_join(list, ", ", fn {key, value} ->
+      to_string(key, fun) <> " => " <> to_string(value, fun)
     end)
   end
 
@@ -1107,7 +1019,7 @@ defmodule Macro do
 
     * Macros (local or remote)
     * Aliases are expanded (if possible) and return atoms
-    * Compilation environment macros (`__CALLER__/0`, `__DIR__/0`, `__ENV__/0` and `__MODULE__/0`)
+    * Compilation environment macros (`__ENV__/0`, `__MODULE__/0` and `__DIR__/0`)
     * Module attributes reader (`@foo`)
 
   If the expression cannot be expanded, it returns the expression
@@ -1142,7 +1054,7 @@ defmodule Macro do
       end
 
   The compilation will fail because `My.Module` when quoted
-  is not an atom, but a syntax tree as follows:
+  is not an atom, but a syntax tree as follow:
 
       {:__aliases__, [], [:My, :Module]}
 
@@ -1222,7 +1134,7 @@ defmodule Macro do
   # Expand possible macro import invocation
   defp do_expand_once({atom, meta, context} = original, env)
        when is_atom(atom) and is_list(meta) and is_atom(context) do
-    if Macro.Env.has_var?(env, {atom, Keyword.get(meta, :counter, context)}) do
+    if :lists.member({atom, Keyword.get(meta, :counter, context)}, env.vars) do
       {original, false}
     else
       case do_expand_once({atom, meta, []}, env) do
@@ -1236,7 +1148,7 @@ defmodule Macro do
        when is_atom(atom) and is_list(args) and is_list(meta) do
     arity = length(args)
 
-    if special_form?(atom, arity) do
+    if :elixir_import.special_form(atom, arity) do
       {original, false}
     else
       module = env.module
@@ -1255,12 +1167,6 @@ defmodule Macro do
           next = :erlang.unique_integer()
           {:elixir_quote.linify_with_context_counter(0, {receiver, next}, quoted), true}
 
-        {:ok, Kernel, op, [arg]} when op in [:+, :-] ->
-          case expand_once(arg, env) do
-            integer when is_integer(integer) -> {apply(Kernel, op, [integer]), true}
-            _ -> {original, false}
-          end
-
         {:ok, _receiver, _name, _args} ->
           {original, false}
 
@@ -1295,39 +1201,6 @@ defmodule Macro do
   # Anything else is just returned
   defp do_expand_once(other, _env), do: {other, false}
 
-  @doc """
-  Returns `true` if the given name and arity is a special form.
-  """
-  @doc since: "1.7.0"
-  @spec special_form?(name :: atom(), arity()) :: boolean()
-  def special_form?(name, arity) when is_atom(name) and is_integer(arity) do
-    :elixir_import.special_form(name, arity)
-  end
-
-  @doc """
-  Returns `true` if the given name and arity is an operator.
-  """
-  @doc since: "1.7.0"
-  @spec operator?(name :: atom(), arity()) :: boolean()
-  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
-
-  @doc """
-  Returns `true` if the given quoted expression is an AST literal.
-  """
-  @doc since: "1.7.0"
-  @spec quoted_literal?(literal) :: true
-  @spec quoted_literal?(expr) :: false
-  def quoted_literal?(term)
-
-  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)
-  end
-
   @doc """
   Receives an AST node and expands it until it can no longer
   be expanded.
@@ -1360,25 +1233,25 @@ defmodule Macro do
 
   ## Examples
 
-      iex> Macro.underscore("FooBar")
+      iex> Macro.underscore "FooBar"
       "foo_bar"
 
-      iex> Macro.underscore("Foo.Bar")
+      iex> Macro.underscore "Foo.Bar"
       "foo/bar"
 
-      iex> Macro.underscore(Foo.Bar)
+      iex> Macro.underscore Foo.Bar
       "foo/bar"
 
   In general, `underscore` can be thought of as the reverse of
   `camelize`, however, in some cases formatting may be lost:
 
-      iex> Macro.underscore("SAPExample")
+      iex> Macro.underscore "SAPExample"
       "sap_example"
 
-      iex> Macro.camelize("sap_example")
+      iex> Macro.camelize "sap_example"
       "SapExample"
 
-      iex> Macro.camelize("hello_10")
+      iex> Macro.camelize "hello_10"
       "Hello10"
 
   """
@@ -1427,15 +1300,15 @@ defmodule Macro do
 
   ## Examples
 
-      iex> Macro.camelize("foo_bar")
+      iex> Macro.camelize "foo_bar"
       "FooBar"
 
-  If uppercase characters are present, they are not modified in any way
+  If uppercase characters are present, they are not modified in anyway
   as a mechanism to preserve acronyms:
 
-      iex> Macro.camelize("API.V1")
+      iex> Macro.camelize "API.V1"
       "API.V1"
-      iex> Macro.camelize("API_SPEC")
+      iex> Macro.camelize "API_SPEC"
       "API_SPEC"
 
   """

lib/elixir/lib/macro/env.ex

@@ -38,19 +38,18 @@ defmodule Macro.Env do
     * `context_modules` - a list of modules defined in the current context
     * `lexical_tracker` - PID of the lexical tracker which is responsible for
       keeping user info
-
-  The following fields pertain to variable handling and must not be accessed or
-  relied on. To get a list of all variables, see `vars/1`:
-
-    * `current_vars`
-    * `unused_vars`
-    * `prematch_vars`
-    * `contextual_vars`
-
-  The following fields are deprecated and must not be accessed or relied on:
-
     * `vars` - a list keeping all defined variables as `{var, context}`
 
+  The following fields are private and must not be accessed or relied on:
+
+    * `export_vars` - a list keeping all variables to be exported in a
+      construct (may be `nil`)
+    * `match_vars` - controls how "new" variables are handled. Inside a
+      match it is a list with all variables in a match. Outside of a match
+      is either `:warn` or `:apply`
+    * `prematch_vars` - a list of variables defined before a match (is
+      `nil` when not inside a match)
+
   """
 
   @type name_arity :: {atom, arity}
@@ -63,16 +62,13 @@ defmodule Macro.Env do
   @type functions :: [{module, [name_arity]}]
   @type macros :: [{module, [name_arity]}]
   @type context_modules :: [module]
+  @type vars :: [{atom, atom | non_neg_integer}]
   @type lexical_tracker :: pid | nil
-  @type var :: {atom, atom | non_neg_integer}
+  @type local :: atom | nil
 
-  @typep vars :: [var]
-  @typep var_type :: :term
-  @typep var_version :: non_neg_integer
-  @typep unused_vars :: %{{var, var_version} => non_neg_integer | false}
-  @typep current_vars :: %{var => {var_version, var_type}}
-  @typep prematch_vars :: current_vars | :warn | :raise | :pin | :apply
-  @typep contextual_vars :: [atom]
+  @opaque export_vars :: vars | nil
+  @opaque match_vars :: vars | :warn | :apply
+  @opaque prematch_vars :: vars | nil
 
   @type t :: %{
           __struct__: __MODULE__,
@@ -88,14 +84,12 @@ defmodule Macro.Env do
           macro_aliases: aliases,
           context_modules: context_modules,
           vars: vars,
-          unused_vars: unused_vars,
-          current_vars: current_vars,
+          export_vars: export_vars,
+          match_vars: match_vars,
           prematch_vars: prematch_vars,
-          lexical_tracker: lexical_tracker,
-          contextual_vars: contextual_vars
+          lexical_tracker: lexical_tracker
         }
 
-  # TODO: Remove :vars field on v2.0
   def __struct__ do
     %{
       __struct__: __MODULE__,
@@ -111,11 +105,10 @@ defmodule Macro.Env do
       macro_aliases: [],
       context_modules: [],
       vars: [],
-      unused_vars: %{},
-      current_vars: %{},
-      prematch_vars: :warn,
       lexical_tracker: nil,
-      contextual_vars: []
+      export_vars: nil,
+      match_vars: :warn,
+      prematch_vars: nil
     }
   end
 
@@ -123,33 +116,6 @@ defmodule Macro.Env do
     Enum.reduce(kv, __struct__(), fn {k, v}, acc -> :maps.update(k, v, acc) end)
   end
 
-  @doc """
-  Returns a list of variables in the current environment.
-
-  Each variable is identified by a tuple of two elements,
-  where the first element is the variable name as an atom
-  and the second element is its context, which may be an
-  atom or an integer.
-  """
-  @doc since: "1.7.0"
-  @spec vars(t) :: [var]
-  def vars(env)
-
-  def vars(%{__struct__: Macro.Env, current_vars: current_vars}) do
-    Map.keys(current_vars)
-  end
-
-  @doc """
-  Checks if a variable belongs to the environment.
-  """
-  @doc since: "1.7.0"
-  @spec has_var?(t, var) :: boolean()
-  def has_var?(env, var)
-
-  def has_var?(%{__struct__: Macro.Env, current_vars: current_vars}, var) do
-    Map.has_key?(current_vars, var)
-  end
-
   @doc """
   Returns a keyword list containing the file and line
   information as keys.
@@ -169,8 +135,8 @@ defmodule Macro.Env do
     env
   end
 
-  def to_match(%{__struct__: Macro.Env, current_vars: vars} = env) do
-    %{env | context: :match, prematch_vars: vars}
+  def to_match(%{__struct__: Macro.Env, prematch_vars: nil, vars: vars} = env) do
+    %{env | context: :match, match_vars: [], prematch_vars: vars}
   end
 
   @doc """

lib/elixir/lib/map.ex

@@ -2,12 +2,6 @@ defmodule Map do
   @moduledoc """
   A set of functions for working with maps.
 
-  Many functions for maps, which implement the `Enumerable` protocol,
-  are found in the `Enum` module. Additionally, the following functions
-  for maps are found in `Kernel`:
-
-    * `map_size/1`
-
   Maps are the "go to" key-value data structure in Elixir. Maps can be created
   with the `%{}` syntax, and key-value pairs can be expressed as `key => value`:
 
@@ -21,7 +15,7 @@ defmodule Map do
 
   Maps do not impose any restriction on the key type: anything can be a key in a
   map. As a key-value structure, maps do not allow duplicated keys. Keys are
-  compared using the exact-equality operator (`===/2`). If colliding keys are defined
+  compared using the exact-equality operator (`===`). If colliding keys are defined
   in a map literal, the last one prevails.
 
   When the key in a key-value pair is an atom, the `key: value` shorthand syntax
@@ -32,8 +26,8 @@ defmodule Map do
       %{:a => 1, :b => 2, "hello" => "world"}
 
   Keys in maps can be accessed through some of the functions in this module
-  (such as `Map.get/3` or `Map.fetch/2`) or through the `map[]` syntax provided
-  by the `Access` module:
+  (such as `Map.get/3` or `Map.fetch/2`) or through the `[]` syntax provided by
+  the `Access` module:
 
       iex> map = %{a: 1, b: 2}
       iex> Map.fetch(map, :a)
@@ -43,9 +37,10 @@ defmodule Map do
       iex> map["non_existing_key"]
       nil
 
-  For accessing atom keys, one may also `map.key`. Note that while `map[key]` will
-  return `nil` if `map` doesn't contain `key`, `map.key` will raise if `map` doesn't
-  contain the key `:key`.
+  The alternative access syntax `map.key` is provided alongside `[]` when the
+  map has a `:key` key; note that while `map[key]` will return `nil` if `map`
+  doesn't contain `key`, `map.key` will raise if `map` doesn't contain
+  the key `:key`.
 
       iex> map = %{foo: "bar", baz: "bong"}
       iex> map.foo
@@ -53,13 +48,7 @@ defmodule Map do
       iex> map.non_existing_key
       ** (KeyError) key :non_existing_key not found in: %{baz: "bong", foo: "bar"}
 
-  The two syntaxes for accessing keys reveal the dual nature of maps. The `map[key]`
-  syntax is used for dynamically created maps that may have any key, of any type.
-  `map.key` is used with maps that hold a predetermined set of atoms keys, which are
-  expected to always be present. Structs, defined via `defstruct/1`, are one example
-  of such "static maps", where the keys can also be checked during compile time.
-
-  Maps can be pattern matched on. When a map is on the left-hand side of a
+  Maps can be pattern matched on; when a map is on the left-hand side of a
   pattern match, it will match if the map on the right-hand side contains the
   keys on the left-hand side and their values match the ones on the left-hand
   side. This means that an empty map matches every map.
@@ -91,6 +80,16 @@ defmodule Map do
       iex> %{map | three: 3}
       ** (KeyError) key :three not found
 
+  ## Modules to work with maps
+
+  This module aims to provide functions that perform operations specific to maps
+  (like accessing keys, updating values, and so on). For traversing maps as
+  collections, developers should use the `Enum` module that works across a
+  variety of data types.
+
+  The `Kernel` module also provides a few functions to work with maps: for
+  example, `Kernel.map_size/1` to know the number of key-value pairs in a map or
+  `Kernel.is_map/1` to know if a term is a map.
   """
 
   @type key :: any
@@ -100,8 +99,6 @@ defmodule Map do
   @doc """
   Returns all keys from `map`.
 
-  Inlined by the compiler.
-
   ## Examples
 
       iex> Map.keys(%{a: 1, b: 2})
@@ -114,8 +111,6 @@ defmodule Map do
   @doc """
   Returns all values from `map`.
 
-  Inlined by the compiler.
-
   ## Examples
 
       iex> Map.values(%{a: 1, b: 2})
@@ -131,8 +126,6 @@ defmodule Map do
   Each key-value pair in the map is converted to a two-element tuple `{key,
   value}` in the resulting list.
 
-  Inlined by the compiler.
-
   ## Examples
 
       iex> Map.to_list(%{a: 1})
@@ -149,7 +142,7 @@ defmodule Map do
 
   ## Examples
 
-      iex> Map.new()
+      iex> Map.new
       %{}
 
   """
@@ -213,8 +206,6 @@ defmodule Map do
   @doc """
   Returns whether the given `key` exists in the given `map`.
 
-  Inlined by the compiler.
-
   ## Examples
 
       iex> Map.has_key?(%{a: 1}, :a)
@@ -222,6 +213,7 @@ defmodule Map do
       iex> Map.has_key?(%{a: 1}, :b)
       false
 
+  Inlined by the compiler.
   """
   @spec has_key?(map, key) :: boolean
   def has_key?(map, key), do: :maps.is_key(key, map)
@@ -232,8 +224,6 @@ defmodule Map do
   If `map` contains the given `key` with value `value`, then `{:ok, value}` is
   returned. If `map` doesn't contain `key`, `:error` is returned.
 
-  Inlined by the compiler.
-
   ## Examples
 
       iex> Map.fetch(%{a: 1}, :a)
@@ -241,6 +231,7 @@ defmodule Map do
       iex> Map.fetch(%{a: 1}, :b)
       :error
 
+  Inlined by the compiler.
   """
   @spec fetch(map, key) :: {:ok, value} | :error
   def fetch(map, key), do: :maps.find(key, map)
@@ -252,8 +243,6 @@ defmodule Map do
   If `map` contains the given `key`, the corresponding value is returned. If
   `map` doesn't contain `key`, a `KeyError` exception is raised.
 
-  Inlined by the compiler.
-
   ## Examples
 
       iex> Map.fetch!(%{a: 1}, :a)
@@ -294,7 +283,6 @@ defmodule Map do
   end
 
   @doc false
-  @deprecated "Use Map.fetch/2 + Map.put/3 instead"
   def replace(map, key, value) do
     case map do
       %{^key => _value} ->
@@ -314,8 +302,6 @@ defmodule Map do
 
   If `key` is not present in `map`, a `KeyError` exception is raised.
 
-  Inlined by the compiler.
-
   ## Examples
 
       iex> Map.replace!(%{a: 1, b: 2}, :a, 3)
@@ -324,8 +310,8 @@ defmodule Map do
       iex> Map.replace!(%{a: 1}, :b, 2)
       ** (KeyError) key :b not found in: %{a: 1}
 
+  Inlined by the compiler.
   """
-  @doc since: "1.5.0"
   @spec replace!(map, key, value) :: map
   def replace!(map, key, value) do
     :maps.update(key, value, map)
@@ -477,8 +463,6 @@ defmodule Map do
   @doc """
   Puts the given `value` under `key` in `map`.
 
-  Inlined by the compiler.
-
   ## Examples
 
       iex> Map.put(%{a: 1}, :b, 2)
@@ -486,6 +470,7 @@ defmodule Map do
       iex> Map.put(%{a: 1, b: 2}, :a, 3)
       %{a: 3, b: 2}
 
+  Inlined by the compiler.
   """
   @spec put(map, key, value) :: map
   def put(map, key, value) do
@@ -497,8 +482,6 @@ defmodule Map do
 
   If the `key` does not exist, returns `map` unchanged.
 
-  Inlined by the compiler.
-
   ## Examples
 
       iex> Map.delete(%{a: 1, b: 2}, :a)
@@ -506,6 +489,7 @@ defmodule Map do
       iex> Map.delete(%{b: 2}, :a)
       %{b: 2}
 
+  Inlined by the compiler.
   """
   @spec delete(map, key) :: map
   def delete(map, key), do: :maps.remove(key, map)
@@ -521,8 +505,6 @@ defmodule Map do
   side into the struct, even if the key is not part of the struct. Instead,
   use `Kernel.struct/2`.
 
-  Inlined by the compiler.
-
   ## Examples
 
       iex> Map.merge(%{a: 1, b: 2}, %{a: 3, d: 4})
@@ -760,7 +742,7 @@ defmodule Map do
   (the retrieved value, which can be operated on before being returned) and the
   new value to be stored under `key` in the resulting new map. `fun` may also
   return `:pop`, which means the current value shall be removed from `map` and
-  returned (making this function behave like `Map.pop(map, key)`).
+  returned (making this function behave like `Map.pop(map, key)`.
 
   The returned value is a tuple with the "get" value returned by
   `fun` and a new map with the updated value under `key`.
@@ -893,7 +875,7 @@ defmodule Map do
 
   @doc false
   # TODO: Remove on 2.0
-  @deprecated "Use Kernel.map_size/1 instead"
+  # (hard-deprecated in elixir_dispatch)
   def size(map) do
     map_size(map)
   end

lib/elixir/lib/map_set.ex

@@ -5,7 +5,7 @@ defmodule MapSet do
   `MapSet` is the "go to" set data structure in Elixir. A set can be constructed
   using `MapSet.new/0`:
 
-      iex> MapSet.new()
+      iex> MapSet.new
       #MapSet<[]>
 
   A set can contain any kind of elements, and elements in a set don't have to be
@@ -13,7 +13,7 @@ defmodule MapSet do
   inserting an element in a set where it's already present, the insertion is
   simply a no-op.
 
-      iex> map_set = MapSet.new()
+      iex> map_set = MapSet.new
       iex> MapSet.put(map_set, "foo")
       #MapSet<["foo"]>
       iex> map_set |> MapSet.put("foo") |> MapSet.put("foo")
@@ -49,7 +49,7 @@ defmodule MapSet do
 
   ## Examples
 
-      iex> MapSet.new()
+      iex> MapSet.new
       #MapSet<[]>
 
   """
@@ -210,7 +210,7 @@ defmodule MapSet do
   @doc """
   Checks if two sets are equal.
 
-  The comparison between elements must be done using `===/2`.
+  The comparison between elements must be done using `===`.
 
   ## Examples
 

lib/elixir/lib/module/locals_tracker.ex

@@ -5,22 +5,47 @@
 # ## Implementation
 #
 # The implementation uses ets to track all dependencies
-# resembling a graph. The keys and what they point to are:
+# resembling a graph. The graph has the following vertices:
 #
-#   * `:reattach` points to `{name, arity}`
-#   * `{:local, {name, arity}}` points to `{name, arity}`
-#   * `{:import, {name, arity}}` points to `Module`
+#   * `Module` - a module that was invoked via an import
+#   * `{name, arity}` - a local function/arity pair
+#   * `{:import, name, arity}` - an invoked function/arity import
+#   * `:reattach` - points to reattached functions
+#
+# Those vertices can associate to other vertices as described
+# below:
+#
+#   * `{name, arity}`
+#     * in neighbours: `:reattach`, `{name, arity}`
+#     * out neighbours: `{:import, name, arity}`
+#
+#   * `{:import, name, arity}`
+#     * in neighbours: `{name, arity}`
+#     * out neighbours: `Module`
 #
-# This is built on top of the internal module tables.
 defmodule Module.LocalsTracker do
   @moduledoc false
 
+  @doc """
+  Starts the tracker table.
+  """
+  def init do
+    :ets.new(__MODULE__, [:bag, :public])
+  end
+
+  @doc """
+  Deletes the tracker table.
+  """
+  def delete(d) do
+    :ets.delete(d)
+  end
+
   @doc """
   Adds and tracks defaults for a definition into the tracker.
   """
-  def add_defaults({_set, bag}, _kind, {name, arity} = pair, defaults) do
+  def add_defaults(d, _kind, {name, arity}, defaults) do
     for i <- :lists.seq(arity - defaults, arity - 1) do
-      put_edge(bag, {:local, {name, i}}, pair)
+      put_edge(d, {name, i}, {name, arity})
     end
 
     :ok
@@ -29,53 +54,58 @@ defmodule Module.LocalsTracker do
   @doc """
   Adds a local dispatch from-to the given target.
   """
-  def add_local({_set, bag}, from, to) when is_tuple(from) and is_tuple(to) do
-    if from != to do
-      put_edge(bag, {:local, from}, to)
-    end
-
-    :ok
+  def add_local(d, from, to) when is_tuple(from) and is_tuple(to) do
+    put_edge(d, from, to)
   end
 
   @doc """
   Adds an import dispatch to the given target.
   """
-  def add_import({set, _bag}, function, module, imported)
+  def add_import(d, function, module, {name, arity})
       when is_tuple(function) and is_atom(module) do
-    put_edge(set, {:import, imported}, module)
+    tuple = {:import, name, arity}
+    put_edge(d, tuple, module)
+    put_edge(d, function, tuple)
     :ok
   end
 
   @doc """
   Yanks a local node. Returns its in and out vertices in a tuple.
   """
-  def yank({_set, bag}, local) do
-    :lists.usort(take_out_neighbours(bag, {:local, local}))
+  def yank(d, local) do
+    {[], take_out_neighbours(d, local)}
   end
 
   @doc """
   Reattach a previously yanked node.
   """
-  def reattach({_set, bag}, tuple, _kind, function, out_neigh) do
+  def reattach(d, tuple, _kind, function, {in_neigh, out_neigh}) do
+    # Reattach the old function
+    for from <- in_neigh do
+      put_edge(d, from, function)
+    end
+
     for to <- out_neigh do
-      put_edge(bag, {:local, function}, to)
+      put_edge(d, function, to)
     end
 
     # Make a call from the old function to the new one
     if function != tuple do
-      put_edge(bag, {:local, function}, tuple)
+      put_edge(d, function, tuple)
     end
 
     # Finally marked the new one as reattached
-    put_edge(bag, :reattach, tuple)
+    put_edge(d, :reattach, tuple)
     :ok
   end
 
   # Collecting all conflicting imports with the given functions
   @doc false
-  def collect_imports_conflicts({set, _bag}, all_defined) do
-    for {pair, _, meta, _} <- all_defined, n = out_neighbour(set, {:import, pair}) do
-      {meta, {n, pair}}
+  def collect_imports_conflicts(d, all_defined) do
+    for {{name, arity}, _, meta, _} <- all_defined,
+        n = out_neighbours(d, {:import, name, arity}),
+        n != [] do
+      {meta, {n, name, arity}}
     end
   end
 
@@ -84,17 +114,17 @@ defmodule Module.LocalsTracker do
   given, also accounting the expected number of default
   clauses a private function have.
   """
-  def collect_unused_locals({_set, bag}, all_defined, private) do
+  def collect_unused_locals(d, all_defined, private) do
     reachable =
       Enum.reduce(all_defined, %{}, fn {pair, kind, _, _}, acc ->
         if kind in [:def, :defmacro] do
-          reachable_from(bag, pair, acc)
+          reachable_from(d, pair, acc)
         else
           acc
         end
       end)
 
-    reattached = :lists.usort(out_neighbours(bag, :reattach))
+    reattached = out_neighbours(d, :reattach)
     {unreachable(reachable, reattached, private), collect_warnings(reachable, private)}
   end
 
@@ -161,20 +191,24 @@ defmodule Module.LocalsTracker do
   A private function is only reachable if it has
   a public function that it invokes directly.
   """
-  def reachable_from({_, bag}, local) do
-    bag
-    |> reachable_from(local, %{})
+  def reachable_from(d, vertex) do
+    d
+    |> reachable_from(vertex, %{})
     |> Map.keys()
   end
 
-  defp reachable_from(bag, local, vertices) do
-    vertices = Map.put(vertices, local, true)
+  defp reachable_from(d, vertex, vertices) do
+    vertices = Map.put(vertices, vertex, true)
 
-    Enum.reduce(out_neighbours(bag, {:local, local}), vertices, fn {_, _} = local, acc ->
-      case acc do
-        %{^local => true} -> acc
-        _ -> reachable_from(bag, local, acc)
-      end
+    Enum.reduce(out_neighbours(d, vertex), vertices, fn
+      {_, _} = local, acc ->
+        case acc do
+          %{^local => true} -> acc
+          _ -> reachable_from(d, local, acc)
+        end
+
+      _, acc ->
+        acc
     end)
   end
 
@@ -184,14 +218,6 @@ defmodule Module.LocalsTracker do
     :ets.insert(d, {from, to})
   end
 
-  defp out_neighbour(d, from) do
-    try do
-      :ets.lookup_element(d, from, 2)
-    catch
-      :error, :badarg -> nil
-    end
-  end
-
   defp out_neighbours(d, from) do
     try do
       :ets.lookup_element(d, from, 2)

lib/elixir/lib/node.ex

@@ -59,8 +59,6 @@ defmodule Node do
   the local node.
 
   Same as `list(:visible)`.
-
-  Inlined by the compiler.
   """
   @spec list :: [t]
   def list do
@@ -74,8 +72,6 @@ defmodule Node do
   satisfying the disjunction(s) of the list elements.
 
   For more information, see `:erlang.nodes/1`.
-
-  Inlined by the compiler.
   """
   @type state :: :visible | :hidden | :connected | :this | :known
   @spec list(state | [state]) :: [t]

lib/elixir/lib/option_parser.ex

@@ -34,14 +34,14 @@ defmodule OptionParser do
 
   When parsing, it is common to list switches and their expected types:
 
-      iex> OptionParser.parse(["--debug"], strict: [debug: :boolean])
+      iex> OptionParser.parse(["--debug"], switches: [debug: :boolean])
       {[debug: true], [], []}
 
-      iex> OptionParser.parse(["--source", "lib"], strict: [source: :string])
+      iex> OptionParser.parse(["--source", "lib"], switches: [source: :string])
       {[source: "lib"], [], []}
 
       iex> OptionParser.parse(["--source-path", "lib", "test/enum_test.exs", "--verbose"],
-      ...>                    strict: [source_path: :string, verbose: :boolean])
+      ...>                    switches: [source_path: :string, verbose: :boolean])
       {[source_path: "lib", verbose: true], ["test/enum_test.exs"], []}
 
   We will explore the valid switches and operation modes of option parser below.
@@ -51,24 +51,24 @@ defmodule OptionParser do
   The following options are supported:
 
     * `:switches` or `:strict` - see the "Switch definitions" section below
-    * `:allow_nonexistent_atoms` - see the "Parsing unknown switches" section below
+    * `:allow_nonexistent_atoms` - see the "Parsing dynamic switches" section below
     * `:aliases` - see the "Aliases" section below
 
   ## Switch definitions
 
   Switches can be specified via one of two options:
 
-    * `:strict` - defines strict switches. Any switch in `argv` that is not
-      specified in the list is returned in the invalid options list.
     * `:switches` - defines some switches and their types. This function
       still attempts to parse switches that are not in this list.
+    * `:strict` - defines strict switches. Any switch in `argv` that is not
+      specified in the list is returned in the invalid options list.
 
   Both these options accept a keyword list of `{name, type}` tuples where `name`
   is an atom defining the name of the switch and `type` is an atom that
   specifies the type for the value of this switch (see the "Types" section below
   for the possible types and more information about type casting).
 
-  Note that you should only supply the `:switches` or the `:strict` option.
+  Note that you should only supply the `:switches` or the`:strict` option.
   If you supply both, an `ArgumentError` exception will be raised.
 
   ### Types
@@ -110,52 +110,50 @@ defmodule OptionParser do
       iex> OptionParser.parse(["--no-op", "path/to/file"], switches: [op: :boolean])
       {[op: false], ["path/to/file"], []}
 
-  ### Parsing unknown switches
+  ### Parsing dynamic switches
 
-  When the `:switches` option is given, `OptionParser` will attempt to parse
-  unknown switches:
+  `OptionParser` also includes a dynamic mode where it will attempt to parse
+  switches dynamically. Such can be done by not specifying the `:switches` or
+  `:strict` option.
 
-      iex> OptionParser.parse(["--debug"], switches: [key: :string])
+      iex> OptionParser.parse(["--debug"])
       {[debug: true], [], []}
 
-  Even though we haven't specified `--debug` in the list of switches, it is part
-  of the returned options. This would also work:
-
-      iex> OptionParser.parse(["--debug", "value"], switches: [key: :string])
-      {[debug: "value"], [], []}
-
   Switches followed by a value will be assigned the value, as a string. Switches
-  without an argument will be set automatically to `true`. Since we cannot assert
-  the type of the switch value, it is preferred to use the `:strict` option that
-  accepts only known switches and always verify their types.
+  without an argument, like `--debug` in the examples above, will automatically be
+  set to `true`.
 
-  If you do want to parse unknown switches, remember that Elixir converts switches
-  to atoms. Since atoms are not garbage-collected, OptionParser will only parse
-  switches that translate to atoms used by the runtime to avoid leaking atoms.
-  For instance, the code below will discard the `--option-parser-example` switch
-  because the `:option_parser_example` atom is never used anywhere:
+  Since Elixir converts switches to atoms, the dynamic mode will only parse
+  switches that translate to atoms used by the runtime. Therefore, the code below
+  likely won't parse the given option since the `:option_parser_example` atom is
+  never used anywhere:
 
-      OptionParser.parse(["--option-parser-example"], switches: [debug: :boolean])
+      OptionParser.parse(["--option-parser-example"])
       # The :option_parser_example atom is not used anywhere below
 
-  However, the code below would work as long as `:option_parser_example` atom is
-  used at some point later (or earlier) **in the same module**:
+  However, the code below does since the `:option_parser_example` atom is used
+  at some point later (or earlier) on:
 
-      {opts, _, _} = OptionParser.parse(["--option-parser-example"], switches: [debug: :boolean])
+      {opts, _, _} = OptionParser.parse(["--option-parser-example"])
       opts[:option_parser_example]
 
-  In other words, Elixir will do the correct thing and only parse options that are
-  used by the runtime, ignoring all others. If you would like to parse all switches,
-  regardless if they exist or not, you can force creation of atoms by passing
-  `allow_nonexistent_atoms: true` as option. Use this option with care. It is only
-  useful when you are building command-line applications that receive
-  dynamically-named arguments and must be avoided in long-running systems.
+  In other words, when using dynamic mode, Elixir will do the correct thing and
+  only parse options that are used by the runtime, ignoring all others. If you
+  would like to parse all switches, regardless if they exist or not, you can
+  force creation of atoms by passing `allow_nonexistent_atoms: true` as option.
+  Such option is useful when you are building command-line applications that
+  receive dynamically-named arguments but must be used with care on long-running
+  systems.
+
+  Switches followed by a value will be assigned the value, as a string.
+  Switches without an argument, like `--debug` in the examples above, will
+  automatically be set to `true`.
 
   ## Aliases
 
   A set of aliases can be specified in the `:aliases` option:
 
-      iex> OptionParser.parse(["-d"], aliases: [d: :debug], strict: [debug: :boolean])
+      iex> OptionParser.parse(["-d"], aliases: [d: :debug])
       {[debug: true], [], []}
 
   ## Examples
@@ -281,7 +279,6 @@ defmodule OptionParser do
       ** (OptionParser.ParseError) 2 errors found!
       --verbose : Missing argument of type integer
       --source : Expected type integer, got "lib"
-
   """
   @spec parse_head!(argv, options) :: {parsed, argv} | no_return
   def parse_head!(argv, opts \\ []) when is_list(argv) and is_list(opts) do
@@ -308,8 +305,8 @@ defmodule OptionParser do
         do_parse(rest, config, opts, args, [{option, value} | invalid], all?)
 
       {:undefined, option, _value, rest} ->
-        invalid = if config.strict?, do: [{option, nil} | invalid], else: invalid
-        do_parse(rest, config, opts, args, invalid, all?)
+        # the option does not exist (for strict cases)
+        do_parse(rest, config, opts, args, [{option, nil} | invalid], all?)
 
       {:error, ["--" | rest]} ->
         {Enum.reverse(opts), Enum.reverse(args, rest), Enum.reverse(invalid)}
@@ -338,7 +335,7 @@ defmodule OptionParser do
       (returned when the value cannot be parsed according to the switch type)
 
     * `{:undefined, key, value, rest}` - the option `key` is undefined
-      (returned in strict mode when the switch is unknown or on nonexistent atoms)
+      (returned in strict mode when the switch is unknown)
 
     * `{:error, rest}` - there are no switches at the head of the given `argv`
 
@@ -372,21 +369,15 @@ defmodule OptionParser do
   # Handles --foo or --foo=bar
   defp next_with_config(["--" <> option | rest], config) do
     {option, value} = split_option(option)
-
-    if String.contains?(option, ["_"]) do
-      {:undefined, "--" <> option, value, rest}
-    else
-      tagged = tag_option(option, config)
-      next_tagged(tagged, value, "--" <> option, rest, config)
-    end
+    tagged = tag_option(option, config)
+    next_tagged(tagged, value, "--" <> option, rest, config)
   end
 
   # Handles -a, -abc, -abc=something
   defp next_with_config(["-" <> option | rest] = argv, config) do
-    %{allow_nonexistent_atoms?: allow_nonexistent_atoms?} = config
+    %{aliases: aliases, allow_nonexistent_atoms?: allow_nonexistent_atoms?} = config
     {option, value} = split_option(option)
     original = "-" <> option
-    letters = String.graphemes(option)
 
     cond do
       is_nil(value) and negative_number?(original) ->
@@ -395,22 +386,21 @@ defmodule OptionParser do
       String.contains?(option, ["-", "_"]) ->
         {:undefined, original, value, rest}
 
-      tl(letters) == [] ->
-        # We have a regular one-letter alias here
-        tagged = tag_oneletter_alias(option, config)
-        next_tagged(tagged, value, original, rest, config)
-
-      true ->
+      String.length(option) > 1 ->
         key = get_option_key(option, allow_nonexistent_atoms?)
-        option_key = config.aliases[key]
+        option_key = aliases[key]
 
         if key && option_key do
-          # TODO: Remove this in Elixir v2.0
           IO.warn("multi-letter aliases are deprecated, got: #{inspect(key)}")
           next_tagged({:default, option_key}, value, original, rest, config)
         else
-          next_with_config(expand_multiletter_alias(letters, value) ++ rest, config)
+          next_with_config(expand_multiletter_alias(option, value) ++ rest, config)
         end
+
+      true ->
+        # We have a regular one-letter alias here
+        tagged = tag_oneletter_alias(option, config)
+        next_tagged(tagged, value, original, rest, config)
     end
   end
 
@@ -418,17 +408,12 @@ defmodule OptionParser do
     {:error, argv}
   end
 
-  defp next_tagged(:unknown, value, original, rest, _) do
-    {value, _kinds, rest} = normalize_value(value, [], rest)
-    {:undefined, original, value, rest}
-  end
-
-  defp next_tagged({tag, option}, value, original, rest, %{switches: switches, strict?: strict?}) do
-    if strict? and not Keyword.has_key?(switches, option) do
+  defp next_tagged(tagged, value, original, rest, %{switches: switches, strict?: strict?}) do
+    if strict? and not option_defined?(tagged, switches) do
       {:undefined, original, value, rest}
     else
-      {kinds, value} = normalize_tag(tag, option, value, switches)
-      {value, kinds, rest} = normalize_value(value, kinds, rest)
+      {option, kinds, value} = normalize_option(tagged, value, switches)
+      {value, kinds, rest} = normalize_value(value, kinds, rest, strict?)
 
       case validate_option(value, kinds) do
         {:ok, new_value} -> {:ok, option, new_value, rest}
@@ -451,9 +436,9 @@ defmodule OptionParser do
 
   ## Examples
 
-      iex> OptionParser.to_argv(foo_bar: "baz")
+      iex>  OptionParser.to_argv([foo_bar: "baz"])
       ["--foo-bar", "baz"]
-      iex> OptionParser.to_argv(bool: true, bool: false, discarded: nil)
+      iex>  OptionParser.to_argv([bool: true, bool: false, discarded: nil])
       ["--bool", "--no-bool"]
 
   Some switches will output different values based on the switches
@@ -558,8 +543,6 @@ defmodule OptionParser do
           {strict, true}
 
         true ->
-          # TODO: Remove this in Elixir v2.0
-          IO.warn("not passing the :switches or :strict option to OptionParser is deprecated")
           {[], false}
       end
 
@@ -586,7 +569,7 @@ defmodule OptionParser do
 
         :count in kinds ->
           case value do
-            nil -> {false, 1}
+            1 -> {false, value}
             _ -> {true, value}
           end
 
@@ -626,9 +609,10 @@ defmodule OptionParser do
     end
   end
 
-  defp tag_option("no-" <> option = original, config) do
-    %{switches: switches, allow_nonexistent_atoms?: allow_nonexistent_atoms?} = config
-
+  defp tag_option("no-" <> option = original, %{
+         switches: switches,
+         allow_nonexistent_atoms?: allow_nonexistent_atoms?
+       }) do
     cond do
       (negated = get_option_key(option, allow_nonexistent_atoms?)) &&
           :boolean in List.wrap(switches[negated]) ->
@@ -642,9 +626,7 @@ defmodule OptionParser do
     end
   end
 
-  defp tag_option(option, config) do
-    %{allow_nonexistent_atoms?: allow_nonexistent_atoms?} = config
-
+  defp tag_option(option, %{allow_nonexistent_atoms?: allow_nonexistent_atoms?}) do
     if option_key = get_option_key(option, allow_nonexistent_atoms?) do
       {:default, option_key}
     else
@@ -652,9 +634,11 @@ defmodule OptionParser do
     end
   end
 
-  defp tag_oneletter_alias(alias, config) when is_binary(alias) do
-    %{aliases: aliases, allow_nonexistent_atoms?: allow_nonexistent_atoms?} = config
-
+  defp tag_oneletter_alias(alias, %{
+         aliases: aliases,
+         allow_nonexistent_atoms?: allow_nonexistent_atoms?
+       })
+       when is_binary(alias) do
     if option_key = aliases[to_existing_key(alias, allow_nonexistent_atoms?)] do
       {:default, option_key}
     else
@@ -662,39 +646,59 @@ defmodule OptionParser do
     end
   end
 
-  defp expand_multiletter_alias(letters, value) do
+  defp expand_multiletter_alias(letters, value) when is_binary(letters) do
     {last, expanded} =
       letters
+      |> String.codepoints()
       |> Enum.map(&("-" <> &1))
       |> List.pop_at(-1)
 
     expanded ++ [last <> if(value, do: "=" <> value, else: "")]
   end
 
-  defp normalize_tag(:negated, option, value, switches) do
+  defp option_defined?(:unknown, _switches) do
+    false
+  end
+
+  defp option_defined?({:negated, option}, switches) do
+    Keyword.has_key?(switches, option)
+  end
+
+  defp option_defined?({:default, option}, switches) do
+    Keyword.has_key?(switches, option)
+  end
+
+  defp normalize_option(:unknown, value, _switches) do
+    {nil, [:invalid], value}
+  end
+
+  defp normalize_option({:negated, option}, value, switches) do
     if value do
-      {[:invalid], value}
+      {option, [:invalid], value}
     else
-      {List.wrap(switches[option]), false}
+      {option, List.wrap(switches[option]), false}
     end
   end
 
-  defp normalize_tag(:default, option, value, switches) do
-    {List.wrap(switches[option]), value}
+  defp normalize_option({:default, option}, value, switches) do
+    {option, List.wrap(switches[option]), value}
   end
 
-  defp normalize_value(nil, kinds, t) do
+  defp normalize_value(nil, kinds, t, strict?) do
     cond do
       :boolean in kinds ->
         {true, kinds, t}
 
       :count in kinds ->
-        {nil, kinds, t}
+        {1, kinds, t}
 
       value_in_tail?(t) ->
         [h | t] = t
         {h, kinds, t}
 
+      kinds == [] and strict? ->
+        {nil, kinds, t}
+
       kinds == [] ->
         {true, kinds, t}
 
@@ -703,7 +707,7 @@ defmodule OptionParser do
     end
   end
 
-  defp normalize_value(value, kinds, t) do
+  defp normalize_value(value, kinds, t, _strict?) do
     {value, kinds, t}
   end
 
@@ -721,14 +725,15 @@ defmodule OptionParser do
   end
 
   defp to_underscore(option), do: to_underscore(option, <<>>)
+  defp to_underscore("_" <> _rest, _acc), do: nil
   defp to_underscore("-" <> rest, acc), do: to_underscore(rest, acc <> "_")
   defp to_underscore(<<c>> <> rest, acc), do: to_underscore(rest, <<acc::binary, c>>)
   defp to_underscore(<<>>, acc), do: acc
 
   defp get_option_key(option, allow_nonexistent_atoms?) do
-    option
-    |> to_underscore()
-    |> to_existing_key(allow_nonexistent_atoms?)
+    if string = to_underscore(option) do
+      to_existing_key(string, allow_nonexistent_atoms?)
+    end
   end
 
   defp to_existing_key(option, true), do: String.to_atom(option)

lib/elixir/lib/path.ex

@@ -592,23 +592,24 @@ defmodule Path do
   Traverses paths according to the given `glob` expression and returns a
   list of matches.
 
-  The wildcard looks like an ordinary path, except that the following
-  "wildcard characters" are interpreted in a special way:
+  The wildcard looks like an ordinary path, except that certain
+  "wildcard characters" are interpreted in a special way. The
+  following characters are special:
 
-    * `?` - matches one character.
+    * `?` - matches one character
 
     * `*` - matches any number of characters up to the end of the filename, the
-      next dot, or the next slash.
+      next dot, or the next slash
 
     * `**` - two adjacent `*`'s used as a single pattern will match all
-      files and zero or more directories and subdirectories.
+      files and zero or more directories and subdirectories
 
     * `[char1,char2,...]` - matches any of the characters listed; two
       characters separated by a hyphen will match a range of characters.
       Do not add spaces before and after the comma as it would then match
       paths containing the space character itself.
 
-    * `{item1,item2,...}` - matches one of the alternatives.
+    * `{item1,item2,...}` - matches one of the alternatives
       Do not add spaces before and after the comma as it would then match
       paths containing the space character itself.
 
@@ -617,14 +618,7 @@ defmodule Path do
   that matching is case-sensitive: `"a"` will not match `"A"`.
 
   By default, the patterns `*` and `?` do not match files starting
-  with a dot `.`. See the `:match_dot` option in the "Options" section
-  below.
-
-  ## Options
-
-    * `:match_dot` - (boolean) if `false`, the special wildcard characters `*` and `?`
-      will not match files starting with a dot (`.`). If `true`, files starting with
-      a `.` will not be treated specially. Defaults to `false`.
+  with a dot `.` unless `match_dot: true` is given in `opts`.
 
   ## Examples
 

lib/elixir/lib/port.ex

@@ -8,12 +8,12 @@ defmodule Port do
   ## Example
 
       iex> port = Port.open({:spawn, "cat"}, [:binary])
-      iex> send(port, {self(), {:command, "hello"}})
-      iex> send(port, {self(), {:command, "world"}})
+      iex> send port, {self(), {:command, "hello"}}
+      iex> send port, {self(), {:command, "world"}}
       iex> flush()
       {#Port<0.1444>, {:data, "hello"}}
       {#Port<0.1444>, {:data, "world"}}
-      iex> send(port, {self(), :close})
+      iex> send port, {self(), :close}
       :ok
       iex> flush()
       {#Port<0.1464>, :closed}
@@ -117,7 +117,7 @@ defmodule Port do
   reimplementing core part of the Runtime System, such as the `:user` and
   `:shell` processes.
 
-  ## Zombie OS processes
+  ## Zombie processes
 
   A port can be closed via the `close/1` function or by sending a `{pid, :close}`
   message. However, if the VM crashes, a long-running program started by the port
@@ -177,8 +177,8 @@ defmodule Port do
   Inlined by the compiler.
   """
   @spec open(name, list) :: port
-  def open(name, options) do
-    :erlang.open_port(name, options)
+  def open(name, settings) do
+    :erlang.open_port(name, settings)
   end
 
   @doc """
@@ -236,9 +236,8 @@ defmodule Port do
 
   def info(port, :registered_name) do
     case :erlang.port_info(port, :registered_name) do
-      :undefined -> nil
       [] -> {:registered_name, []}
-      other -> other
+      other -> nillify(other)
     end
   end
 
@@ -265,7 +264,6 @@ defmodule Port do
 
   Inlined by the compiler.
   """
-  @doc since: "1.6.0"
   @spec monitor(port | {name :: atom, node :: atom} | name :: atom) :: reference
   def monitor(port) do
     :erlang.monitor(:port, port)
@@ -282,7 +280,6 @@ defmodule Port do
 
   Inlined by the compiler.
   """
-  @doc since: "1.6.0"
   @spec demonitor(reference, options :: [:flush | :info]) :: boolean
   defdelegate demonitor(monitor_ref, options \\ []), to: :erlang
 

lib/elixir/lib/process.ex

@@ -20,25 +20,16 @@ defmodule Process do
   """
 
   @doc """
-  Tells whether the given process is alive on the local node.
+  Tells whether the given process is alive.
 
   If the process identified by `pid` is alive (that is, it's not exiting and has
   not exited yet) than this function returns `true`. Otherwise, it returns
   `false`.
 
-  `pid` must refer to a process running on the local node or `ArgumentError` is raised.
+  `pid` must refer to a process running on the local node.
 
   Inlined by the compiler.
   """
-
-  @typedoc """
-  A process destination.
-
-  A remote or local PID, a local port, a locally registered name, or a tuple in
-  the form of `{registered_name, node}` for a registered name at another node.
-  """
-  @type dest :: pid | port | registered_name :: atom | {registered_name :: atom, node}
-
   @spec alive?(pid) :: boolean
   defdelegate alive?(pid), to: :erlang, as: :is_process_alive
 
@@ -229,13 +220,7 @@ defmodule Process do
   end
 
   @doc """
-  Sends a message to the given `dest`.
-
-  `dest` may be a remote or local PID, a local port, a locally
-  registered name, or a tuple in the form of `{registered_name, node}` for a
-  registered name at another node.
-
-  Inlined by the compiler.
+  Sends a message to the given process.
 
   ## Options
 
@@ -253,9 +238,10 @@ defmodule Process do
       iex> Process.send({:name, :node_that_does_not_exist}, :hi, [:noconnect])
       :noconnect
 
+  Inlined by the compiler.
   """
   @spec send(dest, msg, [option]) :: :ok | :noconnect | :nosuspend
-        when dest: dest(),
+        when dest: pid | port | atom | {atom, node},
              msg: any,
              option: :noconnect | :nosuspend
   defdelegate send(dest, msg, options), to: :erlang
@@ -310,8 +296,6 @@ defmodule Process do
   Even if the timer had expired and the message was sent, this function does not
   tell you if the timeout message has arrived at its destination yet.
 
-  Inlined by the compiler.
-
   ## Options
 
     * `:async` - (boolean) when `false`, the request for cancellation is
@@ -329,6 +313,7 @@ defmodule Process do
       cancellation has been performed. If `:async` is `true` and `:info` is
       `false`, no message is sent. Defaults to `true`.
 
+  Inlined by the compiler.
   """
   @spec cancel_timer(reference, options) :: non_neg_integer | false | :ok
         when options: [async: boolean, info: boolean]
@@ -409,9 +394,6 @@ defmodule Process do
       a PID) or `{name, node}` (if monitoring a remote or local name);
     * `reason` is the exit reason.
 
-  If the process is already dead when calling `Process.monitor/1`, a
-  `:DOWN` message is delivered immediately.
-
   See [the need for monitoring](http://elixir-lang.org/getting-started/mix-otp/genserver.html#the-need-for-monitoring)
   for an example. See `:erlang.monitor/2` for more info.
 
@@ -596,6 +578,8 @@ defmodule Process do
 
   See `:erlang.process_flag/2` for more info.
 
+  Note that `flag` values `:max_heap_size` and `:message_queue_data` are only available since OTP 19.
+
   Inlined by the compiler.
   """
   @spec flag(:error_handler, module) :: module
@@ -636,7 +620,7 @@ defmodule Process do
 
   See `:erlang.process_info/1` for more info.
   """
-  @spec info(pid) :: keyword | nil
+  @spec info(pid) :: keyword
   def info(pid) do
     nillify(:erlang.process_info(pid))
   end

lib/elixir/lib/protocol.ex

@@ -44,7 +44,7 @@ defmodule Protocol do
 
       # Convert the spec to callback if possible,
       # otherwise generate a dummy callback
-      Module.spec_to_callback(__MODULE__, {name, arity}) ||
+      Protocol.__spec__?(__MODULE__, name, arity) ||
         @callback unquote(name)(unquote_splicing(type_args)) :: term
     end
   end
@@ -309,7 +309,7 @@ defmodule Protocol do
   end
 
   defp beam_protocol(protocol) do
-    chunk_ids = [:abstract_code, :attributes, :compile_info, 'Docs', 'ExDp']
+    chunk_ids = [:abstract_code, :attributes, :compile_info, 'ExDc', 'ExDp']
     opts = [:allow_missing_chunks]
 
     case :beam_lib.chunks(beam_file(protocol), chunk_ids, opts) do
@@ -612,7 +612,7 @@ defmodule Protocol do
       # Inline struct implementation for performance
       @compile {:inline, struct_impl_for: 1}
 
-      unless Module.defines_type?(__MODULE__, {:t, 0}) do
+      unless Kernel.Typespec.defines_type?(__MODULE__, :t, 0) do
         @type t :: term
       end
 
@@ -715,7 +715,7 @@ defmodule Protocol do
     assert_impl!(protocol, Any, extra)
 
     # Clean up variables from eval context
-    env = :elixir_env.reset_vars(env)
+    env = %{env | vars: [], export_vars: nil}
     args = [for, struct, opts]
     impl = Module.concat(protocol, Any)
 
@@ -757,6 +757,22 @@ defmodule Protocol do
     :ok
   end
 
+  @doc false
+  def __spec__?(module, name, arity) do
+    signature = {name, arity}
+
+    mapper = fn {:spec, expr, pos} ->
+      if Kernel.Typespec.spec_to_signature(expr) == signature do
+        Module.store_typespec(module, :callback, {:callback, expr, pos})
+        true
+      end
+    end
+
+    specs = Module.get_attribute(module, :spec)
+    found = :lists.map(mapper, specs)
+    :lists.any(&(&1 == true), found)
+  end
+
   ## Helpers
 
   @doc false

lib/elixir/lib/range.ex

@@ -59,7 +59,7 @@ defmodule Range do
 
   # TODO: Remove by 2.0
   @doc false
-  @deprecated "Pattern match on first..last instead"
+  @spec range?(term) :: boolean
   def range?(term)
   def range?(first..last) when is_integer(first) and is_integer(last), do: true
   def range?(_), do: false
@@ -70,20 +70,20 @@ defimpl Enumerable, for: Range do
     reduce(first, last, acc, fun, _up? = last >= first)
   end
 
-  defp reduce(_first, _last, {:halt, acc}, _fun, _up?) do
+  defp reduce(_x, _y, {:halt, acc}, _fun, _up?) do
     {:halted, acc}
   end
 
-  defp reduce(first, last, {:suspend, acc}, fun, up?) do
-    {:suspended, acc, &reduce(first, last, &1, fun, up?)}
+  defp reduce(x, y, {:suspend, acc}, fun, up?) do
+    {:suspended, acc, &reduce(x, y, &1, fun, up?)}
   end
 
-  defp reduce(first, last, {:cont, acc}, fun, _up? = true) when first <= last do
-    reduce(first + 1, last, fun.(first, acc), fun, _up? = true)
+  defp reduce(x, y, {:cont, acc}, fun, _up? = true) when x <= y do
+    reduce(x + 1, y, fun.(x, acc), fun, _up? = true)
   end
 
-  defp reduce(first, last, {:cont, acc}, fun, _up? = false) when first >= last do
-    reduce(first - 1, last, fun.(first, acc), fun, _up? = false)
+  defp reduce(x, y, {:cont, acc}, fun, _up? = false) when x >= y do
+    reduce(x - 1, y, fun.(x, acc), fun, _up? = false)
   end
 
   defp reduce(_, _, {:cont, acc}, _fun, _up) do

lib/elixir/lib/record.ex

@@ -4,7 +4,7 @@ defmodule Record do
 
   Records are simply tuples where the first element is an atom:
 
-      iex> Record.is_record({User, "john", 27})
+      iex> Record.is_record {User, "john", 27}
       true
 
   This module provides conveniences for working with records at

lib/elixir/lib/regex.ex

@@ -7,9 +7,9 @@ defmodule Regex do
   in the [`:re` module documentation](http://www.erlang.org/doc/man/re.html).
 
   Regular expressions in Elixir can be created using the sigils
-  [`~r`](`Kernel.sigil_r/2`) or [`~R`](`Kernel.sigil_R/2`):
+  [`~r`](Kernel.html#sigil_r/2) or [`~R`](Kernel.html#sigil_R/2):
 
-      # A simple regular expression that matches foo anywhere in the string
+      # A simple regular expressions that matches foo anywhere in the string
       ~r/foo/
 
       # A regular expression with case insensitive and Unicode options
@@ -41,7 +41,7 @@ defmodule Regex do
   expression engine at any time.
 
   For such reasons, we always recommend precompiling Elixir projects using
-  the Erlang/OTP version meant to run in production. In case cross-compilation is
+  the OTP version meant to run in production. In case cross-compilation is
   really necessary, you can manually invoke `Regex.recompile/1` or
   `Regex.recompile!/1` to perform a runtime version check and recompile the
   regex if necessary.
@@ -93,7 +93,7 @@ defmodule Regex do
       complete matching part of the string; all explicitly captured subpatterns
       are discarded
 
-    * `:all_but_first` - all but the first matching subpattern, i.e. all
+    * `:all_but_first`- all but the first matching subpattern, i.e. all
       explicitly captured subpatterns, but not the complete matching part of
       the string
 
@@ -117,9 +117,8 @@ defmodule Regex do
   Compiles the regular expression.
 
   The given options can either be a binary with the characters
-  representing the same regex options given to the
-  [`~r`](`Kernel.sigil_r/2`) sigil, or a list of options, as
-  expected by the Erlang's `:re` module.
+  representing the same regex options given to the `~r` sigil,
+  or a list of options, as expected by the Erlang's `:re` module.
 
   It returns `{:ok, regex}` in case of success,
   `{:error, reason}` otherwise.
@@ -127,7 +126,7 @@ defmodule Regex do
   ## Examples
 
       iex> Regex.compile("foo")
-      {:ok, ~r/foo/}
+      {:ok, ~r"foo"}
 
       iex> Regex.compile("*foo")
       {:error, {'nothing to repeat', 0}}
@@ -179,13 +178,13 @@ defmodule Regex do
   This checks the version stored in the regular expression
   and recompiles the regex in case of version mismatch.
   """
-  @doc since: "1.4.0"
   @spec recompile(t) :: t
   def recompile(%Regex{} = regex) do
     version = version()
 
-    case regex do
-      %{re_version: ^version} ->
+    # We use Map.get/3 by choice to support old regexes versions.
+    case Map.get(regex, :re_version, :error) do
+      ^version ->
         {:ok, regex}
 
       _ ->
@@ -197,7 +196,6 @@ defmodule Regex do
   @doc """
   Recompiles the existing regular expression and raises `Regex.CompileError` in case of errors.
   """
-  @doc since: "1.4.0"
   @spec recompile!(t) :: t
   def recompile!(regex) do
     case recompile(regex) do
@@ -209,14 +207,12 @@ defmodule Regex do
   @doc """
   Returns the version of the underlying Regex engine.
   """
-  @doc since: "1.4.0"
-  @spec version :: term()
   # TODO: No longer check for function_exported? on OTP 20+.
   def version do
     if function_exported?(:re, :version, 0) do
-      {:re.version(), :erlang.system_info(:endian)}
+      :re.version()
     else
-      {"8.33 2013-05-29", :erlang.system_info(:endian)}
+      "8.33 2013-05-29"
     end
   end
 
@@ -261,8 +257,7 @@ defmodule Regex do
 
   ## Options
 
-    * `:return` - set to `:index` to return byte index and match length.
-      Defaults to `:binary`.
+    * `:return`  - sets to `:index` to return indexes. Defaults to `:binary`.
     * `:capture` - what to capture in the result. Check the moduledoc for `Regex`
       to see the possible capture values.
 
@@ -293,12 +288,9 @@ defmodule Regex do
   end
 
   @doc """
-  Returns the given captures as a map or `nil` if no captures are found.
-
-  ## Options
-
-    * `:return` - set to `:index` to return byte index and match length.
-      Defaults to `:binary`.
+  Returns the given captures as a map or `nil` if no captures are
+  found. The option `:return` can be set to `:index` to get indexes
+  back.
 
   ## Examples
 
@@ -380,8 +372,7 @@ defmodule Regex do
 
   ## Options
 
-    * `:return` - set to `:index` to return byte index and match length.
-      Defaults to `:binary`.
+    * `:return`  - sets to `:index` to return indexes. Defaults to `:binary`.
     * `:capture` - what to capture in the result. Check the moduledoc for `Regex`
       to see the possible capture values.
 
@@ -399,9 +390,6 @@ defmodule Regex do
       iex> Regex.scan(~r/\p{Sc}/u, "$, £, and €")
       [["$"], ["£"], ["€"]]
 
-      iex> Regex.scan(~r/=+/, "=ü†ƒ8===", return: :index)
-      [[{0, 1}], [{9, 3}]]
-
   """
   @spec scan(t, String.t(), [term]) :: [[String.t()]]
   def scan(regex, string, options \\ [])
@@ -444,7 +432,7 @@ defmodule Regex do
       iex> Regex.split(~r{-}, "a-b-c")
       ["a", "b", "c"]
 
-      iex> Regex.split(~r{-}, "a-b-c", parts: 2)
+      iex> Regex.split(~r{-}, "a-b-c", [parts: 2])
       ["a", "b-c"]
 
       iex> Regex.split(~r{-}, "abc")
@@ -599,7 +587,7 @@ defmodule Regex do
 
   def replace(regex, string, replacement, options)
       when is_binary(string) and is_function(replacement) and is_list(options) do
-    {:arity, arity} = Function.info(replacement, :arity)
+    {:arity, arity} = :erlang.fun_info(replacement, :arity)
     do_replace(regex, string, {replacement, arity}, options)
   end
 

lib/elixir/lib/registry.ex

@@ -11,7 +11,7 @@ defmodule Registry do
   Each entry in the registry is associated to the process that has
   registered the key. If the process crashes, the keys associated to that
   process are automatically removed. All key comparisons in the registry
-  are done using the match operation (`===/2`).
+  are done using the match operation (`===`).
 
   The registry can be used for different purposes, such as name lookups (using
   the `:via` option), storing properties, custom dispatching rules, or a pubsub
@@ -89,7 +89,7 @@ defmodule Registry do
             apply(module, function, [pid])
           catch
             kind, reason ->
-              formatted = Exception.format(kind, reason, __STACKTRACE__)
+              formatted = Exception.format(kind, reason, System.stacktrace)
               Logger.error "Registry.dispatch/3 failed with #{formatted}"
           end
         end
@@ -171,19 +171,9 @@ defmodule Registry do
   @typedoc "The type of registry metadata values"
   @type meta_value :: term
 
-  @typedoc "A pattern to match on objects in a registry"
-  @type match_pattern :: atom | term
-
-  @typedoc "A guard to be evaluated when matching on objects in a registry"
-  @type guard :: {atom | term}
-
-  @typedoc "A list of guards to be evaluated when matching on objects in a registry"
-  @type guards :: [guard] | []
-
   ## Via callbacks
 
   @doc false
-  @doc since: "1.4.0"
   def whereis_name({registry, key}) do
     case key_info!(registry) do
       {:unique, partitions, key_ets} ->
@@ -203,7 +193,6 @@ defmodule Registry do
   end
 
   @doc false
-  @doc since: "1.4.0"
   def register_name({registry, key}, pid) when pid == self() do
     case register(registry, key, nil) do
       {:ok, _} -> :yes
@@ -212,7 +201,6 @@ defmodule Registry do
   end
 
   @doc false
-  @doc since: "1.4.0"
   def send({registry, key}, msg) do
     case lookup(registry, key) do
       [{pid, _}] -> Kernel.send(pid, msg)
@@ -221,7 +209,6 @@ defmodule Registry do
   end
 
   @doc false
-  @doc since: "1.4.0"
   def unregister_name({registry, key}) do
     unregister(registry, key)
   end
@@ -272,7 +259,6 @@ defmodule Registry do
     * `:meta` - a keyword list of metadata to be attached to the registry.
 
   """
-  @doc since: "1.5.0"
   @spec start_link(
           keys: keys,
           name: registry,
@@ -324,8 +310,13 @@ defmodule Registry do
     Registry.Supervisor.start_link(keys, name, partitions, listeners, entries)
   end
 
-  @doc false
-  @deprecated "Use Registry.start_link/1 instead"
+  @doc """
+  Starts the registry as a supervisor process.
+
+  Similar to `start_link/1` except the required options,
+  `keys` and `name` are given as arguments.
+  """
+  @spec start_link(keys, registry, keyword) :: {:ok, pid} | {:error, term}
   def start_link(keys, name, options \\ []) when keys in @keys and is_atom(name) do
     start_link([keys: keys, name: name] ++ options)
   end
@@ -335,7 +326,7 @@ defmodule Registry do
 
   See `Supervisor`.
   """
-  @doc since: "1.5.0"
+  @since "1.5.0"
   def child_spec(opts) do
     %{
       id: Keyword.get(opts, :name, Registry),
@@ -354,17 +345,16 @@ defmodule Registry do
 
   ## Examples
 
-      iex> Registry.start_link(keys: :unique, name: Registry.UpdateTest)
+      iex> Registry.start_link(:unique, Registry.UpdateTest)
       iex> {:ok, _} = Registry.register(Registry.UpdateTest, "hello", 1)
       iex> Registry.lookup(Registry.UpdateTest, "hello")
       [{self(), 1}]
-      iex> Registry.update_value(Registry.UpdateTest, "hello", &(&1 + 1))
+      iex> Registry.update_value(Registry.UpdateTest, "hello", & &1 + 1)
       {2, 1}
       iex> Registry.lookup(Registry.UpdateTest, "hello")
       [{self(), 2}]
 
   """
-  @doc since: "1.4.0"
   @spec update_value(registry, key, (value -> value)) ::
           {new_value :: term, old_value :: term} | :error
   def update_value(registry, key, callback) when is_atom(registry) and is_function(callback, 1) do
@@ -408,9 +398,7 @@ defmodule Registry do
   See the module documentation for examples of using the `dispatch/3`
   function for building custom dispatching or a pubsub system.
   """
-  @doc since: "1.4.0"
-  @spec dispatch(registry, key, dispatcher, keyword) :: :ok
-        when dispatcher: (entries :: [{pid, value}] -> term) | {module(), atom(), [any()]}
+  @spec dispatch(registry, key, (entries :: [{pid, value}] -> term), keyword) :: :ok
   def dispatch(registry, key, mfa_or_fun, opts \\ [])
       when is_atom(registry) and is_function(mfa_or_fun, 1)
       when is_atom(registry) and tuple_size(mfa_or_fun) == 3 do
@@ -501,18 +489,18 @@ defmodule Registry do
   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.start_link(:unique, Registry.UniqueLookupTest)
       iex> Registry.lookup(Registry.UniqueLookupTest, "hello")
       []
       iex> {:ok, _} = Registry.register(Registry.UniqueLookupTest, "hello", :world)
       iex> Registry.lookup(Registry.UniqueLookupTest, "hello")
       [{self(), :world}]
-      iex> Task.async(fn -> Registry.lookup(Registry.UniqueLookupTest, "hello") end) |> Task.await()
+      iex> Task.async(fn -> Registry.lookup(Registry.UniqueLookupTest, "hello") end) |> Task.await
       [{self(), :world}]
 
   The same applies to duplicate registries:
 
-      iex> Registry.start_link(keys: :duplicate, name: Registry.DuplicateLookupTest)
+      iex> Registry.start_link(:duplicate, Registry.DuplicateLookupTest)
       iex> Registry.lookup(Registry.DuplicateLookupTest, "hello")
       []
       iex> {:ok, _} = Registry.register(Registry.DuplicateLookupTest, "hello", :world)
@@ -523,7 +511,6 @@ defmodule Registry do
       [{self(), :another}, {self(), :world}]
 
   """
-  @doc since: "1.4.0"
   @spec lookup(registry, key) :: [{pid, value}]
   def lookup(registry, key) when is_atom(registry) do
     case key_info!(registry) do
@@ -553,14 +540,14 @@ defmodule Registry do
 
   Pattern must be an atom or a tuple that will match the structure of the
   value stored in the registry. The atom `:_` can be used to ignore a given
-  value or tuple element, while the atom `:"$1"` can be used to temporarily assign part
+  value or tuple element, while :"$1" can be used to temporarily assign part
   of pattern to a variable for a subsequent comparison.
 
-  Optionally, it is possible to pass a list of guard conditions for more precise matching.
-  Each guard is a tuple, which describes checks that should be passed by assigned part of pattern.
-  For example the `$1 > 1` guard condition would be expressed as the `{:>, :"$1", 1}` tuple.
-  Please note that guard conditions will work only for assigned variables like `:"$1"`, `:"$2"`, etc.
-  Avoid usage of special match variables `:"$_"` and `:"$$"`, because it might not work as expected.
+  It is possible to pass list of guard conditions for more precise matching.
+  Each guard is a tuple, which describes check that should be passed by assigned part of pattern.
+  For example :"$1" > 1 guard condition would be expressed as {:>, :"$1", 1} tuple.
+  Please note that guard conditions will work only for assigned variables like :"$1", :"$2", etc.
+  Avoid usage of special match variables :"$_" and :"$$", because it might not work as expected.
 
   An empty list will be returned if there is no match.
 
@@ -572,7 +559,7 @@ defmodule Registry do
   In the example below we register the current process under the same
   key in a duplicate registry but with different values:
 
-      iex> Registry.start_link(keys: :duplicate, name: Registry.MatchTest)
+      iex> Registry.start_link(:duplicate, Registry.MatchTest)
       iex> {:ok, _} = Registry.register(Registry.MatchTest, "hello", {1, :atom, 1})
       iex> {:ok, _} = Registry.register(Registry.MatchTest, "hello", {2, :atom, 2})
       iex> Registry.match(Registry.MatchTest, "hello", {1, :_, :_})
@@ -589,8 +576,7 @@ defmodule Registry do
       [{self(), {1, :atom, 1}}, {self(), {2, :atom, 2}}]
 
   """
-  @doc since: "1.4.0"
-  @spec match(registry, key, match_pattern, guards) :: [{pid, term}]
+  @spec match(registry, key, match_pattern :: term, guards :: list()) :: [{pid, term}]
   def match(registry, key, pattern, guards \\ []) when is_atom(registry) and is_list(guards) do
     guards = [{:"=:=", {:element, 1, :"$_"}, {:const, key}} | guards]
     spec = [{{:_, {:_, pattern}}, guards, [{:element, 2, :"$_"}]}]
@@ -622,7 +608,7 @@ defmodule Registry do
 
   Registering under a unique registry does not allow multiple entries:
 
-      iex> Registry.start_link(keys: :unique, name: Registry.UniqueKeysTest)
+      iex> Registry.start_link(:unique, Registry.UniqueKeysTest)
       iex> Registry.keys(Registry.UniqueKeysTest, self())
       []
       iex> {:ok, _} = Registry.register(Registry.UniqueKeysTest, "hello", :world)
@@ -633,7 +619,7 @@ defmodule Registry do
 
   Such is possible for duplicate registries though:
 
-      iex> Registry.start_link(keys: :duplicate, name: Registry.DuplicateKeysTest)
+      iex> Registry.start_link(:duplicate, Registry.DuplicateKeysTest)
       iex> Registry.keys(Registry.DuplicateKeysTest, self())
       []
       iex> {:ok, _} = Registry.register(Registry.DuplicateKeysTest, "hello", :world)
@@ -642,7 +628,6 @@ defmodule Registry do
       ["hello", "hello"]
 
   """
-  @doc since: "1.4.0"
   @spec keys(registry, pid) :: [key]
   def keys(registry, pid) when is_atom(registry) and is_pid(pid) do
     {kind, partitions, _, pid_ets, _} = info!(registry)
@@ -693,7 +678,7 @@ defmodule Registry do
 
   For unique registries:
 
-      iex> Registry.start_link(keys: :unique, name: Registry.UniqueUnregisterTest)
+      iex> Registry.start_link(:unique, Registry.UniqueUnregisterTest)
       iex> Registry.register(Registry.UniqueUnregisterTest, "hello", :world)
       iex> Registry.keys(Registry.UniqueUnregisterTest, self())
       ["hello"]
@@ -704,7 +689,7 @@ defmodule Registry do
 
   For duplicate registries:
 
-      iex> Registry.start_link(keys: :duplicate, name: Registry.DuplicateUnregisterTest)
+      iex> Registry.start_link(:duplicate, Registry.DuplicateUnregisterTest)
       iex> Registry.register(Registry.DuplicateUnregisterTest, "hello", :world)
       iex> Registry.register(Registry.DuplicateUnregisterTest, "hello", :world)
       iex> Registry.keys(Registry.DuplicateUnregisterTest, self())
@@ -715,7 +700,6 @@ defmodule Registry do
       []
 
   """
-  @doc since: "1.4.0"
   @spec unregister(registry, key) :: :ok
   def unregister(registry, key) when is_atom(registry) do
     self = self()
@@ -747,7 +731,7 @@ defmodule Registry do
   For unique registries it can be used to conditionally unregister a key on
   the basis of whether or not it matches a particular value.
 
-      iex> Registry.start_link(keys: :unique, name: Registry.UniqueUnregisterMatchTest)
+      iex> Registry.start_link(:unique, Registry.UniqueUnregisterMatchTest)
       iex> Registry.register(Registry.UniqueUnregisterMatchTest, "hello", :world)
       iex> Registry.keys(Registry.UniqueUnregisterMatchTest, self())
       ["hello"]
@@ -762,7 +746,7 @@ defmodule Registry do
 
   For duplicate registries:
 
-      iex> Registry.start_link(keys: :duplicate, name: Registry.DuplicateUnregisterMatchTest)
+      iex> Registry.start_link(:duplicate, Registry.DuplicateUnregisterMatchTest)
       iex> Registry.register(Registry.DuplicateUnregisterMatchTest, "hello", :world_a)
       iex> Registry.register(Registry.DuplicateUnregisterMatchTest, "hello", :world_b)
       iex> Registry.register(Registry.DuplicateUnregisterMatchTest, "hello", :world_c)
@@ -774,9 +758,7 @@ defmodule Registry do
       ["hello", "hello"]
       iex> Registry.lookup(Registry.DuplicateUnregisterMatchTest, "hello")
       [{self(), :world_b}, {self(), :world_c}]
-
   """
-  @doc since: "1.5.0"
   def unregister_match(registry, key, pattern, guards \\ []) when is_list(guards) do
     self = self()
 
@@ -853,7 +835,7 @@ defmodule Registry do
 
   Registering under a unique registry does not allow multiple entries:
 
-      iex> Registry.start_link(keys: :unique, name: Registry.UniqueRegisterTest)
+      iex> Registry.start_link(:unique, Registry.UniqueRegisterTest)
       iex> {:ok, _} = Registry.register(Registry.UniqueRegisterTest, "hello", :world)
       iex> Registry.register(Registry.UniqueRegisterTest, "hello", :later)
       {:error, {:already_registered, self()}}
@@ -862,14 +844,13 @@ defmodule Registry do
 
   Such is possible for duplicate registries though:
 
-      iex> Registry.start_link(keys: :duplicate, name: Registry.DuplicateRegisterTest)
+      iex> Registry.start_link(:duplicate, Registry.DuplicateRegisterTest)
       iex> {:ok, _} = Registry.register(Registry.DuplicateRegisterTest, "hello", :world)
       iex> {:ok, _} = Registry.register(Registry.DuplicateRegisterTest, "hello", :world)
       iex> Registry.keys(Registry.DuplicateRegisterTest, self())
       ["hello", "hello"]
 
   """
-  @doc since: "1.4.0"
   @spec register(registry, key, value) :: {:ok, pid} | {:error, {:already_registered, pid}}
   def register(registry, key, value) when is_atom(registry) do
     self = self()
@@ -935,14 +916,13 @@ defmodule Registry do
 
   ## Examples
 
-      iex> Registry.start_link(keys: :unique, name: Registry.MetaTest, meta: [custom_key: "custom_value"])
+      iex> Registry.start_link(:unique, Registry.MetaTest, meta: [custom_key: "custom_value"])
       iex> Registry.meta(Registry.MetaTest, :custom_key)
       {:ok, "custom_value"}
       iex> Registry.meta(Registry.MetaTest, :unknown_key)
       :error
 
   """
-  @doc since: "1.4.0"
   @spec meta(registry, meta_key) :: {:ok, meta_value} | :error
   def meta(registry, key) when is_atom(registry) and (is_atom(key) or is_tuple(key)) do
     try do
@@ -963,7 +943,7 @@ defmodule Registry do
 
   ## Examples
 
-      iex> Registry.start_link(keys: :unique, name: Registry.PutMetaTest)
+      iex> Registry.start_link(:unique, Registry.PutMetaTest)
       iex> Registry.put_meta(Registry.PutMetaTest, :custom_key, "custom_value")
       :ok
       iex> Registry.meta(Registry.PutMetaTest, :custom_key)
@@ -974,7 +954,6 @@ defmodule Registry do
       {:ok, "tuple_value"}
 
   """
-  @doc since: "1.4.0"
   @spec put_meta(registry, meta_key, meta_value) :: :ok
   def put_meta(registry, key, value) when is_atom(registry) and (is_atom(key) or is_tuple(key)) do
     try do
@@ -986,120 +965,6 @@ defmodule Registry do
     end
   end
 
-  @doc """
-  Returns the number of registered keys in a registry.
-  It runs in constant time.
-
-  ## Examples
-  In the example below we register the current process and ask for the
-  number of keys in the registry:
-
-      iex> Registry.start_link(keys: :unique, name: Registry.UniqueCountTest)
-      iex> Registry.count(Registry.UniqueCountTest)
-      0
-      iex> {:ok, _} = Registry.register(Registry.UniqueCountTest, "hello", :world)
-      iex> {:ok, _} = Registry.register(Registry.UniqueCountTest, "world", :world)
-      iex> Registry.count(Registry.UniqueCountTest)
-      2
-
-  The same applies to duplicate registries:
-
-      iex> Registry.start_link(keys: :duplicate, name: Registry.DuplicateCountTest)
-      iex> Registry.count(Registry.DuplicateCountTest)
-      0
-      iex> {:ok, _} = Registry.register(Registry.DuplicateCountTest, "hello", :world)
-      iex> {:ok, _} = Registry.register(Registry.DuplicateCountTest, "hello", :world)
-      iex> Registry.count(Registry.DuplicateCountTest)
-      2
-
-  """
-  @doc since: "1.7.0"
-  @spec count(registry) :: non_neg_integer()
-  def count(registry) when is_atom(registry) do
-    case key_info!(registry) do
-      {_kind, partitions, nil} ->
-        Enum.reduce(0..(partitions - 1), 0, fn partition_index, acc ->
-          acc + safe_size(key_ets!(registry, partition_index))
-        end)
-
-      {_kind, 1, key_ets} ->
-        safe_size(key_ets)
-    end
-  end
-
-  defp safe_size(ets) do
-    try do
-      :ets.info(ets, :size)
-    catch
-      :error, :badarg -> 0
-    end
-  end
-
-  @doc """
-  Returns the number of `{pid, value}` pairs under the given `key` in `registry`
-  that match `pattern`.
-
-  Pattern must be an atom or a tuple that will match the structure of the
-  value stored in the registry. The atom `:_` can be used to ignore a given
-  value or tuple element, while the atom `:"$1"` can be used to temporarily assign part
-  of pattern to a variable for a subsequent comparison.
-
-  Optionally, it is possible to pass a list of guard conditions for more precise matching.
-  Each guard is a tuple, which describes checks that should be passed by assigned part of pattern.
-  For example the `$1 > 1` guard condition would be expressed as the `{:>, :"$1", 1}` tuple.
-  Please note that guard conditions will work only for assigned variables like `:"$1"`, `:"$2"`, etc.
-  Avoid usage of special match variables `:"$_"` and `:"$$"`, because it might not work as expected.
-
-  Zero will be returned if there is no match.
-
-  For unique registries, a single partition lookup is necessary. For
-  duplicate registries, all partitions must be looked up.
-
-  ## Examples
-
-  In the example below we register the current process under the same
-  key in a duplicate registry but with different values:
-
-      iex> Registry.start_link(keys: :duplicate, name: Registry.MatchTest)
-      iex> {:ok, _} = Registry.register(Registry.MatchTest, "hello", {1, :atom, 1})
-      iex> {:ok, _} = Registry.register(Registry.MatchTest, "hello", {2, :atom, 2})
-      iex> Registry.count_match(Registry.MatchTest, "hello", {1, :_, :_})
-      1
-      iex> Registry.count_match(Registry.MatchTest, "hello", {2, :_, :_})
-      1
-      iex> Registry.count_match(Registry.MatchTest, "hello", {:_, :atom, :_})
-      2
-      iex> Registry.count_match(Registry.MatchTest, "hello", {:"$1", :_, :"$1"})
-      2
-      iex> Registry.count_match(Registry.MatchTest, "hello", {:_, :_, :"$1"}, [{:>, :"$1", 1}])
-      1
-      iex> Registry.count_match(Registry.MatchTest, "hello", {:_, :"$1", :_}, [{:is_atom, :"$1"}])
-      2
-
-  """
-  @doc since: "1.7.0"
-  @spec count_match(registry, key, match_pattern, guards) :: non_neg_integer()
-  def count_match(registry, key, pattern, guards \\ [])
-      when is_atom(registry) and is_list(guards) do
-    guards = [{:"=:=", {:element, 1, :"$_"}, {:const, key}} | guards]
-    spec = [{{:_, {:_, pattern}}, guards, [true]}]
-
-    case key_info!(registry) do
-      {:unique, partitions, key_ets} ->
-        key_ets = key_ets || key_ets!(registry, key, partitions)
-        :ets.select_count(key_ets, spec)
-
-      {:duplicate, 1, key_ets} ->
-        :ets.select_count(key_ets, spec)
-
-      {:duplicate, partitions, _key_ets} ->
-        Enum.reduce(0..(partitions - 1), 0, fn partition_index, acc ->
-          count = :ets.select_count(key_ets!(registry, partition_index), spec)
-          acc + count
-        end)
-    end
-  end
-
   ## Helpers
 
   @compile {:inline, hash: 2}
@@ -1313,4 +1178,8 @@ defmodule Registry.Partition do
 
     {:noreply, ets}
   end
+
+  def handle_info(msg, state) do
+    super(msg, state)
+  end
 end

lib/elixir/lib/set.ex

@@ -1,18 +1,16 @@
 defmodule Set do
   @moduledoc ~S"""
-  Generic API for sets.
+  WARNING: this module is deprecated.
 
-  This module is deprecated, use the `MapSet` module instead.
+  Use the `MapSet` module instead.
   """
 
-  @moduledoc deprecated: "Use MapSet instead"
-
   @type value :: any
   @type values :: [value]
   @type t :: map
 
   # TODO: Remove by 2.0
-  message = "Use the MapSet module for working with sets"
+  # (hard-deprecated in elixir_dispatch)
 
   defmacrop target(set) do
     quote do
@@ -23,12 +21,10 @@ defmodule Set do
     end
   end
 
-  @deprecated message
   def delete(set, value) do
     target(set).delete(set, value)
   end
 
-  @deprecated message
   def difference(set1, set2) do
     target1 = target(set1)
     target2 = target(set2)
@@ -43,7 +39,6 @@ defmodule Set do
     end
   end
 
-  @deprecated message
   def disjoint?(set1, set2) do
     target1 = target(set1)
     target2 = target(set2)
@@ -61,12 +56,11 @@ defmodule Set do
     end
   end
 
-  @deprecated message
+  @doc false
   def empty(set) do
     target(set).empty(set)
   end
 
-  @deprecated message
   def equal?(set1, set2) do
     target1 = target(set1)
     target2 = target(set2)
@@ -83,7 +77,6 @@ defmodule Set do
     end
   end
 
-  @deprecated message
   def intersection(set1, set2) do
     target1 = target(set1)
     target2 = target(set2)
@@ -98,22 +91,18 @@ defmodule Set do
     end
   end
 
-  @deprecated message
   def member?(set, value) do
     target(set).member?(set, value)
   end
 
-  @deprecated message
   def put(set, value) do
     target(set).put(set, value)
   end
 
-  @deprecated message
   def size(set) do
     target(set).size(set)
   end
 
-  @deprecated message
   def subset?(set1, set2) do
     target1 = target(set1)
     target2 = target(set2)
@@ -125,12 +114,10 @@ defmodule Set do
     end
   end
 
-  @deprecated message
   def to_list(set) do
     target(set).to_list(set)
   end
 
-  @deprecated message
   def union(set1, set2) do
     target1 = target(set1)
     target2 = target(set2)

lib/elixir/lib/stream.ex

@@ -1,15 +1,14 @@
 defmodule Stream do
   @moduledoc """
-  Functions for creating and composing streams.
+  Module for creating and composing streams.
 
-  Streams are composable, lazy enumerables (for an introduction on
-  enumerables, see the `Enum` module). Any enumerable that generates
+  Streams are composable, lazy enumerables. Any enumerable that generates
   items one by one during enumeration is called a stream. For example,
   Elixir's `Range` is a stream:
 
       iex> range = 1..5
       1..5
-      iex> Enum.map(range, &(&1 * 2))
+      iex> Enum.map range, &(&1 * 2)
       [2, 4, 6, 8, 10]
 
   In the example above, as we mapped over the range, the elements being
@@ -122,22 +121,13 @@ defmodule Stream do
 
   ## Transformers
 
-  # TODO: Remove by 2.0
+  # Deprecate on v1.7
   @doc false
-  @deprecated "Use Stream.chunk_every/2 instead"
   def chunk(enum, n), do: chunk(enum, n, n, nil)
 
-  # TODO: Remove by 2.0
+  # Deprecate on v1.7
   @doc false
-  @deprecated "Use Stream.chunk_every/3 instead"
-  def chunk(enum, n, step) do
-    chunk_every(enum, n, step, nil)
-  end
-
-  # TODO: Remove by 2.0
-  @doc false
-  @deprecated "Use Stream.chunk_every/4 instead"
-  def chunk(enum, n, step, leftover)
+  def chunk(enum, n, step, leftover \\ nil)
       when is_integer(n) and n > 0 and is_integer(step) and step > 0 do
     chunk_every(enum, n, step, leftover || :discard)
   end
@@ -145,7 +135,6 @@ defmodule Stream do
   @doc """
   Shortcut to `chunk_every(enum, count, count)`.
   """
-  @doc since: "1.5.0"
   @spec chunk_every(Enumerable.t(), pos_integer) :: Enumerable.t()
   def chunk_every(enum, count), do: chunk_every(enum, count, count, [])
 
@@ -166,20 +155,19 @@ defmodule Stream do
 
   ## Examples
 
-      iex> Stream.chunk_every([1, 2, 3, 4, 5, 6], 2) |> Enum.to_list()
+      iex> Stream.chunk_every([1, 2, 3, 4, 5, 6], 2) |> Enum.to_list
       [[1, 2], [3, 4], [5, 6]]
 
-      iex> Stream.chunk_every([1, 2, 3, 4, 5, 6], 3, 2, :discard) |> Enum.to_list()
+      iex> Stream.chunk_every([1, 2, 3, 4, 5, 6], 3, 2, :discard) |> Enum.to_list
       [[1, 2, 3], [3, 4, 5]]
 
-      iex> Stream.chunk_every([1, 2, 3, 4, 5, 6], 3, 2, [7]) |> Enum.to_list()
+      iex> Stream.chunk_every([1, 2, 3, 4, 5, 6], 3, 2, [7]) |> Enum.to_list
       [[1, 2, 3], [3, 4, 5], [5, 6, 7]]
 
-      iex> Stream.chunk_every([1, 2, 3, 4, 5, 6], 3, 3, []) |> Enum.to_list()
+      iex> Stream.chunk_every([1, 2, 3, 4, 5, 6], 3, 3, []) |> Enum.to_list
       [[1, 2, 3], [4, 5, 6]]
 
   """
-  @doc since: "1.5.0"
   @spec chunk_every(Enumerable.t(), pos_integer, pos_integer, Enumerable.t() | :discard) ::
           Enumerable.t()
   def chunk_every(enum, count, step, leftover \\ [])
@@ -217,11 +205,11 @@ defmodule Stream do
 
   ## Examples
 
-      iex> chunk_fun = fn item, acc ->
-      ...>   if rem(item, 2) == 0 do
-      ...>     {:cont, Enum.reverse([item | acc]), []}
+      iex> chunk_fun = fn i, acc ->
+      ...>   if rem(i, 2) == 0 do
+      ...>     {:cont, Enum.reverse([i | acc]), []}
       ...>   else
-      ...>     {:cont, [item | acc]}
+      ...>     {:cont, [i | acc]}
       ...>   end
       ...> end
       iex> after_fun = fn
@@ -233,7 +221,6 @@ defmodule Stream do
       [[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]]
 
   """
-  @doc since: "1.5.0"
   @spec chunk_while(
           Enumerable.t(),
           acc,
@@ -283,11 +270,11 @@ defmodule Stream do
 
   This function only ever needs to store the last emitted element.
 
-  Elements are compared using `===/2`.
+  Elements are compared using `===`.
 
   ## Examples
 
-      iex> Stream.dedup([1, 2, 3, 3, 2, 1]) |> Enum.to_list()
+      iex> Stream.dedup([1, 2, 3, 3, 2, 1]) |> Enum.to_list
       [1, 2, 3, 2, 1]
 
   """
@@ -302,7 +289,7 @@ defmodule Stream do
 
   ## Examples
 
-      iex> Stream.dedup_by([{1, :x}, {2, :y}, {2, :z}, {1, :x}], fn {x, _} -> x end) |> Enum.to_list()
+      iex> Stream.dedup_by([{1, :x}, {2, :y}, {2, :z}, {1, :x}], fn {x, _} -> x end) |> Enum.to_list
       [{1, :x}, {2, :y}, {1, :x}]
 
   """
@@ -415,7 +402,7 @@ defmodule Stream do
 
   ## Examples
 
-      iex> stream = Stream.each([1, 2, 3], fn x -> send(self(), x) end)
+      iex> stream = Stream.each([1, 2, 3], fn(x) -> send self(), x end)
       iex> Enum.to_list(stream)
       iex> receive do: (x when is_integer(x) -> x)
       1
@@ -443,11 +430,11 @@ defmodule Stream do
 
   ## Examples
 
-      iex> stream = Stream.flat_map([1, 2, 3], fn x -> [x, x * 2] end)
+      iex> stream = Stream.flat_map([1, 2, 3], fn(x) -> [x, x * 2] end)
       iex> Enum.to_list(stream)
       [1, 2, 2, 4, 3, 6]
 
-      iex> stream = Stream.flat_map([1, 2, 3], fn x -> [[x]] end)
+      iex> stream = Stream.flat_map([1, 2, 3], fn(x) -> [[x]] end)
       iex> Enum.to_list(stream)
       [[1], [2], [3]]
 
@@ -463,7 +450,7 @@ defmodule Stream do
 
   ## Examples
 
-      iex> stream = Stream.filter([1, 2, 3], fn x -> rem(x, 2) == 0 end)
+      iex> stream = Stream.filter([1, 2, 3], fn(x) -> rem(x, 2) == 0 end)
       iex> Enum.to_list(stream)
       [2]
 
@@ -475,7 +462,7 @@ defmodule Stream do
 
   @doc false
   # TODO: Remove on 2.0
-  @deprecated "Use Stream.filter/2 + Stream.map/2 instead"
+  # (hard-deprecated in elixir_dispatch)
   def filter_map(enum, filter, mapper) do
     lazy(enum, fn f1 -> R.filter_map(filter, mapper, f1) end)
   end
@@ -534,8 +521,9 @@ defmodule Stream do
       reduce.({command, [acc | collectable]})
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         into.(collectable, :halt)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     else
       {:suspended, [acc | collectable], continuation} ->
         {:suspended, acc, &do_into(continuation, collectable, into, &1)}
@@ -552,7 +540,7 @@ defmodule Stream do
 
   ## Examples
 
-      iex> stream = Stream.map([1, 2, 3], fn x -> x * 2 end)
+      iex> stream = Stream.map([1, 2, 3], fn(x) -> x * 2 end)
       iex> Enum.to_list(stream)
       [2, 4, 6]
 
@@ -572,20 +560,19 @@ defmodule Stream do
 
   ## Examples
 
-      iex> stream = Stream.map_every(1..10, 2, fn x -> x * 2 end)
+      iex> stream = Stream.map_every(1..10, 2, fn(x) -> x * 2 end)
       iex> Enum.to_list(stream)
       [2, 2, 6, 4, 10, 6, 14, 8, 18, 10]
 
-      iex> stream = Stream.map_every([1, 2, 3, 4, 5], 1, fn x -> x * 2 end)
+      iex> stream = Stream.map_every([1, 2, 3, 4, 5], 1, fn(x) -> x * 2 end)
       iex> Enum.to_list(stream)
       [2, 4, 6, 8, 10]
 
-      iex> stream = Stream.map_every(1..5, 0, fn x -> x * 2 end)
+      iex> stream = Stream.map_every(1..5, 0, fn(x) -> x * 2 end)
       iex> Enum.to_list(stream)
       [1, 2, 3, 4, 5]
 
   """
-  @doc since: "1.4.0"
   @spec map_every(Enumerable.t(), non_neg_integer, (element -> any)) :: Enumerable.t()
   def map_every(enum, nth, fun)
 
@@ -603,7 +590,7 @@ defmodule Stream do
 
   ## Examples
 
-      iex> stream = Stream.reject([1, 2, 3], fn x -> rem(x, 2) == 0 end)
+      iex> stream = Stream.reject([1, 2, 3], fn(x) -> rem(x, 2) == 0 end)
       iex> Enum.to_list(stream)
       [1, 3]
 
@@ -624,13 +611,13 @@ defmodule Stream do
   Open up a file, replace all `#` by `%` and stream to another file
   without loading the whole file in memory:
 
-      File.stream!("/path/to/file")
+      stream = File.stream!("code")
       |> Stream.map(&String.replace(&1, "#", "%"))
-      |> Stream.into(File.stream!("/path/to/other/file"))
-      |> Stream.run()
+      |> Stream.into(File.stream!("new"))
+      |> Stream.run
 
-  No computation will be done until we call one of the `Enum` functions
-  or `run/1`.
+  No computation will be done until we call one of the Enum functions
+  or `Stream.run/1`.
   """
   @spec run(Enumerable.t()) :: :ok
   def run(stream) do
@@ -765,7 +752,7 @@ defmodule Stream do
 
   ## Examples
 
-      iex> Stream.timer(10) |> Enum.to_list()
+      iex> Stream.timer(10) |> Enum.to_list
       [0]
 
   """
@@ -857,8 +844,9 @@ defmodule Stream do
       next.({:cont, []})
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         do_after(after_fun, user_acc)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     else
       {:suspended, vals, next} ->
         do_transform_user(:lists.reverse(vals), user_acc, :cont, next, inner_acc, funs)
@@ -879,9 +867,10 @@ defmodule Stream do
       user.(val, user_acc)
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         next.({:halt, []})
         do_after(after_fun, user_acc)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     else
       {[], user_acc} ->
         do_transform_user(vals, user_acc, next_op, next, inner_acc, funs)
@@ -908,9 +897,10 @@ defmodule Stream do
       reduce.(inner_acc)
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         next.({:halt, []})
         do_after(after_fun, user_acc)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     else
       {:done, acc} ->
         do_transform_user(vals, user_acc, next_op, next, {:cont, acc}, funs)
@@ -933,13 +923,15 @@ defmodule Stream do
       reduce.({op, [:outer | inner_acc]})
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         next.({:halt, []})
         do_after(after_fun, user_acc)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     else
       # Only take into account outer halts when the op is not halt itself.
       # Otherwise, we were the ones wishing to halt, so we should just stop.
-      {:halted, [:outer | acc]} when op != :halt ->
+      {:halted, [:outer | acc]}
+      when op != :halt ->
         do_transform_user(vals, user_acc, next_op, next, {:cont, acc}, funs)
 
       {:halted, [_ | acc]} ->
@@ -976,11 +968,11 @@ defmodule Stream do
   Keep in mind that, in order to know if an element is unique
   or not, this function needs to store all unique values emitted
   by the stream. Therefore, if the stream is infinite, the number
-  of items stored will grow infinitely, never being garbage-collected.
+  of items stored will grow infinitely, never being garbage collected.
 
   ## Examples
 
-      iex> Stream.uniq([1, 2, 3, 3, 2, 1]) |> Enum.to_list()
+      iex> Stream.uniq([1, 2, 3, 3, 2, 1]) |> Enum.to_list
       [1, 2, 3]
 
   """
@@ -991,7 +983,7 @@ defmodule Stream do
 
   @doc false
   # TODO: Remove on 2.0
-  @deprecated "Use Stream.uniq_by/2 instead"
+  # (hard-deprecated in elixir_dispatch)
   def uniq(enum, fun) do
     uniq_by(enum, fun)
   end
@@ -1006,14 +998,14 @@ defmodule Stream do
   Keep in mind that, in order to know if an element is unique
   or not, this function needs to store all unique values emitted
   by the stream. Therefore, if the stream is infinite, the number
-  of items stored will grow infinitely, never being garbage-collected.
+  of items stored will grow infinitely, never being garbage collected.
 
   ## Example
 
-      iex> Stream.uniq_by([{1, :x}, {2, :y}, {1, :z}], fn {x, _} -> x end) |> Enum.to_list()
+      iex> Stream.uniq_by([{1, :x}, {2, :y}, {1, :z}], fn {x, _} -> x end) |> Enum.to_list
       [{1, :x}, {2, :y}]
 
-      iex> Stream.uniq_by([a: {:tea, 2}, b: {:tea, 2}, c: {:coffee, 1}], fn {_, y} -> y end) |> Enum.to_list()
+      iex> Stream.uniq_by([a: {:tea, 2}, b: {:tea, 2}, c: {:coffee, 1}], fn {_, y} -> y end) |> Enum.to_list
       [a: {:tea, 2}, c: {:coffee, 1}]
 
   """
@@ -1090,8 +1082,8 @@ defmodule Stream do
   ## Examples
 
       iex> concat = Stream.concat(1..3, 4..6)
-      iex> cycle = Stream.cycle([:a, :b, :c])
-      iex> Stream.zip(concat, cycle) |> Enum.to_list()
+      iex> cycle  = Stream.cycle([:a, :b, :c])
+      iex> Stream.zip(concat, cycle) |> Enum.to_list
       [{1, :a}, {2, :b}, {3, :c}, {4, :a}, {5, :b}, {6, :c}]
 
   """
@@ -1108,11 +1100,10 @@ defmodule Stream do
 
       iex> concat = Stream.concat(1..3, 4..6)
       iex> cycle = Stream.cycle(["foo", "bar", "baz"])
-      iex> Stream.zip([concat, [:a, :b, :c], cycle]) |> Enum.to_list()
+      iex> Stream.zip([concat, [:a, :b, :c], cycle]) |> Enum.to_list
       [{1, :a, "foo"}, {2, :b, "bar"}, {3, :c, "baz"}]
 
   """
-  @doc since: "1.4.0"
   @spec zip([Enumerable.t()]) :: Enumerable.t()
   @spec zip(Enumerable.t()) :: Enumerable.t()
   def zip(enumerables) do
@@ -1124,7 +1115,7 @@ defmodule Stream do
 
     enum_funs =
       Enum.map(enumerables, fn enum ->
-        {&Enumerable.reduce(enum, &1, step), [], :cont}
+        {&Enumerable.reduce(enum, &1, step), :cont}
       end)
 
     do_zip(enum_funs, acc, fun)
@@ -1151,8 +1142,9 @@ defmodule Stream do
       do_zip_next_tuple(zips, acc, callback, [], [])
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         do_zip_close(zips)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     else
       {:next, buffer, acc} ->
         do_zip(buffer, acc, callback)
@@ -1165,20 +1157,18 @@ defmodule Stream do
   # do_zip_next_tuple/5 computes the next tuple formed by
   # the next element of each zipped stream.
 
-  defp do_zip_next_tuple([{_, [], :halt} | zips], acc, _callback, _yielded_elems, buffer) do
+  defp do_zip_next_tuple([{_, :halt} | zips], acc, _callback, _yielded_elems, buffer) do
     do_zip_close(:lists.reverse(buffer, zips))
     {:done, acc}
   end
 
-  defp do_zip_next_tuple([{fun, [], :cont} | zips], acc, callback, yielded_elems, buffer) do
+  defp do_zip_next_tuple([{fun, :cont} | zips], acc, callback, yielded_elems, buffer) do
     case fun.({:cont, []}) do
-      {:suspended, [elem | next_acc], fun} ->
-        next_buffer = [{fun, next_acc, :cont} | buffer]
-        do_zip_next_tuple(zips, acc, callback, [elem | yielded_elems], next_buffer)
+      {:suspended, [elem], fun} ->
+        do_zip_next_tuple(zips, acc, callback, [elem | yielded_elems], [{fun, :cont} | buffer])
 
-      {_, [elem | next_acc]} ->
-        next_buffer = [{fun, next_acc, :halt} | buffer]
-        do_zip_next_tuple(zips, acc, callback, [elem | yielded_elems], next_buffer)
+      {_, [elem]} ->
+        do_zip_next_tuple(zips, acc, callback, [elem | yielded_elems], [{fun, :halt} | buffer])
 
       {_, []} ->
         # The current zipped stream terminated, so we close all the streams
@@ -1188,12 +1178,6 @@ defmodule Stream do
     end
   end
 
-  defp do_zip_next_tuple([{fun, zip_acc, zip_op} | zips], acc, callback, yielded_elems, buffer) do
-    [elem | rest] = zip_acc
-    next_buffer = [{fun, rest, zip_op} | buffer]
-    do_zip_next_tuple(zips, acc, callback, [elem | yielded_elems], next_buffer)
-  end
-
   defp do_zip_next_tuple([] = _zips, acc, callback, yielded_elems, buffer) do
     # "yielded_elems" is a reversed list of results for the current iteration of
     # zipping: it needs to be reversed and converted to a tuple to have the next
@@ -1203,11 +1187,11 @@ defmodule Stream do
   end
 
   defp do_zip_close(zips) do
-    :lists.foreach(fn {fun, _, _} -> fun.({:halt, []}) end, zips)
+    :lists.foreach(fn {fun, _} -> fun.({:halt, []}) end, zips)
   end
 
-  defp do_zip_step(x, acc) do
-    {:suspend, :lists.reverse([x | acc])}
+  defp do_zip_step(x, []) do
+    {:suspend, [x]}
   end
 
   ## Sources
@@ -1284,7 +1268,7 @@ defmodule Stream do
 
   ## Examples
 
-      iex> Stream.iterate(0, &(&1 + 1)) |> Enum.take(5)
+      iex> Stream.iterate(0, &(&1+1)) |> Enum.take(5)
       [0, 1, 2, 3, 4]
 
   """
@@ -1381,8 +1365,9 @@ defmodule Stream do
       end
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         after_fun.(next_acc)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     else
       {:opt, acc, next_acc} ->
         do_resource(next_acc, next_fun, acc, fun, after_fun)
@@ -1406,8 +1391,9 @@ defmodule Stream do
       reduce.(acc)
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         after_fun.(next_acc)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     else
       {:done, acc} ->
         do_resource(next_acc, next_fun, {:cont, acc}, fun, after_fun)
@@ -1425,8 +1411,9 @@ defmodule Stream do
       reduce.({op, [:outer | acc]})
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         after_fun.(next_acc)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     else
       {:halted, [:outer | acc]} ->
         do_resource(next_acc, next_fun, {:cont, acc}, fun, after_fun)
@@ -1458,10 +1445,7 @@ defmodule Stream do
 
   ## Examples
 
-      iex> Stream.unfold(5, fn
-      ...>   0 -> nil
-      ...>   n -> {n, n - 1}
-      ...> end) |> Enum.to_list()
+      iex> Stream.unfold(5, fn 0 -> nil; n -> {n, n-1} end) |> Enum.to_list()
       [5, 4, 3, 2, 1]
 
   """
@@ -1490,17 +1474,16 @@ defmodule Stream do
 
   ## Examples
 
-      iex> Stream.intersperse([1, 2, 3], 0) |> Enum.to_list()
+      iex> Stream.intersperse([1, 2, 3], 0) |> Enum.to_list
       [1, 0, 2, 0, 3]
 
-      iex> Stream.intersperse([1], 0) |> Enum.to_list()
+      iex> Stream.intersperse([1], 0) |> Enum.to_list
       [1]
 
-      iex> Stream.intersperse([], 0) |> Enum.to_list()
+      iex> Stream.intersperse([], 0) |> Enum.to_list
       []
 
   """
-  @doc since: "1.6.0"
   @spec intersperse(Enumerable.t(), any) :: Enumerable.t()
   def intersperse(enumerable, intersperse_element) do
     Stream.transform(enumerable, false, fn

lib/elixir/lib/string.ex

@@ -7,7 +7,7 @@ defmodule String do
   ## Codepoints and grapheme cluster
 
   The functions in this module act according to the Unicode
-  Standard, version 11.0.0.
+  Standard, version 10.0.0.
 
   As per the standard, a codepoint is a single Unicode Character,
   which may be represented by one or more bytes.
@@ -203,31 +203,18 @@ defmodule String do
   is generated at runtime and does not survive compile term.
   """
 
-  @typedoc """
-  A UTF-8 encoded binary.
-
-  Note `String.t()` and `binary()` are equivalent to analysis tools.
-  Although, for those reading the documentation, `String.t()` implies
-  it is a UTF-8 encoded binary.
-  """
   @type t :: binary
-
-  @typedoc "A UTF-8 codepoint. It may be one or more bytes."
   @type codepoint :: t
-
-  @typedoc "Multiple codepoints that may be perceived as a single character by readers"
   @type grapheme :: t
-
-  @typedoc "Pattern used in functions like `replace/3` and `split/2`"
   @type pattern :: t | [t] | :binary.cp()
 
   @conditional_mappings [:greek]
 
   @doc """
-  Checks if a string contains only printable characters up to `character_limit`.
+  Checks if a string contains only printable characters.
 
-  Takes an optional `character_limit` as a second argument. If `character_limit` is `0`, this
-  function will return `true`.
+  Takes an optional `limit` as a second argument. `printable?/2` only
+  checks the printability of the string up to the `limit`.
 
   ## Examples
 
@@ -240,47 +227,37 @@ defmodule String do
       iex> String.printable?("abc" <> <<0>>, 2)
       true
 
-      iex> String.printable?("abc" <> <<0>>, 0)
-      true
-
   """
-  @spec printable?(t, 0) :: true
-  @spec printable?(t, pos_integer | :infinity) :: boolean
-  def printable?(string, character_limit \\ :infinity)
-      when is_binary(string) and
-             (character_limit == :infinity or
-                (is_integer(character_limit) and character_limit >= 0)) do
-    recur_printable?(string, character_limit)
-  end
+  @spec printable?(t) :: boolean
+  @spec printable?(t, non_neg_integer | :infinity) :: boolean
+  def printable?(string, counter \\ :infinity)
 
-  defp recur_printable?(_string, 0), do: true
-  defp recur_printable?(<<>>, _character_limit), do: true
+  def printable?(<<>>, _), do: true
+  def printable?(_, 0), do: true
 
   for char <- 0x20..0x7E do
-    defp recur_printable?(<<unquote(char), rest::binary>>, character_limit) do
-      recur_printable?(rest, decrement(character_limit))
+    def printable?(<<unquote(char), rest::binary>>, counter) do
+      printable?(rest, decrement(counter))
     end
   end
 
   for char <- '\n\r\t\v\b\f\e\d\a' do
-    defp recur_printable?(<<unquote(char), rest::binary>>, character_limit) do
-      recur_printable?(rest, decrement(character_limit))
+    def printable?(<<unquote(char), rest::binary>>, counter) do
+      printable?(rest, decrement(counter))
     end
   end
 
-  defp recur_printable?(<<char::utf8, rest::binary>>, character_limit)
-       when char in 0xA0..0xD7FF
-       when char in 0xE000..0xFFFD
-       when char in 0x10000..0x10FFFF do
-    recur_printable?(rest, decrement(character_limit))
+  def printable?(<<char::utf8, rest::binary>>, counter)
+      when char in 0xA0..0xD7FF
+      when char in 0xE000..0xFFFD
+      when char in 0x10000..0x10FFFF do
+    printable?(rest, decrement(counter))
   end
 
-  defp recur_printable?(_string, _character_limit) do
-    false
-  end
+  def printable?(binary, _) when is_binary(binary), do: false
 
   defp decrement(:infinity), do: :infinity
-  defp decrement(character_limit), do: character_limit - 1
+  defp decrement(counter), do: counter - 1
 
   @doc ~S"""
   Divides a string into substrings at each Unicode whitespace
@@ -310,8 +287,7 @@ defmodule String do
   Divides a string into substrings based on a pattern.
 
   Returns a list of these substrings. The pattern can
-  be a string, a list of strings, a regular expression,
-  or a compiled pattern.
+  be a string, a list of strings, or a regular expression.
 
   The string is split into as many parts as possible by
   default, but can be controlled via the `:parts` option.
@@ -367,12 +343,6 @@ defmodule String do
       iex> String.split("abc", ~r{b}, include_captures: true)
       ["a", "b", "c"]
 
-  A compiled pattern:
-
-      iex> pattern = :binary.compile_pattern([" ", ","])
-      iex> String.split("1,2 3,4", pattern)
-      ["1", "2", "3", "4"]
-
   Splitting on empty string returns graphemes:
 
       iex> String.split("abc", "")
@@ -387,15 +357,21 @@ defmodule String do
       iex> String.split("abc", "", parts: 3)
       ["", "a", "bc"]
 
+  A precompiled pattern can also be given:
+
+      iex> pattern = :binary.compile_pattern([" ", ","])
+      iex> String.split("1,2 3,4", pattern)
+      ["1", "2", "3", "4"]
+
   Note this function can split within or across grapheme boundaries.
   For example, take the grapheme "é" which is made of the characters
-  "e" and the acute accent. The following returns the acute accent separately:
+  "e" and the acute accent. The following returns true:
 
       iex> String.split(String.normalize("é", :nfd), "e")
       ["", "́"]
 
   However, if "é" is represented by the single character "e with acute"
-  accent, then it will return "e with acute":
+  accent, then it will return false:
 
       iex> String.split(String.normalize("é", :nfc), "e")
       ["é"]
@@ -457,8 +433,8 @@ defmodule String do
   @doc """
   Returns an enumerable that splits a string on demand.
 
-  This is in contrast to `split/3` which splits the
-  entire string upfront.
+  This is in contrast to `split/3` which splits all
+  the string upfront.
 
   Note splitter does not support regular expressions
   (as it is often more efficient to have the regular
@@ -480,12 +456,6 @@ defmodule String do
       iex> String.splitter("abcd", "", trim: true) |> Enum.take(10)
       ["a", "b", "c", "d"]
 
-  A compiled pattern can also be given:
-
-      iex> pattern = :binary.compile_pattern([" ", ","])
-      iex> String.splitter("1,2 3,4 5,6 7,8,...,99999", pattern) |> Enum.take(4)
-      ["1", "2", "3", "4"]
-
   """
   @spec splitter(t, pattern, keyword) :: Enumerable.t()
   def splitter(string, pattern, options \\ [])
@@ -538,19 +508,19 @@ defmodule String do
 
   ## Examples
 
-      iex> String.split_at("sweetelixir", 5)
+      iex> String.split_at "sweetelixir", 5
       {"sweet", "elixir"}
 
-      iex> String.split_at("sweetelixir", -6)
+      iex> String.split_at "sweetelixir", -6
       {"sweet", "elixir"}
 
-      iex> String.split_at("abc", 0)
+      iex> String.split_at "abc", 0
       {"", "abc"}
 
-      iex> String.split_at("abc", 1000)
+      iex> String.split_at "abc", 1000
       {"abc", ""}
 
-      iex> String.split_at("abc", -1000)
+      iex> String.split_at "abc", -1000
       {"", "abc"}
 
   """
@@ -674,19 +644,15 @@ defmodule String do
   end
 
   def upcase(string, :ascii) when is_binary(string) do
-    IO.iodata_to_binary(upcase_ascii(string))
+    for <<x <- string>>,
+      do: if(x >= ?a and x <= ?z, do: <<x - 32>>, else: <<x>>),
+      into: ""
   end
 
   def upcase(string, mode) when mode in @conditional_mappings do
     String.Casing.upcase(string, [], mode)
   end
 
-  defp upcase_ascii(<<char, rest::bits>>) when char >= ?a and char <= ?z,
-    do: [char - 32 | upcase_ascii(rest)]
-
-  defp upcase_ascii(<<char, rest::bits>>), do: [char | upcase_ascii(rest)]
-  defp upcase_ascii(<<>>), do: []
-
   @doc """
   Converts all characters in the given string to lowercase according to `mode`.
 
@@ -734,19 +700,15 @@ defmodule String do
   end
 
   def downcase(string, :ascii) when is_binary(string) do
-    IO.iodata_to_binary(downcase_ascii(string))
+    for <<x <- string>>,
+      do: if(x >= ?A and x <= ?Z, do: <<x + 32>>, else: <<x>>),
+      into: ""
   end
 
   def downcase(string, mode) when mode in @conditional_mappings do
     String.Casing.downcase(string, [], mode)
   end
 
-  defp downcase_ascii(<<char, rest::bits>>) when char >= ?A and char <= ?Z,
-    do: [char + 32 | downcase_ascii(rest)]
-
-  defp downcase_ascii(<<char, rest::bits>>), do: [char | downcase_ascii(rest)]
-  defp downcase_ascii(<<>>), do: []
-
   @doc """
   Converts the first character in the given string to
   uppercase and the remainder to lowercase according to `mode`.
@@ -783,12 +745,12 @@ defmodule String do
 
   @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use String.trim_trailing/1 instead"
+  # (hard-deprecated in elixir_dispatch)
   defdelegate rstrip(binary), to: String.Break, as: :trim_trailing
 
   @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use String.trim_trailing/2 with a binary as second argument instead"
+  # (hard-deprecated in elixir_dispatch)
   def rstrip(string, char) when is_integer(char) do
     replace_trailing(string, <<char::utf8>>, "")
   end
@@ -998,26 +960,26 @@ defmodule String do
 
   @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use String.trim_leading/1 instead"
+  # (hard-deprecated in elixir_dispatch)
   defdelegate lstrip(binary), to: String.Break, as: :trim_leading
 
   @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use String.trim_leading/2 with a binary as second argument instead"
+  # (hard-deprecated in elixir_dispatch)
   def lstrip(string, char) when is_integer(char) do
     replace_leading(string, <<char::utf8>>, "")
   end
 
   @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use String.trim/1 instead"
+  # (hard-deprecated in elixir_dispatch)
   def strip(string) do
     trim(string)
   end
 
   @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use String.trim/2 with a binary second argument instead"
+  # (hard-deprecated in elixir_dispatch)
   def strip(string, char) do
     trim(string, <<char::utf8>>)
   end
@@ -1242,29 +1204,15 @@ defmodule String do
 
   @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use String.pad_leading/2 instead"
-  def rjust(subject, len) do
-    rjust(subject, len, ?\s)
-  end
-
-  @doc false
-  # TODO: Remove by 2.0
-  @deprecated "Use String.pad_leading/3 with a binary padding instead"
-  def rjust(subject, len, pad) when is_integer(pad) and is_integer(len) and len >= 0 do
+  # (hard-deprecated in elixir_dispatch)
+  def rjust(subject, len, pad \\ ?\s) when is_integer(pad) and is_integer(len) and len >= 0 do
     pad(:leading, subject, len, [<<pad::utf8>>])
   end
 
   @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use String.pad_trailing/2 instead"
-  def ljust(subject, len) do
-    ljust(subject, len, ?\s)
-  end
-
-  @doc false
-  # TODO: Remove by 2.0
-  @deprecated "Use String.pad_trailing/3 with a binary padding instead"
-  def ljust(subject, len, pad) when is_integer(pad) and is_integer(len) and len >= 0 do
+  # (hard-deprecated in elixir_dispatch)
+  def ljust(subject, len, pad \\ ?\s) when is_integer(pad) and is_integer(len) and len >= 0 do
     pad(:trailing, subject, len, [<<pad::utf8>>])
   end
 
@@ -1272,7 +1220,7 @@ defmodule String do
   Returns a new string created by replacing occurrences of `pattern` in
   `subject` with `replacement`.
 
-  The `pattern` may be a string, a regular expression, or a compiled pattern.
+  The `pattern` may be a string or a regular expression.
 
   By default it replaces all occurrences but this behaviour can be controlled
   through the `:global` option; see the "Options" section below.
@@ -1323,12 +1271,6 @@ defmodule String do
       iex> String.replace("a,b,c", ",", "[]", insert_replaced: [1, 1])
       "a[,,]b[,,]c"
 
-  A compiled pattern can also be given:
-
-      iex> pattern = :binary.compile_pattern(",")
-      iex> String.replace("a,b,c", pattern, "[]", insert_replaced: 2)
-      "a[],b[],c"
-
   When an empty string is provided as a `pattern`, the function will treat it as
   an implicit empty string between each grapheme and the string will be
   interspersed. If an empty string is provided as `replacement` the `subject`
@@ -1401,7 +1343,7 @@ defmodule String do
       "̀e"
       iex> String.reverse("̀e")
       "è"
-      iex> String.reverse(String.reverse("̀e"))
+      iex> String.reverse String.reverse("̀e")
       "è"
 
   In the first example the accent is before the vowel, so
@@ -1504,13 +1446,13 @@ defmodule String do
       iex> String.valid?("ø")
       true
 
-      iex> String.valid?(<<0xFFFF::16>>)
+      iex> String.valid?(<<0xFFFF :: 16>>)
       false
 
       iex> String.valid?(<<0xEF, 0xB7, 0x90>>)
       true
 
-      iex> String.valid?("asd" <> <<0xFFFF::16>>)
+      iex> String.valid?("asd" <> <<0xFFFF :: 16>>)
       false
 
   """
@@ -1523,7 +1465,7 @@ defmodule String do
 
   @doc false
   # TODO: Remove on 2.0
-  @deprecated "Use String.valid?/1 instead"
+  # (hard-deprecated in elixir_dispatch)
   def valid_character?(string) do
     case string do
       <<_::utf8>> -> valid?(string)
@@ -1632,7 +1574,7 @@ defmodule String do
   @spec next_grapheme(t) :: {grapheme, t} | nil
   def next_grapheme(binary) do
     case next_grapheme_size(binary) do
-      {size, rest} -> {binary_part(binary, 0, size), rest}
+      {size, rest} -> {:binary.part(binary, 0, size), rest}
       nil -> nil
     end
   end
@@ -1794,7 +1736,7 @@ defmodule String do
       ""
 
   """
-  @spec slice(t, integer, non_neg_integer) :: grapheme
+  @spec slice(t, integer, integer) :: grapheme
 
   def slice(_, _, 0) do
     ""
@@ -1923,55 +1865,36 @@ defmodule String do
   @doc """
   Returns `true` if `string` starts with any of the prefixes given.
 
-  `prefix` can be either a string, a list of strings, or a compiled
-  pattern.
+  `prefix` can be either a single prefix or a list of prefixes.
 
   ## Examples
 
-      iex> String.starts_with?("elixir", "eli")
+      iex> String.starts_with? "elixir", "eli"
       true
-      iex> String.starts_with?("elixir", ["erlang", "elixir"])
+      iex> String.starts_with? "elixir", ["erlang", "elixir"]
       true
-      iex> String.starts_with?("elixir", ["erlang", "ruby"])
+      iex> String.starts_with? "elixir", ["erlang", "ruby"]
       false
 
-  A compiled pattern can also be given:
-
-      iex> pattern = :binary.compile_pattern(["erlang", "elixir"])
-      iex> String.starts_with?("elixir", pattern)
-      true
-
   An empty string will always match:
 
-      iex> String.starts_with?("elixir", "")
+      iex> String.starts_with? "elixir", ""
       true
-      iex> String.starts_with?("elixir", ["", "other"])
+      iex> String.starts_with? "elixir", ["", "other"]
       true
 
   """
-  @spec starts_with?(t, pattern) :: boolean
-  def starts_with?(string, prefix) when is_binary(string) and is_binary(prefix) do
-    starts_with_string?(string, byte_size(string), prefix)
+  @spec starts_with?(t, t | [t]) :: boolean
+  def starts_with?(string, []) when is_binary(string) do
+    false
   end
 
   def starts_with?(string, prefix) when is_binary(string) and is_list(prefix) do
-    string_size = byte_size(string)
-    Enum.any?(prefix, &starts_with_string?(string, string_size, &1))
+    "" in prefix or Kernel.match?({0, _}, :binary.match(string, prefix))
   end
 
   def starts_with?(string, prefix) when is_binary(string) do
-    Kernel.match?({0, _}, :binary.match(string, prefix))
-  end
-
-  @compile {:inline, starts_with_string?: 3}
-  defp starts_with_string?(string, string_size, prefix) when is_binary(prefix) do
-    prefix_size = byte_size(prefix)
-
-    if prefix_size <= string_size do
-      prefix == binary_part(string, 0, prefix_size)
-    else
-      false
-    end
+    "" == prefix or Kernel.match?({0, _}, :binary.match(string, prefix))
   end
 
   @doc """
@@ -1981,40 +1904,39 @@ defmodule String do
 
   ## Examples
 
-      iex> String.ends_with?("language", "age")
+      iex> String.ends_with? "language", "age"
       true
-      iex> String.ends_with?("language", ["youth", "age"])
+      iex> String.ends_with? "language", ["youth", "age"]
       true
-      iex> String.ends_with?("language", ["youth", "elixir"])
+      iex> String.ends_with? "language", ["youth", "elixir"]
       false
 
   An empty suffix will always match:
 
-      iex> String.ends_with?("language", "")
+      iex> String.ends_with? "language", ""
       true
-      iex> String.ends_with?("language", ["", "other"])
+      iex> String.ends_with? "language", ["", "other"]
       true
 
   """
   @spec ends_with?(t, t | [t]) :: boolean
-  def ends_with?(string, suffix) when is_binary(string) and is_binary(suffix) do
-    ends_with_string?(string, byte_size(string), suffix)
+  def ends_with?(string, suffixes) when is_binary(string) and is_list(suffixes) do
+    Enum.any?(suffixes, &do_ends_with(string, &1))
   end
 
-  def ends_with?(string, suffix) when is_binary(string) and is_list(suffix) do
+  def ends_with?(string, suffix) when is_binary(string) do
+    do_ends_with(string, suffix)
+  end
+
+  defp do_ends_with(_string, "") do
+    true
+  end
+
+  defp do_ends_with(string, suffix) when is_binary(suffix) do
     string_size = byte_size(string)
-    Enum.any?(suffix, &ends_with_string?(string, string_size, &1))
-  end
-
-  @compile {:inline, ends_with_string?: 3}
-  defp ends_with_string?(string, string_size, suffix) when is_binary(suffix) do
     suffix_size = byte_size(suffix)
-
-    if suffix_size <= string_size do
-      suffix == binary_part(string, string_size - suffix_size, suffix_size)
-    else
-      false
-    end
+    scope = {string_size - suffix_size, suffix_size}
+    suffix_size <= string_size and :nomatch != :binary.match(string, suffix, scope: scope)
   end
 
   @doc """
@@ -2037,40 +1959,39 @@ defmodule String do
   @doc """
   Checks if `string` contains any of the given `contents`.
 
-  `contents` can be either a string, a list of strings,
-  or a compiled pattern.
+  `contents` can be either a single string or a list of strings.
 
   ## Examples
 
-      iex> String.contains?("elixir of life", "of")
+      iex> String.contains? "elixir of life", "of"
       true
-      iex> String.contains?("elixir of life", ["life", "death"])
+      iex> String.contains? "elixir of life", ["life", "death"]
       true
-      iex> String.contains?("elixir of life", ["death", "mercury"])
+      iex> String.contains? "elixir of life", ["death", "mercury"]
       false
 
-  The argument can also be a compiled pattern:
-
-      iex> pattern = :binary.compile_pattern(["life", "death"])
-      iex> String.contains?("elixir of life", pattern)
-      true
-
   An empty string will always match:
 
-      iex> String.contains?("elixir of life", "")
+      iex> String.contains? "elixir of life", ""
       true
-      iex> String.contains?("elixir of life", ["", "other"])
+      iex> String.contains? "elixir of life", ["", "other"]
+      true
+
+  The argument can also be a precompiled pattern:
+
+      iex> pattern = :binary.compile_pattern(["life", "death"])
+      iex> String.contains? "elixir of life", pattern
       true
 
   Note this function can match within or across grapheme boundaries.
   For example, take the grapheme "é" which is made of the characters
-  "e" and the acute accent. The following returns `true`:
+  "e" and the acute accent. The following returns true:
 
       iex> String.contains?(String.normalize("é", :nfd), "e")
       true
 
   However, if "é" is represented by the single character "e with acute"
-  accent, then it will return `false`:
+  accent, then it will return false:
 
       iex> String.contains?(String.normalize("é", :nfc), "e")
       false
@@ -2103,7 +2024,6 @@ defmodule String do
 
       iex> String.to_charlist("æß")
       'æß'
-
   """
   @spec to_charlist(t) :: charlist
   def to_charlist(string) when is_binary(string) do
@@ -2123,14 +2043,14 @@ defmodule String do
   Converts a string to an atom.
 
   Warning: this function creates atoms dynamically and atoms are
-  not garbage-collected. Therefore, `string` should not be an
+  not garbage collected. Therefore, `string` should not be an
   untrusted value, such as input received from a socket or during
   a web request. Consider using `to_existing_atom/1` instead.
 
   By default, the maximum number of atoms is `1_048_576`. This limit
   can be raised or lowered using the VM option `+t`.
 
-  The maximum atom size is of 255 characters. Prior to Erlang/OTP 20,
+  The maximum atom size is of 255 characters. Prior to OTP 20,
   only latin1 characters are allowed.
 
   Inlined by the compiler.
@@ -2149,7 +2069,7 @@ defmodule String do
   @doc """
   Converts a string to an existing atom.
 
-  The maximum atom size is of 255 characters. Prior to Erlang/OTP 20,
+  The maximum atom size is of 255 characters. Prior to OTP 20,
   only latin1 characters are allowed.
 
   Inlined by the compiler.
@@ -2240,8 +2160,6 @@ defmodule String do
       0.8222222222222223
       iex> String.jaro_distance("even", "odd")
       0.0
-      iex> String.jaro_distance("same", "same")
-      1.0
 
   """
   @spec jaro_distance(t, t) :: float
@@ -2336,16 +2254,16 @@ defmodule String do
       [eq: "fox ", del: "ho", ins: "jum", eq: "ps over the ", del: "dog", ins: "lazy cat"]
 
   """
-  @spec myers_difference(t, t) :: [{:eq | :ins | :del, t}]
+  @spec myers_difference(t, t) :: [{:eq | :ins | :del, t}] | nil
   def myers_difference(string1, string2) do
     graphemes(string1)
     |> List.myers_difference(graphemes(string2))
     |> Enum.map(fn {kind, chars} -> {kind, IO.iodata_to_binary(chars)} end)
   end
 
-  @doc false
   # TODO: Remove by 2.0
-  @deprecated "Use String.to_charlist/1 instead"
+  # (hard-deprecated in elixir_dispatch)
+  @doc false
   @spec to_char_list(t) :: charlist
   def to_char_list(string), do: String.to_charlist(string)
 end

lib/elixir/lib/string_io.ex

@@ -15,7 +15,7 @@ defmodule StringIO do
 
   use GenServer
 
-  @doc ~S"""
+  @doc """
   Creates an IO device.
 
   `string` will be the initial input of the newly created
@@ -23,59 +23,7 @@ defmodule StringIO do
 
   If the `:capture_prompt` option is set to `true`,
   prompts (specified as arguments to `IO.get*` functions)
-  are captured in the output.
-
-  The device will be created and sent to the function given.
-  When the function returns, the device will be closed. The final
-  result will be a tuple with `:ok` and the result of the function.
-
-  ## Examples
-
-      iex> StringIO.open("foo", [], fn(pid) ->
-      ...>   input = IO.gets(pid, ">")
-      ...>   IO.write(pid, "The input was #{input}")
-      ...>   StringIO.contents(pid)
-      ...> end)
-      {:ok, {"", "The input was foo"}}
-
-      iex> StringIO.open("foo", [capture_prompt: true], fn(pid) ->
-      ...>   input = IO.gets(pid, ">")
-      ...>   IO.write(pid, "The input was #{input}")
-      ...>   StringIO.contents(pid)
-      ...> end)
-      {:ok, {"", ">The input was foo"}}
-
-  """
-  @doc since: "1.7.0"
-  @spec open(binary, keyword, (pid -> res)) :: {:ok, res} when res: var
-  def open(string, options, function)
-      when is_binary(string) and is_list(options) and is_function(function, 1) do
-    {:ok, pid} = GenServer.start_link(__MODULE__, {string, options}, [])
-
-    try do
-      {:ok, function.(pid)}
-    after
-      {:ok, {_input, _output}} = close(pid)
-    end
-  end
-
-  @doc ~S"""
-  Creates an IO device.
-
-  `string` will be the initial input of the newly created
-  device.
-
-  `options_or_function` can be a keyword list of options or
-  a function.
-
-  If options are provided, the result will be `{:ok, pid}`, returning the
-  IO device created. The option `:capture_prompt`, when set to `true`, causes
-  prompts (which are specified as arguments to `IO.get*` functions) to be
-  included in the device's output.
-
-  If a function is provided, the device will be created and sent to the
-  function. When the function returns, the device will be closed. The final
-  result will be a tuple with `:ok` and the result of the function.
+  are captured.
 
   ## Examples
 
@@ -91,25 +39,10 @@ defmodule StringIO do
       iex> StringIO.contents(pid)
       {"", ">"}
 
-      iex> StringIO.open("foo", fn(pid) ->
-      ...>   input = IO.gets(pid, ">")
-      ...>   IO.write(pid, "The input was #{input}")
-      ...>   StringIO.contents(pid)
-      ...> end)
-      {:ok, {"", "The input was foo"}}
-
   """
   @spec open(binary, keyword) :: {:ok, pid}
-  @spec open(binary, (pid -> res)) :: {:ok, res} when res: var
-  def open(path, options_or_function \\ [])
-
-  def open(string, options_or_function) when is_binary(string) and is_list(options_or_function) do
-    GenServer.start_link(__MODULE__, {string, options_or_function}, [])
-  end
-
-  def open(string, options_or_function)
-      when is_binary(string) and is_function(options_or_function, 1) do
-    open(string, [], options_or_function)
+  def open(string, options \\ []) when is_binary(string) do
+    GenServer.start_link(__MODULE__, {string, options}, [])
   end
 
   @doc """
@@ -178,8 +111,8 @@ defmodule StringIO do
     {:noreply, state}
   end
 
-  def handle_info(_message, state) do
-    {:noreply, state}
+  def handle_info(message, state) do
+    super(message, state)
   end
 
   @impl true
@@ -195,6 +128,10 @@ defmodule StringIO do
     {:stop, :normal, {:ok, {input, output}}, state}
   end
 
+  def handle_call(request, from, state) do
+    super(request, from, state)
+  end
+
   defp io_request(from, reply_as, req, state) do
     {reply, state} = io_request(req, state)
     io_reply(from, reply_as, to_reply(reply))

lib/elixir/lib/supervisor.ex

@@ -28,19 +28,16 @@ defmodule Supervisor do
 
         ## Callbacks
 
-        @impl true
         def init(stack) do
           {:ok, stack}
         end
 
-        @impl true
-        def handle_call(:pop, _from, [head | tail]) do
-          {:reply, head, tail}
+        def handle_call(:pop, _from, [h | t]) do
+          {:reply, h, t}
         end
 
-        @impl true
-        def handle_cast({:push, head}, tail) do
-          {:noreply, [head | tail]}
+        def handle_cast({:push, h}, t) do
+          {:noreply, [h | t]}
         end
       end
 
@@ -96,8 +93,8 @@ defmodule Supervisor do
 
   Supervisors support different strategies; in the example above, we
   have chosen `:one_for_one`. Furthermore, each supervisor can have many
-  workers and/or supervisors as children, with each one having its own
-  configuration (as outlined in the “Child specification” section).
+  workers and supervisors as children, each of them with their specific
+  configuration, shutdown values, and restart strategies.
 
   The rest of this document will cover how child processes are started,
   how they can be specified, different supervision strategies and more.
@@ -124,8 +121,8 @@ defmodule Supervisor do
   then awaiting for a time interval for the child process to terminate. This
   interval defaults to 5000 milliseconds. If the child process does not
   terminate in this interval, the supervisor abruptly terminates the child
-  with reason `:kill`. The shutdown time can be configured in the child
-  specification which is fully detailed in the next section.
+  with reason `:brutal_kill`. The shutdown time can be configured in the
+  child specification which is fully detailed in the next section.
 
   If the child process is not trapping exits, it will shutdown immediately
   when it receives the first exit signal. If the child process is trapping
@@ -144,15 +141,15 @@ defmodule Supervisor do
 
   ## Child specification
 
-  The child specification describes how the supervisor starts, shuts down,
-  and restarts child processes.
+  The child specification describes how the supervisor start, shutdown and
+  restart child processes.
 
-  The child specification contains 6 keys. The first two are required,
+  The child specification contains 5 keys. The first two are required
   and the remaining ones are optional:
 
-    * `:id` - any term used to identify the child specification
+    * `:id` - a value used to identify the child specification
       internally by the supervisor; defaults to the given module.
-      In the case of conflicting `:id` values, the supervisor will refuse
+      In case of conflicting `:id`, the supervisor will refuse
       to initialize and require explicit IDs. This key is required.
 
     * `:start` - a tuple with the module-function-args to be invoked
@@ -167,11 +164,11 @@ defmodule Supervisor do
       is optional and defaults to `5000` if the type is `:worker` or
       `:infinity` if the type is `:supervisor`.
 
-    * `:type` - specifies that the child process is a `:worker` or a
-      `:supervisor`. This key is optional and defaults to `:worker`.
+    * `:type` - if the child process is a `:worker` or a `:supervisor`.
+      This key is optional and defaults to `:worker`.
 
-  There is a sixth key, `:modules`, that is rarely changed. It is set
-  automatically based on the value in `:start`.
+  There is a sixth key, called `:modules`, which is rarely changed and
+  it is set automatically based on the value in `:start`.
 
   Let's understand what the `:shutdown` and `:restart` options control.
 
@@ -197,8 +194,8 @@ defmodule Supervisor do
       supervisor, the recommended value is `:infinity` to give the supervisor
       and its children enough time to shutdown. This option can be used with
       regular workers but doing so is discouraged and requires extreme care.
-      If not used carefully, the child process will never terminate,
-      preventing your application from terminating as well.
+      If not used carefully and the child process does not terminate, it means
+      your application will never terminate as well.
 
   ### Restart values (:restart)
 
@@ -212,12 +209,11 @@ defmodule Supervisor do
     * `:permanent` - the child process is always restarted.
 
     * `:temporary` - the child process is never restarted, regardless
-      of the supervision strategy: any termination (even abnormal) is
-      considered successful.
+      of the supervision strategy.
 
     * `:transient` - the child process is restarted only if it
       terminates abnormally, i.e., with an exit reason other than
-      `:normal`, `:shutdown`, or `{:shutdown, term}`.
+      `:normal`, `:shutdown` or `{:shutdown, term}`.
 
   For a more complete understanding of the exit reasons and their
   impact, see the "Exit reasons and restarts" section.
@@ -275,20 +271,9 @@ defmodule Supervisor do
   with other developers and they can add it directly to their supervision tree
   without worrying about the low-level details of the worker.
 
-  Overall, the child specification can be one of the following:
-
-    * a map representing the child specification itself - as outlined in the
-      "Child specification" section
-    * a tuple with a module as first element and the start argument as second -
-      such as `{Stack, [:hello]}`. In this case, `Stack.child_spec([:hello])`
-      is called to retrieve the child specification
-    * a module - such as `Stack`. In this case, `Stack.child_spec([])`
-      is called to retrieve the child specification
-
-  If you need to convert how a tuple or module child specification to a map or
-  modify a child specification, you can use the `Supervisor.child_spec/2` function.
-  For example, to run the stack with a different `:id` and a `:shutdown` value of
-  10 seconds (10_000 milliseconds):
+  If you need to access or modify how a worker or a supervisor runs, you can use
+  the `Supervisor.child_spec/2` function. For example, to run the stack with a
+  different `:id` and a `:shutdown` value of 10 seconds (10_000 milliseconds):
 
       children = [
         Supervisor.child_spec({Stack, [:hello]}, id: MyStack, shutdown: 10_000)
@@ -338,7 +323,7 @@ defmodule Supervisor do
       restarts in transient mode, and linked processes exit with the same
       reason unless they're trapping exits
 
-  Notice that the supervisor that reaches maximum restart intensity will exit with
+  Notice that supervisor that reached maximum restart intensity will exit with
   `:shutdown` reason. In this case the supervisor will only be restarted if its
   child specification was defined with the `:restart` option set to `:permanent`
   (the default).
@@ -357,7 +342,6 @@ defmodule Supervisor do
           Supervisor.start_link(__MODULE__, arg, name: __MODULE__)
         end
 
-        @impl true
         def init(_arg) do
           children = [
             {Stack, [:hello]}
@@ -370,27 +354,26 @@ defmodule Supervisor do
   The difference between the two approaches is that a module-based
   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
-  `c:init/1` callback.
+  a list of children that are automatically initialized, we have
+  defined a supervisor alongside its `c:init/1` callback and manually
+  initialized the children by calling `Supervisor.init/2`, passing
+  the same arguments we would have given to `start_link/2`.
 
-  `use Supervisor` also defines a `child_spec/1` function which allows
-  us to run `MyApp.Supervisor` as a child of another supervisor:
+  You may want to use a module-based supervisor if:
 
-      children = [
-        MyApp.Supervisor
-      ]
+    * You need to perform some particular action on supervisor
+      initialization, like setting up an ETS table.
 
-      Supervisor.start_link(children, strategy: :one_for_one)
+    * You want to perform partial hot-code swapping of the
+      tree. The module-based approach allow you to add and remove
+      children on a case-by-case basis.
 
-  A general guideline is to use the supervisor without a callback
-  module only at the top of your supervision tree, generally in the
-  `c:Application.start/2` callback. We recommend using module-based
-  supervisors for any other supervisor in your application, so they
-  can run as a child of another supervision in the tree. The generated
-  `child_spec/1` can be customized with the following options:
+  Note `use Supervisor` defines a `child_spec/1` function, allowing
+  the defined module itself to be put under a supervision tree.
+  The generated `child_spec/1` can be customized with the following
+  options:
 
-    * `:id` - the child specification identifier, defaults to the current module
+    * `:id` - the child specification id, defaults to the current module
     * `:start` - how to start the child process (defaults to calling `__MODULE__.start_link/1`)
     * `:restart` - when the supervisor should be restarted, defaults to `:permanent`
 
@@ -409,14 +392,28 @@ defmodule Supervisor do
         {Stack, [:hello]}
       ], strategy: :one_for_one)
 
-  The first argument given to `start_link/2` and `init/2` is a list of child
-  specifications as defined in the "child_spec/1" section above.
+  Although we have mentioned that the supervisor automatically expands
+  `{Stack, [:hello]}` to a child specification by calling
+  `Stack.child_spec([:hello])`, we haven't formally defined all of the
+  arguments accepted by `start_link/2` and `init/2`. Let's rectify that
+  now.
+
+  The first argument given to `start_link/2` is a list of children which may
+  be either:
+
+    * a map representing the child specification itself - as outlined in the
+      "Child specification" section
+    * a tuple with a module as first element and the start argument as second -
+      such as `{Stack, [:hello]}`. In this case, `Stack.child_spec([:hello])`
+      is called to retrieve the child specification
+    * a module - such as `Stack`. In this case, `Stack.child_spec([])`
+      is called to retrieve the child specification
 
   The second argument is a keyword list of options:
 
-    * `:strategy` - the supervision strategy option. It can be either
-      `:one_for_one`, `:rest_for_one` or `:one_for_all`. Required.
-      See the "Strategies" section.
+    * `:strategy` - the restart strategy option. It can be either
+      `:one_for_one`, `:rest_for_one` or `:one_for_all`. See the
+      "Strategies" section.
 
     * `:max_restarts` - the maximum number of restarts allowed in
       a time frame. Defaults to `3`.
@@ -424,9 +421,8 @@ defmodule Supervisor do
     * `:max_seconds` - the time frame in which `:max_restarts` applies.
       Defaults to `5`.
 
-    * `:name` - a name to register the supervisor process. Supported values are
-      explained in the "Name registration" section in the documentation for
-      `GenServer`. Optional.
+  The `:strategy` option is required and by default a maximum of 3 restarts
+  is allowed within 5 seconds.
 
   ### Strategies
 
@@ -440,18 +436,16 @@ defmodule Supervisor do
       processes are terminated and then all child processes (including
       the terminated one) are restarted.
 
-    * `:rest_for_one` - if a child process terminates, the terminated child
-      process and the rest of the children started after it, are terminated and
-      restarted.
-
-  In the above, process termination refers to unsuccessful termination, which
-  is determined by the `:restart` option.
+    * `:rest_for_one` - if a child process terminates, the "rest" of
+      the child processes, i.e., the child processes after the terminated
+      one in start order, are terminated. Then the terminated child
+      process and the rest of the child processes are restarted.
 
   There is also a deprecated strategy called `:simple_one_for_one` which
   has been replaced by the `DynamicSupervisor`. The `:simple_one_for_one`
   supervisor was similar to `:one_for_one` but suits better when dynamically
   attaching children. Many functions in this module behaved slightly
-  differently when this strategy was used. See the `DynamicSupervisor` module
+  differently when this strategy is used. See the `DynamicSupervisor` module
   for more information and migration strategies.
 
   ## Name registration
@@ -482,6 +476,9 @@ defmodule Supervisor do
       end
 
       defoverridable child_spec: 1
+
+      @doc false
+      def init(arg)
     end
   end
 
@@ -533,10 +530,10 @@ defmodule Supervisor do
   # Note we have inlined all types for readability
   @typedoc "The supervisor specification"
   @type child_spec :: %{
-          required(:id) => atom() | term(),
+          required(:id) => term(),
           required(:start) => {module(), atom(), [term()]},
           optional(:restart) => :permanent | :transient | :temporary,
-          optional(:shutdown) => timeout() | :brutal_kill,
+          optional(:shutdown) => :brutal_kill | non_neg_integer() | :infinity,
           optional(:type) => :worker | :supervisor,
           optional(:modules) => [module()] | :dynamic
         }
@@ -597,7 +594,7 @@ defmodule Supervisor do
 
   ## Options
 
-    * `:strategy` - the supervision strategy option. It can be either
+    * `:strategy` - the restart strategy option. It can be either
       `:one_for_one`, `:rest_for_one`, `:one_for_all`, or the deprecated
       `:simple_one_for_one`.
 
@@ -611,7 +608,6 @@ defmodule Supervisor do
   is allowed within 5 seconds. Check the `Supervisor` module for a detailed
   description of the available strategies.
   """
-  @doc since: "1.5.0"
   # TODO: Warn if simple_one_for_one strategy is used on Elixir v1.8.
   @spec init([:supervisor.child_spec() | {module, term} | module], [init_option]) :: {:ok, tuple}
   def init(children, options) when is_list(children) and is_list(options) do
@@ -634,7 +630,7 @@ defmodule Supervisor do
       module.child_spec(arg)
     rescue
       e in UndefinedFunctionError ->
-        case __STACKTRACE__ do
+        case System.stacktrace() do
           [{^module, :child_spec, [^arg], _} | _] ->
             raise ArgumentError, child_spec_error(module)
 
@@ -654,7 +650,7 @@ defmodule Supervisor do
 
   defp init_child(other) do
     raise ArgumentError, """
-    supervisors expect each child to be one of the following:
+    supervisors expect each child to be one of:
 
       * a module
       * a {module, arg} tuple
@@ -712,8 +708,8 @@ defmodule Supervisor do
   If a module is given, the specification is retrieved by calling
   `module.child_spec(arg)`.
 
-  After the child specification is retrieved, the fields on `overrides`
-  are directly applied on the child spec. If `overrides` has keys that
+  After the child specification is retrieved, the fields on `config`
+  are directly applied on the child spec. If `config` has keys that
   do not map to any child specification field, an error is raised.
 
   See the "Child specification" section in the module documentation
@@ -788,7 +784,7 @@ defmodule Supervisor do
 
       other ->
         raise ArgumentError, """
-        expected :name option to be one of the following:
+        expected :name option to be one of:
 
           * nil
           * atom
@@ -855,9 +851,9 @@ defmodule Supervisor do
   """
   @spec terminate_child(supervisor, term()) :: :ok | {:error, error}
         when error: :not_found | :simple_one_for_one
+  # TODO: Deprecate this on Elixir v1.8
   def terminate_child(supervisor, child_id)
 
-  # TODO: Deprecate this clause on Elixir v1.8
   def terminate_child(supervisor, pid) when is_pid(pid) do
     call(supervisor, {:terminate_child, pid})
   end

lib/elixir/lib/supervisor/spec.ex

@@ -1,6 +1,6 @@
 defmodule Supervisor.Spec do
   @moduledoc """
-  Outdated functions for building child specifications.
+  WARNING: this module is deprecated.
 
   The functions in this module are deprecated and they do not work
   with the module-based child specs introduced in Elixir v1.5.
@@ -106,9 +106,6 @@ defmodule Supervisor.Spec do
 
   """
 
-  @moduledoc deprecated:
-               "Use the new child specifications outlined in the Supervisor module instead"
-
   # TODO: Deprecate all functions in this module on Elixir v1.8.
   # Also deprecate entry in Supervisor.Default.
 

lib/elixir/lib/system.ex

@@ -78,7 +78,7 @@ defmodule System do
   `:micro_seconds` and `:nano_seconds` as time units although Elixir normalizes
   their spelling to match the SI convention.
   """
-  # TODO: Warn all old mappings once Elixir requires Erlang/OTP 19.1+ (on v1.8)
+  # TODO: Warn all old mappings once Elixir requires Erlang/OTP 19.1+
   @type time_unit ::
           :second
           | :millisecond
@@ -139,11 +139,7 @@ defmodule System do
 
   # Get the date at compilation time.
   defmacrop get_date do
-    {{year, month, day}, {hour, minute, second}} = :calendar.universal_time()
-
-    "~4..0b-~2..0b-~2..0bT~2..0b:~2..0b:~2..0bZ"
-    |> :io_lib.format([year, month, day, hour, minute, second])
-    |> :erlang.iolist_to_binary()
+    IO.iodata_to_binary(:httpd_util.rfc1123_date())
   end
 
   @doc """
@@ -190,7 +186,7 @@ defmodule System do
     {:ok, v} = Version.parse(version())
 
     revision_string = if v.pre != [] and revision() != "", do: " (#{revision()})", else: ""
-    otp_version_string = " (compiled with Erlang/OTP #{get_otp_release()})"
+    otp_version_string = " (compiled with OTP #{get_otp_release()})"
 
     version() <> revision_string <> otp_version_string
   end
@@ -445,19 +441,14 @@ defmodule System do
   end
 
   @doc """
-  Deprecated mechanism to retrieve the last exception stacktrace.
-
-  Accessing the stacktrace outside of a rescue/catch is deprecated.
-  If you want to support only Elixir v1.7+, you must access
-  `__STACKTRACE__/0` inside a rescue/catch. If you want to support
-  earlier Elixir versions, move `System.stacktrace/0` inside a rescue/catch.
+  Last exception stacktrace.
 
   Note that the Erlang VM (and therefore this function) does not
   return the current stacktrace but rather the stacktrace of the
   latest exception.
+
+  Inlined by the compiler into `:erlang.get_stacktrace/0`.
   """
-  # TODO: Fully deprecate it on Elixir v1.9.
-  # It is currently partially deprecated in elixir_dispatch.erl
   def stacktrace do
     :erlang.get_stacktrace()
   end
@@ -523,7 +514,6 @@ defmodule System do
       System.stop(1)
 
   """
-  @doc since: "1.5.0"
   @spec stop(non_neg_integer | binary) :: no_return
   def stop(status \\ 0)
 
@@ -561,13 +551,13 @@ defmodule System do
 
   ## Examples
 
-      iex> System.cmd("echo", ["hello"])
+      iex> System.cmd "echo", ["hello"]
       {"hello\n", 0}
 
-      iex> System.cmd("echo", ["hello"], env: [{"MIX_ENV", "test"}])
+      iex> System.cmd "echo", ["hello"], env: [{"MIX_ENV", "test"}]
       {"hello\n", 0}
 
-      iex> System.cmd("echo", ["hello"], into: IO.stream(:stdio, :line))
+      iex> System.cmd "echo", ["hello"], into: IO.stream(:stdio, :line)
       hello
       {%IO.Stream{}, 0}
 
@@ -639,8 +629,9 @@ defmodule System do
       do_cmd(Port.open({:spawn_executable, cmd}, opts), initial, fun)
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         fun.(initial, :halt)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     else
       {acc, status} -> {fun.(acc, :done), status}
     end
@@ -699,7 +690,7 @@ defmodule System do
   This time is monotonically increasing and starts in an unspecified
   point in time.
 
-  Inlined by the compiler.
+  Inlined by the compiler into `:erlang.monotonic_time/0`.
   """
   @spec monotonic_time() :: integer
   def monotonic_time do
@@ -724,7 +715,7 @@ defmodule System do
   case of time warps although the VM works towards aligning
   them. This time is not monotonic.
 
-  Inlined by the compiler.
+  Inlined by the compiler into `:erlang.system_time/0`.
   """
   @spec system_time() :: integer
   def system_time do
@@ -769,7 +760,7 @@ defmodule System do
 
   See `time_offset/1` for more information.
 
-  Inlined by the compiler.
+  Inlined by the compiler into `:erlang.time_offset/0`.
   """
   @spec time_offset() :: integer
   def time_offset do
@@ -798,7 +789,7 @@ defmodule System do
   This time may be adjusted forwards or backwards in time
   with no limitation and is not monotonic.
 
-  Inlined by the compiler.
+  Inlined by the compiler into `:os.system_time/0`.
   """
   @spec os_time() :: integer
   def os_time do
@@ -817,7 +808,7 @@ defmodule System do
   end
 
   @doc """
-  Returns the Erlang/OTP release number.
+  Returns the OTP release number.
   """
   @spec otp_release :: String.t()
   def otp_release do
@@ -861,7 +852,7 @@ defmodule System do
   All modifiers listed above can be combined; repeated modifiers in `modifiers`
   will be ignored.
 
-  Inlined by the compiler.
+  Inlined by the compiler into `:erlang.unique_integer/1`.
   """
   @spec unique_integer([:positive | :monotonic]) :: integer
   def unique_integer(modifiers \\ []) do

lib/elixir/lib/task.ex

@@ -56,18 +56,8 @@ defmodule Task do
 
   ## Supervised tasks
 
-  It is also possible to spawn a task under a supervisor. The `Task`
-  module implements the `child_spec/1` function, which allows it to
-  be started directly under a supervisor by passing a tuple with
-  a function to run:
-
-      Supervisor.start_link([
-        {Task, fn -> ... some function ... end}
-      ])
-
-  However, if you want to invoke a specific module, function and
-  arguments, or give the task process a name, you need to define
-  the task in its own module:
+  It is also possible to spawn a task under a supervisor.
+  It is often done by defining the task in its own module:
 
       defmodule MyTask do
         use Task
@@ -83,9 +73,7 @@ defmodule Task do
 
   And then passing it to the supervisor:
 
-      Supervisor.start_link([
-        {MyTask, arg}
-      ])
+      Supervisor.start_link([MyTask])
 
   Since these tasks are supervised and not directly linked to
   the caller, they cannot be awaited on. Note `start_link/1`,
@@ -96,7 +84,7 @@ defmodule Task do
   defined module to be put under a supervision tree. The generated
   `child_spec/1` can be customized with the following options:
 
-    * `:id` - the child specification identifier, defaults to the current module
+    * `:id` - the child specification id, defaults to the current module
     * `:start` - how to start the child process (defaults to calling `__MODULE__.start_link/1`)
     * `:restart` - when the child should be restarted, defaults to `:temporary`
     * `:shutdown` - how to shut down the child
@@ -190,7 +178,7 @@ defmodule Task do
 
   See `Supervisor`.
   """
-  @doc since: "1.5.0"
+  @since "1.5.0"
   def child_spec(arg) do
     %{
       id: Task,
@@ -207,7 +195,7 @@ defmodule Task do
 
       See `Supervisor`.
       """
-      @doc since: "1.5.0"
+      @since "1.5.0"
       def child_spec(arg) do
         default = %{
           id: __MODULE__,
@@ -388,7 +376,7 @@ defmodule Task do
       Defaults to `true`.
     * `:timeout` - the maximum amount of time (in milliseconds) each
       task is allowed to execute for. Defaults to `5000`.
-    * `:on_timeout` - what to do when a task times out. The possible
+    * `:on_timeout` - what do to when a task times out. The possible
       values are:
       * `:exit` (default) - the process that spawned the tasks exits.
       * `:kill_task` - the task that timed out is killed. The value
@@ -409,7 +397,6 @@ defmodule Task do
       Enum.to_list(stream)
 
   """
-  @doc since: "1.4.0"
   @spec async_stream(Enumerable.t(), module, atom, [term], keyword) :: Enumerable.t()
   def async_stream(enumerable, module, function, args, options \\ [])
       when is_atom(module) and is_atom(function) and is_list(args) do
@@ -429,13 +416,12 @@ defmodule Task do
   Count the codepoints in each string asynchronously, then add the counts together using reduce.
 
       iex> strings = ["long string", "longer string", "there are many of these"]
-      iex> stream = Task.async_stream(strings, fn text -> text |> String.codepoints() |> Enum.count() end)
+      iex> stream = Task.async_stream(strings, fn text -> text |> String.codepoints |> Enum.count end)
       iex> Enum.reduce(stream, 0, fn {:ok, num}, acc -> num + acc end)
       47
 
   See `async_stream/5` for discussion, options, and more examples.
   """
-  @doc since: "1.4.0"
   @spec async_stream(Enumerable.t(), (term -> term), keyword) :: Enumerable.t()
   def async_stream(enumerable, fun, options \\ []) when is_function(fun, 1) do
     build_stream(enumerable, fun, options)
@@ -453,8 +439,8 @@ defmodule Task do
   defp get_info(pid) do
     self_or_name =
       case Process.info(pid, :registered_name) do
-        {:registered_name, name} when is_atom(name) -> name
-        _ -> pid
+        {:registered_name, []} -> self()
+        {:registered_name, name} -> name
       end
 
     {node(), self_or_name}
@@ -518,7 +504,7 @@ defmodule Task do
 
   @doc false
   # TODO: Remove on 2.0
-  @deprecated "Pattern match on the message directly instead"
+  # (hard-deprecated in elixir_dispatch)
   def find(tasks, {ref, reply}) when is_reference(ref) do
     Enum.find_value(tasks, fn
       %Task{ref: ^ref} = task ->
@@ -662,11 +648,7 @@ defmodule Task do
   @spec yield_many([t], timeout) :: [{t, {:ok, term} | {:exit, term} | nil}]
   def yield_many(tasks, timeout \\ 5000) do
     timeout_ref = make_ref()
-
-    timer_ref =
-      if timeout != :infinity do
-        Process.send_after(self(), timeout_ref, timeout)
-      end
+    timer_ref = Process.send_after(self(), timeout_ref, timeout)
 
     try do
       yield_many(tasks, timeout_ref, :infinity)
@@ -674,7 +656,7 @@ defmodule Task do
       {:noconnection, reason} ->
         exit({reason, {__MODULE__, :yield_many, [tasks, timeout]}})
     after
-      timer_ref && Process.cancel_timer(timer_ref)
+      Process.cancel_timer(timer_ref)
       receive do: (^timeout_ref -> :ok), after: (0 -> :ok)
     end
   end

lib/elixir/lib/task/supervised.ex

@@ -74,8 +74,8 @@ defmodule Task.Supervised do
   end
 
   defp get_initial_call({:erlang, :apply, [fun, []]}) when is_function(fun, 0) do
-    {:module, module} = Function.info(fun, :module)
-    {:name, name} = Function.info(fun, :name)
+    {:module, module} = :erlang.fun_info(fun, :module)
+    {:name, name} = :erlang.fun_info(fun, :name)
     {module, name, 0}
   end
 
@@ -83,44 +83,31 @@ defmodule Task.Supervised do
     {mod, fun, length(args)}
   end
 
-  # TODO: Remove conditionals once we depend on Erlang/OTP 20+
   defp do_apply(info, {module, fun, args} = mfa) do
     try do
       apply(module, fun, args)
     catch
       :error, value ->
-        reason = {value, __STACKTRACE__}
-        log(info, mfa, reason)
-
-        if :erlang.system_info(:otp_release) >= '20' do
-          :erlang.raise(:error, value, __STACKTRACE__)
-        else
-          exit(reason)
-        end
+        reason = {value, System.stacktrace()}
+        exit(info, mfa, reason, reason)
 
       :throw, value ->
-        reason = {{:nocatch, value}, __STACKTRACE__}
-        log(info, mfa, reason)
-
-        if :erlang.system_info(:otp_release) >= '20' do
-          :erlang.raise(:throw, value, __STACKTRACE__)
-        else
-          exit(reason)
-        end
-
-      :exit, value
-      when value == :normal
-      when value == :shutdown
-      when tuple_size(value) == 2 and elem(value, 0) == :shutdown ->
-        :erlang.raise(:exit, value, __STACKTRACE__)
+        reason = {{:nocatch, value}, System.stacktrace()}
+        exit(info, mfa, reason, reason)
 
       :exit, value ->
-        log(info, mfa, {value, __STACKTRACE__})
-        :erlang.raise(:exit, value, __STACKTRACE__)
+        exit(info, mfa, {value, System.stacktrace()}, value)
     end
   end
 
-  defp log(info, mfa, reason) do
+  defp exit(_info, _mfa, _log_reason, reason)
+       when reason == :normal
+       when reason == :shutdown
+       when tuple_size(reason) == 2 and elem(reason, 0) == :shutdown do
+    exit(reason)
+  end
+
+  defp exit(info, mfa, log_reason, reason) do
     {fun, args} = get_running(mfa)
 
     message =
@@ -129,14 +116,16 @@ defmodule Task.Supervised do
         '** When function  == ~p~n' ++
         '**      arguments == ~p~n' ++ '** Reason for termination == ~n' ++ '** ~p~n'
 
-    :error_logger.format(message, [self(), get_from(info), fun, args, get_reason(reason)])
+    :error_logger.format(message, [self(), get_from(info), fun, args, get_reason(log_reason)])
+
+    exit(reason)
   end
 
   defp get_from({node, pid_or_name}) when node == node(), do: pid_or_name
   defp get_from(other), do: other
 
   defp get_running({:erlang, :apply, [fun, []]}) when is_function(fun, 0), do: {fun, []}
-  defp get_running({mod, fun, args}), do: {Function.capture(mod, fun, length(args)), args}
+  defp get_running({mod, fun, args}), do: {:erlang.make_fun(mod, fun, length(args)), args}
 
   defp get_reason({:undef, [{mod, fun, args, _info} | _] = stacktrace} = reason)
        when is_atom(mod) and is_atom(fun) do
@@ -306,8 +295,9 @@ defmodule Task.Supervised do
       next.({:cont, []})
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         stream_close(monitor_pid, monitor_ref, timeout)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     else
       {:suspended, [value], next} ->
         waiting = stream_spawn(value, spawned, waiting, monitor_pid, monitor_ref, timeout)
@@ -334,9 +324,10 @@ defmodule Task.Supervised do
       reducer.(reply, acc)
     catch
       kind, reason ->
+        stacktrace = System.stacktrace()
         is_function(next) && next.({:halt, []})
         stream_close(monitor_pid, monitor_ref, timeout)
-        :erlang.raise(kind, reason, __STACKTRACE__)
+        :erlang.raise(kind, reason, stacktrace)
     end
   end
 
@@ -363,9 +354,10 @@ defmodule Task.Supervised do
           reducer.(reply, acc)
         catch
           kind, reason ->
+            stacktrace = System.stacktrace()
             is_function(next) && next.({:halt, []})
             stream_close(monitor_pid, monitor_ref, timeout)
-            :erlang.raise(kind, reason, __STACKTRACE__)
+            :erlang.raise(kind, reason, stacktrace)
         else
           pair ->
             stream_deliver(

lib/elixir/lib/task/supervisor.ex

@@ -12,7 +12,7 @@ defmodule Task.Supervisor do
         {Task.Supervisor, name: MyApp.TaskSupervisor}
       ]
 
-      Supervisor.start_link(children, strategy: :one_for_one)
+      Supervisor.start_link(strategy: :one_for_one)
 
   The options given in the child specification are documented in `start_link/1`.
 
@@ -31,17 +31,10 @@ defmodule Task.Supervisor do
           | {:shutdown, :supervisor.shutdown()}
 
   @doc false
-  def child_spec(opts) when is_list(opts) do
-    id =
-      case Keyword.get(opts, :name, Task.Supervisor) do
-        name when is_atom(name) -> name
-        {:global, name} -> name
-        {:via, _module, name} -> name
-      end
-
+  def child_spec(arg) do
     %{
-      id: id,
-      start: {Task.Supervisor, :start_link, [opts]},
+      id: Task.Supervisor,
+      start: {Task.Supervisor, :start_link, [arg]},
       type: :supervisor
     }
   end
@@ -226,7 +219,6 @@ defmodule Task.Supervisor do
       Enum.to_list(stream)
 
   """
-  @doc since: "1.4.0"
   @spec async_stream(Supervisor.supervisor(), Enumerable.t(), module, atom, [term], keyword) ::
           Enumerable.t()
   def async_stream(supervisor, enumerable, module, function, args, options \\ [])
@@ -244,7 +236,6 @@ defmodule Task.Supervisor do
 
   See `async_stream/6` for discussion, options, and examples.
   """
-  @doc since: "1.4.0"
   @spec async_stream(Supervisor.supervisor(), Enumerable.t(), (term -> term), keyword) ::
           Enumerable.t()
   def async_stream(supervisor, enumerable, fun, options \\ []) when is_function(fun, 1) do
@@ -261,7 +252,6 @@ defmodule Task.Supervisor do
 
   See `async_stream/6` for discussion, options, and examples.
   """
-  @doc since: "1.4.0"
   @spec async_stream_nolink(
           Supervisor.supervisor(),
           Enumerable.t(),
@@ -285,7 +275,6 @@ defmodule Task.Supervisor do
 
   See `async_stream/6` for discussion and examples.
   """
-  @doc since: "1.4.0"
   @spec async_stream_nolink(Supervisor.supervisor(), Enumerable.t(), (term -> term), keyword) ::
           Enumerable.t()
   def async_stream_nolink(supervisor, enumerable, fun, options \\ []) when is_function(fun, 1) do
@@ -328,8 +317,7 @@ defmodule Task.Supervisor do
       or an integer indicating the timeout value, defaults to 5000 milliseconds.
 
   """
-  @spec start_child(Supervisor.supervisor(), (() -> any), keyword) ::
-          DynamicSupervisor.on_start_child()
+  @spec start_child(Supervisor.supervisor(), (() -> any)) :: {:ok, pid}
   def start_child(supervisor, fun, options \\ []) do
     restart = options[:restart]
     shutdown = options[:shutdown]
@@ -343,8 +331,7 @@ defmodule Task.Supervisor do
   Similar to `start_child/2` except the task is specified
   by the given `module`, `fun` and `args`.
   """
-  @spec start_child(Supervisor.supervisor(), module, atom, [term], keyword) ::
-          DynamicSupervisor.on_start_child()
+  @spec start_child(Supervisor.supervisor(), module, atom, [term]) :: {:ok, pid}
   def start_child(supervisor, module, fun, args, options \\ [])
       when is_atom(fun) and is_list(args) do
     restart = options[:restart]
@@ -354,17 +341,15 @@ defmodule Task.Supervisor do
   end
 
   defp start_child_with_spec(supervisor, args, restart, shutdown) do
-    # TODO: This only exists because we need to support reading restart/shutdown
-    # from two different places. Remove this and the associated clause in DynamicSupervisor
-    # on Elixir v2.0
+    # TODO: Remove this on Elixir v2.0 and the associated clause in DynamicSupervisor
     GenServer.call(supervisor, {:start_task, args, restart, shutdown}, :infinity)
   end
 
   defp get_info(self) do
     name =
       case Process.info(self, :registered_name) do
-        {:registered_name, name} when is_atom(name) -> name
-        _ -> self
+        {:registered_name, []} -> self
+        {:registered_name, name} -> name
       end
 
     {node(), name}

lib/elixir/lib/tuple.ex

@@ -2,41 +2,64 @@ defmodule Tuple do
   @moduledoc """
   Functions for working with tuples.
 
-  Please note the following functions for tuples are found in `Kernel`:
-
-    * `elem/2` - access a tuple by index
-    * `put_elem/3` - insert a value into a tuple by index
-    * `tuple_size/1` - get the number of elements in a tuple
-    
-  Tuples are intended as fixed-size containers for multiple elements.
-  To manipulate a collection of elements, use a list instead. `Enum`
-  functions do not work on tuples.
-
-  Tuples are denoted with curly braces:
+  Tuples are composite data types with a fixed number of elements. Tuples
+  can contain elements of any type, and a tuple can contain elements of
+  different types. Curly braces can be used to create tuples:
 
       iex> {}
       {}
       iex> {1, :two, "three"}
       {1, :two, "three"}
 
-  A tuple may contain elements of different types, which are stored
-  contiguously in memory. Accessing any element takes constant time, 
-  but modifying a tuple, which produces a shallow copy, takes linear time. 
-  Tuples are good for reading data while lists are better for traversals.
+  Tuples store elements contiguously in memory. This means accessing a
+  tuple element by index doesn't depend on the number of elements in the
+  tuple. We say the operation is done in constant-time, via the
+  `Kernel.elem/1` function:
 
-  Tuples are typically used either when a function has multiple return values
-  or for error handling. `File.read/1` returns `{:ok, contents}` if reading 
-  the given file is successful, or else `{:error, reason}` such as when 
-  the file does not exist.
+      iex> tuple = {1, :two, "three"}
+      iex> elem(tuple, 0)
+      1
+      iex> elem(tuple, 2)
+      "three"
 
-  The functions in this module that add and remove elements from tuples are
-  rarely used in practice, as they typically imply tuples are being used as
-  collections. To append to a tuple, it is preferrable to use pattern matching:
+  Same goes for getting the tuple size with `Kernel.tuple_size/1`:
+
+      iex> tuple_size({})
+      0
+      iex> tuple_size({1, 2, 3})
+      3
+
+  Tuples being stored contiguously in memory also means that updating a tuple
+  (for example replacing an element with `Kernel.put_elem/3`) will make a
+  shallow copy of the whole tuple. The tuple elements are still shared thanks
+  to immutability.
+
+  Tuples are not meant to be used as a "collection" type but rather as a
+  fixed-size container for multiple elements. That's why it is not possible
+  to traverse a tuple dynamically using the functions in the `Enum` module.
+
+  For example, tuples are often used to have functions return "enriched"
+  values: a common pattern is for functions to return `{:ok, value}` for
+  successful cases and `{:error, reason}` for unsuccessful cases. This is
+  exactly what `File.read/1` does: it returns `{:ok, contents}` if reading
+  the given file is successful, or `{:error, reason}` otherwise, such as
+  when the file does not exist.
+
+  The most common operations performed on tuples are available in `Kernel`
+  (`Kernel.tuple_size/1`, `Kernel.elem/2`, `Kernel.put_elem/3`, and others)
+  and are automatically imported into your code. The functions in this module
+  cover other cases, such as dynamic creation of tuples (`Tuple.duplicate/2`)
+  and conversion to list (`Tuple.to_list/1`). The functions that add and remove
+  elements from tuples, changing their size, are rarely used in practice, as
+  they typically imply tuples are being used as collections. Even if you have
+  a tuple `{:ok, atom}` and you want to append another element to it, such as
+  an empty map, it is preferrable to rely on pattern matching and create a new
+  tuple than manipulating it dynamically:
 
       tuple = {:ok, :example}
 
       # Avoid
-      Tuple.insert_at(tuple, 2, %{})
+      Tuple.insert_at(tuple, 2, %{}}
 
       # Prefer
       {:ok, atom} = tuple

lib/elixir/lib/uri.ex

@@ -88,7 +88,7 @@ defmodule URI do
       iex> URI.encode_query(query)
       "key=value+with+spaces"
 
-      iex> URI.encode_query(%{key: [:a, :list]})
+      iex> URI.encode_query %{key: [:a, :list]}
       ** (ArgumentError) encode_query/1 values cannot be lists, got: [:a, :list]
 
   """
@@ -128,7 +128,7 @@ defmodule URI do
       %{"percent" => "oh yes!", "starting" => "map"}
 
   """
-  @spec decode_query(binary, %{binary => binary}) :: %{binary => binary}
+  @spec decode_query(binary, map) :: map
   def decode_query(query, map \\ %{})
 
   # TODO: Remove on 2.0
@@ -258,7 +258,7 @@ defmodule URI do
   end
 
   @doc """
-  Percent-escapes all characters that require escaping in a string.
+  Percent-escapes all characters that require escaped in a string.
 
   This means reserved characters, such as `:` and `/`, and the so-
   called unreserved characters, which have the same meaning both
@@ -422,13 +422,11 @@ defmodule URI do
 
     parts = Regex.run(regex, string)
 
-    destructure [_, _, scheme, _, authority, path, query_with_question_mark, _, _, fragment],
-                parts
-
+    destructure [_, _, scheme, _, authority, path, _, query, _, fragment], parts
     scheme = nillify(scheme)
     authority = nillify(authority)
     path = nillify(path)
-    query = nillify_query(query_with_question_mark)
+    query = nillify(query)
     {userinfo, host, port} = split_authority(authority)
 
     scheme = scheme && String.downcase(scheme)
@@ -446,9 +444,6 @@ defmodule URI do
     }
   end
 
-  defp nillify_query("?" <> query), do: query
-  defp nillify_query(_other), do: nil
-
   # Split an authority into its userinfo, host and port parts.
   defp split_authority(string) do
     regex = Regex.recompile!(~r/(^(.*)@)?(\[[a-zA-Z0-9:.]*\]|[^:]*)(:(\d*))?/)
@@ -470,28 +465,12 @@ defmodule URI do
   @doc """
   Returns the string representation of the given `URI` struct.
 
-  ## Examples
-
       iex> URI.to_string(URI.parse("http://google.com"))
       "http://google.com"
 
       iex> URI.to_string(%URI{scheme: "foo", host: "bar.baz"})
       "foo://bar.baz"
 
-  Note that when creating this string representation, the `authority` 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

lib/elixir/lib/version.ex

@@ -94,9 +94,7 @@ defmodule Version do
   @type patch :: non_neg_integer | nil
   @type pre :: [String.t() | non_neg_integer]
   @type build :: String.t() | nil
-  @type matchable ::
-          {major :: major, minor :: minor, patch :: patch, pre :: pre,
-           build_parts :: [String.t()]}
+  @type matchable :: {major :: major, minor :: minor, patch :: patch, pre :: pre}
   @type t :: %__MODULE__{major: major, minor: minor, patch: patch, pre: pre, build: build}
 
   defmodule Requirement do
@@ -108,12 +106,10 @@ defmodule Version do
   defmodule InvalidRequirementError do
     defexception [:requirement]
 
-    @impl true
     def exception(requirement) when is_binary(requirement) do
       %__MODULE__{requirement: requirement}
     end
 
-    @impl true
     def message(%{requirement: requirement}) do
       "invalid requirement: #{inspect(requirement)}"
     end
@@ -122,12 +118,10 @@ defmodule Version do
   defmodule InvalidVersionError do
     defexception [:version]
 
-    @impl true
     def exception(version) when is_binary(version) do
       %__MODULE__{version: version}
     end
 
-    @impl true
     def message(%{version: version}) do
       "invalid version: #{inspect(version)}"
     end

lib/elixir/pages/Compatibility and Deprecations.md

@@ -1,55 +1,20 @@
 # Compatibility and Deprecations
 
-Elixir is versioned according to a vMAJOR.MINOR.PATCH schema.
-
-Elixir is currently at major version v1. A new backwards compatible minor release happens every 6 months. Patch releases are not scheduled and are made whenever there are bug fixes or security patches.
-
-Elixir applies bug fixes only to the latest minor branch. Security patches are available for the last 5 minor branch:
-
-Elixir version | Support
-:------------- | :-----------------------------
-1.7            | Bug fixes and security patches
-1.6            | Security patches only
-1.5            | Security patches only
-1.4            | Security patches only
-1.3            | Security patches only
-
-Major Elixir releases may contain breaking changes and those will be explicitly outlined in the CHANGELOG. There are currently no plans for a major v2 release.
-
-## Compatibility between non-major Elixir versions
-
-Elixir minor and patch releases are backwards compatible: well-defined behaviours and documented APIs in a given version will continue working on future versions.
-
-Although we expect the vast majority of programs to remain compatible over time, it is impossible to guarantee that no future change will break any program. Under some unlikely circumstances, we may introduce changes that break existing code:
-
-  * Security: a security issue in the implementation may arise whose resolution requires backwards incompatible changes. We reserve the right to address such security issues.
-
-  * Bugs: if an API has undesired behaviour, a program that depends on the buggy behaviour may break if the bug is fixed. We reserve the right to fix such bugs.
-
-  * Compiler front-end: improvements may be done to the compiler, introducing new warnings for ambiguous modes and providing more detailed error messages. Those can lead to compilation errors (when running with `--warning-as-errors`) or tooling failures when asserting on specific error messages (although one should avoid such). We reserve the right to do such improvements.
-
-  * Imports: new functions may be added to the `Kernel` module, which is auto-imported. They may collide with local functions defined in your modules. Collisions can be resolved in a backwards compatible fashion using `import Kernel, except: [...]` with a list of all functions you don't want to be imported from `Kernel`. We reserve the right to do such additions.
-
-In order to continue evolving the language without introducing breaking changes, Elixir will rely on deprecations to demote certain practices and promote new ones. Our deprecation policy is outlined in the ["Deprecations" section](#deprecations).
-
-The only exception to the compatibility guarantees above are experimental features, which will be explicitly marked as such, and do not provide any compatibility guarantee until they are stabilized.
-
 ## 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.
 
 Elixir version | Supported Erlang/OTP versions
-:------------- | :-------------------------------
-1.0            | 17 - 17 (and Erlang/OTP 18 from v1.0.5)
+:------------- | :----------------------------
+1.0            | 17 - 17 (and OTP 18 from v1.0.5)
 1.1            | 17 - 18
-1.2            | 18 - 18 (and Erlang/OTP 19 from v1.2.6)
+1.2            | 18 - 18 (and OTP 19 from v1.2.6)
 1.3            | 18 - 19
-1.4            | 18 - 19 (and Erlang/OTP 20 from v1.4.5)
+1.4            | 18 - 19 (and 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 - 21
+1.6            | 19 - 20
 
-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.
+While Elixir often adds compatibility to new Erlang versions on released branches, such as support for 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 release.
 
 ## Deprecations
 
@@ -59,53 +24,46 @@ Elixir deprecations happen in 3 steps:
 
   1. The feature is soft-deprecated. It means both CHANGELOG and documentation must list the feature as deprecated but no warning is effectively emitted by running the code. There is no requirement to soft-deprecate a feature.
 
-  2. The feature is effectively deprecated by emitting warnings on usage. This is also known as hard-deprecation. In order to deprecate a feature, the proposed alternative MUST exist for AT LEAST two minor versions. For example, `Enum.uniq/2` was soft-deprecated in favor of `Enum.uniq_by/2` in Elixir v1.1. This means a deprecation warning may only be emitted by Elixir v1.3 or later.
+  2. The feature is effectively deprecated by emitting warnings on usage. In order to deprecate a feature, the proposed alternative MUST exist for AT LEAST two versions. For example, `Enum.uniq/2` was soft-deprecated in favor of `Enum.uniq_by/2` in Elixir v1.1. This means a deprecation warning may only be emitted by Elixir v1.3 or later.
 
   3. The feature is removed. This can only happen on major releases. This means deprecated features in Elixir v1.x shall only be removed by Elixir v2.x.
 
 ### Table of deprecations
 
-Deprecated feature                               | Hard-deprecated in | Replaced by (available since)
-:----------------------------------------------- | :----------------- | :----------------------------
-`Code.get_docs/2`                                | [v1.7]        | `Code.fetch_docs/1` (v1.7)
-Calling `super` on GenServer callbacks           | [v1.7]        | Not calling super (v1.0)
-`Enum.chunk/2`[`/3/4`](Enum.chunk/4)             | [v1.7]        | `Enum.chunk_every/2`[`/3/4`](`Enum.chunk_every/4`) (v1.5)
-`not left in right`                              | [v1.7]        | [`left not in right`](`Kernel.SpecialForms.in/2`) (v1.5)
-`Registry.start_link/3`                          | [v1.7]        | `Registry.start_link/1` (v1.5)
-`Stream.chunk/2`[`/3/4`](Stream.chunk/4)         | [v1.7]        | `Stream.chunk_every/2`[`/3/4`](`Stream.chunk_every/4`) (v1.5)
+Deprecated feature                               | Deprecated in | Replaced by (available since)
+:----------------------------------------------- | :------------ | :----------------------------
 `Enum.partition/2`                               | [v1.6]        | `Enum.split_with/2` (v1.4)
-`Keyword.replace/3`                              | [v1.6]        | `Keyword.fetch/2` + `Keyword.put/3` (v1.0)
+`Keyword.replace/3`                              | [v1.6]        | Use `Keyword.fetch/2` + `Keyword.put/3` (v1.0)
 `Macro.unescape_tokens/1` and `Macro.unescape_tokens/2` | [v1.6] | Use `Enum.map/2` to traverse over the arguments (v1.0)
-`Module.add_doc/6`                               | [v1.6]        | `@doc` module attribute (v1.0)
-`Map.replace/3`                                  | [v1.6]        | `Map.fetch/2` + `Map.put/3` (v1.0)
-`Range.range?/1`                                 | [v1.6]        | Pattern match on `_.._` (v1.0)
+`Module.add_doc/6`                               | [v1.6]        | Use `@doc` instead
+`Map.replace/3`                                  | [v1.6]        | Use `Map.fetch/2` + `Map.put/3` (v1.0)
+`Range.range?/1`                                 | [v1.6]        | Pattern match on `_.._` instead (v1.0)
 `Atom.to_char_list/1`                            | [v1.5]        | `Atom.to_charlist/1` (v1.3)
-`Enum.filter_map/3`                              | [v1.5]        | `Enum.filter/2` + `Enum.map/2` or [`for`](`Kernel.SpecialForms.for/1`) comprehensions (v1.0)
+`Enum.filter_map/3`                              | [v1.5]        | `Enum.filter/2` + `Enum.map/2` or for comprehensions (v1.0)
 `Float.to_char_list/1`                           | [v1.5]        | `Float.to_charlist/1` (v1.3)
-`GenEvent` module                                | [v1.5]        | `Supervisor` and `GenServer` (v1.0);<br/>[`GenStage`](https://hex.pm/packages/gen_stage) (v1.3);<br/>[`:gen_event`](http://www.erlang.org/doc/man/gen_event.html) (Erlang/OTP 17)
+`GenEvent` module                                | [v1.5]        | `Supervisor` and `GenServer` (v1.0);<br/>[`GenStage`](https://hex.pm/packages/gen_stage) (v1.3);<br/>[`:gen_event`](http://www.erlang.org/doc/man/gen_event.html) (OTP 17)
 `Integer.to_char_list/1` and `Integer.to_char_list/2` | [v1.5]   | `Integer.to_charlist/1` and `Integer.to_charlist/2` (v1.3)
 `Kernel.to_char_list/1`                          | [v1.5]        | `Kernel.to_charlist/1` (v1.3)
 `List.Chars.to_char_list/1`                      | [v1.5]        | `List.Chars.to_charlist/1` (v1.3)
 `Stream.filter_map/3`                            | [v1.5]        | `Stream.filter/2` + `Stream.map/2` (v1.0)
-`String.ljust/3` and `String.rjust/3`            | [v1.5]        | Use `String.pad_leading/3` and `String.pad_trailing/3` with a binary padding (v1.3)
+`String.ljust/3` and `String.rjust/3`            | [v1.5]        | `String.pad_leading/3` and `String.pad_trailing/3` with a binary padding (v1.3)
 `String.strip/1` and `String.strip/2`            | [v1.5]        | `String.trim/1` and `String.trim/2` (v1.3)
 `String.lstrip/1` and `String.rstrip/1`          | [v1.5]        | `String.trim_leading/1` and `String.trim_trailing/1` (v1.3)
-`String.lstrip/2` and `String.rstrip/2`          | [v1.5]        | Use `String.trim_leading/2` and `String.trim_trailing/2` with a binary as second argument (v1.3)
+`String.lstrip/2` and `String.rstrip/2`          | [v1.5]        | `String.trim_leading/2` and `String.trim_trailing/2` with a binary as second argument (v1.3)
 `String.to_char_list/1`                          | [v1.5]        | `String.to_charlist/1` (v1.3)
 `()` to mean `nil`                               | [v1.5]        | `nil` (v1.0)
+`:as_char_lists` value in `t:Inspect.Opts.t/0` type | [v1.5]     | `:as_charlists` (v1.3)
+`:char_lists` key in `t:Inspect.Opts.t/0` type   | [v1.5]        | `:charlists` (v1.3)
 `char_list/0` type                               | [v1.5]        | `t:charlist/0` type (v1.3)
-`:char_lists` key in `t:Inspect.Opts.t/0` type   | [v1.5]        | `:charlists` key (v1.3)
-`:as_char_lists` value in `t:Inspect.Opts.t/0` type | [v1.5]     | `:as_charlists` value (v1.3)
 `@compile {:parse_transform, _}` in `Module`     | [v1.5]        | *None*
-EEx: `<%=` in middle and end expressions         | [v1.5]        | Use `<%` (`<%=` is allowed only on start expressions) (v1.0)
+EEx: `<%=` in middle and end expressions         | [v1.5]        | Use `<%` (= is allowed only on start expressions) (v1.0)
 `Access.key/1`                                   | [v1.4]        | `Access.key/2` (v1.3)
-`Behaviour` module                               | [v1.4]        | `@callback` module attribute (v1.0)
+`Behaviour` module                               | [v1.4]        | `@callback` (v1.0)
 `Enum.uniq/2`                                    | [v1.4]        | `Enum.uniq_by/2` (v1.2)
-`Float.to_char_list/2`                           | [v1.4]        | `:erlang.float_to_list/2` (Erlang/OTP 17)
-`Float.to_string/2`                              | [v1.4]        | `:erlang.float_to_binary/2` (Erlang/OTP 17)
+`Float.to_char_list/2`                           | [v1.4]        | `:erlang.float_to_list/2` (OTP 17)
+`Float.to_string/2`                              | [v1.4]        | `:erlang.float_to_binary/2` (OTP 17)
 `HashDict` module                                | [v1.4]        | `Map` (v1.2)
 `HashSet` module                                 | [v1.4]        | `MapSet` (v1.1)
- Multi-letter aliases in `OptionParser`          | [v1.4]        | Use single-letter aliases (v1.0)
 `Set` module                                     | [v1.4]        | `MapSet` (v1.1)
 `Stream.uniq/2`                                  | [v1.4]        | `Stream.uniq_by/2` (v1.2)
 `IEx.Helpers.import_file/2`                      | [v1.4]        | `IEx.Helpers.import_file_if_available/1` (v1.3)
@@ -113,7 +71,6 @@ EEx: `<%=` in middle and end expressions         | [v1.5]        | Use `<%` (`<%
 `Mix.Utils.underscore/1`                         | [v1.4]        | `Macro.underscore/1` (v1.2)
 Variable used as function call                   | [v1.4]        | Use parentheses (v1.0)
 Anonymous functions with no expression after `->` | [v1.4]       | Use an expression or explicitly return `nil` (v1.0)
-Support for making private functions overridable | [v1.4]        | Use public functions (v1.0)
 `Dict` module                                    | [v1.3]        | `Keyword` (v1.0) or `Map` (v1.2)
 `Keyword.size/1`                                 | [v1.3]        | `Kernel.length/1` (v1.0)
 `Map.size/1`                                     | [v1.3]        | `Kernel.map_size/1` (v1.0)
@@ -123,7 +80,7 @@ Support for making private functions overridable | [v1.4]        | Use public fu
 `:append_first` option in `Kernel.defdelegate/2` | [v1.3]        | Define the function explicitly (v1.0)
 `/r` option in `Regex`                           | [v1.3]        | `/U` (v1.1)
 `\x{X*}` inside strings/sigils/charlists         | [v1.3]        | `\uXXXX` or `\u{X*}` (v1.1)
-Map or dictionary as second argument in `Enum.group_by/3` | [v1.3] | `Enum.reduce/3` (v1.0)
+Map or dictionary as second argument in `Enum.group_by/3` | [v1.3] | Use `Enum.reduce/3` (v1.0)
 Non-map as second argument in `URI.decode_query/2` | [v1.3]      | Use a map (v1.0)
 `Dict` behaviour                                 | [v1.2]        | `MapSet` data structure (v1.1)
 `Access` protocol                                | [v1.1]        | `Access` behaviour (v1.1)
@@ -136,4 +93,3 @@ Non-map as second argument in `URI.decode_query/2` | [v1.3]      | Use a map (v1
 [v1.4]: https://github.com/elixir-lang/elixir/blob/v1.4/CHANGELOG.md#4-deprecations
 [v1.5]: https://github.com/elixir-lang/elixir/blob/v1.5/CHANGELOG.md#4-deprecations
 [v1.6]: https://github.com/elixir-lang/elixir/blob/v1.6/CHANGELOG.md#4-deprecations
-[v1.7]: https://github.com/elixir-lang/elixir/blob/v1.7/CHANGELOG.md#4-hard-deprecations

lib/elixir/pages/Guards.md

@@ -8,15 +8,12 @@ Not all expressions are allowed in guard clauses, but only a handful of them. Th
 
 For reference, the following is a comprehensive list of all expressions allowed in guards:
 
-  * comparison operators ([`==`](`Kernel.==/2`), [`!=`](`Kernel.!=/2`), [`===`](`Kernel.===/2`), [`!==`](`Kernel.!==/2`),
-    [`>`](`Kernel.>/2`), [`>=`](`Kernel.>=/2`), [`<`](`Kernel.</2`), [`<=`](`Kernel.<=/2`))
-  * strictly boolean operators ([`and`](`Kernel.and/2`), [`or`](`Kernel.or/2`), [`not`](`Kernel.not/1`))
-    - __NOTE__: [`&&`](`Kernel.&&/2`), [`||`](`Kernel.||/2`), and [`!`](`Kernel.!/1`) sibling operators are not allowed as they're not
-    *strictly* boolean - meaning they don't require both sides to be booleans
-  * arithmetic binary operators ([`+`](`Kernel.+/2`), [`-`](`Kernel.-/2`), [`*`](`Kernel.*/2`), [`/`](`Kernel.//2`))
-  * arithmetic unary operators ([`+`](`Kernel.+/1`), [`-`](`Kernel.-/1`))
-  * binary concatenation operator ([`<>`](`Kernel.<>/2`))
-  * [`in`](`Kernel.in/2`) and [`not in`](`Kernel.in/2`) operators (as long as the right-hand side is a list or a range)
+  * comparison operators (`==`, `!=`, `===`, `!==`, `>`, `>=`, `<`, `<=`)
+  * strictly boolean operators (`and`, `or`, `not`) (the `&&`, `||`, and `!` sibling operators are not allowed as they're not *strictly* boolean - meaning they don't require both sides to be booleans)
+  * arithmetic binary operators (`+`, `-`, `*`, `/`)
+  * arithmetic unary operators (`+`, `-`)
+  * binary concatenation operator (`<>`)
+  * `in` and `not in` operators (as long as the right-hand side is a list or a range)
   * the following "type-check" functions (all documented in the `Kernel` module):
     * `is_atom/1`
     * `is_binary/1`
@@ -53,12 +50,12 @@ For reference, the following is a comprehensive list of all expressions allowed
     * `trunc/1`
     * `tuple_size/1`
   * the following handful of Erlang bitwise operations, if imported from the `Bitwise` module:
-    * [`band/2`](`Bitwise.band/2`) or the [`&&&`](`Bitwise.&&&/2`) operator
-    * [`bor/2`](`Bitwise.bor/2`) or the [`|||`](`Bitwise.|||/2`) operator
-    * [`bnot/1`](`Bitwise.bnot/1`) or the [`~~~`](`Bitwise.~~~/1`) operator
-    * [`bsl/2`](`Bitwise.bsl/2`) or the [`<<<`](`Bitwise.<<</2`) operator
-    * [`bsr/2`](`Bitwise.bsr/2`) or the [`>>>`](`Bitwise.>>>/2`) operator
-    * [`bxor/2`](`Bitwise.bxor/2`) or the [`^^^`](`Bitwise.^^^/2`) operator
+    * `band/2` or the `&&&` operator
+    * `bor/2` or the `|||` operator
+    * `bnot/1` or the `~~~` operator
+    * `bsl/1` or the `<<<` operator
+    * `bsr/1` or the `>>>` operator
+    * `bxor/2` or the `^^^` operator
 
 Macros constructed out of any combination of the above guards are also valid guards - for example, `Integer.is_even/1`. See the section "Defining custom guard expressions" below.
 
@@ -86,7 +83,7 @@ In the example above, we show how guards can be used in function clauses. There
   def foo(term) when is_float(term), do: round(term)
   ```
 
-  * [`case`](`Kernel.SpecialForms.case/2`) expressions:
+  * `case` expressions:
 
   ```elixir
   case x do
@@ -96,7 +93,7 @@ In the example above, we show how guards can be used in function clauses. There
   end
   ```
 
-  * anonymous functions ([`fn`](`Kernel.SpecialForms.fn/1`)s):
+  * anonymous functions (`fn`s):
 
   ```elixir
   larger_than_two? = fn
@@ -108,7 +105,7 @@ In the example above, we show how guards can be used in function clauses. There
   * custom guards can also be defined with `Kernel.defguard/1` and `Kernel.defguardp/1`.
     A custom guard is always defined based on existing guards.
 
-Other constructs are [`for`](`Kernel.SpecialForms.for/1`), [`with`](`Kernel.SpecialForms.with/1`), [`try/rescue/catch/else`](`Kernel.SpecialForms.try/1`), and the `Kernel.match?/2`.
+Other constructs are `for`, `with`, `try`/`rescue`/`catch`/`else`/, and the `match?/2` macro in the `Kernel` module.
 
 ## Failing guards
 

lib/elixir/pages/Library Guidelines.md

@@ -1,285 +0,0 @@
-# Library Guidelines
-
-This document outlines general guidelines, anti-patterns, and rules for those writing and publishing Elixir libraries meant to be consumed by other developers.
-
-## Getting started
-
-You can create a new Elixir library by running the `mix new` command:
-
-    $ mix new my_library
-
-The project name is given in the `snake_case` convention where all letters are lowercase and words are separate with underscores. This is the same convention used by variables, function names and atoms in Elixir. See the [Naming Conventions](naming-conventions.html) document for more information.
-
-Every project has a `mix.exs` file, with instructions on how to build, compile, run tests, and so on. Libraries commonly have a `lib` directory, which includes Elixir source code, and a `test` directory. A `src` directory may also exist for Erlang sources.
-
-For more information on running your project, see the official [Mix & OTP guide](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) or [Mix documentation](https://hexdocs.pm/mix/Mix.html).
-
-### Applications with supervision tree
-
-The `mix new` command also allows the `--sup` flag to scaffold an application with a supervision tree out of the box. We talk about supervision trees later on when discussing one of the common anti-patterns when writing libraries.
-
-## Publishing
-
-Writing code is only the first of many steps to publish a package. We strongly recommend developers to:
-
-  * Choose a versioning schema. Elixir requires versions to be in the format `MAJOR.MINOR.PATCH` but the meaning of those numbers is up to you. Most projects choose [Semantic Versioning](https://semver.org/).
-
-  * Choose a [license](https://choosealicense.com/). The most common licenses in the Elixir community are the [MIT License](https://choosealicense.com/licenses/mit/) and the [Apache 2.0 License](https://choosealicense.com/licenses/apache-2.0/). The latter is also the one used by Elixir itself.
-
-  * Run the [code formatter](https://hexdocs.pm/mix/Mix.Tasks.Format.html). The code formatter formats your code according to a consistent style shared by your library and the whole community, making it easier for other developers to understand your code and contribute.
-
-  * Write tests. Elixir ships with a test-framework named [ExUnit](https://hexdocs.pm/ex_unit/ExUnit.html). The project generated by `mix new` includes sample tests and doctests.
-
-  * Write documentation. The Elixir community is proud of treating documentation as a first-class citizen and making documentation easily accessible. Libraries contribute to the status quo by providing complete API documentation with examples for their modules, types and functions. See the [Writing Documentation](writing-documentation.html) guide for more information. Projects like [ExDoc](https://github.com/elixir-lang/ex_doc) can be used to generate HTML and EPUB documents from the documentation. ExDoc also supports "extra pages", like this one that you are reading. Such pages augment the documentation with tutorials, guides and references.
-
-Projects are often made available to other developers [by publishing a Hex package](https://hex.pm/docs/publish). Hex also [supports private packages for organizations](https://hex.pm/pricing). If ExDoc is configured for the Mix project, publishing a package on Hex will also automatically publish the generated documentation to [HexDocs](https://hexdocs.pm).
-
-## Anti-patterns
-
-In this section we document common anti-patterns to avoid when writing libraries.
-
-### Avoid using exceptions for control-flow
-
-You should avoid using exceptions for control-flow. For example, instead of:
-
-```elixir
-try do
-  contents = File.read!("some_path_that_may_or_may_not_exist")
-  {:it_worked, contents}
-rescue
-  File.Error ->
-    :it_failed
-end
-```
-
-you should prefer:
-
-```elixir
-case File.read("some_path_that_may_or_may_not_exist") do
-  {:ok, contents} -> {:it_worked, contents}
-  {:error, _} -> :it_failed
-end
-```
-
-As a library author, it is your responsibility to make sure users are not required to use exceptions for control-flow in their applications. You can follow the same convention as Elixir here, using the name without `!` for returning `:ok`/`:error` tuples and appending `!` for a version of the function which raises an exception.
-
-It is important to note that a name without `!` does not mean a function will never raise. For example, even `File.read/1` can fail in case of bad arguments:
-
-```iex
-iex> File.read(1)
-** (FunctionClauseError) no function clause matching in IO.chardata_to_string/1
-```
-
-The usage of `:ok`/`:error` tuples is about the domain that the function works on, in this case, filesystem access. Bad arguments, logical errors, invalid options should raise regardless of the function name. If in doubt, prefer to return tuples instead of raising, as users of your library can always match on the results and raise if necessary.
-
-### Avoid working with invalid data
-
-Elixir programs should prefer to validate data as close to the end user as possible, so the errors are easy to locate and fix. This practice also saves you from writing defensive code in the internals of the library.
-
-For example, imagine you have an API that receives a filename as a binary. At some point you will want to write to this file. You could have a function like this:
-
-```elixir
-def my_fun(some_arg, file_to_write_to, options \\ []) do
-  ...some code...
-  AnotherModuleInLib.invoke_something_that_will_eventually_write_to_file(file_to_write_to)
-  ...more code...
-end
-```
-
-The problem with the code above is that, if the user supplies an invalid input, the error will be raised deep inside the library, which makes it confusing for users. Furthermore, when you don't validate the values at the boundary, the internals of your library are never quite sure which kind of values they are working with.
-
-A better function definition would be:
-
-```elixir
-def my_fun(some_arg, file_to_write_to, options \\ []) when is_binary(file_to_write_to) do
-```
-
-Elixir also leverages pattern matching and guards in function clauses to provide clear error messages in case invalid arguments are given.
-
-This advice does not only apply to libraries but to any Elixir code. Every time you receive multiple options or work with external data, you should validate the data at the boundary and convert it to structured data. For example, if you provide a `GenServer` that can be started with multiple options, you want to validate those options when the server starts and rely only on structured data throughout the process life cycle. Similarly, if a database or a socket gives you a map of strings, after you receive the data, you should validate it and potentially convert it to a struct or a map of atoms.
-
-### Avoid application configuration
-
-You should avoid using [the application environment](https://hexdocs.pm/elixir/Application.html#get_env/2) as the configuration mechanism for libraries. The application environment is **global** which means it becomes impossible for two dependencies to use your library in two different ways.
-
-Let's see a simple example. Imagine that you implement a library that breaks a string in two parts based on the first occurrence of the dash `-` character:
-
-```elixir
-defmodule DashSplitter do
-  def split(string) when is_binary(string) do
-    String.split(string, "-", parts: 2)
-  end
-end
-```
-
-Now imagine someone wants to split the string in three parts. You decide to make the number of parts configurable via the application environment:
-
-```elixir
-def split(string) when is_binary(string) do
-  parts = Application.get_env(:dash_splitter, :parts, 2)
-  String.split(string, "-", parts: parts)
-end
-```
-
-Now users can configure your library in their `config/config.exs` file as follows:
-
-```elixir
-config :dash_splitter, :parts, 3
-```
-
-Once your library is configured, it will change the behaviour of all users of your library. If a library was expecting it to split the string in 2 parts, since the configuration is global, it will now split it in 3 parts.
-
-The solution is to provide configuration as close as possible to where it is used and not via the application environment. In case of a function, you could expect keyword lists as a new argument:
-
-```elixir
-def split(string, opts \\ []) when is_binary(string) and is_list(opts) do
-  parts = Keyword.get(opts, :parts, 2)
-  String.split(string, "-", parts: parts)
-end
-```
-
-In case you need to configure a process, the options should be passed when starting that process.
-
-The application environment should be reserved only for configurations that are truly global, for example, to control your application boot process and its supervision tree.
-
-For all remaining scenarios, libraries should not force their users to use the application environment for configuration. If the user of a library believes that certain parameter should be configured globally, then they can wrap the library functionality with their own application environment configuration.
-
-### Avoid `use` when an `import` is enough
-
-A library should not provide `use MyLib` functionality if all `use MyLib` does is to `import`/`alias` the module itself. For example, this is an anti-pattern:
-
-```elixir
-defmodule MyLib do
-  defmacro __using__(_) do
-    quote do
-      import MyLib
-    end
-  end
-
-  def some_fun(arg1, arg2) do
-    ...
-  end
-end
-```
-
-The reason why defining the `__using__` macro above should be avoided is because when a developer writes:
-
-```elixir
-defmodule MyApp do
-  use MyLib
-end
-```
-
-it allows `use MyLib` to run *any* code into the `MyApp` module. For someone reading the code, it is impossible to assess the impact that `use MyLib` has in a module without looking at the implementation of `__using__`.
-
-The following code is much clearer:
-
-```elixir
-defmodule MyApp do
-  import MyLib
-end
-```
-
-The code above says we are only bringing in the functions from `MyLib` so we can invoke `some_fun(arg1, arg2)` directly without the `MyLib.` prefix. Even more important, `import MyLib` says that we have an option to not `import MyLib` at all as we can simply invoke the function as `MyLib.some_fun(arg1, arg2)`.
-
-If the module you want to invoke a function on has a long name, such as `SomeLibrary.Namespace.MyLib`, and you find it verbose, you can leverage the `alias/2` special form and still refer to the module as `MyLib`.
-
-While there are many situations where using a module is required, `use` should be skipped when all it does is to `import` or `alias` a module. In a nutshell, `alias` is simpler and clearer than `import`, and `import` is simpler and clearer than `use`.
-
-### Avoid macros
-
-Although the previous section could be summarized as "avoid macros", both topics are important enough to deserve their own sections.
-
-To quote [the official guide on Macros](https://elixir-lang.org/getting-started/meta/macros.html):
-
-> Even though Elixir attempts its best to provide a safe environment for macros, the major responsibility of writing clean code with macros falls on developers. Macros are harder to write than ordinary Elixir functions and it’s considered to be bad style to use them when they’re not necessary. So write macros responsibly.
->
-> Elixir already provides mechanisms to write your everyday code in a simple and readable fashion by using its data structures and functions. Macros should only be used as a last resort. Remember that **explicit is better than implicit**. **Clear code is better than concise code**.
-
-When you absolutely have to use a macro, make sure that a macro is not the only way the user can interface with your library and keep the amount of code generated by a macro to a minimum. For example, the `Logger` module provides `debug/2`, `info/2` and friends as macros that are capable of extracting environment information, but a low-level mechanism for logging is still available with `Logger.bare_log/3`.
-
-### Avoid using processes for code organization
-
-A developer must never use a process for code organization purposes. A process must be used to model runtime properties such as:
-
-  * Mutable state and access to shared resources (such as ets, files, etc)
-  * Concurrency and distribution
-  * Initialization, shutdown and restart logic (as seen in supervisors)
-  * System messages such as timer messages and monitoring events
-
-In Elixir, code organization is done by modules and functions, processes are not necessary. For example, imagine you are implementing a calculator and you decide to put all the calculator operations behind a `GenServer`:
-
-```elixir
-def add(a, b) do
-  GenServer.call(__MODULE__, {:add, a, b})
-end
-
-def handle_call({:add, a, b}, _from, state) do
-  {:reply, a + b, state}
-end
-
-def handle_call({:subtract, a, b}, _from, state) do
-  {:reply, a - b, state}
-end
-```
-
-This is an anti-pattern not only because it convolutes the calculator logic but also because you put the calculator logic behind a single process that will potentially become a bottleneck in your system, especially as the number of calls grow. Instead just define the functions directly:
-
-```elixir
-def add(a, b) do
-  a + b
-end
-
-def subtract(a, b) do
-  a - b
-end
-```
-
-Use processes only to model runtime properties, never for code organization. And even when you think something could be done in parallel with processes, often it is best to let the callers of your library decide how to parallelize, rather than impose a certain execution flow in users of your code.
-
-### Avoid spawning unsupervised processes
-
-You should avoid spawning processes outside of a supervision tree, especially long-running ones. Instead, processes must be started inside supervision trees. This guarantees developers have full control over the initialization, restarts, and shutdown of the system.
-
-If your application does not have a supervision tree, one can be added by changing `def application` inside `mix.exs` to include a `:mod` key with the application callback name:
-
-```elixir
-def application do
-  [
-    extra_applications: [:logger],
-    mod: {MyApp.Application, []}
-  ]
-end
-```
-
-and then defining a `my_app/application.ex` file with the following template:
-
-```elixir
-defmodule MyApp.Application do
-    # See https://hexdocs.pm/elixir/Application.html
-    # for more information on OTP Applications
-    @moduledoc false
-
-    use Application
-
-    def start(_type, _args) do
-      # List all child processes to be supervised
-      children = [
-        # Starts a worker by calling: MyApp.Worker.start_link(arg)
-        # {MyApp.Worker, arg},
-      ]
-
-      # See https://hexdocs.pm/elixir/Supervisor.html
-      # for other strategies and supported options
-      opts = [strategy: :one_for_one, name: MyApp.Supervisor]
-      Supervisor.start_link(children, opts)
-    end
-  end
-end
-```
-
-This is the same template generated by `mix new --sup`.
-
-Each process started with the application must be listed as a child under the `Supervisor` above. We call those "static processes" because they are known upfront. For handling dynamic processes, such as the ones started during requests and other user inputs, look at the `DynamicSupervisor` module.
-
-One of the few times where it is acceptable to start a process outside of a supervision tree is with `Task.async/1` and `Task.await/2`. Opposite to `Task.start_link/1`, the `async/await` mechanism gives you full control over the spawned process life cycle - which is also why you must always call `Task.await/2` after starting a task with `Task.async/1`. Even though, if your application is spawning multiple async processes, you should consider using `Task.Supervisor` for better visibility when instrumenting and monitoring the system.

lib/elixir/pages/Naming Conventions.md

@@ -15,7 +15,7 @@ Atoms can be written either in `:snake_case` or `:CamelCase`, although the conve
 
 Generally speaking, filenames follow the `snake_case` convention of the module they define. For example, `MyApp` should be defined inside the `my_app.ex` file. However, this is only a convention. At the end of the day, any filename can be used as they do not affect the compiled code in any way.
 
-## Underscore (`_foo`)
+## Underscore (_foo)
 
 Elixir relies on underscores in different situations.
 
@@ -40,9 +40,9 @@ Due to this property, Elixir relies on functions starting with underscore to att
     iex> String.__info__(:functions)
     [at: 2, capitalize: 1, chunk: 2, ...]
 
-Elixir also includes five special forms that follow the double underscore format: `__CALLER__/0`, `__DIR__/0`, `__ENV__/0`and `__MODULE__/0` retrieve compile-time information about the current environment, while `__STACKTRACE__/0` retrieves the stacktrace for the current exception.
+Elixir also includes four special forms that follow the double underscore format. These forms retrieve compile-time information about the current environment: `__MODULE__/0`, `__DIR__/0`, `__ENV__/0` and `__CALLER__/0`.
 
-## Trailing bang (`foo!`)
+## Trailing bang (foo!)
 
 A trailing bang (exclamation mark) signifies a function or macro where failure cases raise an exception.
 
@@ -73,7 +73,7 @@ There are also some non-paired functions, with no non-bang variant. The bang sti
 
 In macro code, the bang on `Kernel.alias!/1` and `Kernel.var!/2` signifies that [macro hygiene](http://elixir-lang.org/getting-started/meta/macros.html#macros-hygiene) is set aside.
 
-## Trailing question mark (`foo?`)
+## Trailing question mark (foo?)
 
 Functions that return a boolean are named with a trailing question mark.
 
@@ -81,7 +81,7 @@ Examples: `Keyword.keyword?/1`, `Mix.debug?/0`, `String.contains?/2`
 
 However, functions that return booleans and are valid in guards follow another convention, described next.
 
-## `is_` prefix (`is_foo`)
+## is_ prefix (is_foo)
 
 Type checks and other boolean checks that are allowed in guard clauses are named with an `is_` prefix.
 

lib/elixir/pages/Operators.md

@@ -26,22 +26,22 @@ Operator
 `\|`                                                                                     | Right to left
 `::`                                                                                     | Right to left
 `when`                                                                                   | Right to left
-`<-` `\\`                                                                                | Left to right
+`<-`, `\\`                                                                               | Left to right
 
 ## Comparison operators
 
 Elixir provides the following built-in comparison operators:
 
-  * [`==`](`Kernel.==/2`) - equality
-  * [`===`](`Kernel.===/2`) - strict equality
-  * [`!=`](`Kernel.!=/2`) - inequality
-  * [`!==`](`Kernel.!==/2`) - strict inequality
-  * [`>`](`Kernel.>/2`) - greater than
-  * [`<`](`Kernel.</2`) - less than
-  * [`>=`](`Kernel.>=/2`) - greater than or equal
-  * [`<=`](`Kernel.<=/2`) - less than or equal
+  * `==` - equality
+  * `===` - strict equality
+  * `!=` - inequality
+  * `!==` - strict inequality
+  * `>` - greater than
+  * `<` - less than
+  * `>=` - greater than or equal
+  * `<=` - less than or equal
 
-The only difference between [`==`](`Kernel.==/2`) and [`===`](`Kernel.===/2`) is that [`===`](`Kernel.===/2`) is stricter when it comes to comparing integers and floats:
+The only difference between `==` and `===` is that `===` is stricter when it comes to comparing integers and floats:
 
 ```elixir
 iex> 1 == 1.0
@@ -50,7 +50,7 @@ iex> 1 === 1.0
 false
 ```
 
-[`!=`](`Kernel.!=/2`) and [`!==`](`Kernel.!==/2`) act as the negation of [`==`](`Kernel.==/2`) and [`===`](`Kernel.===/2`), respectively.
+`!=` and `!==` act as the negation of `==` and `===`, respectively.
 
 ### Term ordering
 
@@ -120,7 +120,7 @@ The following is a table of all the operators that Elixir is capable of parsing,
   * `^^^`
   * `~~~`
 
-The following operators are used by the `Bitwise` module when imported: [`&&&`](`Bitwise.&&&/2`), [`^^^`](`Bitwise.^^^/2`), [`<<<`](`Bitwise.<<</2`), [`>>>`](`Bitwise.>>>/2`), [`|||`](`Bitwise.|||/2`), [`~~~`](`Bitwise.~~~/1`). See the documentation for `Bitwise` for more information.
+The following operators are used by the `Bitwise` module when imported: `&&&`, `^^^`, `<<<`, `>>>`, `|||`, `~~~`. See the documentation for `Bitwise` for more information.
 
 ### Redefining existing operators
 

lib/elixir/pages/Syntax Reference.md

@@ -6,7 +6,7 @@ This document covers all of Elixir syntax constructs as a reference and then dis
 
 ## Reserved words
 
-These are the reserved words in the Elixir language. They are detailed throughout this guide but summed up here for convenience:
+Those are the reserved words in the Elixir language. They are detailed throughout this guide but summed up here for convenience:
 
   * `true`, `false`, `nil` - used as atoms
   * `when`, `and`, `or`, `not`, `in` - used as operators
@@ -21,7 +21,7 @@ Integers (`1234`) and floats (`123.4`) in Elixir are represented as a sequence o
 
 ### Atoms
 
-Atoms in Elixir start with a colon (`:`) which must be followed by non-combining Unicode characters and underscore. The atom may continue using a sequence of Unicode characters, including numbers, underscore and `@`. Atoms may end in `!` or `?`. See [Unicode Syntax](unicode-syntax.html) for a formal specification. Unicode characters require Erlang/OTP 20.
+Atoms in Elixir start with a colon (`:`) which must be followed by non-combining Unicode characters and underscore. The atom may continue using a sequence of Unicode characters, including numbers, underscore and `@`. Atoms may end in `!` or `?`. See [Unicode Syntax](unicode-syntax.html) for a formal specification. Unicode characters require OTP 20.
 
 All operators in Elixir are also valid atoms. Valid examples are `:foo`, `:FOO`, `:foo_42`, `:foo@bar` and `:++`. Invalid examples are `:@foo` (`@` is not allowed at start), `:123` (numbers are not allowed at start) and `:(*)` (not a valid operator).
 
@@ -80,13 +80,13 @@ Structs built on the map syntax by passing the struct name between `%` and `{`.
 
 ### Variables
 
-Variables in Elixir must start with underscore or a non-combining Unicode character that is not in uppercase or titlecase. The variable may continue using a sequence of Unicode characters, including numbers and underscore. Variables may end in `?` or `!`. See [Unicode Syntax](unicode-syntax.html) for a formal specification. Unicode characters require Erlang/OTP 20.
+Variables in Elixir must start with underscore or a non-combining Unicode character that is not in uppercase or titlecase. The variable may continue using a sequence of Unicode characters, including numbers and underscore. Variables may end in `?` or `!`. See [Unicode Syntax](unicode-syntax.html) for a formal specification. Unicode characters require OTP 20.
 
 [Elixir's naming conventions](naming-conventions.html) recommend variables to be in `snake_case` format.
 
 ### Non-qualified calls (local calls)
 
-Non-qualified calls, such as `add(1, 2)`, must start with underscore or a non-combining Unicode character that is not in uppercase or titlecase. The call may continue using a sequence of Unicode characters, including numbers and underscore. Calls may end in `?` or `!`. See [Unicode Syntax](unicode-syntax.html) for a formal specification. Unicode characters require Erlang/OTP 20.
+Non-qualified calls, such as `add(1, 2)`, must start with underscore or a non-combining Unicode character that is not in uppercase or titlecase. The call may continue using a sequence of Unicode characters, including numbers and underscore. Calls may end in `?` or `!`. See [Unicode Syntax](unicode-syntax.html) for a formal specification. Unicode characters require OTP 20.
 
 Parentheses for non-qualified calls are optional, except for zero-arity calls, which would then be ambiguous with variables. If parentheses are used, they must immediately follow the function name *without spaces*. For example, `add (1, 2)` is a syntax error, since `(1, 2)` is treated as an invalid block which is attempted to be given as a single argument to `add`.
 
@@ -98,7 +98,7 @@ As many programming languages, Elixir also support operators as non-qualified ca
 
 ### Qualified calls (remote calls)
 
-Qualified calls, such as `Math.add(1, 2)`, must start with underscore or a non-combining Unicode character that is not in uppercase or titlecase. The call may continue using a sequence of Unicode characters, including numbers and underscore. Calls may end in `?` or `!`. See [Unicode Syntax](unicode-syntax.html) for a formal specification. Unicode characters require Erlang/OTP 20.
+Qualified calls, such as `Math.add(1, 2)`, must start with underscore or a non-combining Unicode character that is not in uppercase or titlecase. The call may continue using a sequence of Unicode characters, including numbers and underscore. Calls may end in `?` or `!`. See [Unicode Syntax](unicode-syntax.html) for a formal specification. Unicode characters require OTP 20.
 
 [Elixir's naming conventions](naming-conventions.html) recommend calls to be in `snake_case` format.
 
@@ -118,7 +118,7 @@ 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. The left side may have zero, one or more arguments, the right side is zero, one or more expressions separated by new line. The `->` is always between one of the following terminators: `do`/`end`, `fn`/`end` or `(`/`)`.
+The left to right arrow (`->`) is used to establish a relationship between left and right. The left side may have zero, one or more arguments, the right side is zero, one or more expressions separted by new line. The `->` is always between one of the following terminators: `do`/`end`, `fn`/`end` or `(`/`)`.
 
 It is seen on `case` and `cond` constructs between `do`/`end`:
 

lib/elixir/pages/Typespecs.md

@@ -14,41 +14,20 @@ Type specifications (sometimes referred to as *typespecs*) are defined in differ
   * `@callback`
   * `@macrocallback`
 
-See the "User-defined types" and "Defining a specification" sub-sections below for more information on defining types and typespecs.
-
-## A simple example
-
-    defmodule StringHelpers do
-      @type word() :: String.t()
-
-      @spec long_word?(word()) :: boolean()
-      def long_word?(word) when is_binary(word) do
-        String.length(word) > 8
-      end
-    end
-
-In the example above, this happens:
-
-  * we declare a new type (`word()`) that is equivalent to the string type (`String.t()`);
-
-  * we specify that the `long_word?/1` function takes an argument of type `word()` and
-    returns a boolean (`boolean()`), that is, either `true` or `false`.
+See the "Defining a type" and "Defining a specification" sub-sections below for more information on defining types and typespecs.
 
 ## Types and their syntax
 
-The syntax Elixir provides for type specifications is similar to [the one in Erlang](http://www.erlang.org/doc/reference_manual/typespec.html). Most of the built-in types provided in Erlang (for example, `pid()`) are expressed in the same way: `pid()` (or simply `pid`). Parameterized types (such as `list(integer)`) are supported as well and so are remote types (such as `Enum.t`). Integers and atom literals are allowed as types (e.g., `1`, `:atom`, or `false`). All other types are built out of unions of predefined types. Some shorthands are allowed, such as `[...]`, `<<>>`, and `{...}`.
-
-The notation to represent the union of types is the pipe `|`. For example, the typespec `type :: atom() | pid() | tuple()` creates a type `type` that can be either an `atom`, a `pid`, or a `tuple`. This is usually called a [sum type](https://en.wikipedia.org/wiki/Tagged_union) in other languages
+The syntax Elixir provides for type specifications is similar to [the one in Erlang](http://www.erlang.org/doc/reference_manual/typespec.html). Most of the built-in types provided in Erlang (for example, `pid()`) are expressed in the same way: `pid()` (or simply `pid`). Parametrized types (such as `list(integer)`) are supported as well and so are remote types (such as `Enum.t`). Integers and atom literals are allowed as types (e.g., `1`, `:atom`, or `false`). All other types are built out of unions of predefined types. Some shorthands are allowed, such as `[...]`, `<<>>`, and `{...}`.
 
 ### Basic types
 
-    type ::
-          any()                     # the top type, the set of all terms
+    type :: any()                   # the top type, the set of all terms
           | none()                  # the bottom type, contains no terms
           | atom()
           | map()                   # any map
           | pid()                   # process identifier
-          | port()                  # port identifier
+          | port()
           | reference()
           | struct()                # any struct
           | tuple()                 # tuple of any size
@@ -77,7 +56,7 @@ The notation to represent the union of types is the pipe `|`. For example, the t
 The following literals are also supported in typespecs:
 
     type ::                               ## Atoms
-          :atom                           # atoms: :foo, :bar, ...
+            :atom                         # atoms: :foo, :bar, ...
           | true | false | nil            # special atom literals
 
                                           ## Bitstrings
@@ -86,10 +65,10 @@ The following literals are also supported in typespecs:
           | <<_::_*unit>>                 # unit is an integer from 1 to 256
           | <<_::size, _::_*unit>>
 
-                                          ## (Anonymous) Functions
-          | (-> type)                     # 0-arity, returns type
-          | (type1, type2 -> type)        # 2-arity, returns type
+                                          ## Functions
           | (... -> type)                 # any arity, returns type
+          | (() -> type)                  # 0-arity, returns type
+          | (type1, type2 -> type)        # 2-arity, returns type
 
                                           ## Integers
           | 1                             # integer
@@ -256,8 +235,8 @@ If a callback module that implements a given behaviour doesn't export all the fu
 
 Elixir's standard library contains a few frequently used behaviours such as `GenServer`, `Supervisor`, and `Application`.
 
-## The `string()` type
+## Notes
 
-Elixir discourages the use of the `string()` type. The `string()` type refers to Erlang strings, which are known as "charlists" in Elixir. They do not refer to Elixir strings, which are UTF-8 encoded binaries. To avoid confusion, if you attempt to use the type `string()`, Elixir will emit a warning. You should use `charlist()`, `binary()` or `String.t()` accordingly.
+Elixir discourages the use of type `t:string/0` as it might be confused with binaries which are referred to as "strings" in Elixir (as opposed to character lists). In order to use the type that is called `t:string/0` in Erlang, one has to use the `t:charlist/0` type which is a synonym for `string`. If you use `string`, you'll get a warning from the compiler.
 
-Note `String.t()` and `binary()` are equivalent to analysis tools. Although, for those reading the documentation, `String.t()` implies it is a UTF-8 encoded binary.
+If you want to refer to the "string" type (the one operated on by functions in the `String` module), use `t:String.t/0` type instead.

lib/elixir/pages/Unicode Syntax.md

@@ -4,58 +4,56 @@ Elixir supports Unicode throughout the language.
 
 Quoted identifiers, such as strings (`"olá"`) and charlists (`'olá'`), support Unicode since Elixir v1.0. Strings are UTF-8 encoded. Charlists are lists of Unicode codepoints. In such cases, the contents are kept as written by developers, without any transformation.
 
-Elixir also supports Unicode in identifiers since Elixir v1.5, as defined in the [Unicode Annex #31](http://unicode.org/reports/tr31/). The focus of this document is to describe how Elixir implements the requirements outlined in the Unicode Annex. These requirements are referred to as R1, R6 and so on.
+Elixir also supports Unicode in identifiers since Elixir v1.5, as defined in the [Unicode Annex #31](http://unicode.org/reports/tr31/). The focus of this document is to describe how Elixir implements the requirements outlined in the Unicode Annex. These requirements are refered to as R1, R6 and so on.
 
 To check the Unicode version of your current Elixir installation, run `String.Unicode.version()`.
 
 ## R1. Default Identifiers
 
-The general Elixir identifier rule is specified as:
+Elixir identifiers are specified as:
 
     <Identifier> := <Start> <Continue>* <Ending>?
 
-where `<Start>` uses the same categories as the spec but restricts them to the NFC form (see R6):
+where `<Start>` is:
 
 > characters derived from the Unicode General Category of uppercase letters, lowercase letters, titlecase letters, modifier letters, other letters, letter numbers, plus `Other_ID_Start`, minus `Pattern_Syntax` and `Pattern_White_Space` code points
 >
-> In set notation: `[\p{L}\p{Nl}\p{Other_ID_Start}-\p{Pattern_Syntax}-\p{Pattern_White_Space}]`
+> In set notation: `[[:L:][:Nl:][:Other_ID_Start:]--[:Pattern_Syntax:]--[:Pattern_White_Space:]]`
 
-and `<Continue>` uses the same categories as the spec but restricts them to the NFC form (see R6):
+and `<Continue>` is:
 
 > ID_Start characters, plus characters having the Unicode General Category of nonspacing marks, spacing combining marks, decimal number, connector punctuation, plus `Other_ID_Continue`, minus `Pattern_Syntax` and `Pattern_White_Space` code points.
 >
-> In set notation: `[\p{ID_Start}\p{Mn}\p{Mc}\p{Nd}\p{Pc}\p{Other_ID_Continue}-\p{Pattern_Syntax}-\p{Pattern_White_Space}]`
+> In set notation: `[[:ID_Start:][:Mn:][:Mc:][:Nd:][:Pc:][:Other_ID_Continue:]--[:Pattern_Syntax:]--[:Pattern_White_Space:]]`
 
-`<Ending>` is an addition specific to Elixir that includes only the codepoints `?` (003F) and `!` (0021).
+`<Ending>` is an addition specific to Elixir that includes the codepoints ? (003F) and ! (0021).
 
-The spec also provides a `<Medial>` set but Elixir does not include any character on this set. Therefore the identifier rule has been simplified to consider this.
-
-Elixir does not allow the use of ZWJ or ZWNJ in identifiers and therefore does not implement R1a. R1b is guaranteed for backwards compatibility purposes.
+Elixir also implements requirements R1a for security and R1b for backwards compatibility.
 
 ### Atoms
 
 Atoms in Elixir follow the identifier rule above with the following modifications:
 
-  * `<Start>` includes the codepoint `_` (005F)
-  * `<Continue>` includes the codepoint `@` (0040)
+  * `<Start>` includes the codepoint _ (005F)
+  * `<Continue>` includes the codepoint @ (0040)
 
 ### Variables
 
 Variables in Elixir follow the identifier rule above with the following modifications:
 
-  * `<Start>` includes the codepoint `_` (005F)
+  * `<Start>` includes the codepoint _ (005F)
   * `<Start>` must not include Lu (letter uppercase) and Lt (letter titlecase) characters
 
 ## R3. Pattern_White_Space and Pattern_Syntax Characters
 
-Elixir supports only codepoints `\t` (0009), `\n` (000A), `\r` (000D) and `\s` (0020) as whitespace and therefore does not follow requirement R3. R3 requires a wider variety of whitespace and syntax characters to be supported.
+Elixir supports only codepoints \t (0009), \n (000A), \r (000D) and \s (0020) as whitespace and therefore does not follow requirement R3. R3 requires a wider variety of whitespace and syntax characters to be supported.
 
 ## R6. Filtered Normalized Identifiers
 
 Identifiers in Elixir are case sensitive.
 
-Elixir requires all atoms and variables to be in NFC form. Any other form will fail with a relevant error message. Quoted-atoms and strings can, however, be in any form and are not verified by the parser.
+Elixir requires all atoms and variables to be in NFC form. Any other form will fail with a relevant error message. Quoted-atoms and variables can, however, be in any form and are not verified by the parser.
 
-In other words, the atom `:josé` can only be written with the codepoints `006A 006F 0073 00E9`. Using another normalization form will lead to a tokenizer error. On the other hand, `:"josé"` may be written as `006A 006F 0073 00E9` or `006A 006F 0073 0065 0301`, since it is written between quotes.
+In other words, the atom `:josé` can only be written with the codepoints 006A 006F 0073 00E9. Using another normalization form will lead to a tokenizer error. On the other hand, `:"josé"` may be written as 006A 006F 0073 00E9 or 006A 006F 0073 0065 0301, since it is written in quotes.
 
 Choosing requirement R6 automatically excludes requirements R4, R5 and R7.

lib/elixir/pages/Writing Documentation.md

@@ -46,7 +46,7 @@ When documenting a function, argument names are inferred by the compiler. For ex
 
 The compiler will infer this argument as `map`. Sometimes the inference will be suboptimal, especially if the function contains multiple clauses with the argument matching on different values each time. You can specify the proper names for documentation by declaring only the function head at any moment before the implementation:
 
-    def size(map_with_size)
+    def size(map)
     def size(%{size: size}) do
       size
     end
@@ -121,6 +121,6 @@ Elixir warns if a private function has a `@doc` attribute and discards its conte
 
 Private functions may still need internal documentation for maintainers, though. That can be accomplished with code comments.
 
-## Code.fetch_docs/1
+## Code.get_docs/2
 
-Elixir stores documentation inside pre-defined chunks in the bytecode. It can be accessed from Elixir by using the `Code.fetch_docs/1` function. This also means documentation is only accessed when required and not when modules are loaded by the Virtual Machine. The only downside is that modules defined in-memory, like the ones defined in IEx, cannot have their documentation accessed as they do not have their bytecode written to disk.
+Elixir stores documentation inside pre-defined chunks in the bytecode. It can be accessed from Elixir by using the `Code.get_docs/2` function. This also means documentation is only accessed when required and not when modules are loaded by the Virtual Machine. The only downside is that modules defined in-memory, like the ones defined in IEx, cannot have their documentation accessed as they do not have their bytecode written to disk.

lib/elixir/rebar.config

@@ -1,4 +1,4 @@
-{'src/*', [
+{erl_opts, [
   warn_unused_vars,
   warn_export_all,
   warn_shadow_vars,
@@ -14,6 +14,10 @@
   %% warn_missing_spec,
   %% warn_untyped_record,
   %% warnings_as_errors,
-  debug_info,
-  {outdir, "ebin/"}
+  debug_info
+]}.
+
+{yrl_opts, [
+  {report, true},
+  {verbose, false}
 ]}.