Scripting: Utilities for writing Scheme scripts

_Scripting: Utilities for writing Scheme scripts_
=================================================

By Ryan Culpepper (ryanc at ccs dot neu dot edu)

Keywords: _script_, _scripting_, _files_, _system_

----------------------------------------
_byteslike.ss_
----------------------------------------

To use: (require (planet "byteslike.ss" ("ryanc" "scripting.plt" 1)))

Some functions can accept either a bytes or a string for a particular
argument. This module provides a predicate, conversion functions, and
utility procedures for byteslike values.

This module uses utf8 encoding for all conversions. If you care about
the actual encoding being used, do not use this module.

> type byteslike
       ::= bytes
         | string

> (byteslike? any) -> boolean

Predicate for byteslike values.

> (byteslike->bytes byteslike) -> bytes

Identify function on bytes; converts strings to bytes using utf8.

> (byteslike->string byteslike) -> string

Identity function on strings; converts bytes to strings using utf8.

> (byteslike-append byteslike ...) -> byteslike

Appends many byteslikes into a single byteslike.

----------------------------------------
_pathlike.ss_
----------------------------------------

To use: (require (planet "pathlike.ss" ("ryanc" "scripting.plt" 1)))

Paths, strings, and bytes can all be used to refer to filesystem
entities, and all interact differently with other parts of the
system. For example, when composing command string to invoke using
system, paths must be converted to string form. This module provides a
predicate and conversion utilities for a pathlike type.

> type pathlike
      ::= path
        | string

> (pathlike? any) -> boolean

Predicate for pathlike values.

> (pathlike->path pathlike) -> path
> (pathlike->string pathlike) -> string

Converts a pathlike into one of its specific data representations.

> (pathlike->bytes pathlike) -> bytes

Converts a pathlike into a bytes (note that a bytes is not a pathlike).


----------------------------------------
_loud.ss_
----------------------------------------

To use: (require (planet "loud.ss" ("ryanc" "scripting.plt" 1)))

It is helpful for a script to echo to the screen the actions it is
performing on the filesystem and the command lines it is
invoking. This module defines versions of many filesystem and process
procedures that echo their arguments to the current output port.

For example, executing (loud:delete-file "foo.txt") will print out

  delete-file: "foo.txt"

when the procedure is called (it does not imply that the deletion
succeeds).

The following procedures have the same filesystem effect as their
mzscheme counterparts:

> (loud:make-directory pathlike) -> void
> (loud:delete-directory pathlike) -> void
> (loud:copy-file pathlike pathlike) -> void
> (loud:delete-file pathlike) -> void
> (loud:rename-file-or-directory pathlike pathlike) -> void

The following procedures have the same filesystem effect as their 
(lib "file.ss") counterparts:

> (loud:make-directory* pathlike) -> void
> (loud:copy-directory/files pathlike pathlike) -> void
> (loud:delete-directory/files pathlike) -> void

The following procedures have the same process effect as their
(lib "process.ss") counterparts:

> (loud:system string) -> boolean
> (loud:system* string string ...) -> boolean
> (loud:system/exit-code string) -> integer
> (loud:system*/exit-code string string ...) -> integer

