Deprecate %b and %B in favor of %s and %S

Author: José Valim

CHANGELOG.md

@@ -50,6 +50,7 @@
   * [Kernel] `list_to_binary/1`, `binary_to_list/1` and `binary_to_list/3` are deprecated in favor of `String.from_char_list!/1` and `String.to_char_list!/1` for characters and `:binary.list_to_bin/1`, `:binary.bin_to_list/1` and `:binary.bin_to_list/3` for bytes
   * [Kernel] `to_binary/1` is deprecated in favor of `to_string/1`
   * [Kernel] Deprecate `def/4` and friends in favor of `def/2` with unquote and friends
+  * [Kernel] Deprecate `%b` and `%B` in favor of `%s` and `%S`
   * [List] `List.concat/2` is deprecated in favor of `Enum.concat/2`
   * [Macro] `Macro.unescape_binary/1` and `Macro.unescape_binary/2` are deprecated in favor of `Macro.unescape_string/1` and `Macro.unescape_string/2`
   * [Mix] `:umbrella` option for umbrella paths has been deprecated in favor of `:in_umbrella`

lib/eex/lib/eex.ex

@@ -1,7 +1,7 @@
 defexception EEx.SyntaxError, message: nil
 
 defmodule EEx do
-  @moduledoc %B"""
+  @moduledoc %S"""
   EEx stands for Embedded Elixir. It allows you to embed
   Elixir code inside a string in a robust way:
 

lib/eex/lib/eex/engine.ex

@@ -1,5 +1,5 @@
 defmodule EEx.Engine do
-  @moduledoc %B"""
+  @moduledoc %S"""
   This is the basic EEx engine that ships with Elixir.
   An engine needs to implement two functions:
 

lib/elixir/lib/dict.ex

@@ -1,5 +1,5 @@
 defmodule Dict do
-  @moduledoc %B"""
+  @moduledoc %S"""
   This module specifies the Dict API expected to be
   implemented by different dictionaries. It also provides
   functions that redirect to the underlying Dict, allowing

lib/elixir/lib/file.ex

@@ -397,7 +397,7 @@ defmodule File do
     end
   end
 
-  @doc %B"""
+  @doc %S"""
   Copies the contents in source to destination.
   Similar to the command `cp -r` in Unix systems,
   this function behaves differently depending

lib/elixir/lib/inspect.ex

@@ -135,7 +135,7 @@ defimpl Inspect, for: Atom do
 end
 
 defimpl Inspect, for: BitString do
-  @doc %B"""
+  @doc %S"""
   Represents a string as itself escaping all necessary
   characters. Binaries that contain non-printable characters
   are printed using the bitstring syntax.
@@ -243,7 +243,7 @@ defimpl Inspect, for: BitString do
 end
 
 defimpl Inspect, for: List do
-  @doc %B"""
+  @doc %S"""
   Represents a list, checking if it can be printed or not.
   If so, a single-quoted representation is returned,
   otherwise the brackets syntax is used. Keywords are
@@ -389,7 +389,7 @@ defimpl Inspect, for: Number do
 end
 
 defimpl Inspect, for: Regex do
-  @doc %B"""
+  @doc %S"""
   Represents the Regex using the `%r""` syntax.
 
   ## Examples

lib/elixir/lib/inspect/algebra.ex

@@ -1,5 +1,5 @@
 defmodule Inspect.Algebra do
-  @moduledoc %B"""
+  @moduledoc %S"""
   A set of functions for creating and manipulating algebra
   documents, as described in ["Strictly Pretty" (2000) by Christian Lindig][0].
 
@@ -130,7 +130,7 @@ defmodule Inspect.Algebra do
   def nest(x, 0),                    do: x
   def nest(x, i) when is_integer(i), do: doc_nest(indent: i, doc: x)
 
-  @doc %B"""
+  @doc %S"""
   Document entity representing a break. This break can
   be rendered as a linebreak or as spaces, depending on the
   `mode` of the chosen layout or the provided separator.
@@ -170,7 +170,7 @@ defmodule Inspect.Algebra do
   @spec glue(t, binary, t) :: doc_cons_t
   def glue(x, g, y) when is_binary(g), do: concat(x, concat(break(g), y))
 
-  @doc %B"""
+  @doc %S"""
   Returns a group containing the specified document.
 
   ## Examples
@@ -213,7 +213,7 @@ defmodule Inspect.Algebra do
   @spec space(t, t) :: doc_cons_t
   def space(x, y), do: concat(x, concat(" ", y))
 
-  @doc %B"""
+  @doc %S"""
   Inserts a mandatory linebreak between two document entities.
 
   ## Examples
@@ -247,7 +247,7 @@ defmodule Inspect.Algebra do
 
   # Elixir conveniences
 
-  @doc %B"""
+  @doc %S"""
   Surrounds a document with characters.
 
   Puts the document between left and right enclosing and nesting it.
@@ -266,7 +266,7 @@ defmodule Inspect.Algebra do
     group concat [left, nest(doc, @nesting), right]
   end
 
