Deprecate skipchars for skipuntil

Closes JuliaLang#36132

The name skipchars does not clearly communicate the functionality
available.

Tests for skipchars were left in place to ensure the @deprecate macro
correctly converted those calls to using skipuntil. Although CI only
runs tests with --depwarn=error, I have confirmed these tests pass
successfully with --depwarn=yes/no locally.

Author: non-Jedi

base/deprecated.jl

@@ -208,3 +208,9 @@ macro get!(h, key0, default)
 end
 
 # END 1.5 deprecations
+
+# BEGIN 1.6 deprecations
+
+@deprecate skipchars(pred, io::IO; linecomment=nothing) skipuntil(!pred, io::IO; linecomment=linecomment)
+
+# END 1.6 deprecations

base/exports.jl

@@ -820,7 +820,6 @@ export
     seekend,
     seekstart,
     skip,
-    skipchars,
     skipuntil,
     take!,
     truncate,

base/io.jl

@@ -1069,38 +1069,6 @@ Commit all currently buffered writes to the given stream.
 """
 flush(io::IO) = nothing
 
-"""
-    skipchars(predicate, io::IO; linecomment=nothing)
-
-Advance the stream `io` such that the next-read character will be the first remaining for
-which `predicate` returns `false`. If the keyword argument `linecomment` is specified, all
-characters from that character until the start of the next line are ignored.
-
-# Examples
-```jldoctest
-julia> buf = IOBuffer("    text")
-IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=8, maxsize=Inf, ptr=1, mark=-1)
-
-julia> skipchars(isspace, buf)
-IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=8, maxsize=Inf, ptr=5, mark=-1)
-
-julia> String(readavailable(buf))
-"text"
-```
-"""
-function skipchars(predicate, io::IO; linecomment=nothing)
-    while !eof(io)
-        c = read(io, Char)
-        if c === linecomment
-            readline(io)
-        elseif !predicate(c)
-            skip(io, -ncodeunits(c))
-            break
-        end
-    end
-    return io
-end
-
 """
     skipuntil(predicate, io::IO; linecomment=nothing)
 

doc/src/base/io-network.md

@@ -43,7 +43,6 @@ Base.redirect_stdin
 Base.redirect_stdin(::Function, ::Any)
 Base.readchomp
 Base.truncate
-Base.skipchars
 Base.skipuntil
 Base.countlines
 Base.PipeBuffer

test/iobuffer.jl

@@ -275,28 +275,30 @@ let io = IOBuffer()
     @test Base.buffer_writes(io) === io
 end
 
-@testset "skipchars" begin
-    io = IOBuffer("")
-    @test eof(skipchars(isspace, io))
+@static if Base.JLOptions().depwarn != 2
+    @testset "skipchars" begin
+        io = IOBuffer("")
+        @test eof(@test_deprecated(skipchars(isspace, io)))
 
-    io = IOBuffer("   ")
-    @test eof(skipchars(isspace, io))
+        io = IOBuffer("   ")
+        @test eof(@test_deprecated(skipchars(isspace, io)))
 
-    io = IOBuffer("#    \n     ")
-    @test eof(skipchars(isspace, io, linecomment='#'))
+        io = IOBuffer("#    \n     ")
+        @test eof(@test_deprecated(skipchars(isspace, io, linecomment='#')))
 
-    io = IOBuffer("      text")
-    skipchars(isspace, io)
-    @test String(readavailable(io)) == "text"
+        io = IOBuffer("      text")
+        @test_deprecated skipchars(isspace, io)
+        @test String(readavailable(io)) == "text"
 
-    io = IOBuffer("   # comment \n    text")
-    skipchars(isspace, io, linecomment='#')
-    @test String(readavailable(io)) == "text"
+        io = IOBuffer("   # comment \n    text")
+        @test_deprecated skipchars(isspace, io, linecomment='#')
+        @test String(readavailable(io)) == "text"
 
-    for char in ['@','߷','࿊','𐋺']
-        io = IOBuffer("alphabeticalstuff$char")
-        @test !eof(skipchars(isletter, io))
-        @test read(io, Char) == char
+        for char in ['@','߷','࿊','𐋺']
+            io = IOBuffer("alphabeticalstuff$char")
+            @test !eof(@test_deprecated(skipchars(isletter, io)))
+            @test read(io, Char) == char
+        end
     end
 end
 

test/iostream.jl

@@ -1,40 +1,42 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
-@testset "skipchars for IOStream" begin
-    mktemp() do path, file
-        function append_to_file(str)
-            mark(file)
-            print(file, str)
-            flush(file)
-            reset(file)
-        end
-        # test it doesn't error on eof
-        @test eof(skipchars(isspace, file))
-
-        # test it correctly skips
-        append_to_file("    ")
-        @test eof(skipchars(isspace, file))
-
-        # test it correctly detects comment lines
-        append_to_file("#    \n   ")
-        @test eof(skipchars(isspace, file, linecomment='#'))
-
-        # test it stops at the appropriate time
-        append_to_file("   not a space")
-        @test !eof(skipchars(isspace, file))
-        @test read(file, Char) == 'n'
-
-        # test it correctly ignores the contents of comment lines
-        append_to_file("  #not a space \n   not a space")
-        @test !eof(skipchars(isspace, file, linecomment='#'))
-        @test read(file, Char) == 'n'
-
-        # test it correctly handles unicode
-        for (byte, char) in zip(1:4, ('@','߷','࿊','𐋺'))
-            append_to_file("abcdef$char")
-            @test ncodeunits(char) == byte
-            @test !eof(skipchars(isletter, file))
-            @test read(file, Char) == char
+@static if Base.JLOptions().depwarn != 2
+    @testset "skipchars for IOStream" begin
+        mktemp() do path, file
+            function append_to_file(str)
+                mark(file)
+                print(file, str)
+                flush(file)
+                reset(file)
+            end
+            # test it doesn't error on eof
+            @test eof(@test_deprecated(skipchars(isspace, file)))
+
+            # test it correctly skips
+            append_to_file("    ")
+            @test eof(@test_deprecated(skipchars(isspace, file)))
+
+            # test it correctly detects comment lines
+            append_to_file("#    \n   ")
+            @test eof(@test_deprecated(skipchars(isspace, file, linecomment='#')))
+
+            # test it stops at the appropriate time
+            append_to_file("   not a space")
+            @test !eof(@test_deprecated(skipchars(isspace, file)))
+            @test read(file, Char) == 'n'
+
+            # test it correctly ignores the contents of comment lines
+            append_to_file("  #not a space \n   not a space")
+            @test !eof(@test_deprecated(skipchars(isspace, file, linecomment='#')))
+            @test read(file, Char) == 'n'
+
+            # test it correctly handles unicode
+            for (byte, char) in zip(1:4, ('@','߷','࿊','𐋺'))
+                append_to_file("abcdef$char")
+                @test ncodeunits(char) == byte
+                @test !eof(@test_deprecated(skipchars(isletter, file)))
+                @test read(file, Char) == char
+            end
         end
     end
 end