update docs with more information

changes to file "docs/built-ins.md":

+ add undocumented subs

+ add undocumented methods on a file handle

changes to file "docs/ops.markdown":

+ correct and expand on some nqp subs

change to file "src/core/IO.nqp":

+ correct indent to four spaces on IO.nqp

Author: tbrowder

docs/built-ins.md

@@ -1,19 +1,128 @@
 # NQP Built-in Subs List
 
-The following subroutines are available to use in ```nqp``` programs.
-They are described in ```nqp/src/core``` modules.
+The following subroutines are available to use in `nqp` programs.
+They are described in `nqp/src/core` modules.
 
-# From ```nqp/src/core/Regex.nqp```
+# From `nqp/src/core/Regex.nqp`
 
 ## match
-* `match($text, $regex, :$global?)`
+* `match($text, $regex, :$global? --> @array)`
 
-Match ```$text``` against ```$regex```.  If the ```$global``` flag is
+Match `$text` against `$regex`.  If the `$global` flag is
 given, then return an array of all non-overlapping matches.
 
 ## subst
-* `subst($text, $regex, $replacement, :$global?)`
+* `subst($text, $regex, $replacement, :$global? --> str)`
 
-Substitute a match of ```$regex``` in ```$text``` with ```$replacement```,
-returning the substituted string.  If ```$global``` is given, then
-perform the replacement on all matches of ```$text```.
+Substitute a match of `$regex` in `$text` with `$replacement`,
+returning the substituted string.  If `$global` is given, then
+perform the replacement on all matches of `$text`.
+
+# From `nqp/src/core/IO.nqp`
+
+## open
+* `open($filename, :$r, :$w, :$a, :$bin, :$enc, :$chomp --> $filehandle)`
+
+Open file `$filename`. Options:
++ :w - open for writing
++ :r - open for reading (default)
++ :a - open for appending
++ :bin - open in binary  mode
++ :enc - define encoding (default: `utf8`)
++ :chomp - strip ending newlines (default: true)
+
+## close
+* `close($fh)`
+
+Close the file attached to file handle `$fh`.
+
+## slurp
+* `slurp ($filename --> str)`
+
+Returns the contents of `$filename` as a single string.
+
+## spew
+* `spew($filename, $contents)`
+
+Write the string value of `$contents` to `$filename`.
+
+## say
+* `say($string)`
+
+Write `$string` to `stdout` with a newline added.
+
+## note
+* `note($string)`
+
+Write `$string` to `stderr` with a newline added.
+
+## join
+* `join($delim, @array --> str)`
+
+Returns a string formed by joining each element of `@array`
+with the `$delim`.
+
+## print
+* `print($string)`
+
+Write `$string` to `stdout`.
+
+## stdin
+* `stdin(--> $filehandle)`
+
+Returns a file handle to `stdin`.
+
+## stdout
+* `stdout(--> $filehandle)`
+
+Returns a file handle to `stdout`.
+
+## stderr
+* `stderr(--> $filehandle)`
+
+Returns a file handle to `stderr`.
+
+# File handle (fh) methods
+
+Some methods available on the file handle (fh) returned from `open`.
+Other methods available of lesser interest not documented below are:
++ flush
++ get
++ seek
++ set-encoding
++ set-nl-in
++ t
++ tell
++ wrap
+
+## fh.slurp
+* `$fh.slurp()`
+
+Reads the entire file attached to file handle `$fh`.
+
+## fh.print
+* `$fh.print($string)`
+
+Write `$string` to the file attached to file handle `$fh`.
+An ending newline is not added.
+
+## fh.say
+* `$fh.say($string)`
+
+Write `$string` to the file attached to file handle `$fh`.
+An ending newline is added.
+
+## fh.close
+* `$fh.close()`
+
+Close the file attached to file handle `$fh`.
+
+## fh.readchars
+* `$fh.readchars($nchars)`
+
+Read `$nchars` characters from file handle `$fh`.
+
+## fh.eof
+* `$fh.eof`
+
+Returns true if end-of-file has been reached on file handle `$fh`.

docs/ops.markdown

@@ -1,4 +1,4 @@
-# NQP Opcode List
+ List
 
 ## Table of Contents
 
@@ -1321,7 +1321,7 @@ must have elements of type `int8` or `uint8`.
 
 Returns an NFG string consisting of `$num-chars` graphemes, provided that
 many are available after decoding. If less than `$num-chars` characters
-can be decoded, then `nqp::null_s` will be returned. Note that some a
+can be decoded, then `nqp::null_s` will be returned. Note that a
 decoded codepoint at the end of a byte buffer may not be available as a
 character if the encoding allows the next character to be a combining
 character.
@@ -1349,7 +1349,7 @@ Decodes bytes until a line separator is reached, or all bytes have been
 decoded. If `$incomplete-ok` is zero and the separator was not found, then
 `nqp::null_s` will be returned. (Thus, `$incomplete-ok` is appropriate only
 when knowing that the end of the stream has been reached.) If `$chomp` is
-non-zero, then the separator - if present - will not be included in the
+non-zero, then the separator--if present--will not be included in the
 resulting string.
 
 ## decoderbytesavailable
@@ -2540,18 +2540,23 @@ specific to a given backend. The type to use for that is given as $handle_type.
 ## permit
 * `permit(AsyncTask $handle, int $channel, int $permits)`
 
-Takes something with the AsyncTask REPR and permits it to emit up to `$permits`
-more notifications. This is used as a back-pressure mechanism for asynchronous
-tasks that produce a stream of events, such as representing data arriving over
-a socket. Some kinds of tasks may emit on multiple channels, for example an
-asynchronous process may emit events for STDOUT and STDERR if both are of
-interest. The `$channel` argument is used to specify which channel is to get
-the permits if needed. If `$permits` is less than zero then it means there is
-no limit to the emits. If it is set to any value greater than or equal to
-zero, then:
+Takes something with the AsyncTask REPR (the `$handle` parameter) and
+permits it to emit up to `$permits` more notifications. This is used
+as a back-pressure mechanism for asynchronous tasks that produce a
+stream of events, such as representing data arriving over a
+socket. Some kinds of tasks may emit on multiple channels, for example
+an asynchronous process may emit events for STDOUT (channel 1) and
+STDERR (channel 2) if both are of interest. The `$channel` argument is
+used to specify which channel is to get the permits if needed (use a
+separate `permit` stament for each channel of interest).
+
+If `$permits` is less than zero (e.g., `permit($task, $channel, -1)`,
+then it means there is no limit to the emits.
+
+If `$permits` is set to any value greater than or equal to zero, then:
 
 * In the case unlimited emits were permitted previously, the permits will be
-  set to the new value. If the new value is zero then the reader will be
+  set to the new value. If the new value is zero, then the reader will be
   stopped.
 * Otherwise the number of permits will be incremented by the specified value.
   If the resulting number of permits allowed is greater than zero and the

src/core/IO.nqp

@@ -147,7 +147,7 @@ my class NQPFileHandle {
         $line
     }
 
-     method slurp() {
+    method slurp() {
         $!decoder || nqp::die("Cannot 'slurp' on a binary file handle");
         while nqp::elems(my $buf := nqp::readfh($!vmio, nqp::create($NQPBuf), 0x100000)) {
             $!decoder.add-bytes($buf);