diff --git a/lib/elixir/lib/exception.ex b/lib/elixir/lib/exception.ex index e1f8f82a434..69b862c8a27 100644 --- a/lib/elixir/lib/exception.ex +++ b/lib/elixir/lib/exception.ex @@ -1040,7 +1040,15 @@ defmodule ArgumentError do An exception raised when an argument to a function is invalid. You can raise this exception when you want to signal that an argument to - a function is invalid. + a function is invalid. For example, this exception is raised when calling + `Integer.to_string/1` with an invalid argument: + + iex> Integer.to_string(1.0) + ** (ArgumentError) errors were found at the given arguments: + + * 1st argument: not an integer + + :erlang.integer_to_binary(1.0) `ArgumentError` exceptions have a single field, `:message` (a `t:String.t/0`), which is public and can be accessed freely when reading or creating `ArgumentError` @@ -1104,7 +1112,11 @@ defmodule SystemLimitError do @moduledoc """ An exception raised when a system limit has been reached. - For example, this can happen if you try to create an atom that is too large. + For example, this can happen if you try to create an atom that is too large: + + iex> String.to_atom(String.duplicate("a", 100_000)) + ** (SystemLimitError) a system limit has been reached + """ defexception message: "a system limit has been reached" @@ -1252,6 +1264,8 @@ defmodule TokenMissingError do * `:opening_delimiter` - an atom representing the opening delimiter * `:expected_delimiter` - an atom representing the expected delimiter * `:description` - a description of the missing token error + + This is mostly raised by Elixir tooling when compiling and evaluating code. """ defexception [ @@ -1337,6 +1351,7 @@ defmodule CompileError do the error occurred in code that did not come from a file * `:line` (`t:non_neg_integer/0`) - the line where the error occurred + This is mostly raised by Elixir tooling when compiling and evaluating code. """ defexception [:file, :line, description: "compile error"] @@ -1360,6 +1375,14 @@ defmodule Kernel.TypespecError do the error occurred in code that did not come from a file * `:line` (`t:non_neg_integer/0`) - the line where the error occurred + For example, if your typespec definition points to an invalid type, you get an exception: + + @type my_type :: intger() + + will raise: + + ** (Kernel.TypespecError) type strng/0 undefined + """ defexception [:file, :line, :description] @@ -1374,6 +1397,17 @@ defmodule Kernel.TypespecError do end defmodule BadFunctionError do + @moduledoc """ + An exception raised when a function is expected, but something else was given. + + For example: + + iex> value = "hello" + value.() + ** (BadFunctionError) expected a function, got: "hello" + + """ + defexception [:term] @impl true @@ -1399,7 +1433,14 @@ end defmodule BadMapError do @moduledoc """ - An exception raised when something expected a map, but received something else. + An exception raised when a map is expected, but something else was given. + + For example: + + iex> value = "hello" + %{value | key: "value"} + ** (BadMapError) expected a map, got: "hello" + """ defexception [:term] @@ -1412,7 +1453,13 @@ end defmodule BadBooleanError do @moduledoc """ - An exception raised when an operator expected a boolean, but received something else. + An exception raised when a boolean is expected, but something else was given. + + This exception is raised by `and` and `or` when the first argument is not a boolean: + + iex(1)> 123 and true + ** (BadBooleanError) expected a boolean on left-side of "and", got: 123 + """ defexception [:term, :operator] @@ -1524,8 +1571,19 @@ end defmodule TryClauseError do @moduledoc """ - An exception raised when a term in a `try/1` expression - does not match any of the defined `->` clauses in its `else`. + An exception raised when none of the `else` clauses in a `try/1` match. + + For example: + + iex> try do + ...> :ok + ...> rescue + ...> e -> e + ...> else + ...> # :ok -> :ok is missing + ...> :not_ok -> :not_ok + ...> end + ** (TryClauseError) no try clause matching: :ok The following fields of this exception are public and can be accessed freely: @@ -1543,6 +1601,13 @@ end defmodule BadArityError do @moduledoc """ An exception raised when a function is called with the wrong number of arguments. + + For example: + + iex> my_function = fn x, y -> x + y end + iex> my_function.(42) + ** (BadArityError) #Function<41.39164016/2 in :erl_eval.expr/6> with arity 2 called with 1 argument (42) + """ defexception [:function, :args] @@ -1955,6 +2020,11 @@ defmodule Code.LoadError do @moduledoc """ An exception raised when a file cannot be loaded. + This is typically raised by functions in the `Code` module, for example: + + iex> Code.require_file("missing_file.exs") + ** (Code.LoadError) could not load missing_file.exs. Reason: enoent + The following fields of this exception are public and can be accessed freely: * `:file` (`t:String.t/0`) - the file name @@ -2054,7 +2124,11 @@ defmodule KeyError do An exception raised when a key is not found in a data structure. For example, this is raised by `Map.fetch!/2` when the given key - cannot be found in the given map. + cannot be found in the given map: + + iex> map = %{name: "Alice", age: 25} + iex> Map.fetch!(map, :first_name) + ** (KeyError) key :first_name not found in: %{name: "Alice", age: 25} The following fields of this exception are public and can be accessed freely: @@ -2138,6 +2212,15 @@ defmodule KeyError do end defmodule UnicodeConversionError do + @moduledoc """ + An exception raised when converting data to or from Unicode. + + For example: + + iex> String.to_charlist(<<0xFF>>) + ** (UnicodeConversionError) invalid encoding starting at <<255>> + + """ defexception [:encoded, :message] def exception(opts) do @@ -2215,7 +2298,11 @@ defmodule Enum.OutOfBoundsError do An exception that is raised when a function expects an enumerable to have a certain size but finds that it is too small. - For example, this is raised by `Access.at!/1`. + For example: + + iex> Enum.fetch!([1, 2, 3], 5) + ** (Enum.OutOfBoundsError) out of bounds error + """ defexception [:enumerable, :index, :message] @@ -2244,7 +2331,11 @@ defmodule Enum.EmptyError do An exception that is raised when something expects a non-empty enumerable but finds an empty one. - For example, this is raised by `Enum.min/3`. + For example: + + iex> Enum.min([]) + ** (Enum.EmptyError) empty error + """ defexception message: "empty error" @@ -2254,6 +2345,11 @@ defmodule File.Error do @moduledoc """ An exception that is raised when a file operation fails. + For example, this exception is raised, when trying to read a non existent file: + + iex> File.read!("nonexistent_file.txt") + ** (File.Error) could not read file "nonexistent_file.txt": no such file or directory + The following fields of this exception are public and can be accessed freely: * `:path` (`t:Path.t/0`) - the path of the file that caused the error @@ -2282,6 +2378,11 @@ defmodule File.CopyError do @moduledoc """ An exception that is raised when copying a file fails. + For example, this exception is raised when trying to copy to file or directory that isn't present: + + iex> File.cp_r!("non_existent", "source_dir/subdir") + ** (File.CopyError) could not copy recursively from "non_existent" to "source_dir/subdir". non_existent: no such file or directory + The following fields of this exception are public and can be accessed freely: * `:source` (`t:Path.t/0`) - the source path @@ -2311,6 +2412,11 @@ defmodule File.RenameError do @moduledoc """ An exception that is raised when renaming a file fails. + For example, this exception is raised when trying to rename a file that isn't present: + + iex> File.rename!("source.txt", "target.txt") + ** (File.RenameError) could not rename from "source.txt" to "target.txt": no such file or directory + The following fields of this exception are public and can be accessed freely: * `:source` (`t:Path.t/0`) - the source path @@ -2340,6 +2446,11 @@ defmodule File.LinkError do @moduledoc """ An exception that is raised when linking a file fails. + For example, this exception is raised when trying to link to file that isn't present: + + iex> File.ln!("source.txt", "target.txt") + ** (File.LinkError) could not create hard link from "source.txt" to "target.txt": no such file or directory + The following fields of this exception are public and can be accessed freely: * `:existing` (`t:Path.t/0`) - the existing file to link @@ -2360,6 +2471,19 @@ defmodule File.LinkError do end defmodule ErlangError do + @moduledoc """ + An exception raised when invoking an Erlang code that errors + with a value not handled by Elixir. + + Most common error reasons, such as `:badarg` are automatically + converted into exceptions by Elixir. However, you may invoke some + code that emits a custom error reason and those get wrapped into + `ErlangError`: + + iex> :erlang.error(:some_invalid_error) + ** (ErlangError) Erlang error: :some_invalid_error + """ + defexception [:original, :reason] @impl true