This is the manual page for the Tclresource extension (version 1.3).
NAME
resource - Manipulate Mac OS resources
SYNOPSIS
package require resource
resource [subcommand] ?arg arg ...?
INTRODUCTION
The resource command provides some generic operations for dealing
with Mac OS resource forks. This command is only supported on the Mac OS
platform. Prior to Mac OS X, each Mac OS file consisted of two forks: a
data fork and a resource fork. Since the advent of Mac OS X, 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). One must use this command 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, under each type, are designated by an
ID and possibly a name. See RESOURCE TYPES and
RESOURCE IDS below for
details.
Use the following instruction to load the Tclresource extension in a
Tcl script:
package require resource
The syntax of the command is:
resource subcommand ?args ...?
Basically a resource fork is opened with the command resource open which
returns a unique token. This token is used in all the other commands to
specify the resource fork they apply to.
The valid subcommands are explained in the next sections.
resource attributes
The general syntax of this command is:
resource attributes resToken ?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. There
are four different syntaxes: the first two concern resource maps, the other
two concern specific resources within a resource map.
resource attributes resToken
To get the attributes of the resource map specified by the resToken
argument.
resource attributes resToken value
To give the value value to the attributes of the resource map specified
by the resToken argument.
resource attributes resToken option resourceType
To get the attributes of the resource specified by the argument option in the resource map designated by the resToken argument. The
option argument 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 resToken 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 resToken argument. The resource can be specified using either the -id or the -name as indicated above.
The resource attributes command was introduced in version
1.1 of the Tclresource extension.
See RESOURCE ATTRIBUTES below for details about the
possible values for attributes.
resource close
resource close resToken
Closes the resource specified by the token resToken (typically
obtained with the resource open command). Resources from that
resource file will no longer be available.
resource delete
resource delete ?options ? resourceType
This command will delete the resource specified by the options
argument and the resource type resourceType (see RESOURCE TYPES below).
The options give you several ways to specify the resource to be
deleted. The possible values are:
- -id resourceId : if the -id option is
specified, 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 the -name option 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 resToken : if the -file option is
specified, the resource will be deleted from the file corresponding to the
token resToken. 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 files
resource files ?resToken ?
If resToken is not provided, this command returns a Tcl list of the
resource tokens for all the currently open resource files. The list
is in the normal Mac OS search order for resources. If resToken is
specified, the command will return the path to the file whose resource
fork is represented by that token.
resource fork
resource fork resToken
Returns which fork (either data fork or resource fork) contains
the resource map specified by the argument resToken . The return value
will be datafork , resourcefork or unknown . The value unknown 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.
The resource fork command was introduced in version 1.1 of
the Tclresource extension.
resource id
resource id resourceType resourceName resToken
Returns the id of the resource of type resourceType with name
resourceName in the resource map designated by the argument resToken .
This is the reverse of command [resource name].
resource list
resource list ?-ids ? resourceType ?resToken ?
List all of the resources ids of type resourceType (see RESOURCE TYPES
below). If resToken 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 resource IDs.
The -ids option was introduced in version 1.1 of the
Tclresource extension.
resource name
resource name resourceType resourceId resToken
Returns the (possibly empty) name of the resource of type resourceType
with ID resourceId in the resource map designated by the argument
resToken . This is the reverse of command [resource id].
resource open
resource open ?(-datafork |-resourcefork )? fileName ?access ?
Open the resource map for the file fileName . On Mac OS X, 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 token (resToken ) 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.
The -datafork and -resourcefork switches were
introduced in version 1.1 of the Tclresource extension.
resource read
resource read resourceType resourceId ?resToken ?
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 resToken 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 Mac OS resources use a binary format and the data returned from
this command may have embedded NULLs or other non-ASCII data.
resource types
resource types ?resToken ?
This command returns a Tcl list of all resource types (see RESOURCE
TYPES below) found in the resource file pointed to by resToken . If
resToken is not specified it will return all the resource types found
in every resource file currently opened by the application.
resource update
resource update resToken
This command updates the resource map designated by the resToken
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
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 resToken : if the -file option is specified then the resource will be written in
the file pointed to by resToken , 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 Mac OS resource type
for text. The type STR# is a list of counted strings. All Mac OS
resources must be of some type. See Mac OS 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
Mac OS 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 command
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 are additive values. To set both the mapReadOnly and
mapChanged attributes for the resource map with token resToken , one
would write:
resource attributes resToken 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
Here is some history about the resource command. The resource command is only available on Mac OS. On systems older than Mac OS X,
the resource command was built in Tcl itself but, with the advent
of Mac OS X, it was eventually removed from the Tcl framework and was made
available as an extension.
Version 1.0 of the extension was simply a port to Mac OS X of the
old resource command: in particular, it did not handle data fork
resource files. Support for data fork resource files was introduced in
version 1.1. Support for 64 bits architectures was introduced in version
2.0.
VERSION HISTORY
- 1.0 - 03/09/25 - First release of the extension for Mac OS X.
- 1.1 - 03/10/05 - Support for data fork resources, attributes, update, name.
- 1.1.4 - 04/09/07 - Fixed a bug related to permissions. Added a
complete tests suite. Better error messages.
- 1.2 - 2007-11-15 - Support for Intel and native endianness. Universal build.
- 1.3 - 2012-04-07 - Support for 64 bits.
KNOWN ISSUES
Report any issues concerning this extension with the Bugs Tracker
available on the official page of the project at SourceForge.
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 had the following copyright.
Copyright (c) 1997 Sun Microsystems, Inc.
Copyright (c) 1995-1997 Roger E. Critchlow Jr.
For the Tclresource extension:
Copyright (c) 2003-2012 Bernard Desgraupes, Daniel Steffen
SOURCE CODE
Tclresource is an Open Source Project. Its source code is public and can
be found on the SourceForge site at
this address.
SEE ALSO
open
KEYWORDS
open, resource