planet print, planet structure commands

svn: r9403

collects/planet/planet.scrbl

@@ -212,7 +212,7 @@ If the PLaneT client doesn't have any previous linkage information, it
 checks its list of already-installed PLaneT packages for one that
 meets the requirement, and uses it if available. Both PLaneT-installed
 packages and packages established through a development link 
-(see @secref["devlinks"])
+(see @secref{devlinks})
 are checked simultaneously at this stage.
 
 @subsection{Acceptable Remote Package}
@@ -245,18 +245,23 @@ command line as
 where @italic{command} is a subcommand from the following list, and
 @exec{arg} is a sequence of arguments determined by that subcommand:
 
+@(define (cmd name desc)
+    @item{@(seclink name (exec name)): @desc})
+
 @itemize{
-  @item{@exec{create}:      create a PLaneT archive from a directory}
+  @cmd["create"]{create a PLaneT archive from a directory}
-  @item{@exec{install}:     download and install a given package}
+  @cmd["install"]{download and install a given package}
-  @item{@exec{remove}:      remove the specified package from the local cache}
+  @cmd["remove"]{remove the specified package from the local cache}
-  @item{@exec{show}:        list the packages installed in the local cache}
+  @cmd["show"]{list the packages installed in the local cache}
-  @item{@exec{clearlinks}:  clear the linkage table, allowing upgrades}
+  @cmd["clearlinks"]{clear the linkage table, allowing upgrades}
-  @item{@exec{fileinject}:  install a local file to the planet cache}
+  @cmd["fileinject"]{install a local file to the planet cache}
-  @item{@exec{link}:        create a development link}
+  @cmd["link"]{create a development link}
-  @item{@exec{unlink}:      remove development link associated with the given package}
+  @cmd["unlink"]{remove development link associated with the given package}
-  @item{@exec{fetch}:       download a package file without installing it}
+  @cmd["fetch"]{download a package file without installing it}
-  @item{@exec{url}:         get a URL for the given package}
+  @cmd["url"]{get a URL for the given package}
-  @item{@exec{open}:        unpack the contents of the given package}}
+  @cmd["open"]{unpack the contents of the given package}
+  @cmd["structure"]{display the structure of a given .plt archive}
+  @cmd["print"]{display a file within of the given .plt archive}}
 
 Each of these commands is described in more detail below. All the
 functionality of the command-line tool is also provided with a programmatic interface by 
@@ -323,14 +328,15 @@ the given file's filename as the its package name, and the given major and minor
 
 Usage:
 @commandline{planet link  <owner> <pkg> <maj> <min> <path>}
-Create a development link between the given package specifier and the
+Create a development link (see @secref{devlinks}) between the given
-specified directory name.
+package specifier and the specified directory name.
 
 @subsection[#:tag "unlink"]{@exec{unlink}}
 
 Usage:
 @commandline{planet unlink <owner> <pkg> <maj> <min>}
-Remove any development link associated with the given package.
+Remove any development link (see @secref{devlinks}) associated with
+the given package.
 
 @subsection[#:tag "fetch"]{@exec{fetch}}
 
@@ -357,6 +363,25 @@ installing.
 This command is not necessary for normal use of planet. It is intended to allow
 you to inspect package contents offline without needing to install the package.
 
+@subsection[#:tag "structure"]{@exec{structure}}
+
+Usage:
+@commandline{planet structure <plt-file>}
+Print the structure of the PLaneT archive named by <plt-file> to the standard
+output port.
+
+This command does not unpack or install the named .plt file.
+
+@subsection[#:tag "print"]{@exec{print}}
+
+Usage:
+@commandline{planet print <plt-file> <path>}
+
+Print the contents of the file named by <path>, which must be a relative path
+within the PLaneT archive named by <plt-file>, to the standard output port.
+
+This command does not unpack or install the named .plt file.
+
 @section{Utility Libraries}
 
 The planet collection provides configuration and utilities for using PLaneT. 
@@ -477,6 +502,17 @@ into the given directory (creating that path if necessary).}
 	 any]{
 Removes the specified package from the local planet cache.}
 
+@defproc[(display-plt-file-structure [plt-file (or/c path-string? path?)])
+         any]{
+Print a tree representing the file and directory structure of the
+PLaneT archive .plt file named by @scheme[plt-file] to @scheme[(current-output-port)].}
+
+@defproc[(display-plt-archived-file [plt-file (or/c path-string? path?)]
+				    [file-to-print string?])
+	 any]{
+Print the contents of the file named @scheme[file-to-print] within the 
+PLaneT archive .plt file named by @scheme[plt-file] to @scheme[(current-output-port)].}
+
 @defproc[(unlink-all) any]{
 Removes the entire linkage table from the system, which will force all
 modules to relink themselves to PLaneT modules the next time they run.}

collects/planet/planet.ss

@@ -97,7 +97,19 @@ Unpack the contents of the given package into the given directory without instal
 This command is not necessary for normal use of planet. It is intended to allow you to inspect package contents offline without needing to install the package."
       #:args (plt-file target)
       (do-unpack plt-file target)]
-                                       
+     
+     ["structure" "display the structure of a given .plt archive"
+      "\nPrint the structure of the PLaneT archive named by <plt-file> to the standard output port.
+This command does not unpack or install the named .plt file."
+      #:args (plt-file)
+      (do-structure plt-file)]
+     
+     ["print" "display a file within of the given .plt archive"
+      "\nPrint the contents of the file named by <path>, which must be a relative path within the PLaneT archive named by <plt-file>, to the standard output port.
+This command does not unpack or install the named .plt file."
+      #:args (plt-file path)
+      (do-display plt-file path)]
+
      ;; unimplemented so far:
      #;(("-u" "--unlink")
          module
@@ -246,6 +258,18 @@ This command is not necessary for normal use of planet. It is intended to allow
     (let ([file (normalize-path plt-file)])
       (unpack-planet-archive file target)))
   
+  (define (do-structure plt-file)
+    (unless (file-exists? plt-file)
+      (fail (format "The specified file (~a) does not exist" plt-file))) 
+    (let ([file (normalize-path plt-file)])
+      (display-plt-file-structure file)))
+  
+  (define (do-display plt-file file-to-print)
+    (unless (file-exists? plt-file)
+      (fail (format "The specified file (~a) does not exist" plt-file))) 
+    (let ([file (normalize-path plt-file)])
+      (display-plt-archived-file file file-to-print)))
+  
   ;; ------------------------------------------------------------
   ;; Utility
     
@@ -259,12 +283,6 @@ This command is not necessary for normal use of planet. It is intended to allow
                [(not ((cadar c) (car a) (car b))) #f]
                [else (loop (cdr a) (cdr b) (cdr c))])))))
   
-  
-  
-            
-            
-
-
   ;; ============================================================
   ;; start the program