Update usage of Unicode characters in atoms, variables and friends (#8603)

Update the Syntax Reference as well as List.to_atom/1
and List.to_existing_atom/1

Author: eksperimental

lib/elixir/lib/list.ex

@@ -748,15 +748,18 @@ defmodule List do
   @doc """
   Converts a charlist to an atom.
 
-  Currently Elixir does not support conversions from charlists
-  which contains Unicode codepoints greater than 0xFF.
+  Elixir supports conversions from charlists which contains any Unicode
+  codepoint.
 
   Inlined by the compiler.
 
   ## Examples
 
-      iex> List.to_atom('elixir')
-      :elixir
+      iex> List.to_atom('Elixir')
+      :Elixir
+
+      iex> List.to_atom('🌢 Elixir')
+      :"🌢 Elixir"
 
   """
   @spec to_atom(charlist) :: atom
@@ -768,8 +771,8 @@ defmodule List do
   Converts a charlist to an existing atom. Raises an `ArgumentError`
   if the atom does not exist.
 
-  Currently Elixir does not support conversions from charlists
-  which contains Unicode codepoints greater than 0xFF.
+  Elixir supports conversions from charlists which contains any Unicode
+  codepoint.
 
   Inlined by the compiler.
 
@@ -779,6 +782,10 @@ defmodule List do
       iex> List.to_existing_atom('my_atom')
       :my_atom
 
+      iex> _ = :"🌢 Elixir"
+      iex> List.to_existing_atom('🌢 Elixir')
+      :"🌢 Elixir"
+
       iex> List.to_existing_atom('this_atom_will_never_exist')
       ** (ArgumentError) argument error
 

lib/elixir/pages/Syntax Reference.md

@@ -21,11 +21,13 @@ 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 a non-combining Unicode character or underscore. The atom may continue using a sequence of Unicode characters, including letters, numbers, underscore, and `@`. Atoms may end in `!` or `?`. See [Unicode Syntax](unicode-syntax.html) for a formal specification.
+Unquoted atoms start with a colon (`:`) which must be inmediately followed by an underscore or a Unicode letter. The atom may continue using a sequence of Unicode letters, numbers, underscores, and `@`. Atoms may end in `!` or `?`. See [Unicode Syntax](unicode-syntax.html) for a formal specification. Valid unquoted atoms are: `:ok`, `:ISO8601`, and `:integer?`.
 
-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).
+If the colon is immediately followed by a pair of double- or single-quotes surrounding the atom name, the atom is considered quoted. In contrast with an unquoted atom, this one can be made of any Unicode character (not only letters), such as `:'🌢 Elixir'`, `:"++olá++"`, and `:"123"`.
 
-If the colon is followed by a double- or single-quote, the atom can be made of any character, such as `:"++olá++"`.
+Quoted and unquoted atoms with the same name are considered equivalent, so `:atom`, `:"atom"`, and `:'atom'` represent the same atom. The only catch is that the compiler will warn when quotes are used in atoms that do not need to be quoted.
+
+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).
 
 `true`, `false`, and `nil` are reserved words that are represented by the atoms `:true`, `:false` and `:nil` respectively.
 
@@ -80,13 +82,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.
+Variables in Elixir must start with an underscore or a Unicode letter that is not in uppercase or titlecase. The variable may continue using a sequence of Unicode letters, numbers, and underscores. Variables may end in `?` or `!`. See [Unicode Syntax](unicode-syntax.html) for a formal specification.
 
 [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.
+Non-qualified calls, such as `add(1, 2)`, must start with an underscore or a Unicode letter that is not in uppercase or titlecase. The call may continue using a sequence of Unicode letters, numbers, and underscore. Calls may end in `?` or `!`. See [Unicode Syntax](unicode-syntax.html) for a formal specification.
 
 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 +100,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.
+Qualified calls, such as `Math.add(1, 2)`, must start with an underscore or a Unicode letter that is not in uppercase or titlecase. The call may continue using a sequence of Unicode letters, numbers, and underscores. Calls may end in `?` or `!`. See [Unicode Syntax](unicode-syntax.html) for a formal specification.
 
 [Elixir's naming conventions](naming-conventions.html) recommend calls to be in `snake_case` format.