About:

Batch Compiler Specification (BCS) files are simple element orientated text files that are used to specify the batches, stages and options that can be used. They construct the objects on Batch Compiler's main form and specify the layout of the batch file Batch Compiler produces. In short, the define almost everything you see in Batch Compiler.

• Batch Element
• Stage Element
• Control Elements
  • LabelBox
  • Space
  • Option Elements
    • CheckBox
    • TextBox
    • ComboBox
    • FileBox
    • FolderBox
    • ColorBox
    • Shared Options
• Directives
  • Define Directive
  • Include Directive
  • Once Directive
• Naming Conventions
• Comment Syntax
• Error Messages

The Batch Element:

Specification files are made up of two main sections, a Batch section that specifies the batch files Batch Compiler produces, and Stage section that specifies the stages these batch files use. There is no set order in which they must appear, but general place the Batch sections at the top of the specification file (as a convention). The following is the main Batch section from the "Zoners Tools" specification file that comes with Batch Compiler:

This is a good example of a batch section because it shows all the various aspects of Batch Compiler's elements and attributes. The general format for all of the various elements and attributes in a specification file is as follows:

All attribute values, wheather they are numeric or strings, are written in quotes. If an attribute's value is long you can split it into two or more strings by placing a underscore ("_") charactor in between each string as showen above. Attributes can also contain escape sequences to represent characters you can't easily type. These escape sequences are modeled after the C language escape sequences and are as follows:

Escape Sequence	Character
\t	Tab
\n	New Line
\\	Backslash
\"	Quote

The quote escape sequence can be very usefull for adding quotes to your attribute's value without confusing the parser. For example the string Ryan "The Yellow Dart" Gregg would be written as "Ryan \"The Yellow Dart\" Gregg".

The various attributes that the Batch element can take are as follows:

Attribute	Type	Default	Value
Filter	String	All Files (*.*)|*.*	The file filter to use when browsing for files on the main form in the standard windows format.
Links	List	N/A	A list of web site links associated with the batch. The format is "Link1 Name,Link1 URL|Link2 Name,Link2 URL".
LogFile	String	N/A	The template for the log file path.
Name	ID	N/A	The name of the batch. Must be unique.
Priority	Integer	0	The priority of the batch. The batch with the highest priority will be the batch that Batch Compiler loads.
ShellExecute	Boolean	False	If true, the batch will be run through the shell and not a batch file. The batch must be no longer than one line and only one command if this is true.
Stages	List	N/A	A list of all the stages the batch uses in the order they will be run (and appear in Batch Compiler).
Template	String	N/A	The template for the batch.

The Template attribute of the Batch element is simply a batch script mixed in with variables.

Variables:

Batch Compiler defines the following variables that can be used anywhere in your Template:

Variable	Value
${Date}	The current date in short format.
${FileExt}	The input file's extension. For example, the extension of C:\test.map would be map.
${FileName}	The input file's Name. For example, the name of C:\test.map would be test.
${FilePath}	The input file's Path. For example, the path of C:\test.map would be C:\.
${InputPath}	The input path (as set in the options form.)
${LogViewerPath}	The full path to the log viewer (as set in the options form).
${OutputPath}	The output path (as set in the options form.)
${StageCmd=XXX}	The command list of a stage generated by Batch Compiler where XXX is the stage you want the command list for.
${StageParam=XXX}	The parameter list of a stage generated by Batch Compiler where XXX is the stage you want the parameter list for.
${StagePath=XXX}	The full path of a stage where XXX is the stage you want the full path for.
${StageTitle=XXX}	The ftitle of a stage where XXX is the stage you want the title for.
${Time}	The current time in short format.
${Version}	The version of Batch Compiler you are using.

It should be noted that when StagePath or StageParam occurs on a line, that line will not be part of the batch if the stage is a program and it is not checked to run in Batch Compiler.

The Stage Element:

The Stage element is used to specify the programs that are used to make up a Batch. Each Stage makes up a tab in Batch Compiler. Here is a sample Stage:

This example illustrates how the Stage element is made up of other elements such as ComboBoxes and TextBoxes. The various attributes that the Stage element can take are as follows:

Attribute	Type	Default	Value
Filter	String	Applications (*.exe)|*.exe	The file filter to use when browsing for the stage's program in the standard windows format.
Groups	List	N/A	The list of all the element groups in the sage. You must list these if you wish to access individual element groups.
Name	ID	N/A	The name of the stage. Must be unique.
Title	String	N/A	The title of the stage.
Type	Enumeration	Program	The type of stage the stage is. Options are Program, ParameterList and CommandList.