> (loud:process string) -> (list input-port output-port number input-port (symbol -> any))
> (loud:process* string string ...) -> (list input-port output-port number input-port (symbol -> any))
> (loud:process/ports output-port/#f input-port/#f output-port/#f string) -> (list input-port/#f output-port/#f number input-port/#f (symbol -> any))
> (loud:process*/ports output-port/#f input-port/#f output-port/#f string string ...) -> (list input-port/#f output-port/#f number input-port/#f (symbol -> any))

----------------------------------------
_read.ss_
----------------------------------------

To use: (require (planet "read.ss" ("ryanc" "scripting.plt" 1)))

Scripts often need to read configuration files and data files, and it
is often convenient to do so in one gulp (the DOM approach, rather
than the SAX/event approach).

> (read-all [input-port]) -> (list-of s-expr)

Calls read repeatedly until end of file and returns a list of the
s-expressions read (not including the end of file object).

> (read-all/file pathlike) -> (list-of s-expr)

Calls read-all on the contents of the given file.

> (read-all-syntax [any [input-port [offset-list]]]) -> (list-of syntax)

Calls read-syntax repeatedly until end of file and returns a list of
the syntax object read (not including the end of file object). See the
description of _read-syntax_ for details on the source and offset-list
arguments.

> (read-all-syntax/file pathlike) -> (list-of syntax)

Calls read-all-syntax on the contents of the given file. Uses the
pathlike object as the source argument.

----------------------------------------
_file.ss_
----------------------------------------

To use: (require (planet "file.ss" ("ryanc" "scripting.plt" 1)))

This module provides procedures for manipulating paths, performing
filesystem queries and actions.

The following procedures only manipulate path representations. They do
not touch the filesystem.

> (path-wrt-path pathlike pathlike) -> path

Interprets the second path with respect to the first. If the second
path is absolute, the first path is ignored. The resulting path is
relative if both input paths were relative; otherwise, it is absolute.

For example: 
  (path-wrt-path "here" "there.txt") = #<path: here/there.txt>
  (path-wrt-path "/home/me" "/tmp/foo") = #<path: /tmp/foo>

> (replace-file-extension pathlike byteslike) -> path

Like path-replace-suffix in mzscheme, but slightly different.

  (replace-file-extension "a.b" "c") = #<path: a.c>

> (pathlike-append pathlike ...) -> path

Like string-append, but accepts bytes and path arguments (*not* like
build-path). For example:

  (pathlike-append "email" "-number-" #<path: 45.txt>) = #<path: email-number-45.txt>

The following procedures interact with the filesystem.

> (touch pathlike) -> void

Creates a file with no contents. If the file already exists, nothing
is done (the modification time is not be updated).

> (check-file-exists name-symbol pathlike) -> void

If the given file does not exist, raises an exception using
raise-file-not-found with the given name as plaintiff.

> (directory-list/sorted [pathlike]) -> (list-of path)

Returns the sorted contents of the given (or current) directory.

> (directory-list/paths pathlike) -> (list-of path)

The procedure directory-list returns a list of paths representing only
the entry names. This procedure (directory-list/paths) returns a list
of paths to the contents of the directory. If the directory was given
as a relative path, they are relative to the current directory;
otherwise, they are absolute paths.

> (directory-list/absolute pathlike) -> (list-of absolute-path)

Returns a list of absolute paths referring to the contents of the
given directory. The directory may be given as either a relative or
absolute path.

> (newer? pathlike pathlike) -> boolean

Indicates whether the file indicated by the first path is newer than
the second. If the second file does not exist, then the first is
trivially newer.

----------------------------------------
_error.ss_
----------------------------------------

To use: (require (planet "error.ss" ("ryanc" "scripting.plt" 1)))

This module provides additional exception structure types and
exception-raising procedures.

> (define-struct (exn:fail:filesystem:path exn:fail:filesystem) (path))

> (raise-file-not-found name-symbol pathlike) -> raises exn

Raises an exception of type exn:fail:filesystem:path with a "file not
found" message and the given path.

----------------------------------------
_misc.ss_
----------------------------------------

To use: (require (planet "misc.ss" ("ryanc" "scripting.plt" 1)))

> (map/separated item-proc separator-proc items) -> list
> (for-each/separated item-proc separator-proc items) -> void

Like map and for-each, but calls separator-proc on no arguments
between every pair of items in the list. If the list contains fewer
than two items, separator-proc will never be called.

> (format-byte-count integer) -> string

Displays a number as a byte count (eg, "12 KB", "153 GB").

> (hash-table-put-fresh! hashtable key value) -> void

Like hash-table-put!, but raises an exception if there is already a
value associated with that key.