Re: [Tcllib-devel] More file utilities ?

[Andreas K. <aku...@sh...>]

Here is an updated proposal.

Overview:

*	get_file/readFile is gone, replaced by the existing 'cat'
	command, albeit extended (encodings, etc.).

*	The 'touch' command which confused everyone (also called
	'clear'), is gone as well.

*	The basic modifications of a file in place (insertion,
	removal, replacement of segments) are represented by their own
	commands (keeping memory usage down), everything else has to
	be expressed in terms of the 'updateInPlace' command Joe
	proposed after looking at the old 'hack*' commands.

Now for the descriptions ...

=================================================

Basic descriptions for a set of commands operating on whole files.

The recognized options are generally

    -encoding    ENC
    -translation TRA
    -eofchar     ECH
    --

where "--" forces the recognition of a file, even if its name start
with a dash. None of the options are required. Unspecified settings
use the system defaults of the channel.

=================================================

::fileutil::cat (?options? file)+

	Read all specified files, using the given options, and return
	a string containing the concatenated contents.

	Note: option settings persist between file names, i.e. when
	doing

		cat -encoding binary fileA fileB

	fileB will be read using the binary encoding as well.

	The specified paths have to exist, have to refer to files, and
	have to be readable.


::fileutil::writeFile ?options? file data

	Writes the data into the file, creating it if needed.

	If the specified path exists it has to refer to a writable
	file.

::fileutil::appendToFile ?options? file data

	Appends the data to the file.

	The specified path has to refer to an existing readable and
	writable file.

::fileutil::insertIntoFile ?options? file at data

	Insert the data into the file, at the offset.

	The specified path has to refer to an existing readable and
	writable file.

::fileutil::removeFromFile ?options? file at n

	Removes n characters from the file, starting at the given
	offset. Characters are counted as per the active encoding.

	The specified path has to refer to an existing readable and
	writable file.

::fileutil::replaceInFile ?options? file at n data

	A combination of 'removeFromFile' and
	'insertIntoFile'. Removes n characters from the file, starting
	at the given offset, and replaces them with the given data.

	The specified path has to refer to an existing readable and
	writable file.

	Semantics:
		removeFromFile path at n
		insertIntoFile path at data

::fileutil::updateInPlace ?options? file cmd

	Reads the contents of the file and passes it as an additional
	argument to the cmd (prefix). Overwrites the original file
	with the return value of the command. If the command raises an
	error, the original file is not modified.

	The specified path has to refer to an existing readable and
	writable file.

	The last three operations could be expressed in terms of
	updateInPlace. Their transforms are however so simple that a
	direct implementation is possible without loading the whole
	file into memory.

=================================================

-- 
So long,
	Andreas Kupries <aku...@sh...>
			<http://www.purl.org/NET/akupries/>
	Developer @	<http://www.activestate.com/>
-------------------------------------------------------------------------------