Warning: Work in progress! Leave feedback on Zulip or Github if you'd like this doc to be updated.

I/O Builtins in Oil

In POSIX shell, the echo, printf, read builtins, and the $(command sub) construct, are overlapping and quirky.

Oil fixes this with write, long flags to read, $(string sub), @(array sub), and QSN.

TODO: Also see JSON.

Table of Contents
Summary of Constructs
Buffered vs. Unbuffered
Invariants
Array -> QSN Lines -> Array
File -> Array -> File
File -> String -> File
read doesn't lose information, while $() and @() do

Summary of Constructs

Buffered vs. Unbuffered

Invariants

# This will get messed up with newlines, and empty strings.
IFS='\n'
@(write -- @myarray)

# This will give you back an array
@(write -q -- @myarray)

Array -> QSN Lines -> Array

This is one way to make a copy of an array

write -q -- @myarray | read --lines -q :otherarray

In contrast, this doesn't work when the elements have newlines:

var myarray = %( 'bad\n' )
write -- @myarray | read --lines :otherarray

File -> Array -> File

cat input.txt | read --all-lines :myarray

# suppress the newline
write --sep '' --end '' -- @myarray > output.txt

diff input.txt output.txt  # should be equal

File -> String -> File

cat input.txt | read --all :x

# suppress the newline
write --end '' $x > output.txt

diff input.txt output.txt  # should be equal

read doesn't lose information, while $() and @() do

Compare:

var s = $(hostname)       # strips trailing newline
hostname | read --all :s  # preserves it

And:

var lines = @(cat file.txt)
cat file.txt | read --lines :lines

Generated on Wed Aug 19 00:07:37 PDT 2020