;;;
;;; $Header: /home/gene/library/website/docsrc/pathnames-0/RCS/merge-examples.lisp,v 395.1 2008/04/20 17:25:56 gene Exp $
;;;

;;;
;;; In these examples, assume there is a function
;;; which allows a human user to enter a namestring.
;;; Maybe it just prompts for a namestring which the
;;; user must type in full, maybe it allows for
;;; selection on a text-only console, or maybe it
;;; displays the local graphical user interface's
;;; customary file-chooser widget.
;;;
(defun choose-file ()
  ;; Maybe we prompt & read, or maybe we do something
  ;; fancy.  Whatever follows the local user customs.
  ;; Assume we get the namestring into a variable 
  ;; called NS.  Then we convert it to a pathname &
  ;; return that.
  (pathname ns))

;;;
;;; Assume we're a text editor.  A human user provides
;;; use with the namestring for a file to edit.  We
;;; want to construct the pathname for a backup file
;;; so we can backup the first file before we edit it.
;;;
(setq edit-pn (choose-file))

(defconstant *backup-template* (make-pathname :type "bk")
  "Is this portable?  Strictly speaking, a program
should not hard-code any pathnames except for logical
pathnames.  I suspect what I've done is portable in
practice, if not in all theoretical cases, but why not
use a logical pathname for real portability?")

(setq backup-pn (merge-pathnames backup-template edit-pn))

;;;
;;; Now assume we're a different program, one that allows
;;; the human user to enter a namestring that describes a
;;; family of output files.  All the output files are in
;;; the same directory & have the same pathname name, but
;;; we give each one a different type.
;;; Here is an example of doing that.
;;;
(setq family-pn (choose-file))

(setq log-pn (merge-pathnames (make-pathname :type "log") family-pn)
      a-pn   (merge-pathnames (make-pathname :type "a")   family-pn)
      b-pn   (merge-pathnames (make-pathname :type "b")   family-pn))

;;;
;;; For a twist on the previous example, the user might
;;; specify a directory, & your program might use
;;; multiple files in it, distinguished by their names,
;;; not just their types (a.k.a. filename extensions).
;;; The technique doesn't change much:
;;;
(setq dir (choose-file))
(setq log-pn (merge-pathnames (make-pathname :name "log" :type "txt") dir)
      a-pn   (merge-pathnames (make-pathname :name "a"   :type "txt") dir)
      b-pn   (merge-pathnames (make-pathname :name "b"   :type "bin"  dir))

;;; --- end of file ---