From 4ba285e74bbdffd1c7ca18c6a1e9f7ee118c3ac9 Mon Sep 17 00:00:00 2001
From: sammyette <torchedsammy@gmail.com>
Date: Wed, 2 Apr 2025 20:49:49 -0400
Subject: [PATCH] chore: rename nature snail code file, add docs

---
 nature/hilbish.lua | 30 --------------------------
 nature/init.lua    |  2 +-
 nature/snail.lua   | 53 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 54 insertions(+), 31 deletions(-)
 delete mode 100644 nature/hilbish.lua
 create mode 100644 nature/snail.lua

diff --git a/nature/hilbish.lua b/nature/hilbish.lua
deleted file mode 100644
index f37bab9..0000000
--- a/nature/hilbish.lua
+++ /dev/null
@@ -1,30 +0,0 @@
-local hilbish = require 'hilbish'
-local snail = require 'snail'
-
-hilbish.snail = snail.new()
-
-function hilbish.run(cmd, streams)
-	local sinks = {}
-
-	if type(streams) == 'boolean' then
-		if not streams then
-			sinks = {
-				out = hilbish.sink.new(),
-				err = hilbish.sink.new(),
-				input = io.stdin
-			}
-		end
-	elseif type(streams) == 'table' then
-		sinks = streams
-	end
-
-	local out = hilbish.snail:run(cmd, {sinks = sinks})
-	local returns = {out}
-
-	if type(streams) == 'boolean' and not streams then
-		table.insert(returns, sinks.out:readAll())
-		table.insert(returns, sinks.err:readAll())
-	end
-
-	return table.unpack(returns)
-end
diff --git a/nature/init.lua b/nature/init.lua
index 4c47bfe..7c30c79 100644
--- a/nature/init.lua
+++ b/nature/init.lua
@@ -18,7 +18,7 @@ table.insert(package.searchers, function(module)
 	return function() return hilbish.module.load(path) end, path
 end)
 
-require 'nature.hilbish'
+require 'nature.snail'
 
 require 'nature.commands'
 require 'nature.completions'
diff --git a/nature/snail.lua b/nature/snail.lua
new file mode 100644
index 0000000..2a9ce19
--- /dev/null
+++ b/nature/snail.lua
@@ -0,0 +1,53 @@
+local hilbish = require 'hilbish'
+local snail = require 'snail'
+
+hilbish.snail = snail.new()
+
+--- run(cmd, streams) -> exitCode (number), stdout (string), stderr (string)
+--- Runs `cmd` in Hilbish's shell script interpreter.
+--- The `streams` parameter specifies the output and input streams the command should use.
+--- For example, to write command output to a sink.
+--- As a table, the caller can directly specify the standard output, error, and input
+--- streams of the command with the table keys `out`, `err`, and `input` respectively.
+--- As a boolean, it specifies whether the command should use standard output or return its output streams.
+--- #param cmd string
+--- #param streams table|boolean
+--- #returns number, string, string
+--- #example
+--- This code is the same as `ls -l | wc -l`
+--- local fs = require 'fs'
+--- local pr, pw = fs.pipe()
+--- hilbish.run('ls -l', {
+--- 	stdout = pw,
+--- 	stderr = pw,
+--- })
+--- pw:close()
+--- hilbish.run('wc -l', {
+--- 	stdin = pr
+--- })
+--- #example
+function hilbish.run(cmd, streams)
+	local sinks = {}
+
+	if type(streams) == 'boolean' then
+		if not streams then
+			sinks = {
+				out = hilbish.sink.new(),
+				err = hilbish.sink.new(),
+				input = io.stdin
+			}
+		end
+	elseif type(streams) == 'table' then
+		sinks = streams
+	end
+
+	local out = hilbish.snail:run(cmd, {sinks = sinks})
+	local returns = {out}
+
+	if type(streams) == 'boolean' and not streams then
+		table.insert(returns, sinks.out:readAll())
+		table.insert(returns, sinks.err:readAll())
+	end
+
+	return table.unpack(returns)
+end