wiki:HemlockProgrammer/Files

Version 3 (modified by gz, 6 years ago) (diff)

--

Back to Table of Contents

13. Files

This chapter discusses ways to read and write files at various levels---at marks, into regions, and into buffers. This also treats automatic mechanisms that affect the state of buffers in which files are read.

13.1. File Options and Type Hooks

The user specifies file options with a special syntax on the first line of a file. If the first line contains the string "-*-", then Hemlock interprets the text between the first such occurrence and the second, which must be contained in one line , as a list of "option: value" pairs separated by semicolons. The following is a typical example:

;;; -*- Mode: Lisp, Editor; Package: Hemlock -*-

See the Hemlock User's Manual for more details and predefined options.

File type hooks are executed when Hemlock reads a file into a buffer based on the type of the pathname. When the user specifies a Mode file option that turns on a major mode, Hemlock ignores type hooks. This mechanism is mostly used as a simple means for turning on some appropriate default major mode.

define-file-option name (buffer value) {declaration}* {form}* [Macro]

This defines a new file option with the string name name. Buffer and value specify variable names for the buffer and the option value string, and forms are evaluated with these bound.

define-file-type-hook type-list (buffer type) {declaration}* {form}* [Macro]

This defines some code that process-file-options(below) executes when the file options fail to set a major mode. This associates each type, a string, in type-list with a routine that binds buffer to the buffer the file is in and type to the type of the pathname.

process-file-options buffer &optional pathname [Function]

This checks for file options in buffer and invokes handlers if there are any. Pathname defaults to buffer's pathname but may be nil. If there is no Mode file option that specifies a major mode, and pathname has a type, then this tries to invoke the appropriate file type hook. read-buffer-file calls this.

13.2. Pathnames and Buffers

There is no good way to uniquely identify buffer names and pathnames. However, Hemlock has one way of mapping pathnames to buffer names that should be used for consistency among customizations and primitives. Independent of this, Hemlock provides a means for consistently generating prompting defaults when asking the user for pathnames.

pathname-to-buffer-name pathname [Function]

This function returns a string of the form "file-namestring directory-namestring".

Pathname Defaults (initial value (pathname "gazonk.del")) [Hemlock Variable]
Last Resort Pathname Defaults Function [Hemlock Variable]
Last Resort Pathname Defaults (initial value (pathname "gazonk")) [Hemlock Variable]

These variables control the computation of default pathnames when needed for promting the user. Pathname Defaults is a sticky default. See the Hemlock User's Manual for more details.

buffer-default-pathname buffer [Function]

This returns Buffer Pathname if it is bound. If it is not bound, and buffer's name is composed solely of alphnumeric characters, then return a pathname formed from buffer's name. If buffer's name has other characters in it, then return the value of Last Resort Pathname Defaults Function called on buffer.

13.3. File Groups

Currently Hemlock doesn't have support for file groups.

13.4. File Reading and Writing

Common Lisp pathnames are used by the file primitives. For probing, checking write dates, and so forth, all of the Common Lisp file functions are available.

read-file pathname mark [Function]

This inserts the file named by pathname at mark.

write-file region pathname &key :keep-backup :append [Function]
Keep Backup Files (initial value nil) [Hemlock Variable]

This function writes the contents of region to the file named by pathname. This writes region using a stream as if it were opened with :if-exists supplied as :rename-and-delete.

When keep-backup, which defaults to the value of Keep Backup Files, is non-nil, this opens the stream as if :if-exists were :rename. If append is non-nil, this writes the file as if it were opened with:if-exists supplied as :append.

This signals an error if both append and keep-backup are supplied as non-nil.

write-buffer-file buffer pathname [Function]
Write File Hook [Hemlock Variable]
Add Newline at EOF on Writing File (initial value :ask-user) [Hemlock Variable]

write-buffer-file writes buffer to the file named by pathname including the following:

  • It assumes pathname is somehow related to buffer's pathname: if the buffer's write date is not the same as pathname's, then this prompts the user for confirmation before overwriting the file.
  • It consults Add Newline at EOF on Writing File (see Hemlock User's Manual for possible values) and interacts with the user if necessary.
  • It sets Pathname Defaults, and after using write-file, marks buffer unmodified.
  • It updates Buffer's pathname and write date.
  • It renames the buffer according to the new pathname if possible.
  • It invokes Write File Hook.

Write File Hook is a list of functions that take the newly written buffer as an argument.

read-buffer-file pathname buffer [Function]
Read File Hook [Hemlock Variable]

read-buffer-file deletes buffer's region and uses read-file to read pathname into it, including the following:

  • It sets buffer's write date to the file's write date if the file exists; otherwise, it messages that this is a new file and sets buffer's write date to nil.
  • It moves buffer's point to the beginning.
  • It sets buffer's unmodified status.
  • It sets buffer's pathname to the result of probing pathname if the file exists; otherwise, this function sets buffer's pathname to the result of merging pathname with default-directory.
  • It sets Pathname Defaults to the result of the previous item.
  • It processes the file options.
  • It invokes Read File Hook.

Read File Hook is a list functions that take two arguments---the buffer read into and whether the file existed, t if so.

Back to Table of Contents