Control Elements:

The Stage element is also made up of additional control elements which are used to define the objects on the tab and the parameters of the program. Batch Compiler defines for the following control elements: LabelBox, Space, CheckBox, TextBox, ComboBox, FileBox, FolderBox and the ColorBox control element.

These control elements are placed on the tabs in a grid like manor. Each tab is divided into 11x3 (33) grid boxes, each of which a control element can be added to. The position of the control elements is determined automatically by the order of their creation, starting from the top left then making their way down each column until it is full.

The LabelBox:

The LabelBox is a simple control element that is used to provide headings for other control elements. An example LabelBox element is as follows:

The attributes that the LabelBox element defines are as follows:

Attribute	Type	Default	Value
Bold	Boolean	False	The element's bold state.
Name	ID	N/A	The name of the element.
Size	Integer	1	The width of the element in grid blocks.

The Space:

The Space is a simple control element that is used to provide vitrical spacing between control elements. An example Space element is as follows:

The attributes that the Space element defines are as follows:

Attribute	Type	Default	Value
Size	Integer	1	The height of the element in grid blocks.

When Batch Compiler encounters a Space element it simply moves ahead the specified number of spaces (grid blocks) as if a sub class had been placed there. It is important to note that if you use a 'Width' value greater then 1 for any of the sub classes, you'll need to use the 'Spaces' field to prevent other sub classes from being placed on top of the wide sub class by jumping over any additional grid blocks it takes up.

Option Elements:

Option elements are used to define parameters and batch commands for use in your Batch. If your Stage is of type Program or ParameterList the option created will be in the format parameter value. If your Stage is of type CommandList the option created will be in the format parameter\n.

All option elements allow you to create variable switches by using any of the following variables as part of their parameter:

Variable	Value
${Date}	The current date in short format.
${FileExt}	The input file's extension. For example, the extension of C:\test.map would be map.
${FileName}	The input file's Name. For example, the name of C:\test.map would be test.
${FilePath}	The input file's Path. For example, the path of C:\test.map would be C:\.
${InputPath}	The input path (as set in the options form.)
${LogViewerPath}	The full path to the log viewer (as set in the options form).
${OutputPath}	The output path (as set in the options form.)
${Time}	The current time in short format.
${Version}	The version of Batch Compiler you are using.

