ruby-changes:67775
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:01:52 +0900 (JST)
Subject: [ruby-changes:67775] 398be8bc92 (master): include/ruby/internal/intern/io.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=398be8bc92 From 398be8bc92a1affef5aa3a72ef5730f16b8098d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?= <shyouhei@r...> Date: Mon, 12 Apr 2021 17:27:01 +0900 Subject: include/ruby/internal/intern/io.h: add doxygen Must not be a bad idea to improve documents. [ci skip] --- include/ruby/internal/intern/io.h | 633 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 612 insertions(+), 21 deletions(-) diff --git a/include/ruby/internal/intern/io.h b/include/ruby/internal/intern/io.h index 38b5a78..02c2497 100644 --- a/include/ruby/internal/intern/io.h +++ b/include/ruby/internal/intern/io.h @@ -26,43 +26,634 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/io.h#L26 RBIMPL_SYMBOL_EXPORT_BEGIN() /* io.c */ + +/** + * @private + * + * @deprecated This macro once was a thing in the old days, but makes no sense + * any longer today. Exists here for backwards compatibility + * only. You can safely forget about it. + */ #define rb_defout rb_stdout + +/* string.c */ /* ...why? moved in commit de7161526014b781468cea5d84411e23be */ + +/** + * The field separator character for inputs, or the `$;`. This affects how + * `String#split` works. You can set this via the `-F` command line option. + * You can also assign arbitrary ruby objects programmatically, but it makes + * best sense for you to assign a regular expression here. + * + * @internal + * + * Tidbit: "fs" comes from AWK's `FS` variable. + */ RUBY_EXTERN VALUE rb_fs; + +/* io.c */ /* ...why? given rb_fs is in string.c? */ + +/** + * The field separator character for outputs, or the `$,`. This affects how + * `Array#join` works. + * + * @deprecated Assigning anything other than ::RUBY_Qnil to this variable is + * deprecated. + */ RUBY_EXTERN VALUE rb_output_fs; + +/** + * The record separator character for inputs, or the `$/`. This affects how + * `IO#gets` works. You can set this via the `-0` command line option. + * + * @deprecated Assigning anything other than ::RUBY_Qnil to this variable is + * deprecated. + * + * @internal + * + * Tidbit: "rs" comes from AWK's `RS` variable. + */ RUBY_EXTERN VALUE rb_rs; + +/** + * This is the default value of ::rb_rs, i.e. `"\n"`. It seems it has always + * been just a newline string since the beginning. Not sure why C codes has to + * use this, given there is no way for ruby programs to interface. + * + * Also it has not been deprecated for unknown reasons. + */ RUBY_EXTERN VALUE rb_default_rs; + +/** + * The record separator character for outputs, or the `$\`. This affects how + * `IO#print` works. + * + * @deprecated Assigning anything other than ::RUBY_Qnil to this variable is + * deprecated. + */ RUBY_EXTERN VALUE rb_output_rs; -VALUE rb_io_write(VALUE, VALUE); -VALUE rb_io_gets(VALUE); -VALUE rb_io_getbyte(VALUE); -VALUE rb_io_ungetc(VALUE, VALUE); -VALUE rb_io_ungetbyte(VALUE, VALUE); -VALUE rb_io_close(VALUE); -VALUE rb_io_flush(VALUE); -VALUE rb_io_eof(VALUE); -VALUE rb_io_binmode(VALUE); -VALUE rb_io_ascii8bit_binmode(VALUE); -VALUE rb_io_addstr(VALUE, VALUE); -VALUE rb_io_printf(int, const VALUE*, VALUE); -VALUE rb_io_print(int, const VALUE*, VALUE); -VALUE rb_io_puts(int, const VALUE*, VALUE); -VALUE rb_io_fdopen(int, int, const char*); -VALUE rb_io_get_io(VALUE); -VALUE rb_file_open(const char*, const char*); -VALUE rb_file_open_str(VALUE, const char*); + +/** + * Writes the given string to the given IO. + * + * @param[out] io An IO, opened for writing. + * @param[in] str A String-like object to write to `io`. + * @exception rb_eIOError `io` isn't opened for writing. + * @exception rb_eFrozenError `io` is frozen. + * @exception rb_eTypeError No conversion from `str` to String. + * @exception rb_eSystemCallError `write(2)` failed for some reason. + * @return The number of bytes written to the `io`. + * @post `str` (up to the length of return value) is written to `io`. + * @note This function blocks. + * @note Partial write is a thing. It must be at least questionable not + * to check the return value. + * + * @internal + * + * Above description is in fact inaccurate. This function can take arbitrary + * objects, and calls their `write` method. What is written above in fact + * describes how `IO#write` works. You can pass StringIO etc. here, and would + * work completely differently. + */ +VALUE rb_io_write(VALUE io, VALUE str); + +/** + * Reads a "line" from the given IO. A line here means a chunk of characters + * which is terminated by either `"\n"` or an EOF. + * + * @param[in,out] io An IO, opened for reading. + * @exception rb_eIOError `io` isn't opened for reading. + * @exception rb_eFrozenError `io` is frozen. + * @retval RUBY_Qnil `io` is at EOF. + * @retval otherwise An instance of ::rb_cString. + * @post `io` is read. + * @note Unlike `IO#gets` it doesn't set `$_`. + * @note Unlike `IO#gets` it doesn't consider `$/`. + */ +VALUE rb_io_gets(VALUE io); + +/** + * Reads a byte from the given IO. + * + * @note In Ruby a "byte" always means an 8 bit integer ranging from + * 0 to 255 inclusive. + * @param[in,out] io An IO, opened for reading. + * @exception rb_eIOError `io` is not opened for reading. + * @exception rb_eFrozenError `io` is frozen. + * @retval RUBY_Qnil `io` is at EOF. + * @retval otherwise An instance of ::rb_cInteger. + * @post `io` is read. + * + * @internal + * + * Of course there was a function called `rb_io_getc()`. It was removed in + * commit a25fbe3b3e531bbe479f344af24eaf9d2eeae6ea. + */ +VALUE rb_io_getbyte(VALUE io); + +/** + * "Unget"s a string. This function pushes back the passed string onto the + * passed IO, such that a subsequent buffered read will return it. If the + * passed content is in fact an integer, a single character string of that + * codepoint of the encoding of the IO will be pushed back instead. + * + * It might be counter-intuitive but this function can push back multiple + * characters at once. Also this function can be called multiple times on a + * same IO. Also a "character" can be wider than a byte, depending on the + * encoding of the IO. + * + * @param[out] io An IO, opened for reading. + * @param[in] c Either a String, or an Integer. + * @exception rb_eIOError `io` is not opened for reading. + * @exception rb_eFrozenError `io` is frozen. + * @exception rb_eTypeError No conversion from `c` to ::rb_cString. + * @return Always returns ::RUBY_Qnil. + * + * @internal + * + * Why there is ungetc, given there is no getc? + */ +VALUE rb_io_ungetc(VALUE io, VALUE c); + +/** + * Identical to rb_io_ungetc(), except it doesn't take the encoding of the + * passed IO into account. When an integer is passed, it just casts that value + * to C's `unsigned char`, and pushes that back. + * + * @param[out] io An IO, opened for reading. + * @param[in] b Either a String, or an Integer. + * @exception rb_eIOError `io` is not opened for reading. + * @exception rb_eFrozenError `io` is frozen. + * @exception rb_eTypeError No conversion from `b` to ::rb_cString. + * @return Always returns ::RUBY_Qnil. + */ +VALUE rb_io_ungetbyte(VALUE io, VALUE b); + +/** + * Closes the IO. Any buffered contents are flushed to the operating system. + * Any future operations against the IO would raise ::rb_eIOError. In case the + * io was created using `IO.popen`, it also sets the `$?`. + * + * @param[out] io Target IO to close. + * @return Always returns ::RUBY_Qnil. + * @post `$?` is set in case IO is a pipe. + * @post No operations are possible against `io` any further. + * @note This can block to flush the contents. + * @note This can wake other threads up, especially those who are + * `select()`-ing the passed IO. + * @note Multiple invocations of this function over the same IO again + * and again is not an error, since Ruby 2.3. + * + * @internal + * + * You can close a frozen IO... Is this intentional? + */ +VALUE rb_io_close(VALUE io); + +/** + * Flushes any buffered data within the passed IO to the underlying operating + * system. + * + * @param[out] io Target IO to flush. + * @exception rb_eIOError `io` is closed. + * @exception rb_eFrozenError `io` is frozen. + * @exception rb_eSystemCallError `write(2)` failed for some reason. + * @return The passed `io`. + * @post `io`'s buffers are empty. + * @note This operation also discards the read buffer. Should basically + * be harmless, but in an esoteric situation like when user pushed + * something different from what was read using `ungetc`, this + * operation in fact changes the behaviour of the `io`. + * @note Buffering is difficult. This operation flushes the data from + * our userspace to the kernel, but that doesn't always mean you + * can expect them stored persistently onto your hard drive. + */ +VALUE rb_io_flush(VALUE io); + +/** + * Queries if the passed IO is at the end of file. "The end of file" here mans + * that there are no more data to read. This function blocks until the read + * buffer is filled in, and if that operation reached the end of file, it still + * returns ::RUBY_Qfalse (because there are data yet in that buffer). It + * returns ::RUBY_Qtrue once after the buffer is cleared. + * + * @param[in,out] io Target io to query. + * @exception rb_eIOErro (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/