doc/api-popen.texi: Add examples

1 files changed, 44 insertions, 0 deletions

diff --git a/doc/api-popen.texi b/doc/api-popen.texi
index ccde3c0..695fc1c 100644
--- a/doc/api-popen.texi
+++ b/doc/api-popen.texi
@@ -36,6 +36,50 @@ Equvalent to @code{open-remote-pipe} and @code{open-remote-pipe*} respectively
 with mode @code{OPEN_WRITE}.
 @end deffn
 
+@subsection Examples
+
+Here's a self-explanatory little script that executes @code{uname -o} command
+on the local host and prints the result:
+
+@lisp
+#!/usr/bin/guile \
+-e main -s
+!#
+
+(use-modules (ice-9 rdelim)             ; @{read,write@}-line
+             ;; Guile-SSH
+             (ssh session)
+             (ssh auth)
+             (ssh popen))               ; remote pipes
+
+(define (main args)
+  ;; Make a session with local machine and the current user.
+  (let ((session (make-session #:host "localhost")))
+
+    ;; Connect the session and perform the authentication.
+    (connect! session)
+    (authenticate-server session)
+    (userauth-agent! session)
+
+    ;; Execute the command on the remote side and get the input pipe
+    ;; to it.
+    (let ((channel (open-remote-input-pipe session "uname -o")))
+      ;; Read and display the result.
+      (write-line (read-line channel)))))
+@end lisp
+
+Surely we aren't limited to one-line outputs; for example, we can watch
+@code{top} command executing on a remote side locally, by reading data from
+the channel in a loop:
+
+@lisp
+(let ((channel (open-remote-input-pipe* session "top" "-u avp")))
+  (let r ((line (read-line channel)))
+    (unless (eof-object? line)
+      (write-line line)
+      (r (read-line channel)))))
+@end lisp
+
 @c Local Variables:
 @c TeX-master: "guile-ssh.texi"
 @c End: