MyWebUniversity.com Home Page

Darwin Mac OS X man pages main menu

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 sys-
tem 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 pos-
sibly 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 spec-
ified
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 ATRIBUTES
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 ver-
sion 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 mem-
ory 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
NULs or other non-ASCI 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 resource-
Name, 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 command will return names if they exist or numbers if
the name is NUL.

RESOURCE ATRIBUTES
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
Th]e--attributes-]are-ad]ditional-values.--To--set--both--the--mapReadO]nly
and mapChanged 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 ISUES
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 ISUES
The resource command has been ported to OSX as a Tcl extension by
Bernard Desgraupes. Please e-mail any bug or problem you encounter:
((p Version 1.0 corresponds strictly to
the code provided in the Tcl source code (tclMacResource.c). Version
1.1 added several improvements:

* 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 distri-
bution. The original code of the resource command has the following
copyright.

For the Tclresource extension:

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:
((p Tclresource binary
releases are available at or on my web page at ((p The code is under CVS control. You
can retrieve the latest stage of development using any CVS client. See
instructions at: ((p You
can browse the cvs repository online at