TclResource(n) Extension for Tcl TclResource(n)
NAME
resource - Manipulate Macintosh resources
SYNOPSIS
package require resource 1.1
resource option ?arg arg ...?
INTRODUCTION
The resource command provides some generic operations for dealing with Macintosh resources. This
command is only supported on the Macintosh platform. Prior to system OSX, each Macintosh file
consisted of two forks: a data fork and a resource fork. Since the advent of system OSX, resources
can also be stored in the data fork (this is the recommended format for portability reasons:
resource forks tend to be otherwise deleted when copied on another platform). You use the normal
open, puts, close, etc. commands to manipulate the data fork but you must use this command, however,
to interact with the resource map, even if it is stored in the data fork. In a resource map,
resources are categorized by type and, in each type, are designated by an ID and possibly a name. See
RESOURCE TYPES and RESOURCE IDS below for details. On OSX, the resource command is not a built-in
command of Tcl anymore. It is made available by this extension which much be explicitely loaded
with a package require instruction like this:
package require resource 1.1
Subcommand indicates what resource operation to perform. Any unique abbreviation for option is
acceptable. The valid options are explained in the next sections.
resource attributes resourceRef ?option resourceType? ?value?
This command is used to get or set the attributes of the resource map or
the attributes of a particular resource in the resource map. It has four
different syntaxes:
resource attributes resourceRef
To get the attributes of the resource map specified by the resourceRef
argument.
resource attributes resourceRef value
To give the value value to the attributes of the resource map specified
by the resourceRef argument.
resource attributes resourceRef option resourceType
To get the attributes of the resource specified by the argument option
in the resource map designated by the resourceRef argument. The option
can be one of:
-id resourceId
If the -id option is given, the id resourceId (see RESOURCE IDS below)
is used to specify the resource whose attributes must be returned or set.
The id must be a number: to specify a name use the -name option.
-name resourceName
If the -name option is specified, the resource named resourceName is
used.
resource attributes resourceRef option resourceType value
To give the value value to the attributes of the resource specified by
the argument option in the resource map designated by the resourceRef
argument. The resource can be specified using either the -id or the
-name as indicated above.
Note that the [resource attributes] command is available only since
version 1.1 of the Tclresource extension. See RESOURCE ATTRIBUTES below
for details about the possible values for attributes.
resource close resourceRef
Closes the given resource reference (obtained from resource open).
Resources from that resource file will no longer be available.
resource delete ?options? resourceType
This command will delete the resource specified by options and type
resourceType (see RESOURCE TYPES below). The options give you several
ways to specify the resource to be deleted.
-id resourceId
If the -id option is given the id resourceId (see RESOURCE IDS below) is
used to specify the resource to be deleted. The id must be a number: to
specify a name use the -name option.
-name resourceName
If -name is specified, the resource named resourceName will be deleted.
If the -id is also provided, then there must be a resource with BOTH this
name and this id. If no name is provided, then the id will be used
regardless of the name of the actual resource.
-file resourceRef
If the -file option is specified then the resource will be deleted from
the file pointed to by resourceRef. Otherwise the first resource with the
given resourceName and or resourceId which is found on the resource file
path will be deleted. To inspect the file path, use the resource files
command.
resource fork resourceRef
Returns which fork (either data fork or resource fork) contains
the resource map specified by the argument resourceRef. The return value
will be datafork, resourcefork or unknown. The unknown value is returned
for the resource maps listed by the command resource list which were not
opened explicitely by a resource open command but were already in memory.
Note that the [resource fork] command is available only since version 1.1
of the Tclresource extension.
resource files ?resourceRef?
If resourceRef is not provided, this command returns a Tcl list of the
resource references for all the currently open resource files. The list
is in the normal Macintosh search order for resources. If resourceRef is
specified, the command will return the path to the file whose resource
fork is represented by that token.
resource id resourceType resourceName resourceRef
Returns the id of the resource of type resourceType with name
resourceName in the resource map designated by the argument resourceRef.
This is the reverse of command [resource name].
resource list ?-ids? resourceType ?resourceRef?
List all of the resources ids of type resourceType (see RESOURCE TYPES
below). If resourceRef is specified then the command will limit the
search to that particular resource file. Otherwise, all resource files
currently opened by the application will be searched. A Tcl list of
either the resource name's or resource id's of the found resources will
be returned: each time the name of the resource is not empty, it is used
preferably to the id, unless the -ids option has been specified, in
which case only id's are returned. See the RESOURCE IDS section below for
more details about what a resource id is.
Note that the -ids option is only available since version 1.1 of the
Tclresource extension.
resource name resourceType resourceId resourceRef
Returns the (possibly empty) name of the resource of type resourceType
with ID resourceId in the resource map designated by the argument
resourceRef. This is the reverse of command [resource id].
resource open ?(-datafork|-resourcefork)? fileName ?access?
Open the resource map for the file fileName. On OSX, resources can be
stored either in the resource fork of the file or in the data fork of the
file. By default, resource open will try to find resources in the data
fork of the file, then, if none is found, in its resource fork. This
behavior can be modified with one of the -datafork or -resourcefork
switches which force the command to search only in the data fork or the
resource fork respectively. Standard file access permissions may also be
specified with the access optional argument (see the manual entry for
open for details). A resource reference (resourceRef) is returned that
can be used by the other resource commands to refer to this opened
resource map.
An error can occur if the file doesn't exist or the file does not have
resources in the data or the resource fork. However, if you open the file
with write permissions the file and/or resource fork will be created
instead of generating an error: the -datafork or -resourcefork switches
let you specify which kind of resource file should be created (data fork
resource file or resource fork resource file). If neither -datafork nor
-resourcefork are specified, a data fork resource file is created by
default.
Note that the -datafork and -resourcefork switches are only available
since version 1.1 of the Tclresource extension.
resource read resourceType resourceId ?resourceRef?
Read the entire resource of type resourceType (see RESOURCE TYPES below)
and the name or id of resourceId (see RESOURCE IDS below) into memory and
return the result. If resourceRef is specified we limit our search to
that resource file, otherwise we search all open resource forks in the
application. It is important to note that most Macintosh resource use a
binary format and the data returned from this command may have embedded
NULLs or other non-ASCII data.
resource types ?resourceRef?
This command returns a Tcl list of all resource types (see RESOURCE
TYPES below) found in the resource file pointed to by resourceRef. If
resourceRef is not specified it will return all the resource types found
in every resource file currently opened by the application.
resource update resourceRef
This command updates the resource map designated by the resourceRef
argument. It performs three tasks:
* changing, adding, or removing resource data in the fork on disk to
match the resource map in memory;
* compacting the resource fork, closing up any empty space created when
a resource was removed, made smaller, or made larger;
* writing the resource map in memory to the resource fork.
Because the [resource close] command calls [resource update] before it
closes the resource fork, you need to call it directly only if you want
to update the file without closing it.
Note that the [resource update] command is available only since version
1.1 of the Tclresource extension.
resource write ?options? resourceType data
This command will write the passed in data as a new resource of type
resourceType (see RESOURCE TYPES below). Several options are available
that describe where and how the resource is stored.
-id resourceId
If the -id option is given the id resourceId (see RESOURCE IDS below) is
used for the new resource, otherwise a unique id will be generated that
will not conflict with any existing resource. However, the id must be a
number: to specify a name use the -name option.
-name resourceName
If -name is specified the resource will be named resourceName, otherwise
it will have the empty string as the name.
-file resourceRef
If the -file option is specified then the resource will be written in
the file pointed to by resourceRef, otherwise the most recently open
resource will be used.
-force If the target resource already exists, then by default Tcl will not
overwrite it, but raise an error instead. Use the -force flag to force
overwriting the existant resource.
RESOURCE TYPES
Resource types are defined as a four character string that is then mapped to an underlying id. For
example, TEXT refers to the Macintosh resource type for text. The type STR# is a list of
counted strings. All Macintosh resources must be of some type. See Macintosh documentation for
a more complete list of resource types that are commonly used.
RESOURCE IDS
For this command the notion of a resource id actually refers to two ideas in Macintosh resources.
Every place you can use a resource Id you can use either the resource name or a resource number.
Names are always searched or returned in preference to numbers. For example, the resource list com-mand command
mand will return names if they exist or numbers if the name is NULL.
RESOURCE ATTRIBUTES
Resource maps and individual resources have attributes. The attributes for resource maps are:
+-------------+-----+---------------------------------------------+
| mapChanged | 32 | Write map out at update |
| mapCompact | 64 | Compact resource file when writing to disk |
| mapReadOnly | 128 | Resource file is read-only |
The attributes ar--+------------ed attributes for
the resource map with reference resourceRef, one would write:
resource attributes resourceRef 160
The allowable attributes for individual resources are:
+--------------+----+-----------------------------+
| resChanged | 2 | Resource changed |
| resPreload | 4 | Load in on OpenResFile |
| resProtected | 8 | Protected |
| resLocked | 16 | Load it in locked |
| resPurgeable | 32 | Purgeable resource |
| resSysHeap | 64 | System or application heap |
+--------------+----+-----------------------------+
PORTABILITY ISSUES
The resource command is only available on Macintosh. On systems older than OSX, the resource command
was built in Tcl but it was removed from the versions of Tcl compiled for OSX. It is now made
available as an extension which should be loaded in the scripts with the following instruction:
package require resource 1.1
Version 1.0 of the extension is simply a port to OSX of the old resource command: it does not handle
data fork resource files. Support for data fork resource files is introduced in version 1.1.
VERSION HISTORY
* 1.0 - 03/09/25 - First release of the extension for OSX.
* 1.1 - 03/10/05 - Support for data fork resources, attributes, update, name.
KNOW ISSUES
The resource command has been ported to OSX as a Tcl extension by Bernard Desgraupes. Please e-mail
any bug or problem you encounter: <bdesgraupes@easyconnect.fr> ((p Version 1.0 corresponds strictly
to the code provided in the Tcl source code (tclMacResource.c). Version 1.1 added several improve-ments: improvements:
ments:
* possibility of opening and writing to datafork resource files as well
as resource fork resource files.
* new subcommand [resource attributes] to get/set the attributes of a resource
map or an individual resource.
* new subcommand [resource update] to update a resource map without closing it.
* new subcommand [resource fork] to indicate which fork a resource map was opened from.
* new subcommands [resource name] and [resource id] returning the name of a resource given
its ID, and vice versa.
* new -ids option for the [resource list] command
The Tclresource folder (Tclresource1.0, Tclresource1.1 etc) contains the extension compiled as a
dynamic library. For the Tcl interpreter to find it automatically, it should be located on
your system in /Library/Tcl/ (administrator password required) or in your personal folder
~/Library/Tcl/.
LICENSE AND DISCLAIMER
This software is free software and distributed under the same licensing terms as the Tcl language
itself. See license.terms in the Tcl distribution. The original code of the resource command has the
following copyright.
Copyright (C) 1997 Sun Microsystems, Inc.
Copyright (C) 1995-1997 Roger E. Critchlow Jr.
For the Tclresource extension:
Copyright (C) 2003 Bernard Desgraupes
SOURCE CODE
Tclresource is an Open Source Project. Its source code is public and can be found on the SourceForge
site at the following address: <http://sourceforge.net/projects/tclresource ((p Tclresource binary
releases are available at <http://sourceforge.net/project/showfiles.php?group_id=93101 or on my web
page at <http://webperso.easyconnect.fr/bdesgraupes/tcl.html ((p The code is under CVS control. You
can retrieve the latest stage of development using any CVS client. See instructions at:
<http://sourceforge.net/cvs/?group_id=93101 ((p You can browse the cvs repository online at
<http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tclresource
SEE ALSO
open
KEYWORDS
open(n), resource(n)
2004-01-09 TclResource(n)
|