Add :label option to IO.inspect/2

[michalmuskala]

This option will decorate the output with additional string, so
it's easy to distinguish between different IO.inspect calls.

IO.inspect("foo", tag: "bar")
#=> bar: "foo"

Closes #5009

[whatyouhide]

"of formatting options" -> "of the remaining formatting options"?

[josevalim]

We use #=> for return values, so those should be reversed or something.

[michalmuskala]

@whatyouhide I tried improving the docs for whole IO.inspect/2, wdyt?

[whatyouhide]

Awesome with the before/after example, I love it. About the format though, what if we do:

@doc """
...

## Examples

    IO.inspect <<0, 1, 2>>, width: 40
    # Prints:
    # <<0, 1, 2>>

    IO.inspect 1..100, tag: "a wonderful range"
    # Prints:
    # a wonderful range: 1..100

without showing the return value (which is what we already do?

[michalmuskala]

I like this

[lexmag]

We don't say this in other docs. It's structured like:

expression
#=> output

[lexmag]

Also this Prints: looks like part of actual output.

[michalmuskala]

Well, that's confusing: #5010 (comment)

We use #=> for return values, so those should be reversed or something.

[michalmuskala]

@lexmag @whatyouhide maybe something like this will be clearer:

      [1, 2, 3]
      |> IO.inspect(tag: "before")
      |> Enum.map(&(&1 * 2))
      |> IO.inspect(tag: "after")
      |> Enum.sum

      Prints:
      # before: [1, 2, 3]
      # after: [2, 4, 6]

[lexmag]

I think we had same discussion when warn function was introduced and decided to go with #=> until we find a better option.

@michalmuskala that Prints: now looks like a part of the code, what if we inline this into comment like:

      [1, 2, 3]
      |> IO.inspect(tag: "before") # prints "before: [1, 2, 3]"
      |> Enum.map(&(&1 * 2))
      |> IO.inspect(tag: "after") # prints "after: [2, 4, 6]"
      |> Enum.sum

?

[whatyouhide]

I am definitely 👎 on using #=> because we use if for return values (and we should fix IO.warn/2 and friends as well). I like @michalmuskala's suggestion of showing the whole snippet of code (with the return value of the whole pipe after #=> maybe) and then something like:

"""
    [1, 2, 3]
    |> ...
    #=> ...

Prints:

    before: [1, 2, 3]
    after: [2, 4, 6]
"""

[josevalim]

Another option is to not doctest this module but keep examples exactly as users would see in the terminal. For example:

iex> [1, 2, 3] |>
...> IO.inspect(tag: "before") |>
...> Enum.map(&(&1 * 2)) |>
...> IO.inspect(tag: "after") |>
...> Enum.sum
before: [1, 2, 3]
after: [2, 4, 6]
12

[whatyouhide]

@josevalim that would work but we would lose the doctests (even if that may be ok, in general it's not good I think 😕) and also still not have a solution for this. I think the two separate blocks of code may be good here.

[lexmag]

Two separate blocks are good option I think 👍.

[whatyouhide]

So @michalmuskala, to recap:

• let's go with :label instead of :tag (as just decided in Support a :label option in IO.inspect/2 #5009)
• let's use two separate code blocks to show what the code in the first and what IO.inspect/2 prints in the second, as you showed in your example above

and we should be good to go :)

[michalmuskala]

@whatyouhide ready for review

[whatyouhide]

@michalmuskala now that I'm seeing it in action, I think we should drop the #=> altogether 😕 It makes things a bit confusing IMO and we already said that this function returns its argument so there's not too much value in showing it everytime IMO. Wdyt?

[michalmuskala]

@whatyouhide removed

[whatyouhide]

This looks fantastic to me, and ready to merge :) @josevalim do I ?

[ericentin]

"This makes it possible to "spy" on values by inserting an IO.inspect/2 call almost anywhere in your code, even in the middle of a pipeline.", might be better phrasing?

[whatyouhide]

I don't like the "even" like using IO.inspect/2 in a pipeline was special, but 👍 on the rest of the phrasing, may be a bit better :) But overall I think we're ok to merge, these are mostly details for now, otherwise we're gonna be torturing @michalmuskala with fixes over fixes 😄

[ericentin]

It's not bad as is, but currently this does not read as idiomatic English, imo. :) Just figured this is some documentation people new to the language might see frequently, so it should be as good as possible.

[whatyouhide]

Up to you @michalmuskala :)

[michalmuskala]

This makes it possible to "spy" on values by inserting an
IO.inspect/2 call almost anywhere in your code, for example,
in the middle of a pipeline.

[ericentin]

💯

[ericentin]

I love this. Would anyone be in support of adding a short name for the :label option, perhaps :l?

[whatyouhide]

@antipax strong 👎 for my side for :l. More complexity and more crypticness, no need to introduce either IMO 😄

[ericentin]

@whatyouhide that's all quite fair. :) The idea behind the short version was being able to add inspects quickly, but label isn't particularly long either. :)

[michalmuskala]

@antipax @whatyouhide updated

[whatyouhide]

Looks great to me. Let's wait for the official seal of approval™ :)

[josevalim]

Else should probably use an empty list instead of an empty binary. It is a small detail but since we are working with iodata, that makes more sense as an empty value.

[lexmag]

Seems we're actually working with chardata here, and it would be better to rename iodata accordingly.

[whatyouhide]

So let's rename iodata below to chardata and replace "" with [] @michalmuskala?

[josevalim]

Looks good to me!

[michalmuskala]

@whatyouhide updated

[whatyouhide]

Beautiful, thanks @michalmuskala 💟 I already love this feature :D