Options that are part of a Stage of type CommandList (excluding CheckBox's) can use the following additional variables:

Variable	Value
${Value}	The value of the option.

The bellow example uses variables to delete an intermittent file. The parameter looks as follows:

The CheckBox:

The CheckBox is a common control element that defines a single valueless switch. An example CheckBox element is as follows:

The attributes that the CheckBox element defines are as follows:

Attribute	Type	Default	Value
Bold	Boolean	False	The element's bold state.
Checked	Boolean	False	The element's checked state. If true the element will be checked by default.
Group	String	N/A	The group the element belongs to.
Hint	String	N/A	The hint that is displayed when you hover your mouse over the element.
Index	Integer	N/A	The index of the element in the parameter list.
Name	ID	N/A	The name of the element.
Param	String	N/A	The switch to use for the element.
Size	Integer	1	The width of the element in grid blocks.
Stages	List	N/A	A list of stages that share the element.

The TextBox:

The TextBox is a common control element that defines a single switch with a value. An example TextBox element is as follows:

The attributes that the TextBox element defines are as follows:

Attribute	Type	Default	Value
Bold	Boolean	False	The element's bold state.
Checked	Boolean	False	The element's checked state. If true the element will be checked by default.
Default	String	N/A	The default value for the element.
Group	String	N/A	The group the element belongs to.
Hint	String	N/A	The hint that is displayed when you hover your mouse over the element.
Index	Integer	N/A	The index of the element in the parameter list.
Max	Variable	N/A	If the element is a numeric type, the maximum value it can take.
Min	Variable	N/A	If the element is a numeric type, the minimum value it can take.
Name	ID	N/A	The name of the element.
Param	String	N/A	The switch to use for the element.
Quote	Boolean	True	The element's quote state. If true values with white space in them will be surounded in quotes.
Size	Integer	1	The width of the element in grid blocks.
Stages	List	N/A	A list of stages that share the element.
Type	Enumeration	String	The type of value the element can take. Options are String, Integer and Single.

The ComboBox:

The ComboBox is a common control element that defines a single switch with multipule fixed values. An example ComboBox element is as follows:

The attributes that the ComboBox element defines are as follows:

Attribute	Type	Default	Value
Bold	Boolean	False	The element's bold state.
Checked	Boolean	False	The element's checked state. If true the element will be checked by default.
Default	String	N/A	The name of the default option for the element.
Group	String	N/A	The group the element belongs to.
Hint	String	N/A	The hint that is displayed when you hover your mouse over the element.
Index	Integer	N/A	The index of the element in the parameter list.
Name	ID	N/A	The name of the element.
Options	List	N/A	A list of options that the element can take. The format is "Option1 Name,Option1 Value|Option2 Name,Option2 Value".
Param	String	N/A	The switch to use for the element.
Quote	Boolean	True	The element's quote state. If true values with white space in them will be surounded in quotes.
Size	Integer	1	The width of the element in grid blocks.
Stages	List	N/A	A list of stages that share the element.

The ComboBox can also be a useful element for switching between multiple valueless switches. For example, you can only start Half-Life in fullscreen or windowed mode, so if you wanted to switch between the two you would do the following:

The FileBox:

The FileBox is a control element that defines a single switch that takes a file as a value. An example FileBox element is as follows:

The attributes that the FileBox element defines are as follows:

Attribute	Type	Default	Value
Bold	Boolean	False	The element's bold state.
Checked	Boolean	False	The element's checked state. If true the element will be checked by default.
Default	String	N/A	The default file name.
Filter	String	All Files (*.*)|*.*	The file filter to use when browsing for files in the standard windows format.
FullPath	Boolean	True	The element's full path state. If true the path and file name of the file will be used, if false only the file name will be used.
Group	String	N/A	The group the element belongs to.
Hint	String	N/A	The hint that is displayed when you hover your mouse over the element.
Index	Integer	N/A	The index of the element in the parameter list.
Name	ID	N/A	The name of the element.
Param	String	N/A	The switch to use for the element.
Quote	Boolean	True	The element's quote state. If true values with white space in them will be surounded in quotes.
Size	Integer	1	The width of the element in grid blocks.
Stages	List	N/A	A list of stages that share the element.

The FolderBox:

The FolderBox is a control element that defines a single switch that takes a folder as a value. An example FolderBox element is as follows:

The attributes that the FolderBox element defines are as follows:

Attribute	Type	Default	Value
Bold	Boolean	False	The element's bold state.
Checked	Boolean	False	The element's checked state. If true the element will be checked by default.
Group	String	N/A	The group the element belongs to.
Hint	String	N/A	The hint that is displayed when you hover your mouse over the element.
Index	Integer	N/A	The index of the element in the parameter list.
Name	ID	N/A	The name of the element.
Param	String	N/A	The switch to use for the element.
Quote	Boolean	True	The element's quote state. If true values with white space in them will be surounded in quotes.
Size	Integer	1	The width of the element in grid blocks.
Stages	List	N/A	A list of stages that share the element.

The ColorBox:

The ColorBox is a control element that defines a single switch that takes a color as a value. An example ColorBox element is as follows:

The attributes that the ColorBox element defines are as follows:

Attribute	Type	Default	Value
Bold	Boolean	False	The element's bold state.
Checked	Boolean	False	The element's checked state. If true the element will be checked by default.
Default	Color	0 0 0	The default color in R G B mode. The color can be defined as a Integer or a Single.
Group	String	N/A	The group the element belongs to.
Hint	String	N/A	The hint that is displayed when you hover your mouse over the element.
Index	Integer	N/A	The index of the element in the parameter list.
Name	ID	N/A	The name of the element.
Param	String	N/A	The switch to use for the element.
Quote	Boolean	False	The element's quote state. If true values with white space in them will be surounded in quotes.
Size	Integer	1	The width of the element in grid blocks.
Stages	List	N/A	A list of stages that share the element.
Type	Enumeration	String	The type of value the color is defined with. Options are Integer and Single. Integer values range from 0 to 255 and Single values range from 0.0 to 1.0.

Shared Options:

In some cases you have an option element that you want to include in multiple Stages. These are called shared options. (An example of one of these would be the -texdata option in Zoners Tools, you want this to be added to all Stages). This can be done with any option element through the use of the Stages attribute. In the Stages attribute list all the Stages that you want the option element to be used with. An example shared option is as follows:

Note that shared options only appear in the Stage you create them in, but their options are added to the parameter list of all the Program and ParameterList Stages they are shared with.

Directives:

Directives are special commands that tell the parser how to parse the specification file. The three directives available are Define, Include and Once.

Define Directive:

The Define directive allows you to define custom variables that can be used anywhere you can use the variables that the Define is composed of. An example of the Define directive is as follows:

This defines a new variable, ${DateTime}, that you can use anywhere in place of ${Date} ${Time}. This also defines a new variable, ${Author}, which you can use any where in place of Ryan "Nemesis" Gregg. For example: echo ${Author}.

Include Directive:

The Include directive allows you to include Batches and Stages defined in another specification file in the current specification file. When you include a specification file it is parsed separately from the specification file you included it from. This means the specification file you include must be a complete standalone specification file. You cannot include a specification file from within a Batch or Stage element. An example of the Include directive is as follows:

Once Directive:

If you Include a specification file more than once you will run into errors because you will be declaring the elements in that specification file more than once. As a work around you can use the Once directive to indicate that the specification file is only to be parsed once. The Once directive should only be used at the top of a specification file. An example of the Once directive is as follows:

Naming Conventions:

As a convention, specification files that you wish to use with the Include directive but don't wish to allow users to use as standalone specifications should be given the .bci (Batch Compiler Include File) extension. Files that you wish to allow users to use as standalone specifications should be given the .bcs (Batch Compiler Specification File) extension.

Comment Syntax:

Comments can be added anywhere in specification files. Batch Compiler uses the standard C++ style comment syntax to allow for both line and block comments. An example of correct line comment syntax is as follows:

An example of correct block comment syntax is as follows:

Error Messages:

When Batch Compiler encounters an error parsing a specification file it outputs an error message in the format Error (line): message. The line number Batch Compiler reports isn't necessarily the line that the error occurred on, it is the line Batch Compiler is on when it determines that there is an error. This will typically be the line of the error or the line after the error but it could potentially be any line after the error. If Batch Compiler encounters an error within an include file Batch Compiler will stack the error messages with the lowest level include file on the bottom of the stack. Below is an example error message:

In the above error message we can see that on or below line 18 of the specification file we are loading there was an error parsing the include file Zoners Tools P Series.bci. We can also see that on or below line 118 of the include file Batch Compiler encountered an attribute that did not belong to an element. This attribute is most likely a misspelled Hint attribute.

Opening a Specification File in Batch Compiler:

When Batch Compiler starts up it automatically searches the Batch Compiler\Specifications directory for .bcs files to add to the Specifications menu. Because of this, all you have to do is save your new .bcs file to your Batch Compiler\Specifications directory, then once Batch Compiler has started, select it form the Specifications menu.

Batch Compiler Preset Files:

When Batch Compiler saves a preset (.bcp) file it dynamically builds a XML database off of your specification file's format. This allows Batch Compiler to load presets saved by any specification file even if the specification file has been altered since you last saved the preset.

Conclusion:

That pretty much concludes the Batch Compiler Specification file format. Hopefully now you will be able to customize your specification files to your liking or create additional specification files for other tools. Just one word of caution before you go editing specification files; when you do so, please save them under a different name, this will save you from possibly loosing them if you ever choose to download an update to Batch Compiler and it overwrites the changes you made to your specification files.

i have made a spec file that among others applications supports steam, but i am having a problem as steam requires the -applaunch tag to be the first that it gets, i would like to make it a ComboBox but thees are add after all the CheckBox commands have been added so the only work around i have found is making every game mode a CheckBox but thet files up a line just consisting of games when you can only select one any way. could you either change it so that it adds the commands based on the order in the bcs instead, or you could just make it add ComboBox before CheckBox tho this would cause a problem if the opposed satiation accrued.

another thing that would be nice to have would be if you could make the selection of a stage or option wold force select/deselected a notes stage or option.

other then that this tool has made me very

I am aware of this problem, it is an issue with how Batch Compiler is coded and there is no easy fix. BC v2.0.0 has been around for quite some time and it has become apparent to me that a rewrite (BC v3.0.0) is necessary.

When I first released Batch Compiler your only options as far as compiling was concerned was Q Tools or Zoners Tools. Now there are so many different utilities and versions of these tools that defining them all in one BCS file is no longer particle and is a pain to maintain, modularization is required. There are also other smaller issues like the one you have observed.

The next version of BC will has a very similar GUI but will be far more refined from a coding and specification writing and maintenance viewpoint.