Add a few scripts to examples/.

These are of the same "form" as the canonical extensions, such that
sourcing them from .esrc will modify the shell in some more-or-less
useful way.  However, they don't have the same historical pedigree or
universally acknowledged usefulness as the canonical extensions, so
instead we put them in examples/ until people decide they should be
installed with every copy of es.

Author: jpco

examples/noclobber.es

@@ -0,0 +1,55 @@
+# noclobber.es -- do not accidentally clobber files
+
+# Sloppy demo of an imitation of the "noclobber" option in some shells -- simply
+# throws an error if the file exists.  Not 100% confident this plays nice with
+# other spoofs to these hooks, though I don't actually know of any spoofs which
+# change the files or pre-create them (in theory, something dwimming would.)
+# Note also that this has TOCTTOU risks.
+#
+# %clobbers can be overwritten to modify our idea of what counts as clobbering:
+# for example, perhaps we don't mind clobbering an empty file.
+
+fn %clobbers file {
+	access -f $file
+
+	# simple alternate empty-file check might look like the following;
+	# this may act unexpectedly for unreadable files:
+	# access -f $file && !~ <={%read < $file} ()
+}
+
+let (o = $fn-%create)
+fn %create fd file cmd {
+	if {%clobbers $file} {
+		throw error %create $cmd would clobber $file
+	} {
+		$o $fd $file $cmd
+	}
+}
+
+# This function lets someone override noclobber.  Note that it needs to be run
+# "around" the redirection, like
+#
+#     clobber {command > file}
+#
+# as opposed to
+#
+#     clobber command > file
+#
+# Why this is the case is left as an exercise for the reader.
+
+fn clobber cmd {
+	local (fn-%clobbers = false) $cmd
+}
+
+# Imitates the APPEND_CREATE option in zsh, where we only successfully append to
+# files which already exist.
+# TODO: figure out a nicer way to toggle this on or off.
+
+let (o = $fn-%append)
+fn %append fd file cmd {
+	if {!access $file} {
+		throw error %append file $file does not exist
+	} {
+		$o $fd $file $cmd
+	}
+}

examples/nullcmd.es

@@ -0,0 +1,58 @@
+#!/usr/local/bin/es
+
+# Implementation of zsh's customizable NULLCMD behavior for es (see the
+# "REDIRECTIONS WITH NO COMMAND" section in zshmisc(1) for what that means).
+# If a redirection with an empty command is run, like
+#
+#     > file
+#
+# then with these hooks, that empty command is replaced with a call to the
+# %nullcmd function, which is called with the "mode" of the redirection as its
+# only argument, which will be one of the list (r w a r+ w+ a+ here).
+#
+# Like in zsh, %nullcmd is initially defined as `cat`, but csh
+# or sh behavior can be implemented by setting %nullcmd to an error-throwing
+# command or {}, respectively.  Note that since es' default behavior here is
+# already like sh's, there's probably no reason to source this file and then set
+# fn-%nullcmd = {}.
+#
+# Note that some scripts may expect `> file` to be a quick way to create/empty a
+# file, and those scripts may break with these hooks.  To avoid that, you may
+# want to define your %nullcmd to only do something special if %is-interactive.
+
+fn %nullcmd {cat}
+
+let (of = $fn-%openfile)
+fn %openfile mode fd file cmd {
+	if {!~ $#fn-%nullcmd 0 && ~ $cmd *'{}'} {
+		$of $mode $fd $file {%nullcmd $mode}
+	} {
+		$of $mode $fd $file $cmd
+	}
+}
+
+
+# Try to unset `%nullcmd` in `exec {> foo}` cases.
+# FIXME: This is reeeally ugly.
+
+let (e = $fn-exec)
+fn exec cmd {
+	if {~ $cmd *'{'^(%create %append %open-create)^*'{}}'} {
+		$e {local (fn-%nullcmd = ()) $cmd}
+	} {
+		$e $cmd
+	}
+}
+
+
+# %here doesn't use %openfile, so we override it as well so that we can do neat
+# things like `> file << EOF`.
+
+let (h = $fn-%here)
+fn %here fd str cmd {
+	if {!~ $#fn-%nullcmd 0 && ~ $cmd *'{}'} {
+		$h $fd $str {%nullcmd here}
+	} {
+		$h $fd $str $cmd
+	}
+}

examples/preparse.es

@@ -0,0 +1,40 @@
+# preparse.es -- parse scripts strictly before evaluating
+
+# Sourcing this script redefines %batch-loop such that it reads and parses the
+# entire input, saving the commands in the input to $cmds, before evaluating the
+# whole script at once.  This allows the shell to catch any syntax errors before
+# evaluating any part of a potentially-buggy script, which is a nice "sanity"
+# feature.  In theory, buffering all the commands has an impact on memory use as
+# well as script "start-up" time, but in practice these impacts are quite small.
+#
+# It's nice that %batch-loop was made hookable despite the original authors'
+# reservations on whether hooking it would ever be a good idea :)  It's also
+# impressive how relatively simple this is to do.  However, note the couple of
+# "gotchas" in the function, each of which represent potential issues in the
+# shell.  (Crashing while printing circular bindings is a known problem; the
+# other note indicates more marginal issues.)
+
+fn %batch-loop {
+	let (cmds = ()) {
+		# Read and buffer the commands until we get an eof.
+		catch @ e rest {
+			if {!~ $e eof} {
+				throw $e $rest
+			}
+		} {
+			forever {
+				# NOTE: Don't echo $cmds or the shell will die.
+				let (cmd = <=%parse)
+				if {!~ $#cmd 0} {
+					cmds = $cmds {$fn-%dispatch $cmd}
+				}
+			}
+		}
+		# Evaluate the commands.
+		# NOTE: using a for loop here catches the `break` exception,
+		# which we want to avoid.  Also, due to some particular details
+		# about how %seq is parsed, we need the {} around this
+		# invocation or else $cmds won't get called at all.
+		{%seq $cmds}
+	}
+}