scripting: Utilities for writing Scheme scripts
_scripting_: Utilities for writing Scheme scripts
=================================================
By Ryan Culpepper (ryanc at plt-scheme dot org)
Keywords: _script_, _scripting_, _files_, _system_, _path_
_scripting.ss_
--------------
To use: (require (planet "scripting.ss" ("ryanc" "scripting.plt" 1 1)))
Provides everything described in this document.
_byteslike.ss_
--------------
To use: (require (planet "byteslike.ss" ("ryanc" "scripting.plt" 1 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.
> 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 1)))
Paths and strings can both be used to refer to filesystem entities,
but they 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.
> 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 1)))
It is often 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
> (loud:make-file-or-directory-link 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 1)))
Scripts often need to read configuration files and data files, and it
is often convenient to do so in one gulp.
> (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]]) -> (list-of syntax)
Calls 'read-syntax' repeatedly until end of file and returns a list of
the syntax objects read (not including the end of file object). See the
description of 'read-syntax; for details on the source argument.
> (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 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 only replaces the part of
the name *after* the dot.
(replace-file-extension "a.b" "c") = #<path: a.c>
> (pathlike-append pathlike ...) -> path
Like 'string-append', but accepts bytes and path arguments and
produces a path. It is *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 in the function position.
> (directory-list/sorted [pathlike]) -> (list-of path)
Returns the sorted contents of the given (or current) directory.
> (directory-list/paths pathlike) -> (list-of path)
Returns the contents of the given directory as paths such that the
paths, interpreted with respect to the current directory, point to the
contents of the given directory. If the directory was given as a
relative path, they are relative to the current directory; otherwise,
they are absolute paths.
Example:
(directory-list/paths "that/other/directory")
=> (list #<path: that/other/directory/a.txt>
#<path: that/other/directory/b.ss>)
> (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 1)))
This module provides additional exception structure types and
exception-raising procedures.
> (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 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.