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:

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:

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: 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.

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:
mapChanged32Write map out at update
mapCompact64Compact resource file when writing to disk
mapReadOnly128Resource 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:
resChanged2Resource changed
resPreload4Load in on OpenResFile
resProtected8Protected
resLocked16Load it in locked
resPurgeable32Purgeable resource
resSysHeap64System 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

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