-  @doc %B"""
+  @doc %S"""
   Maps and glues a collection of items together using the given separator
   and surrounds them. A limit can be passed which, once reached, stops
   gluing and outputs "..." instead.

lib/elixir/lib/io/ansi.ex

@@ -138,7 +138,7 @@ defmodule IO.ANSI do
     raise ArgumentError, message: "invalid ANSI sequence specification: #{spec}"
   end
 
-  @doc %B"""
+  @doc %S"""
   Escapes a string by converting named ANSI sequences into actual ANSI codes.
 
   The format for referring to sequences is `%{red}` and `%{red,bright}` (for
@@ -167,7 +167,7 @@ defmodule IO.ANSI do
     end
   end
 
-  @doc %B"""
+  @doc %S"""
   Escapes a string by converting named ANSI sequences into actual ANSI codes.
 
   The format for referring to sequences is `%{red}` and `%{red,bright}` (for

lib/elixir/lib/kernel.ex

@@ -1379,7 +1379,7 @@ defmodule Kernel do
   @doc false
   defmacro defmacrop(name, args, guards, do: contents)
 
-  @doc %B"""
+  @doc %S"""
   Exports a module with a record definition and runtime operations.
 
   Please see the `Record` module's documentation for an introduction
@@ -1500,7 +1500,7 @@ defmodule Kernel do
     end
   end
 
-  @doc %B"""
+  @doc %S"""
   Defines a set of private macros to manipulate a record definition.
 
   This macro defines a set of macros private to the current module to
@@ -2025,7 +2025,7 @@ defmodule Kernel do
     end
   end
 
-  @doc %B"""
+  @doc %S"""
   Inspect the given arguments according to the `Inspect` protocol.
 
   ## Options
@@ -3373,34 +3373,46 @@ defmodule Kernel do
   end
 
   @doc """
-  Handles the sigil %B. It simples returns a binary
+  Handles the sigil %S. It simples returns a string
   without escaping characters and without interpolations.
 
   ## Examples
 
-      iex> %B(foo)
+      iex> %S(foo)
       "foo"
-      iex> %B(f\#{o}o)
+      iex> %S(f\#{o}o)
       "f\\\#{o}o"
 
   """
+  defmacro sigil_S(string, []) do
+    string
+  end
+
+  @doc false
   defmacro sigil_B(string, []) do
+    IO.write "%B() is deprecated, please use %S() instead\n#{Exception.format_stacktrace}"
     string
   end
 
   @doc """
-  Handles the sigil %b. It returns a binary as if it was double quoted
+  Handles the sigil %s. It returns a string as if it was double quoted
   string, unescaping characters and replacing interpolations.
 
   ## Examples
 
-      iex> %b(foo)
+      iex> %s(foo)
       "foo"
-      iex> %b(f\#{:o}o)
+      iex> %s(f\#{:o}o)
       "foo"
 
   """
+  defmacro sigil_s({ :<<>>, line, pieces }, []) do
+    { :<<>>, line, Macro.unescape_tokens(pieces) }
+  end
+
+  @doc false
   defmacro sigil_b({ :<<>>, line, pieces }, []) do
+    IO.write "%b() is deprecated, please use %s() instead\n#{Exception.format_stacktrace}"
     { :<<>>, line, Macro.unescape_tokens(pieces) }
   end
 
@@ -3599,21 +3611,24 @@ defmodule Kernel do
 
   defp split_words(string, modifiers) do
     mod = case modifiers do
-      [] -> ?b
-      [mod] when mod in [?b, ?a, ?c] -> mod
-      _else -> raise ArgumentError, message: "modifier must be one of: b, a, c"
+      [] -> ?s
+      [mod] when mod in [?b] ->
+        IO.write "%w()b is deprecated, please use %w()s instead\n#{Exception.format_stacktrace}"
+        ?s
+      [mod] when mod in [?s, ?a, ?c] -> mod
+      _else -> raise ArgumentError, message: "modifier must be one of: s, a, c"
     end
 
     case is_binary(string) do
       true ->
         case mod do
-          ?b -> String.split(string)
+          ?s -> String.split(string)
           ?a -> lc p inlist String.split(string), do: binary_to_atom(p)
           ?c -> lc p inlist String.split(string), do: String.to_char_list!(p)
         end
       false ->
         case mod do
-          ?b -> quote do: String.split(unquote(string))
+          ?s -> quote do: String.split(unquote(string))
           ?a -> quote do: lc(p inlist String.split(unquote(string)), do: binary_to_atom(p))
           ?c -> quote do: lc(p inlist String.split(unquote(string)), do: String.to_char_list!(p))
         end

lib/elixir/lib/list/chars.ex

@@ -1,5 +1,5 @@
 defprotocol List.Chars do
-  @moduledoc %B"""
+  @moduledoc %S"""
   The List.Chars protocol is responsible for
   converting a structure to a list (only if applicable).
   The only function required to be implemented is