ibtool3(1) ibtool3(1)
NAME
ibtool3 - compiles, prints, updates, and verifies Interface Builder
documents.
SYNOPSIS
ibtool3 [options] document
DESCRIPTION
ibtool3 verifies, updates, and prints the contents of an Interface
Builder document, generating its output in standard plist format. The
tool follows a "read", "modify", "write", "print" order of operations.
OPTIONS
Specifying Output:
--write path
Write the resulting Interface Builder document to the specified
path.
--output-format format
By default, ibtool provides output in the form of an XML prop-
erty list. Specifying binary1 will instruct ibtool to output a
binary property list. Similarly, xml1 specifies an XML property
list, and human-readable-text specifies human readable text.
Compiling:
--compile path
Compile the input file and write it to the specified path. The
compile option instructs ibtool to convert an Interface Builder
document to a file that can be loaded at runtime. The compile
option can be combined with --flatten NO to produce an output
file that is both runnable, and editable. Additionally, --warn-
ings, --errors, and --output-format are three other options that
are commonly combined with --compile.
--flatten boolean
When combined with the --compile option and a value of NO,
--flatten instructs ibtool to produce an output file that is
both runnable, and editable. This option is typically used when
preparing a product for localization. If no value is specified,
the default flattening option is YES.
Postprocessing:
--strip path
Remove design-time content from the input Interface Builder NIB
document and write the stripped output to path. Stripping a NIB
reduces its size and makes it uneditable.
Loading Plug-ins and Bundles:
--bundle bundlePath
Load the bundle located at bundlePath.
--plugin pluginPath
Load the plug-in located at pluginPath.
--plugin-dir pluginPath
Load all valid plug-ins found in the first level of pluginPath.
Localization:
--previous-file previousFile
Specifies the Interface Builder document from the previous
developement iteration for the purpose of incremental localiza-
tions.
--incremental-file incrementalFile
Specifies the Interface Builder document from which to take
prior localizations during incremental localizations.
incrementalFile will often be the translated version of the doc-
ument specified with --previous-file.
--localize-incremental
Consolidate the structural and localization changes between the
input document, the document specified by previousFile, and the
document specified by incrementalFile, writing the resulting
document to the path specified by --write. When specifying this
option, one MUST provide a --previous-file and an --incremental-
file.
Importing:
--import plist
Apply the property values specified in plist to the object in
the Interface Builder document with the matching object ID.
plist should be a plist in the format produced by --export, only
with the dictionary containing the key com.apple.ibtool.docu-
ment.export removed from surrounding the object IDs. Note that
setting a property in this manner may not actually modify the
value of the property, or conversely may alter additional prop-
erties. Often, the input to this option is a modified version
of the output from --export. Combine this option with --write in
order to produce an Interface Builder document with the modified
property values.
--import-strings-file stringsFile
Replace the document's localizable strings with the translations
specified by stringsFile. stringsFile must be in the format
generated by --export-strings-file.
--import-xliff XLIFFDocument
Replace the document's localizable strings with the translations
specified by XLIFFDocument. XLIFFDocument must be in the format
generated by --export-xliff.
Exporting:
--export plist
For each object in the Interface Builder document, export the
union of the properties specified in plist for each class listed
in plist of which the object is either a member, or a member of
a descending class. plist should be a plist composed of a dic-
tionary with class names for keys, and arrays of property key
paths for values. The output is a plist composed of a dictio-
nary under the key com.apple.ibtool.document.export, where each
key is an object ID, and each value is a dictionary of property
key paths to their corresponding value. If a key in the second
level dictionary begins with a '.', it isn't a key path. Cur-
rently, the only special key is ".nilKeypaths", which identifies
an array of key paths whose value was nil.
An example of the plist format expected for the --export command
follows; this sample will export the 'title' property of any
NSCell in the given document.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>NSCell</key>
<array>
<string>title</string>
</array>
</dict>
</plist>
Refactoring:
--convert old-new
Rename the class named 'old' to 'new'. If 'old' ends with an
'*', then rename all classes beginning with 'old' to instead
begin with 'new'. This Updates all outlet types, class names,
custom classes, as well as actual instances.
--upgrade
Upgrade the input Interface Builder document to the latest
document type. If the output path is not specified by --write,
the upgraded document will be written to the input path.
Printing File Contents:
--export-strings-file stringsfile
Extract the localizable strings from the Interface Builder
document into stringsfile in the format expected by --import-
strings-file.
--export-xliff XLIFFDocument
Extract the localizable strings from the Interface Builder
document into XLIFFDocument as an XLIFF XML document in the for-
mat expected by --import-xliff. This argument can be combined
with the --source-language and --target-language arguments in
order to specify the resultant XLIFF document's source and tar-
get languages.
--source-language sourceLanguage
Specifies the source language of the resultant XLIFF document.
This argument MUST be used in conjunction with the --export-
xliff argument. If the --source-language argument is not speci-
fied, the language "en" is used by default.
--target-language targetLanguage
Specifies the target language of the resultant XLIFF document.
This argument MUST be used in conjunction with the --export-
xliff argument. If the --target-language argument is not speci-
fied, no target language is used.
--warnings
Include document warning messages in ibtool's plist output.
Warnings will appear under the key
com.apple.ibtool.document.warnings, with messages listed under
the subkey message and warning types under the subkey type.
--errors
Include document error messages in ibtool's plist output.
Errors will appear under the key
com.apple.ibtool.document.errors, with messages listed under the
subkey message and error types under the subkey type.
--notices
Include document notice messages in ibtool's plist output.
Notices will appear under the key
com.apple.ibtool.document.notices, with messages listed under
the subkey message and error types under the subkey type.
--localizable-strings
Include the document's non-empty localizable strings in ibtool's
plist output. The localizable strings are output as a dictio-
nary under the key com.apple.ibtool.document.localizable-
strings, where the keys are the object ids for objects with
localizable strings, and the values are dictionaries of property
names and their associated localizable strings. Empty strings
are ignored.
--localizable-stringarrays
Include the document's localizable strings that are values of
to-many relationships in ibtool's plist output. The to-many
localizable strings are output as a dictionary under the key
com.apple.ibtool.document.localizable-stringarrays, where the
keys are the object ids for objects with to-many localizable
strings, and the values are dictionaries of property names and
their associated array of localizable strings.
--localizable-geometry
Include the document's localizable geometry in ibtool's plist
output. The localizable geometry is output as a dictionary
under the key com.apple.ibtool.document.localizable-geometry,
where the keys are the object ids for objects with localizable
geometry, and the values are dictionaries of property names and
a plist representation of that geometry.
--localizable-other
Include the document's localizable attributes, other than
strings and geometry, in ibtool's plist output. These
attributes are output as a dictionary under the key
com.apple.ibtool.document.localizable-other, where the keys are
the object ids for objects with the localizable attributes, and
the values are dictionaries of localizable property names and
their associated values.
--localizable-to-many-relationships
Include the document's localizable to-many relationships in
ibtool's plist output. These attributes are output as a dictio-
nary under the key com.apple.ibtool.document.to-many-relation-
ships, where the keys are the object ids for objects with the
localizable attributes, and the values are dictionaries of
localizable property names and their associated values.
--localizable-all
Include all the document's localizable attributes in ibtool's
plist output. The localizable attributes are output as a dic-
tionary under the key com.apple.ibtool.document.localizable-all,
where the keys are the objects ids of the objects with localiz-
able properties, and the values are the union of the properties
returned by --localizable-strings, --localizable-stringarrays,
--localizable-geometry, and --localizable-other.
--objects
Include the document's objects in ibtool's plist output. The
objects are output as a dictionary under the key
com.apple.ibtool.document.objects, where the keys are the object
ids, and the values are the associated object's properties.
--hierarchy
Include the document's hierarchy in ibtool's plist output. The
hierarchy is output as a nested array of dictionaries under the
key com.apple.ibtool.document.hierarchy with the subkeys
objectID, label, name, children, and customClass.
--connections
Include the document's connections in ibtool's plist output.
The connections are output as a dictionary under the key
com.apple.ibtool.document.connections, where the keys are the
object ids, and the values are dictionaries including the sub-
keys type, label, source-id, source-label, destination-id, and
destination-label.
--classes
Include the document's classes in ibtool's plist output. The
classes are output as a dictionary under the key
com.apple.ibtool.document.classes, where the keys are the class
names, and the values are dictionaries including the subkeys
actions, outlets, superclass, and class.
--version-history
Print the version of IB/System Version used when this Interface
Builder document was last saved. The version history informa-
tion is output under the key com.apple.ibtool.document.version-
history with the subkey interface-builder-version.
--all Include all the information listed above in ibtool's plist out-
put.
Agent Usage:
--agent-name NAME
Use a named instance of ibtool to act as a server. If no such
server exists, create one. It is advantageous to use named agent
when invoking ibtool multiple times in quick succession, since
ibtool's setup time can be amortized across several invocation
of the tool. Note that there will be a penalty paid for starting
the agent, so not recommended for one-off invocations of the
tool.
Version Information:
--version
Print the version of ibtool. The version information is output
under the key com.apple.ibtool.version with the subkeys bundle-
version and short-bundle-version.
EXAMPLES
ibtool --export-strings-file file.strings file.nib
ibtool will output a strings file containing all of file.nib's
localizable strings.
ibtool --previous-file orig.nib --incremental-file trans.nib --local-
ize-incremental --write newTrans.nib mod.nib
ibtool will leverage orig.nib against changes in mod.nib and
localizations from trans.nib, and write the new translated nib.
ibtool --previous-file orig.nib --incremental-file trans.nib --import-
strings-file str.strings --localize-incremental mod.nib --write new-
Trans.nib
ibtool will execute in the same manner as above, but will apply
the strings from str.strings before writing the document.
ibtool --warnings --errors --notices file.nib > alerts.plist
alerts.plist will contain all warning, error, and notice mes-
sages from file.nib.
ibtool --plugin path/to/some.plugin --localizable-geometry file.nib
ibtool will load some.plugin and output a plist of all localiz-
able geometry in file.nib.
ibtool --convert oldName-newName file.nib
ibtool will change all classes with the exact name "oldName" to
be named "newName" instead.
ibtool --convert Old'*'-New file
ibtool will change all classes with names beginning with "Old",
such as "OldName", "OldClassName", and "OldClass", to instead
begin with "New". For example, the previously mentioned classes
would be changed to "NewName", "NewClassName", and "NewClass",
respectively.
ibtool --export export.plist file.nib
ibtool will export properties specified in the export.plist, and
output a plist mapping Object IDs to property values.
ibtool --agent-name CMPAgent --all file.nib
ibtool will start (or use if already running) an agent named
CMPAgent to get the results of --all from file.nib.
ibtool --export-xliff generated.xlf inputDocument.xib
ibtool will create an XLIFF document, "generated.xlf", that con-
tains all of the localizable strings from the input document
"inputDocument.xib". As the source and target languages were
not specified, English will be used as the source language, and
the target language will not be included.
ibtool --export-xliff generated.xlf --source-language es --target-lan-
guage fr inputDocument.xib
ibtool will create an XLIFF document, "generated.xlf", that con-
tains all of the localizable strings from the input document
"inputDocument.xib". The source language of "generated.xlf" is
marked as Spanish, and the target language is marked as French.
ibtool --import-xliff translation.xlf --write translated.xib inputDocu-
ment.xib
ibtool will apply the translations found in the XLIFF document
"translation.xlf" to the input document "inputDocument.xib", and
write the resulting translated document to "translated.xib".
SEE ALSO
plist(1)
Apple Inc. Dec 07 2010 ibtool3(1)
Mac OS X 10.7 - Generated Thu Aug 11 09:52:51 CDT 2011