Polystyle Users Manual
0.0 Table Of Contents (Important sections are in bold)
(Note to Vista and Windows 7 users: You may need to install it somewhere other than program files, such as your user directory,
for it to work because of the permissions.)
1.0 About Polystyle
Polystyle is a source code formatter which learns your personal formatting style by examining examples of your code.
First, use a text editor to format your examples and define your style. You may then format your files by invoking Polystyle through Windows Explorer or your IDE.
Polystyle comes with several predefined styles as well as a GUI Configuration Tool to make Polystyle easy to set up.
1.1 What Polystyle Will And Will Not Do
Polystyle works by making the whitespace in your source files look the same as the whitespace in your example files. This is the idea to keep in mind when formatting your examples, Polystyle learns how you place padding between tokens and how many newlines you use in various areas. It then applies these rules to your source.
Since Polystyle only updates the whitespace in your source code, it will not alter the actual contents of your files such as adding {}'s in if statements or alphabetizing method declarations. At this time Polystyle will not alter comments although this may change with a future version.
After formatting, Polystyle performs very strict tests on the to make sure the original meaning of your source is preserved and that only the styling has changed.
Next important section: 2.1.2.0 Step 2: Set Global Preferences
2.0 Configuring Polystyle To Match Your Style
Configuring Polystyle takes two steps: formatting your example files and setting preferences in the Configuation Tool.
The example files are used to express the bulk of the information about your style.
The Configuration Tool is used to set things that can't be easily expressed in an example file, such as whether to
make backups or not.
2.1.0 Using The Configuration Tool And Formatting Files
The Configuration Tool contains several tabs which walk you through step by step the process
of configuring Polystyle and running Polystyle against source files.
2.1.1.0 Step 1: Define Your Examples
You example files contain most of the styling information Polystyle needs, such as how to format braced blocks and how many spaces to put around equal signs. The Configuration Tool offers three ways to define your example files to set up this aspect of your style.
2.1.1.1 Option 1: Edit Examples Directly
The first option allows you to edit each example file using Notepad. First select the language you want to restyle ion the dropdown, then click the push button. Notepad will pop up with the example file loaded.
2.1.1.2 Option 2: Select A Predefined Example For All Languages
This option allows you to overwrite all your current example files with a set of predefined examples that come with Polystyle. Select your indent length and the overall style type, then click the push button. Polystyle will select the correct directory, such as ${TRITA_HOME}\examples\other-predefined-styles\2-space-indent\KnR-1TBS-unix-kernel, and copy all the example files in that directory to your example directory.
2.1.1.3 Option 3: Browse Your Examples Directory
This option is similar to Option 1, but is designed to make it easier for you to edit your examples in your preferred text editor. Click the push button and an explorer window will pop up in your examples directory (${TRITA_HOME}\examples).
2.1.2.0 Step 2: Set Global Preferences
This tab allows you to define information that can't be easily expressed in an example file. Each option has a Help push button to give you context-sensitive directions on it use. When you've set your preferences, click the Save Changes push button to write your preferences to disk.
2.1.2.1 Indent Character
The indent character is used to indent text between the end of the last line and the first character on each line. Spaces are always used when spacing things out after the first token regardless of the Indent Character setting.
2.1.2.2 Tab Width
Affects Polystyle's interpretation of a tab character in an example file. The default is one tab equals 4 spaces.
2.1.2.3 Make Backups
When this is selected, Polystyle will make a backup of each file it formats named something like MyFile.java.polystyle.backup.
2.1.2.4 Newline Style
You may use this preference to force the formatted files into a certain newline format, or to detect and keep the original format. DOS newlines are \r\n, while UNIX newlines are \n.
2.1.2.5 Page Width
Polystyle will attempt to fit the source into the given page width. Note that this is not always possible, for example comments may be larger than the page width.
2.1.3.0 Step 3: Run Polystyle
Polystyle can be run from within Windows Explorer, the command line, or from inside your IDE.
2.1.3.1 Option 1: Run From Windows Explorer
After installing Polystyle using the setup program, when you right-click on files and directories in Windows Explorer a menu box will pop up. Select Format with Polystyle in the menu box to run Polystyle on those files.
2.1.3.2 Option 2: Run From The Command Line
This option in the Configuration Tool gives you detailed instructions how to set your system up to run Polystyle from the command line.
Usage:
polystyle [switches] fileOrDir1 fileOrDir2 ...
Switches:
-help Prints this message
-error-file <FILENAME> Redirects errors (STDERR) to FILENAME
-status-file <FILENAME> Redirects status messages (STDOUT) to FILENAME
-no-status-window Hide the status window. Be sure to specify
-status-file and -error-file or you won't get
any messages.
Files:
If you specify a directory to be formatted, Polystyle will recursively
format all the files in the tree and skip over CVS and .svn directories.
Example:
To run Polystyle as a command line app that does not pop up the status window:
polystyle -status-file status.txt -error-file err.txt -no-status-window x.java
2.1.3.3 Option 3: Run From Your IDE
Clicking the push button will launch Windows Explorer to view the Integrations page which contains instructions for integrating Polystyle into a number of IDEs.
2.1.4.0 (Optional) Step 0: Use Style Suite
Style suites allow you to easily maintain multiple sets of styling configurations.
For example, you can have a suite for your personal style and a suite for your company's corporate style.
A suite contains all the information the Configuration Tool lists in the 'Step 1: Define Your Examples' and
'Step 2: Set Global Preferences' tabs. ");
You can easily select which suite Polystyle uses with the 'Use Style Suite' dropdown on the Configuation Tool.
When you select a suite, the Configuation Tool will load that suite's data into the Configuation Tool's GUI.
This will also cause Polystyle to use that suite whenever you format a file.
2.1.4.1 Edit Suites
This window allows you to add, rename, and delete style suites.
2.1.4.2 Associate Suites With Specific Languages
Style suite associations allow you to cause Polystyle to use specific suites for certain languages regardless of
the current selected suite.
For example, you may want to have java code formatted differently when it is in a JSP than when it is in a
standalone file.
To do this, first define two suites. Edit the Java examples accordingly, then associate JSP with one suite
and Java with the other suite.
2.1.5 Register Polystyle
To purchase a registration key click here.
You will be emailed a key which you may copy and paste into the text box in the Register Polystyle window.
2.1.6 About Polystyle
|
