mirror of
https://github.com/nickshanks/ResKnife.git
synced 2024-06-25 11:29:28 +00:00
131 lines
5.7 KiB
Plaintext
131 lines
5.7 KiB
Plaintext
WHAT IS A TEMPLATE?
|
|
|
|
For AngelTemplate, a Template is a file that describes a (binary) file format.
|
|
AngelTemplate uses template files to find out how to best display certain
|
|
kinds of binary files to you.
|
|
|
|
|
|
HOW DO I CREATE A TEMPLATE?
|
|
|
|
A template is basically a property list file. So, just use Property List
|
|
Editor to create your template, and when you're finished change its file
|
|
name extension from ".plist" to ".fileTemplate" and drop it in your ~/Library/Application Support/AngelTemplate/Templates/ folder.
|
|
|
|
|
|
BASIC STRUCTURE OF A TEMPLATE
|
|
|
|
A template file's root is a dictionary. It contains a "templateType" key that
|
|
must currently always be set to the string "fieldList", and a "templateVersion"
|
|
key that must currently always be set to the number "1".
|
|
|
|
A field list template consists of a list of "fields", which are the individual
|
|
pieces of data present in the file. An example of a field would be an integer,
|
|
a string, or a boolean. In addition, some fields can contain other fields, for
|
|
example the Array field can in turn contain integers, strings etc.
|
|
|
|
In addition to the keys mentioned above, fieldList Templates of type 1 (the only
|
|
type of template at this time) also contain the following keys:
|
|
|
|
fieldDefaults - A dictionary containing fallback key-value pairs for certain
|
|
field types. For example, if a field's value can be stored
|
|
as big-endian or little-endian, and you want all fields to
|
|
be big-endian, you can specify the "endianness" key with
|
|
value "big" in this dictionary instead of for each field,
|
|
and thus make the entire file big-endian.
|
|
|
|
fieldList - An array of dictionaries, where each dictionary contains
|
|
key-value pairs describing a certain field. All fields
|
|
have at least the following two key-value pairs:
|
|
|
|
type - A string identifying the type of field. See
|
|
below for a list of supported field types.
|
|
label - A label to display to the left of this field.
|
|
This is a bit of description whose text you
|
|
can choose arbitrarily to tell people using
|
|
this template what a particular field
|
|
contains.
|
|
|
|
Some field types also understand the following (optional)
|
|
key-value pairs:
|
|
|
|
description - A piece of (longer) descriptional text that
|
|
you can choose arbitrarily to provide
|
|
additional information about a field.
|
|
endianness - This is a string cintaining either "big" or
|
|
"little" and decides whether multi-byte data
|
|
types like integers and array counters will
|
|
be stored with least-significant byte first
|
|
(Intel) or last (PowerPC, M68000). If you
|
|
do not specify this key, the little-endian
|
|
format used on today's Intel-Chip-Based Macs
|
|
is used.
|
|
defaultValue - This is a value that will be used for new
|
|
fields to fill them with an initial value.
|
|
You can for example use this to fill in the
|
|
newest version number into a data structure.
|
|
Depending on what type a field has, the
|
|
defaultValue will adopt an appropriate
|
|
data type, generally a string or a number.
|
|
fieldList - Some fields can contain other fields. For
|
|
example, array fields contain a list of
|
|
fields that make up one array item. The
|
|
fieldList key is used in the array field and
|
|
other fields with sub-fields to hold an
|
|
Array listing these fields. Such a fieldList
|
|
has the exact same format as the fieldList
|
|
at the root level of the file.
|
|
Generally, if a field type understands the
|
|
fieldList field, it is /not/ optional.
|
|
setVariable - This is a string used as a variable name in
|
|
which this field's value will be stored. You
|
|
can then later take the saved value and
|
|
specify it to another field to use as its
|
|
value. This is e.g. useful with arrays where
|
|
the number of elements doesn't immediately
|
|
precede the array items.
|
|
|
|
LIST OF FIELD TYPES
|
|
|
|
The following field types are currently available in AngelTemplate:
|
|
|
|
Integer - A 4-byte signed integer.
|
|
UnsignedInteger - A 4-byte unsigned integer.
|
|
TwoByteInteger - A 2-byte signed integer.
|
|
TwoByteUnsignedInteger - A 2-byte unsigned integer.
|
|
UnsignedTwoByteInteger - A 2-byte unsigned integer.
|
|
Boolean - A 1-byte boolean value that is either 1 or 0
|
|
(YES or NO).
|
|
Comment - This is a field that only exists in the template. It
|
|
does not read or write any data from/to the file,
|
|
but rather simply displays its label in the template.
|
|
You can use this to group together certain fields
|
|
and add descriptions.
|
|
CString - A C string is a bunch of characters followed by a zero byte.
|
|
You can specify an "encoding" key for this field containing
|
|
a string like "MacOSRoman", "UTF8", "ISOLatin1" or "ASCII"
|
|
(See NSStringEncoding for other encoding names you can use.
|
|
Simply take the xxx part of the "NSxxxStringEncoding"
|
|
constants). If no encoding is specified, AngelTemplate will
|
|
assume an encoding of "UTF8".
|
|
PString - A Pascal String. Pascal Strings start with one byte
|
|
indicating their length in bytes, and up to 255 characters
|
|
after that.
|
|
Like for C strings, you can specify the "encoding" key. Note
|
|
that most Pascal strings out there won't be in the default
|
|
encoding of UTF8, so you'd better explicitly specify
|
|
MacRoman or ISOLatin1.
|
|
Array - An array of other fields. The array starts off with a 4-byte
|
|
integer containing the number of array elements, followed
|
|
by that many array items. Each array item's field layout is
|
|
defined by the fieldList contained in the array field.
|
|
TwoByteArray - Like Array, but the counter is a two-byte integer instead of
|
|
a 4-byte integer.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|