PeekIt Users Guide

PeekIt 2.6.1 January 2008 by C.K. Haun
Copyright © 1989-2008 C.K. Haun and Ravenware Software, all rights reserved.
Download PeekIt PowerPC - Download PeekIt Universal Application - PeekIt Plugin SDK - Back to Software - Back Home

PeekIt is a quick and easy utility for examining any file on your Mac. 
PeekIt allows you to open, examine, and change (as raw or hex values) the contents of a file.  This is very useful for anyone from programmers to people who just want to snoop around the system to learn more.
PeekIt also allows you to annotate files, adding notes about interesting data locations, fields, and other information.  This can be a huge boon to programmers working in remote teams, and with the addition of exporting .pinotes files in 2.4 this gets even better, see the Notes section of the docs.

The ability to directly modify the contents of any file can be invaluable, for everything from making a change in a file you don't have an application for, to fixing a value quickly during debugging of an application.
PeekIt can also be a fun tool to explore and learn, and in some cases make other applications more usable.  Peeking a game save file, for example, can teach you how programmers think and work when they are saving a complex bunch of information.  If along the way you figure out how to give yourself 1,000,000 extra gold pieces that can be fun, too!
It's important to note that PeekIt will make no changes to a file unless you specifically indicate that you want to make changes.  PeekIt will never modify a file accidentally or without your complete knowledge.  PeekIt also uses very little memory, it does not read the entire file under investigation into memory, only a small portion.
I use PeekIt when I'm writing code (including PeekIt, recursively), so I'm always thinking of new things that I want it to do. Check the PeekIt home page regularly for updates, I usually do 2-3 a year. Also, I designed PeekIt primarily for viewing and investigating, the modification/editing side of things is secondary. I'll always be tweaking and increasing the capabilities to explore, annotate, and investigate, but the editing it is lower priority unless you give me a compelling idea or request (like pasting in 2.5.3)

Note: People have commented on the lack-of-beauty of PeekIt's icons. This is True. I ain't an artist, if you can make better icons do so and send 'em to me, I'll probably use them.

PeekIt is provided free of charge.

System Requirements: I dunno. I usually develop and test PeekIt! on the latest version of the OS (10.4.10 currently, for example) and don't test anywhere else. I try not to use anything particularly 10.4-ish or version specific. See if it runs on what you're using.

Release Notes
PeekIt 2.6.1 Released January 2008
- Fixed a divide-by-zero error in resizing the value window on intel-based machines
- Added the ability to set the amount a click in the page area of the scroll bar moves the selection. Read about it.
- Fixed an obscure access control list error

PeekIt 2.6.0 Released October 2007
- Added File comparison functionality, check the documentation
- Fixed the selection rect in the value drawer.
- Fixed a 32->64 bit extension bug in the Notes popup. It's the compilers fault, not mine, I swear.
- Updated source window with file comparison code

Previous release notes

The PeekIt Main Window

This is the PeekIt window.  You can have as many PeekIt windows open as you'd like.Each PeekIt window is your view into one file. 

The top part of the window is the data view area, and when you first open a file it shows you two representations of the data.  On the left is the raw data from the file, with no filtering.  This is handy for looking for text, or patterns of data that might be important.  The view on the right shows the hex values of the data on the left.Each view has a scroll bar for convenience,  but the views do not scroll separately.  They are locked together, when one scrolls the other scrolls. The far left column shows the file position of the starting byte in the currently displayed row, this can be displayed as a decimal number or hex number.

In version 2.6.1 I added the ability to change how much the data area and selection point move when you click in the page up or page down areas of the scroll bar. This was suggested by Thom K. , and can be very useful for stepping from record to record in a structured file, great idea.
Easy to use. Say you have a file with data structures that you figured out were 48 bytes in size. Go to the Tools menu and select Change Scroll Page Amount

A sheet will drop down;


Enter 48 (or whatever value) in the eidt field and click OK.
Now any clicks in the page areas will move the selection point up or down 48 bytes, which would enable you to quickly step through a series of records without having to figure out where each starts yourself. Use this in conjunction with a Formatter and you can really speed through a series of records.
When you're done paging by a specific amount, select Change Scroll Page Amount again and click Revert to default scroll and everything will be back to normal behaviour.


You can also move through the file with the arrow keys, page up, page down, home, and end keys.
- Left and right Arrow keys move one byte either way.
- Up and down arrow keys move up and down one line.
- Page up and page down move up or down one screen of information
- Home and End keys move to the start or the end of a file.
Note: Holding down the shift key when using any of the keys above increases the number of bytes move by 10x.  Shift-page up move up 10 screens of data, for example.
On the far left is the position column, this shows you the position (in bytes) that the line directly to the right starts at.
The numeric position of the selection rectangle is at is always shown at the bottom of the main screen. This can also be shown as decimal or hex.

The value drawer has two panes (right now, I have ideas for more), Values and Formatters. You choose the pane you wish to use with the selector at the bottom of the drawer.

The first pane is the raw value of the selected position;

The value drawer shows you the byte, word, and long word decimal values, signed and unsigned, big-endian and little endian,of the data at the insertion point, as well as a string and hex stream representation. This display is live, so it will update constantly as you move the selection point around the file, can be very handy!

New on 2.4.6, there is a graphic panel in the value drawer below the text string. This allows you to quickly see patterns in the file, look for variations in color, or repeating colors, to find some interesting things. You can change the baseline color from grayscale to red, green, or blue in the Preferences window. Note that the larger you make the window or further out you pull the drawer the larger the data pixels get, it's easier to see the difference between close numeric values (like $7F and $80, for example) with the graphic panel larger.

The red rectangle encloses the byte currently selected in the main window. You can click on the color pane to move the selection point, in the main window and the color pane, to the byte you want to investigate.

On the right end of the drawer are the scale adjustment buttons. These adjust the size fo the pixels, allowing you to see more of the file in the graphic panel than is currently being shown in the main window view. This can make it easier for trying to find a specific pattern or hot spot in a file.

 
Press the '-' button to scale out, or make the pixels smaller. Press the '+' key to make the pixels bigger.

 

New in 2.5.0 is being able to view file data in a structured way. This is similar to looking at a structure in a Xcode debugging window. You define a structure and PeekIt will display the data from the selection point onwards in that structure.

The first step is to define (or load) appropriate structures for the file you're working on. This is somewhat complex, please refer to the Data Formatter Management section of this document for all the details.

Once you've defined some formatters, using them is simple. Click on the "formatters" button at the bottom of the Value drawer and the formatter pane is displayed.
At the top of the Formatter pane is a popup menu that contains all the non-empty defined formatters. Non-empty means that they have at least one data field. Select the formatter you want to filter the file data through, and PeekIt will show the representation of the data you want.

Very simple to use. And, of course, the data dynamically updates as you move the selection point, or if you modify a formatter.

The vertical bar separating the names from the values is moveable to give more space per side, just click ont he gray line and drag.

If a formatter embeds another formatter, meaning that one of the formatter elements is another formatter, then the formatter title and embedded formatter title will be highlighted in the value color. The data elements of the embedded formatter will be indented slightly to show that this is an embedded formatter.

Since a formatter can embed a formatter which can embed a formatter (and so on.... ) there can be multiple levels of indentation.

Selection Ranges

You can now select a range of bytes in a file. After selecting the range, you can then do things with that range. Which is good, because it would be kinda pointless to make a range and not do anything with it.
Start and End marking

Click and drag to select a range of bytes. Or, move to the byte you want to have at the start of the range, and press command-1 (or select Mark range start from the Tools menu). Then move to the end of the range and press command-2 (or select Mark range end from the Tools menu). The range will be highlighted (you can change the highlight color in the Preferences window). And of course you can change the start and end of the range by selecting a new byte anywhere in the file and hitting command-1 or command-2 again.
When you have a range marked, you can do the following tasks;

Finding

PeekIt allows you to find ASCII text or hex bytes . SelectFind in this File from the Find menu, or press command-F, and the Find sheet will drop down.
Just select the appropriate radio button, enter the pattern to find, and click Find. With the Hex radio button selected, you'll be restricted to hex values, of course.

Find Not helps you find the first byte that is not a value. If you're looking at a file full of 0's, for example, and want to go quickly to the first value that is not a 0, enter "00" in the search field and click "Find NOT". This only works for single bytes, because it's boring code to write and that's all I got done before I started yawning.

Finds usually start at the currently selected file position. If you want the find to start at the beginning of the file, check "Start at the beginning of file".

New in 2.5.2 is multi-window finding. Clicking "Multi-Window Find" will search for the string in all the windows you currently have open, in order. This also applies to finding again (command-G).

So, for example, if you have 3 windows open and you're searching for "D5AA96" (if you remember what byte string is from, email me) across all the windows, click "Multi-window find". Each window in turn will be searched, and if the string is found that window will be selected and the string moved to. If you want to find it again, just hit "command-G" that the multi-window search will continue through that window and the next. Note: the window order is established when you first do the multi-window search. If you open another file, or switch window layering, that will not change a"Find Again" search, you have to re-start (command-F) the search to get a new window ordering.

Harder to describe than to do, just give it a try.

File Modification
PeekIt allows you to modify any data in a file, with no restrain or common-sense filtering. This is very powerful and useful.  It can be a great self-teaching tool.  It can also cause you no end of grief used improperly. 

Warning: PeekIt allows you to make permanent random changes to critical files, you can conceivably render your computer unable to boot, applications unable to launch, and destroy the integrity of data files by careless use of PeekIt.  Modify file at your own risk, modify backup files only, or backup your data before using PeekIt for modifications!

OK, that's out of the way.  You know what trouble you can get yourself into, but you also know how handy it can be. PeekIt is not the easiest file modification tool in the world. That's by design, the goal is to slow you down just a little while making wholesale changes.
First thing to always remember:  PeekIt makes no changes to the original file until you explicitly tell it to make changes.  All your work is only applied in memory until you explicitly ask to save the modifications, so if you make a mistake or choose to make the changes permanent, you can remove the changes, quit the app, or simply undo everything you've done.  PeekIt offers you many ways to change your mind.

Allowing Modifications

When you click the Modifiable radio button additional controls appear:

You can modify files by entering data in two ways, either as straight ASCII (text), or byte by byte.

ASCII is useful if you're changing a text document, or an XML file, and you can easily enter the characters from the keyboard.  Hex entry is useful for numeric values, or to affect saved data that isn't text.
ASCII entry is the default, and is pretty simple.  Just type the new characters, and the file view will be updated.  The changed bytes will be shown in red (or the color you select in the Prefs window). 

Hex entry takes an extra step. Click the Hex radio button, then enter the new hex value in the text edit box, and click the Apply button or hit the Return key.  Do the same for each hex value.  Easier than it sounds, after each hex change the text box is fully selected, so you then can enter your next hex value, hit return, enter hex, hit return, and so on.

You can also paste. Command-v (or select paste from the Edit menu) and PeekIt will paste the data from the clipboard into the file, starting at the current selection point. The Paste menu item will only be enabled if you have copied Text to the clipboard from another application, or you have Copied data from a PeekIt window inside PeekIt. Note also that pasting will not currently extend the length of a file, though it may in the future. So a paste that would go past the end of the file will just stop at the end. Let me know if you'd like it to extend the file.

Undoing changes

There are four ways for you to remove changes from a file.  Remember, no changes are permanent until you tell PeekIt to make them permanent!

Committing the changes

OK, so you've increased your D&D characters gold points to a million, and you want to save the changes.
Click Commit Changes. A sheet appears asking you if you are sure you want to permanently change the file.

This sheet also asks if you would like to create a Changes file at the same time. This will allow you to save the changes to share with a friend, and as of PeekIt! 2.5.5 this will also allow you to undo the changes you've made to this file at a later date ( revert the file). There is also a preference to make sure that checkbox is always set, helping to insure that you can always revert a file.

 

Save As

Another way to keep the original file untouched is to Save As. If you've made changes to the original file and would like to test these changes without affecting the original file select Save As from the file menu. You'll be prompted for a file name.
The new file created will have all of your changes, while the original file continues to be in a pre-saved, unmodified state with changes pending. You can remove the changes ( by clicking revert to original or closing the file and responding don't save to modified dialog).

Other PeekIt main window features

Window Size setting
You can set the default size for all the windows PeekIt creates, using the current window as a template. Just set the window size to what you would like, then select the Set Default window size menu item from the Tools window. All windows created from then on will be that size, this is a handy way to have the same number of columns in every window. This is saved as a preference.

Help tags
PeekIt has help tags for all of the controls in the main window. But, in addition to Help the tags can show you interesting things about the data. Hovering over a changed byte will show you the bytes original value. Hovering over a byte with a note will show you the title of the note for that byte.

PeekIt Colors
In the data view, you'll see some of the text data is in different colors.  These colors represent different attributes of that data . Column colors  The column colors alternate lavender and white.  This is to more easily identify patterns and differentiate columns of data.
Black  Normal data
Red This data has been modified by you during this session
Green A green square behind a data byte indicates that there is a note for this byte

Note:  All the colors lists above are the defaults for PeekIt.  You can choose to change any or all of these colors (see Preferences).Those are the basic controls and interface for Peeking at files.  One additional feature to help with Peeking is Finding.

 

Data Formatter Management

Data formatters allow you to look at data in a file in a structured way. Using a formatter is described in the Value drawer section, this section covers how to create and manage your own formatters, and how to save and load formatters so you can share them with others. This is very handy for teams of programmers, or again, so you can tell your buddy how to give himself 1,000,000 gold pieces and armor and weapons, if you can describe the character on-disk.

A formatter is a container with data elements, very similar to a programming structure. You create one by creating a named container, then adding the appropriate data elements, specifying lengths, signed-ness, endian-ness.

Note: This is the start of a powerful feature. Formatters are easy to make now, but I expect to make Formatters even easier to create over the next few releases. I'll need feedback on this feature and what you want added, or changed, so please email me about Formatters!

The Formatter window:

The left hand list shows all the formatters available. The right hand list shows the contents of the selected formatter. Column sizes (besides the "Locked" column in the formatter list) can be resized, just click on the appropriate line and drag. PeekIt will remember your column positions between launches. PeekIt resets the column widths to default proportions when you resize the window.

Formatter definitions and results

Here is a formatter definition

And here's what that definition results in in the Value Drawer Formatter view

Creating a formatter

Lets look at the Formatter list first. You can add a new formatter by clicking on the plus button (+) at the bottom of the list.


To change the name of the formatter, double click on it's name and an edit field will open.

Click anywhere outside of the edit field, or hit Return or Enter and the name change will be made. Hitting Escape cancels the name change. Maybe. If I write that code.

Along the right side of the Formatter list you'll see a dividing line, and beyond that line light gray"L" characters. Double clicking on one of those "L"s locks the selected formatter. The L turns solid black t.... actually when I was typing that I realized red would be better than black so I just changed the code. If the formatter is locked the L will be bright red. When a formatter is locked, it cannot be renamed, deleted, or have any of it's elements changed. Double-click on the L again to unlock the formatter for modifications.
Select a formatter. It's contents will then be shown in the Formatter Content pane.
You remove the selected formatter by clicking the minus button (-). If a formatter is locked, the minus sign will be dimmed. PeekIt looks to see if the formatter you want to delete is in use (embedded in another formatter, more on this later) and will not allow you to delete the formatter if another formatter is using it.

A formatter can't be used without data elements inside it, it has to be able to do something. The next step is to add the data elements that define a formatter.

Working with data elements

When you have a Formatter selected in the left hand list, you're able to add or delete data elements from that formatter. The Plus and Minus buttons under the right hand list add and remove formatter elements.

When you click Plus, a new data element is added to the end of the list. By default, the element is a single byte, unsigned, displayed in hex.

To change any data field, double-click on the field.

Double click on the name and a text box will appear to allow renaming. The name is entered as text.

The Type field describes the data type. Double-click on this field and a popup menu appears. The popup menu contains standard data types (byte, word, etc.) and then a dividing line. Below that dividing line all the other formatters appear.

Note: A formatter can contain other formatters. The list of formatters in the menu contain any formatter that has a data element (empty formatters do not appear). The formatter you are currently working on shows up as disabled, a formatter cannot contain itself. This extends deeply, meaning that you cannot embed a different formatter that might, somewhere inside it, embed yourself again. So if a formatter is dimmed assume that somewhere in that formatter chain the formatter you are working on is embedded somewhere.

Select the data type you want. For some standard types or embedded formatters, the length field is filled in for you. For byte strings or padding bytes the length value is set to 1. Double-click on the length field to enter a different number of bytes.

Note: Any formatter that contains a Pascal or C string or other data-defined length type (or embeds a formatter that contains one of those types) cannot be accurately sized. i.e., I don't know how much data it will consume, since that depends on the size of a string on disk. PeekIt, by default, uses 256 for a pstring and 1024 for a C string for guesstimating as a performance enhancement. When the formatter is actually applied to file data real values will be used, of course, but those data types will always appear over-large.

You cannot change the length of c or pascal strings, or of embedded formatters. You can change words, longs. Don't know why you would, but you might so I left it in.

The next field is the signed/unsigned state of that field. Double-click and a checkbox appears for you to set the signed-ness of the value.

The next field is endian-ness. Double-click on that field to select big or little endian. Remember that PeekIt is working on file data, not in-memory data. So byte-swapping isn't relevant in the little-endianness or big-endianess that PeekIt works with. I just look at a byte stream that came from a file and swap as appropriate, nothing to do with the endian-ness of the processor in the Macintosh you're running PeekIt on.

The final field allows you to specify whether this field is displayed as hex or decimal. Again, double-click to change the value.

If PeekIt runs out of data, reaching the end of the file, it will stop parsing, of course, and display dashes in the remaining data fields Formatters are automatically saved in a file Library/Ravenware/PeekIt Formatters.piform, that file is opened and read at each launch. Play around with it, it's one of those features that's harder to write about than just use.

Behavior of standard data types

You can read about each formatter, including plugins, by clicking on the "toggle info pane" button in the lower right of the formatter management window.

This opens the formatter info pane. Select the Formatter or Formatter plugin you're interested in from the popup list.

The name of the formatter, the author, and other information will be displayed. The description will in most cases be the most useful.

 

Exporting and Importing formatters

You can easily share formatters with co-workers or friends. Open the Formatter window, and you have two choices, you can select one formatter and export it, or you can export all the formatters you're using in PeekIt. You can also import formatters co-workers or friends have given you. Three new items appear in the Tools menu;

Exporting Formatters.
Open the Formatter window, and you have the choice of exporting the currently selected formatter (if there is one) or all the formatters you currently have. Select either menu item as appropriate, and you'll go through a standard file saving process. Note that plugin formatters are not saved.
The extension for PeekIt formatter files is .piform and the very lame icon is this;

Please someone make me some decent icons and send them to me before I create another horrible one!

Importing Formatters

Importing formatters is easy. Just select Import Formatter File, navigate to the formatter file you've been given, select it, and it will be added to the suite of formatters you current have.

Formatter notes:
Formatters are managed using internal unique IDs, not name, size, or contents. That insures that you can be as flexible with naming as you like, and insures that embedding, saving, and restoring are managed without you having to manually avid collisions in namespaces. This also applies to imported formatters, they are given their own unique ID when they are loaded, insuring that any embedding they contain works correctly.
If PeekIt cannot find an embedded formatter (a very unlikely occurrence, but I put it in because it could theoretically happen) it will put a dummy formatter in it's place, named "MISSING FORMATTER". As I think about this more, I cannot see how this would happen, so if it does send me a bug report and tell me how it happened.
If a PlugIn formatter (see below ) is missing, PeekIt will report "MISSING PLUGIN". Quit PeekIt, find the plugin, and relaunch and PeekIt will find it and continue appropriately.

Formatter Plugins
There are literally hundreds of numeric types; you might want to look at numbers as IEEE floats, long doubles, monetary amounts, and so on. PeekIt will never have all the numeric types built-in.
To help solve this, PeekIt 2.5.3 adds Formatter Plugins. You, or other developers, can expand the formatted data types by writing PlugIns that PeekIt can load and use to display numeric types. PeekIt Formatter PlugIns should be placed in the Ravenware plugin folder at Library/Application Support/Ravenware. Launch PeekIt, and PeekIt will collect all the plugins in that folder and add them to the list of available data types in the Formatter management window. By the way, there is a button in the Formatter management info drawer that will open the Plugins window in the Finder for you if you'd like.
Plugin formatters are managed by their name, the name listed in the info.plist file in the formatter plugin not by the filename of the plugin bundle. PeekIt will warn you about duplicate plugin names, and will use the first one of that name it finds.

WARNING: Formatter Plugins are not written by Ravenware. A badly-written formatter could cause a crash or other damage. A malicious formatter could cause otehr problems. Use formatters at your own risks, talk to the person who wrote it/them. If you experience problems with PeekIt, remove all the plugins first to isolate the issue, then add them back one at a time to see where the trouble may lie. Ravenware cannot debug issues with 3rd party plugins. You can find links to plugins 3rd parties have written on the Plug-in page.

Note: Plugins are managed by name, the name in the plist inside the plugin bundle. If there are multiple plugins with the same plist name, PeekIt will use the last one loaded. Yes, this could be a problem if people make duplicate named plugins. I'm not going to worry about that (and write the code to manage it) until I get a report of it happening. Yes, that's lazy, but I don't even know if anyone is going to write any plugins, much less conflicting ones, so I'm not going to.

Writing a Formatter PlugIn. Formatter PlugIns are simple, straightforward code. Read the PeekIt Formatter Plugin Builders Guide for all the details, and to download a sample plugin. Ravenware would be happy to host your plugin.

Notes
Modifying a file is interesting, but investigating and watching where things are, annotating all the fields in a file, might be the most useful capability PeekIt delivers.The Notes feature in PeekIt lets you annotate a file with notes. 

You can mark individual bytes in the file with your commentary about what that value means, where an interesting data segment starts, or a flag that changes at an interesting time and you want to keep track of it.  For programmers, this can be an easy way to insure that what you think you wrote to a file at a specific location actually got written.The notes for all files are kept in a separate database (not attached to the file) so they don't disturb the data, they are completely independent of the file ( For your information, the file is called PeekIt Notes File.pimnotes, in your Library/Application Support/Ravenware folder).

New with version 2.4, you can even save notes in a separate file and share that file with a friend or colleague, allowing them to attach your notes to a file on their computer.  Imagine, instead of telling your buddy where his characters' gold is stored in a file, you send him a PeekIt Notes file, he opens and associates it with his character file, and your notes are pointing to just the right bytes!

Opening the Notes pane

The Notes pane appears at the bottom of the page when you click on the disclosure triangle

You can also open the Notes pane by selecting Open Notes Pane from the Notes window.

Note: When you open the notes area, PeekIt will move to the first note (if there are any associated with this file). If the first note is in the other fork from the currently displayed fork, the data display will change forks. Don't be supervised.

This is the Notes area:

The disclosure triangle shows you how many notes are currently associated with this file

Each note has a title (in bold) and a large area for you to enter text.

The controls for notes are described below.  The Notes menu has commands for many of these commands, allowing you to annotate and manage notes without opening the notes pane.

If you choose export as Notes file, then the notes are saved into a new PeekIt file, a file with the extension .pinotes.

This file contains all the notes, and the information about where in the file the notes belong.  You can then later open this notes file and associate this file with any other file you like. Say you have two saved game files from the same game.  You've done your research in one of the files, and you've found out where the time limit is, and you have it marked as a note in one file.  But, you're interested in finding the same spot in the other file.

You could just  Peek the other file and go to the byte position you've written down and write a new note, easy enough for 1 note.  But what if you have a few notes?  Finding and re-entering the notes you already have seems silly.

A .pinotes file fixes this.  Export your notes on a file as a Notes file.   Now, open that new .pinotes file you just created.

You'll be asked to open another file that you want to associate with these notes

Select the other saved game file, and all the notes will be automatically added to this file, no extra work!

It gets even better if you want to share this information with a friend or co-worker.  Just email your friend the Notes file for a saved game, and he or she can learn (and make changes) with your knowledge.

On a serious note, this can be a valuable tool for programmers working on the same project.  If you are the team member who is responsible for defining and verifying a file format that others have to read or write to, you can create a .pinotes file for that file format, with guidance on what should be appearing at any point in a file, and put it up on your internal web site for all the programmers to grab.  Then they can use PeekIt and your .pinotes file to verify what should be at what position in a file.

This can also be a great supplementary tool for the documentation of your file format, you can annotate every interesting byte or field and send those annotations as a .pinote file, along with a sample file you've generated, and your other programmers can have a very easy to understand guide to the file format.

Notes are great.  Use 'em!

Go To Note popup

This popup lists all the note titles for this file, allowing you quickly go to any notated position in the file.

Changes Files
PeekIt 2.4.7 introduces Changes files. Just like sharing notes, you can now share your changes with a friend, or save them so you can apply them to another file later. Changes files also let you revert or undo the changes you've made to a file at a later date.
Creating a Changes file
When you make modifications to a file, the Create changes file...menu item in the File menu will be enabled. Select that item, and you'll be prompted for a name and location for to save a changes file. The file that's created will contain all the changes you've applied to the current file during this editing session. This can be very very handy if you've made extensive changes, keeps you from having to document and re-type them in the future. Sharing the changes with a friend can also make your friend like you a lot. PeekIt! will also ask you if you would like to create a Changes file when you save modifications to a file . A changes file has the extension .pichgs and looks like;

Using changes files


For file modification;
To use a changes file, open a file for modification as usual. Then, from the File menu, select the Apply a changes file....menu item. You can then find the appropriate changes file, open it, and the changes will be made to the file you're currently Peeking. Simple!

PeekIt checks two things when using a changes file;

To revert a file

If you would like ot undo the modifications you've made to a file, and you made a Changes file either from the menu or during modification save, it's easy.

The file will be restored to it's previous condition. You can see the changes just like any other PeekIt operation, the text will be red (or whatever color you've selected) so you can review the reverted bytes if you'd like. You must now click on Commit changes to complete the reversion.

Comparing Files
The ability to compare two files with PeekIt is introduced in v. 2.6.0. This can obviously be very handy if you need to quickly determine what bytes change in a file during an operation. This can help you determine if your own application is writing data correctly, see what another application might be doing to a file, and find out where the Gold value is stored in your Neverwinter Nights character file.
PeekIt's file comparison is strictly a byte-by-byte comparison. This is not a file merge, no attempt is made to extrapolate the range of data that might have been inserted or deleted to create the differences, that's the forte of tools like File Merge. PeekIts' comparison function is primal, if byte 250018 in file A is different that byte 250018 in file B you'll be able to find and see that quickly (quickly within limits, read the compare performance section).

File comparison is straightforward. Open one of the files you wish to compare as you normally open a file to be Peek'ed, from "open" or "open recent" in the file menu.
Next go to the Tools menu and select Compare To... .

At this poing the default behaviour is to open a drawer along the bottom edge of the window that shows the contents of the second file (there is an alternative view). Any differences will be highlighted with the Difference color which you can set in the Preference window;

In this example byte 100 is different from file A to file B and is highlighted in purple.
The Difference drawer shows the name of the file being compared, and has two data panes that are very similar to the data panes in a main PeekIt window. Two key differences with the difference panes;
- They do not respond to clicks
- There are no scroll bars
Navigation through the file is managed through the main window scroll bars and arrow keys, the data view in the drawer will follow along.
The differences drawer will also tell you if the data forks or resource forks are of different sizes
You can go to the next difference in a file by selecting Go to next difference from the Tools menu.
The Tools menu also has a 10-place Compare to Recent submenu, very useful if you're repeatedly comparing a particular file to another during development or research.

Typical use
Best way to use Comparing is of course to make a backup of the file you want to compare, then run the application that will change the original. Open the Original for peeking, then open the backup as Compare to. SInce this puts them both in recent menus (Open recent and Compare to recent) you can quickly repeat the operation as your development or research progresses, adding notes as you go.
Of course, as I type that I realize a nice feature would be to have an Open recent compare file pair submenu. Dang it. I'll see about getting this in the first version, if not it'll be on the list for the next one.

Alternate view
I realized during development that, while a drawer is a great tool for viewing differences, another way to view would also be good. So you can also bring up the other files contents and difference highlights as a floating window or palette or whatever the heck they're called now;

The pallete can be moved anywhere you'd like, of course. When it's opened, it opens to be the size of the raw data view. You can grow or shrink it as you like, hiding data or revealing the hex pane.

You can switch between these two views two ways. When you are currently comparing files, select Toggle Compare view to switch between drawer and palette.

To permenently set your view, go to the Preference window and select the default view you'd always prefer to use from the popup in the General preferences pane;
You can also quickly switch between the drawer view and the pallette view, just select Toggle compare view from the Tools menu, if the view is currently a drawer it will become a palette, if it's a palette it will revert to being a drawer.

 

Comparing performance
PeekIt is built for speed and a light memory footprint. File comparisons can strain the ability to stay fast and lean. If you compare to 500 megabyte files that have almost every byte different, PeekIt will spend a good bit of time doing the comparison, and use up quite a bit of memory keeping track of 495,000,000 differences.
I've tried to mitigate that in two ways;
- Compare performance. All file comparisons are done on a seperate thread with no interaction any other part of PeekIt until the entire compare is done. This keeps the rest of PeekIt very responsive during long compares. During the compare the compare drawer or floater will say "Processing file differences". Once the compare operation is complete the panes will refresh with real data.
- Display performance: If you're comparing two very large files (500 mybte or more) that have almost all their bytes different, scroll performance and moving around the file can slow a little. I actually don't expect many people to encounter this.
- Memory footprint. I've tried to be as efficient with keeping track of differences as I can, manging ranges of change instead of some other method. This can work very well, but if two multi-hundred megabyte files contain many similarities interspersed with differences the recordkeeping can build up. Again, this actually is not a very likely real-world use scenario, I've just run into it with test files I created to proof the functionality.

Menus

Preferences

PeekIt's preferences window allows you to set a few different settings. More importantly, this is always a great place to look when a new version of PeekIt comes out, since new features will usually have new preferences. And now that I look at this, this is the only place in the application or this help file where the correct name, PeekIt!, with the exclamation mark, is used.

The Preferences window as of 2.5.2 now has multiple panes to organize information more effectively.

General Preferences Pane

Color Preferences Pane

Here you can set the colors for almost everything in PeekIt. Column colors, color of the text in the data areas, and so on. To change a color just click on the appropriate box and select a color from the color picker. Note that these color changes DO have an immediate effect on currently open windows, as well as being saved for future windows.

Find Preferences Pane

Added, at user request, default behavior for Finds. Setting these checkboxes will make sure that these checkboxes are always set in the Find sheet when it drops down, saving you some clicks (and annoyance) if you almost always find in a particular way.

Files Created

PeekIt creates a few files to manage notes, formatters and preferences. You can delete these at any time, or if you are uninstalling PeekIt. You may also want to delete them if PeekIt begins to act strangely, it might clear up the symptoms. PeekIt also creates a folder called Ravenware in the Application support folder. This folder may already have been created by another Ravenware application

The files in Library/Application Support/Ravenware are:

And in Library/Preferences

PeekIt is a straight C application using the Carbon/procedural API set in Mac OS X. Some source code in PeekIt! has been in continuous use since 1983.

Previous Version Release Notes

PeekIt 2.5.5 Released June 2007
- Made plugin formatters optional, you now have to turn them on and re-launch in Preferences.
- Fixed a silly sign extension bug in the "Go to byte" window.
- Added "revert file" functionality. It was kinda like the Wizard of Oz, it was there all along I just didn't see it. Uses a Changes file, see the docs.
- Kevin A. wanted the pixels in the color panel in the value drawer scalable. Now they are. Click "-" to make the pixels smaller, allowing you to see more of the file at once, "+" to make the pixels bigger. This feature is not yet perfect, if you have ideas on how you'd like to use it let me know.
- Made committing modifications a little less complicated.

PeekIt 2.5.4 Released March 2007, minor update
- Moved the pref for val panel popup to the color pane, where it should be.
- Fixed a sign extension bug in dragging in the graphic pane in the val drawer
- Below things added for Kevin A.
- Added a "turn off help tags" preference.
- If there is a selection, the size will be shown after the "Selection position:"
- Added a viewing window not associated with a file. Select "new" from the File menu for a blank window.

PeekIt 2.5.3 Released October 2006
- Added Pasting. Martin K. wrote wondering why he couldn't paste like in any other Mac application. Good Question. So I've added pasting, see the docs for a discussion of how pasting works.
- PlugIns! Other people can now write external formatter plugins to enable new data types in the value drawer! Read the docs and download the SDK. Thanks to Michael for suggesting Plugins. The Source Code window contains most fo the source for plugin management.
- Fixed a bug where a crash could happen if you closed one of the windows during a multi-window find.
- Fixed a cosmetic bug in "scroll to next change"
- Completed large file support, any size file should be peek-able and mod-able.

PeekIt 2.5.2 Released July 2006
- Made the file position column (left side of the window) re-size so the leading numbers on a very large file don't go off to the left. Now it will be the width of the widest number that would ever be viewed when you go to the end of the file. I've resisted doing this for years (despite requests), and now that I have I still don't like it. So made it a preference, check "Turn off Pos. resizing" if you don't like it.
- Added an "Open path" option in the file menu for the text-adept. Use "/" as the directory delimter cuz I'm lazy.
- Changed Prefs window to have a tabbed interface for different option areas.
- Added persistent preferences for Finding, things like case insensitivity. Thanks to Bruce Y. for all the Find suggestions in 2.5.2.
- Added multi-window Finds, find will search all open windows. See documentation.
- Fixed a minor Find bug in large files.
- Fixed a bug where hex finds were being treated as case-insensitive, with odd results.
- Fixed the return/enter key in the FInd window...and in the "go to byte" window, sheesh, where else did I forget that?
- Added a frame around the list box in the Find File window For Completeness and Aesthetics.
- Updated some of the source files for your viewing.

PeekIt 2.5.1 released June 2006
- Fixed enter/return key committing when applying hex modifications .
- Added a gratuitous Find File window under the Tools menu to allow you to find files to peek even easier.
Warning: This is the start of adding a whole bunch of non-Peeking stuff into this application and making it a grab bag. Happens every time.
- Fixed a cosmetic bug where the views were showing an extra 0 byte. Cosmetic only, did not affect file editing. Thanks Igor A. for the bug report!
- Fixed a bug where we moved past the end of the file when editing. Again, cosmetic only.

PeekIt 2.5.0 released March 2006

- New very useful feature, Data Formatters. Allows you to view file data in a structured way. Read about it here andhere. Also some interesting code in the two formatter lists for embedding controls, dragging column widths, and so on look at the Formatters section in the source code window.
- Added a red "current byte" indicator in the value drawer color plot
- Added ability to click in color plot and goto/select a byte
- Changed the window theme to Utility instead of Document
- Finally got Fred in the appropriate place in the about box
- Turned on your ability to select and drag text out of, or copy text from, the source code window. You still can't copy all the source out and build PeekIt yourself (nor will you ever be able to) but you can cut and paste routines or HIView code now if you'd like. If you use a lot please credit where you got it from.

PeekIt 2.4.8 released November 2005
- Added little endian values to the value drawer for cross-platform file and in anticipation of Intel-based Macs (suggested by MM). Redesign the val drawer to be cleaner and easier to read.
- Enabled the "revert" menu item, sorry, forgot about that one.
- Added a preference to turn OFF creating a selection by dragging.
- Fixed the grow behavior of the release notes window. Perhaps someday I'll do the same for the Source Code window. And Perhaps Not.
- Fixed a font resizing bug
- Finally fixed a small cosmetic bug with the selection byte count
- Added an additional pref to make the data area background bars horizontal instead of vertical if you wish. Some data is easier to see that way.
PeekIt 2.4.7 released September 2005
- Added to the help tags. Hovering over a changed byte in the data display will now show the original byte value.
If there is a note, hovering over the byte will show the note title.
- Fixed a range selection bug
- Added full support for changes files
PeekIt 2.4.6 July 2005
- Added a graphic panel to the value drawer
PeekIt 2.4.5 June 2005
- Added a hex stream to the value drawer
- Added ability to set the default window size
- Added option to show file position in Hex
- Changed the text string in the value drawer to a larger, 300 character, text box.
Bug fixes suggested by Chris K.
- Fixed an odd-number "find" hex byte crasher
- Allowed pasting hex into "find" edit field
More suggestions from Jean L. in Canada (if you ask, I'll probably add or fix it)
- Made "Find NOT" work for single bytes. I'll get around to making it work for more later, it's kinda boring.
- Allowed selection expansion by dragging. Comand-1 and Command-2 still work for large, multi-page selections.
- Added a hex stream in the value drawer for easier readability
- Added ability to set the default window size (use the "Set Default window size" item in the Tools menu)
- Added option to show file position in Hex PeekIt 2.4.4
- Fixed a crashing bug that happened when a file could not be opened
- Fixed an obscure undo bug that no-one noticed.
Implemented more suggestions from JL of Canada
- Added "undo at selection", select a modified byte and undo just that change
- Added a "Save As" item. Save a copy of the current file with modifications to try out.
- Added selection of data range (use command 1 to mark the start, command 2 to mark the end)
allowing you to;
- copy that range to the clipboard
- export just that range to a file
- quick-modify a range of bytes
PeekIt 2.4.3 Released 22 January 2005 another minor release, just posted to the Ravenware web site, no broadcast email
- Changed drawing from QuickDraw to Quartz/CoreGraphics.
This will insure PeekIt continues to gain performance and features.
PeekIt 2.4.2, minor release, just posted to the Ravenware web site, no broadcast email
Released 10 January 2005.
- Rename the "find" menu to "tools"
- Added a "value" drawer to display the numeric & text value at the selection point
- Fixed the selection box size irregularity
Peekit 2.4.1
-Fixed the annoying "why don't you select the text field in the find box?" bug. Same in "go to byte" box and
other places.
PeekIt version 2.4 released October 2004:
- Updated source code in source code window
- Added resource fork peeking
- Added gratuitous ability to make windows Metal look for absolutely no good reason. Look in Prefs.
- Fixed an obscure startup crasher
Bugs reported by JL in Canada. If you report 'em, I'll fix 'em
- Added keyboard navigation for file data, i.e., arrow keys, page up & down, etc. move you around the file.
- Fixed bug in single-character find
- Added window sizing constraint code so you can no longer make the window really really tiny
- Fixed a bug in the 'Open file with notes' menu where it was opening the file right above the one you selected.

New in 2.3

Find

 

Credits

Thanks to Jean in Canada and Kevin A., Kenneth, Thom K., and Chris K. in the US for their suggestions, got most of them in!  Feedback is great, send it to  peekit@ravenware.com, I only know how to make it more useful if you tell me what you need.

Some Q&As on PeekIt!

Q:Why is this free software?
A:Some have asked why this is free. It's free because I want it to be free. I write software like this for fun in my free time. It would not be fun if I were trying to make money with it (I do that during the day). So just enjoy it. If you have spare money that you'd give me for this, donate it to someone who needs it more than me. If you really really feel as if you'd like to contribute (at least one person, a fellow Objectivist, has felt compelled to do so) PayPal money to ck@ravenware.com. But again, you have no obligation to do so.

Q: You keep mentioning finding gold pieces (or health, or items) in a game file and modifying them. Isn't that ethically un-pure?
A: Using your intelligence and persistence to figure out how a data file is organized is as challenging as fighting a Red Dragon. Which means that this is not cheating, this is an Advanced Playing Technique. That has been acceptable in computer gaming since the first days.