From 55f635c84426a523b4a46c70829d049db555b002 Mon Sep 17 00:00:00 2001 From: Sam O'Connor Date: Wed, 13 Jan 2016 10:57:01 +1100 Subject: [PATCH] revert mistaken docstring change -- read! vs readbytes! update base/docs/helpdb/Base.jl update rst docs, BBEditTextWrangler-julia.plist replace missing chomp() in getmetabranch() doc tweaks make && make julia-genstdlib more doc tweaks whitespace tweak --- base/docs/helpdb/Base.jl | 32 +++++++++------------- base/pkg/dir.jl | 2 +- base/stream.jl | 2 +- contrib/BBEditTextWrangler-julia.plist | 3 +-- doc/manual/networking-and-streams.rst | 6 ++--- doc/manual/running-external-programs.rst | 8 +++--- doc/stdlib/io-network.rst | 34 ++++++++++-------------- 7 files changed, 36 insertions(+), 51 deletions(-) diff --git a/base/docs/helpdb/Base.jl b/base/docs/helpdb/Base.jl index af7091436b9ead..eb7118e86ea68c 100644 --- a/base/docs/helpdb/Base.jl +++ b/base/docs/helpdb/Base.jl @@ -452,7 +452,7 @@ the mantissa. precision """ - readlines(stream) + readlines(stream or filename) Read all lines as an array. """ @@ -1018,7 +1018,7 @@ See `rounding` for available rounding modes. Float32 """ - readuntil(stream, delim) + readuntil(stream or filename, delim) Read a string, up to and including the given delimiter byte. """ @@ -2438,19 +2438,11 @@ the process. triu!(M, k) """ - readstring(stream::IO) + readstring(stream or filename) -Read the entire contents of an I/O stream as a string. +Read the entire contents of an I/O stream or a file as a string. """ -readstring(stream::IO) - -""" - readstring(filename::AbstractString) - -Open `filename`, read the entire contents as a string, then close the file. Equivalent to -`open(readstring, filename)`. -""" -readstring(filename::AbstractString) +readstring """ poll_file(path, interval_s::Real, timeout_s::Real) -> (previous::StatStruct, current::StatStruct) @@ -2468,9 +2460,9 @@ it is more reliable and efficient, although in some situations it may not be ava poll_file """ - eachline(stream) + eachline(stream or filename) -Create an iterable object that will yield each line from a stream. +Create an iterable object that will yield each line. """ eachline @@ -4251,9 +4243,9 @@ Squared absolute value of `x`. abs2 """ - write(stream, x) + write(stream or filename, x) -Write the canonical binary representation of a value to the given stream. Returns the number +Write the canonical binary representation of a value to the given stream or file. Returns the number of bytes written into the stream. You can write multiple values with the same :func:`write` call. i.e. the following are @@ -6445,7 +6437,7 @@ Read at most `nb` bytes from the stream into `b`, returning the number of bytes See `read` for a description of the `all` option. """ -read! +readbytes! """ basename(path::AbstractString) -> AbstractString @@ -7423,10 +7415,10 @@ Return the supertype of DataType `T`. supertype """ - readline(stream=STDIN) + readline(stream=STDIN or filename) Read a single line of text, including a trailing newline character (if one is reached before -the end of the input), from the given `stream` (defaults to `STDIN`), +the end of the input), from the given stream or file (defaults to `STDIN`), """ readline diff --git a/base/pkg/dir.jl b/base/pkg/dir.jl index fdb2231de3e240..ef38251c99f883 100644 --- a/base/pkg/dir.jl +++ b/base/pkg/dir.jl @@ -67,7 +67,7 @@ end function getmetabranch() try - readline(joinpath(path(),"META_BRANCH")) + chomp(readline(joinpath(path(),"META_BRANCH"))) catch err META_BRANCH end diff --git a/base/stream.jl b/base/stream.jl index 718a50807c0e01..052a65c20466dc 100644 --- a/base/stream.jl +++ b/base/stream.jl @@ -268,7 +268,7 @@ disassociate_julia_struct(handle::Ptr{Void}) = function init_stdio(handle::Ptr{Void}) t = ccall(:jl_uv_handle_type, Int32, (Ptr{Void},), handle) if t == UV_FILE - return File(RawFD(ccall(:jl_uv_file_handle,Int32,(Ptr{Void},),handle))) + return File(RawFD(ccall(:jl_uv_file_handle,Int32,(Ptr{Void},),handle))) else if t == UV_TTY ret = TTY(handle) diff --git a/contrib/BBEditTextWrangler-julia.plist b/contrib/BBEditTextWrangler-julia.plist index ecb364c3188415..c0c9693a03151c 100644 --- a/contrib/BBEditTextWrangler-julia.plist +++ b/contrib/BBEditTextWrangler-julia.plist @@ -843,10 +843,9 @@ rationalize read read! - readall + readstring readandwrite readavailable - readbytes readbytes! readchomp readcsv diff --git a/doc/manual/networking-and-streams.rst b/doc/manual/networking-and-streams.rst index f19598688da481..31eb0ba56c905d 100644 --- a/doc/manual/networking-and-streams.rst +++ b/doc/manual/networking-and-streams.rst @@ -53,7 +53,7 @@ For example, to read a simple byte array, we could do:: However, since this is slightly cumbersome, there are several convenience methods provided. For example, we could have written the above as:: - julia> readbytes(STDIN,4) + julia> read(STDIN,4) abcd 4-element Array{UInt8,1}: 0x61 @@ -142,7 +142,7 @@ as its first argument and filename as its second, opens the file, calls the func an argument, and then closes it again. For example, given a function:: function read_and_capitalize(f::IOStream) - return uppercase(readall(f)) + return uppercase(readstring(f)) end You can call:: @@ -156,7 +156,7 @@ To avoid even having to define a named function, you can use the ``do`` syntax, function on the fly:: julia> open("hello.txt") do f - uppercase(readall(f)) + uppercase(readstring(f)) end "HELLO AGAIN." diff --git a/doc/manual/running-external-programs.rst b/doc/manual/running-external-programs.rst index 56d436a72cf2c7..ea72d8992310fd 100644 --- a/doc/manual/running-external-programs.rst +++ b/doc/manual/running-external-programs.rst @@ -42,12 +42,12 @@ The ``hello`` is the output of the ``echo`` command, sent to :const:`STDOUT`. The run method itself returns ``nothing``, and throws an :exc:`ErrorException` if the external command fails to run successfully. -If you want to read the output of the external command, :func:`readall` +If you want to read the output of the external command, :func:`readstring` can be used instead: .. doctest:: - julia> a=readall(`echo hello`) + julia> a=readstring(`echo hello`) "hello\n" julia> (chomp(a)) == "hello" @@ -314,7 +314,7 @@ When reading and writing to both ends of a pipeline from a single process, it is important to avoid forcing the kernel to buffer all of the data. For example, when reading all of the output from a command, -call ``readall(out)``, not ``wait(process)``, since the former +call ``read(out)``, not ``wait(process)``, since the former will actively consume all of the data written by the process, whereas the latter will attempt to store the data in the kernel's buffers while waiting for a reader to be connected. @@ -323,7 +323,7 @@ Another common solution is to separate the reader and writer of the pipeline into separate Tasks:: writer = @async writeall(process, "data") - reader = @async do_compute(readall(process)) + reader = @async do_compute(read(process)) wait(process) fetch(reader) diff --git a/doc/stdlib/io-network.rst b/doc/stdlib/io-network.rst index 2dc48956a0ec85..33e3236ebc73bd 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -65,7 +65,7 @@ General I/O Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. - **Example**: ``open(readall, "file.txt")`` + **Example**: ``open(readstring, "file.txt")`` .. function:: IOBuffer() -> IOBuffer @@ -121,11 +121,11 @@ General I/O Close an I/O stream. Performs a ``flush`` first. -.. function:: write(stream, x) +.. function:: write(stream or filename, x) .. Docstring generated from Julia source - Write the canonical binary representation of a value to the given stream. Returns the number of bytes written into the stream. + Write the canonical binary representation of a value to the given stream or file. Returns the number of bytes written into the stream. You can write multiple values with the same :func:``write`` call. i.e. the following are equivalent: @@ -158,9 +158,9 @@ General I/O Read at most ``nb`` bytes from the stream into ``b``\ , returning the number of bytes read (increasing the size of ``b`` as needed). - See ``readbytes`` for a description of the ``all`` option. + See ``read`` for a description of the ``all`` option. -.. function:: readbytes(stream, nb=typemax(Int); all=true) +.. function:: read(stream, nb=typemax(Int); all=true) .. Docstring generated from Julia source @@ -330,7 +330,7 @@ General I/O .. Docstring generated from Julia source - Read the entirety of ``x`` as a string but remove trailing newlines. Equivalent to ``chomp(readall(x))``\ . + Read the entirety of ``x`` as a string but remove trailing newlines. Equivalent to ``chomp(readstring(x))``\ . .. function:: truncate(file,n) @@ -493,41 +493,35 @@ Text I/O Show all structure of a value, including all fields of objects. -.. function:: readall(stream::IO) +.. function:: readstring(stream or filename) .. Docstring generated from Julia source - Read the entire contents of an I/O stream as a string. + Read the entire contents of an I/O stream or a file as a string. -.. function:: readall(filename::AbstractString) +.. function:: readline(stream=STDIN or filename) .. Docstring generated from Julia source - Open ``filename``\ , read the entire contents as a string, then close the file. Equivalent to ``open(readall, filename)``\ . + Read a single line of text, including a trailing newline character (if one is reached before the end of the input), from the given stream or file (defaults to ``STDIN``\ ), -.. function:: readline(stream=STDIN) - - .. Docstring generated from Julia source - - Read a single line of text, including a trailing newline character (if one is reached before the end of the input), from the given ``stream`` (defaults to ``STDIN``\ ), - -.. function:: readuntil(stream, delim) +.. function:: readuntil(stream or filename, delim) .. Docstring generated from Julia source Read a string, up to and including the given delimiter byte. -.. function:: readlines(stream) +.. function:: readlines(stream or filename) .. Docstring generated from Julia source Read all lines as an array. -.. function:: eachline(stream) +.. function:: eachline(stream or filename) .. Docstring generated from Julia source - Create an iterable object that will yield each line from a stream. + Create an iterable object that will yield each line. .. function:: readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#')