C Within Help File

This page recreates the current Help file for C Within.

Introducing C Within

C Within lets you inspect the operations performed on a text file by the C++ or C preprocessor. Usually the text file is a C++ or C source file. The purpose of C Within is to help you find bugs resulting from complicated uses of the C/C++ preprocessor.

C Within lets you see how preprocessor macros are expanded, from the original source, through all the intermediate macro expansions, to the final preprocessed source. You can interactively expand or collapse each level of macro expansion, for each individual macro.

C Within also lets you step into #include files. Dead code (resulting from inactive #if branches) is lowlighted. Together, these allow you to easily see the flow of preprocessing.

Note: Thinkage Ltd. has obtained U.S. patent #5,946,488 for the processing algorithms that allow C Within to expand and unexpand preprocessor directives.

Other Topics

General Concepts of C Within

Phases of Operation

C Within first runs an enhanced C/C++ preprocessor on your text file. If this phase is successful, you can then interactively browse through the file, inspecting particular macro expansions and #include files.

The browser presents you with a split window. The top window contains any diagnostic messages generated by the preprocessing phase. This will include any warnings about suspicious or non-portable preprocessing actions. It will also include any errors encountered during preprocessing, such as the inability to find particular #include files.

If no preprocessing errors occur, the bottom right window presents an interactive view of your source. You can increase your viewing area by dragging the dividing bar to minimize the preprocessor report window.

The bottom left window is a tree view of the #include structure of your text. You can use this to jump directly to a particular instance of an #included source text, without having to search for all the relevant #include statements in the parent texts.

Configuration Files

Since the input file for C Within is first passed through a C/C++ preprocessor, you will usually want to specify things such as the #include search orders and additional macro definitions (such as would appear on compiler command lines, rather than in the source files). You can also tell the browser whether you are using C or C++. This affects how C Within treats constructs like // comments and tokens that are only supported by C++.

You specify these things via a typical Windows dialogue. Since you will frequently want to use the same settings, you can save them in a configuration file and reload them later.

Browsing

After a successful preprocessing, the bottom right window will display an interactive view of your input file. Elements are color-coded to make them easier to identify. Colors can be changed by using the View menu, but the default colors are as follows:

Dead code
Dead code is text that will not be compiled because of #if directives. By default, dead code is shown in light gray (although the View menu offers an option that can make dead code disappear entirely).
#include line
An #include line contains an #include directive. Such lines are displayed in red (unless they are in dead code).
Macro identifier
A macro identifier is a macro name that would be expanded if the code is compiled. It is shown with a blue or green background.
Expansion text
Expansion text is text that is the result of macro expansion. Its background color is:

Along the left edge of the view of the input file, you will see a red arrow referred to as the marker. The status bar will show the file and line number of the marker. You can change the location of the marker by left clicking along the left edge of the view.

Right-clicking any text displays a context menu specifying the operations that can be performed on that text. The following operations may be available on the context menu (depending on the text being clicked):

Expand
Expands a macro into its expanded text. This action is only available when the text is an expandable macro identifier.
Unexpand
Collapses the expansion of a macro back into the original macro expression (the macro identifier and its arguments). This action is only available when the text is a macro expansion.
Goto Definition
Goes to the #define directive that defined a particular macro. This action is only available when the text is a macro identifier. If the #define directive was given in another file, C Within goes to that file. The #define directive is highlighted with an arrow to make it easier to identify on the screen.
Expand Line
Fully expands all macros on the line.
Unexpand Line
Fully collapses all macros on the line.
Expand to Marker
Performs Expand Line on all lines from the marker to the mouse pointer.
Unexpand to Marker
Performs Unexpand Line on all lines from the marker to the mouse pointer.
Open Include
Opens an #included file for browsing. This action is only available when the text is an #include directive.
Previous Marker
Returns to the previous file and position within that file (if any). This action is available anywhere, provided that you have looked at a file previously in this session.
Copy to Clipboard
Copies all lines from the marker to the current mouse position, and places the text in the Windows clipboard. The lines are copied as text, using the currently presented level of macro expansion.

Instead of selecting these actions from the context menu, you can get the same effect from mouse shortcuts.

Note that actions involving the middle button are only available if you have a three-button mouse. Also note that on Windows 95, the default meaning of the middle button is a double-click of the left button. To use the middle mouse button as described above, you must use the Windows 95 control panel to prevent Windows 95 from changing a middle-click to a left double-click; you can do this by making a middle-click "undefined". (This tells Windows 95 not to convert a middle-click into something else.)

The File Menu

This menu lets you select which files to view.

Open
Selects a file to view via a standard Windows file open dialogue. You can only select one file at a time.
Reopen
Reopens the currently viewed file. This is needed if the file has been modified during your viewing session.
Most recently used files
Opens a previously viewed file. Warning: this does not load the configuration that was in effect at the time that file was viewed; it uses the configuration that is currently set.
Exit
Terminates C Within.

The Configuration Menu

This menu lets you specify the preprocessing parameters.

Set
Presents a dialogue to set #defines, #include search paths, and the recognition of constructs that are by C++ but not C. The macro body of a define follows the macro identifier, as it does in a #define.
Load
Loads a previously created configuration. This file becomes the current configuration file.
Load From Project
Loads configuration parameters from an IDE project file. Currently, only Microsoft Developer Studio 5.0 projects are supported. The parameters are loaded as for the first source file of the first target in the project file.
Save
Saves the current configuration into the current configuration file.
Save As
Saves the current configuration into a new file. This file becomes the current configuration file.

The View Menu

This menu lets you control the appearance of the browsing view.

Status Bar
Shows or hides the status bar. The status bar shows the name of the file being viewed, as well as some brief usage comments.
Set Tab Stops
Sets the number of characters between tab stop positions.
Set Font
Sets the font used to view the preprocessed input file.
Set Color
Set the colors used to present the preprocessed input file.
Show Dead Code
Dead code is code that will not be compiled because of #if and similar constructions. If the Show Dead Code option is turned on, C Within displays such code in light gray. If Show Dead Code is turned off, dead code will not be shown at all; C Within only shows the code that will actually be compiled.
Find Marker
Moves the view so that it includes the marker. The marker will be at the top of the view, except near the end of the subfile.
Search
Searches for text in the current subfile. The search runs forward from the marker until it finds a match. At the end of the file, the search wraps around to the beginning of the file; if no match is found, it stops at the original marker position. The text searched is only the text that is currently seen—it does not search into unexpanded macros.

The following characters have special meanings in the search patterns:

^
matches start of line
$
matches end of line
.
matches any character
*
matches zero or more of the previous character or closure
+
matches one or more of the previous character or closure
?
matches zero or one of the previous character or closure
[
starts a character closure (as in [abc])
]
ends a character closure
^
can be used as the first character in a closure to indicate all characters not in the closure; [^AB] means all characters except A or B
Reverse Search
Same as Search, but searches in the opposite direction.
Goto Line
Moves the marker to the next occurrence of the given line number in the current subfile. The search starts from the current marker and wraps around at the end of the file, stopping at the original marker position if no match is found. (Note that there may be several lines with the same number because of #line directives.)

The Help Menu

This menu presents information about C Within.

Help Topics
Shows documentation on the use of C Within.
About C Within
Shows copyright notice and contact information for Thinkage Ltd.

Command Line Parameters

The general command line format is:

cwithin options file

This opens the given file for browsing.

Possible options are:

/Define:macro
Defines a macro, as if a #define directive was inserted at the beginning of the text to be preprocessed. The syntax of the definition is the same as in a normal #define directive with the word #define omitted. If there are spaces in the macro definition, the whole string should be enclosed in quotes. For example, /Define:"MYMACRO 3" has the same effect as 
#define MYMACRO 3
/user_Include:directory
Adds the given directory to the search path for #include directives.
/System_include:directory
Adds the given directory to the search path for #include directives. This only affects #include directives that enclose the filename in angle brackets (for example, #include <file.h>).
/Project:projfile
Opens an IDE project file specified by the projfile pathname. C Within tries to determine what kind of project file it is, then reads the file to determine which macros should be predefined and what #include search paths should be used. The project file is opened in a manner similar to the Load from Project operation on the Configuration menu. This option may only be specified once on the command line.
/C-
Tells the preprocessor not to run in C++ mode. In other words, you are looking at C code rather than C++. C Within will not recognize C++ comments or other special constructs. You may only specify this option once on the command line.
/C+
Explicitly tells the preprocessor to run in C++ mode. This is only necessary if you want to override settings in a project file that say the source code is C only (not C++). You may only specify this option once on the command line.
/HELP
Displays a message box showing the syntax of the C Within command line. If you specify this option, C Within does not attempt to do any preprocessing or show any processed output.
Note: The documentation included with C Within talks about options C+++ and C++-. These have been changed to C+ and C-. To use these options, you must download the patched version of C Within, as discussed on the C Within download page.

Keywords in the above options can be abbreviated by omitting any underscores and/or letters shown in lower case. For example, /Project may be abbreviated as /proj, /pj, /p and so on. Keywords may also be typed in upper case, lower case, or mixed case.

Installing C Within as a Microsoft Developer Studio Tool

If you use Microsoft Developer Studio 5.0, you will want to install C Within as a tool that is known to the studio. This will make it easier for you to invoke C Within on the source files of your programming projects.

  1. From the Tools menu, select the Customize item, then select the Tools property page.
  2. In the Menu box, select the Open entry and set the tool name (for example, C Within).
  3. In the Command box, set the pathname of C Within (wherever you installed it).
  4. In the Arguments box, insert the following: 
    "/project:$(WkspDir)\$(WkspName).dsp" "$(FilePath)"
  5. In the Initial directory box, insert $(FileDir).

To launch the browser, first open a file for editing in the Developer Studio. With that editing window selected, bring up the Tools menu and select the C Within item (or whatever name you entered in Step 2 above).

Registering C Within

To register your copy, please fill out the registration form in the file register.txt (found in the same folder where you installed C Within). The file provides complete information on how to register the software with Thinkage. In return, Thinkage will supply a registration number that you can use to register your copy of the software.

Once you have received a registration number from Thinkage, start C Within and select the Register item of the File menu. Type your registration number into the input boxes, and your copy of C Within will be registered.