Quick documentation (probably out of date - see options.h)

$Id: configuration.txt 497 2006-09-09 14:13:13Z bengardner $

There are three type of arguments:
	- boolean (true/false)
	- numeric
	- ignore/add/remove/force

"Ignore" means do not change it.
"Add" in the context of spaces means make sure there is at least 1.
"Add" elsewhere means make sure one is present.
"Remove" mean remove the space/brace/newline/etc.
"Force" in the context of spaces means ensure that there is exactly 1.
"Force" in other contexts means the same as "add".

Configuration items may reference previously defined configuration items.
Numeric items may be prefixed with a '-' to invert the number.
Boolean items may be prefixed with a '-' or '~' to invert the value.
For example, the following is valid:
  output_tab_size = 4
  indent_columns  = output_tab_size


All items default to false/0/ignore except:
	- input_tab_size = 8
	- output_tab_size = 8
	- indent_columns = 8
	- indent_with_tabs = 1
	- indent_label = 1

	Refer to set_arg_defaults()

Terminology:
	There are three types of parenthesis: sparen, fparen, paren.
	sparen are found with if/for/switch/while statements.
	fparen are found with function prototypes, calls and implementations.
	paren are everything else, such as those found with arithmetic ops.
	
	A 'span' is the maximum number of lines that a aligning feature will be
	considered.  This is done to limit the scope of the aligning.

	A 'gap' is the minimum spacing for aligned items.

	A 'threshold' is the maximum number of columns that a aligning feature
	will be considered.  This is done to limit the scope of the aligning.


Here's a list of all the options from options.h and a brief description.


   newlines:			AUTO/LF/CRLF/CR
	Sets the line endings for the output file

   input_tab_size:		number
	The original tab space value.
	Used to determine what was already aligned. (TODO)

   output_tab_size:		number
	Size of tabs in the output.
	Only important if indent_with_tabs=2.

   indent_columns:		number
	The number of columns to indent.
	Usually 2, 3, 4, or 8.

   indent_with_tabs:		number
	How to use tabs when indenting code.
	 0 = Use spaces only
	 1 = Use tabs to the brace-level indent (very portable)
	 2 = Use tabs whenever possible

   indent_paren_nl:		bool
	If an open paren is followed by a newline, indent the next line
	so that it lines up after the open paren.
	Not recommended.

   indent_square_nl:		bool
	If an open square is followed by a newline, indent the next line
	so that it lines up after the open square.
	Not recommended.

   indent_member:		number
	If the previous line ends with of the current line begins with
	'.' or '->', the line should be indent this number of column.
	Recommend setting to indent_columns:
	indent_member = indent_columns

   pp_space:			IARF
	Changes the space between # and, say, define.
	One space per #if level.

   pp_indent:			IARF
	Changes the indent of preprocessors.
	One space per #if level.

   indent_switch_case:		number		* REVISIT: make TRUE/FALSE? *
	Spaces to indent case from switch (usually 0 or indent_columns).

	If set to 0 (the default):
	switch (a) {
	case 34:


	If set to 3:
	switch (a) {
	   case 34:

   indent_case_body:		number
	Spaces to indent case body from case (usually 0).

	If set to 0 (the default) and indent_columns = 3:
	case 34:
	   break;

	If set to -indent_columns:
	case 34:
	break;

   indent_case_brace:		number
	Spaces to indent '{' from case.

	Default (0, assuming indent_columns is 3):
	switch (a) {
	   case 34:
	      {
	         break;
	      }

	If set to -indent_columns:
	switch (a) {
	   case 34:
	      {
	      break;
	      }

   indent_brace:		number
	Spaces to indent '{' from level (usually 0). For GNU style, set to 2.

	Default 0
	if (x)
	{
	}

	If set to 2
	if (x)
	  {
	  }

   indent_braces:		bool
	Whether braces are indented to the body level or not.

	Default false, indent_columns=3
	if (x)
	{
	   a--;
	}

	If set to true and indent_columns=3
	if (x)
	   {
	   a--;
	   }

   indent_class:		bool
	Whether the class body is indented.

	Default false:
	class foo
	{
	int bar();
	}

	If set to true and indent_columns=3
	class foo
	{
	   int bar();
	}

   indent_namespace:		bool
	Whether the namespace body is indented.
	
	Default false:
	namespace foo
	{
	int bar();
	}

	If set to true and indent_columns=3
	namespace foo
	{
	   int bar();
	}

   indent_label:		number
	How to indent goto labels.
	> 0 : Absolute column (1=leftmost column)
	<= 0  : Subtract from brace indent

	Default (1):
	{
	   a++;
mylabel:
	   foo();
	}

	Set to -indent_columns:
	{
	   a++;
	mylabel:
	   foo();
	}

   indent_align_string:		bool
	Whether to indent broken strings so that they line up.
	
	Example:
	fprintf(stderr, "Some really long explination "
	                "that is broken in two");
		vs
	fprintf(stderr, "Some really long explination "
	        "that is broken in two");

   indent_col1_comment:		bool
	Whether to indent comments found in column 1.

   indent_func_call_param:	bool
	If true, indent continued function call parameters one indent level.
	
	If set to false (default), it aligns instead of indents:
	thisisareallylongfunctionname(param1,
	                              param2, param3, param4);

	If set to true, it indents one level:
	thisisareallylongfunctionname(param1,
	    param2, param3, param4);

   indent_class_colon:		bool
	If true, indents the stuff after a leading class colon.
	
	Example if true:
	Foo::Foo(int a)
	   : myA(a),
	     var2(-a)
	
	Example if false (default):
	Foo::Foo(int a)
	   : myA(a),
	   var2(-a)

#
#  Spacing Options
#

   sp_paren_brace:		IARF
	Space between ')' and '{'
	Example: "if (a){" vs "if (a) {"

   sp_after_cast:		IARF
	Space after cast - "(int) a" vs "(int)a"

   sp_before_byref:		IARF
	Space before & in function definition param:
	'foo( int& count )' vs 'foo( int & count )'

   sp_inside_fparen:		IARF
	Space inside 'foo( xxx )' vs 'foo(xxx)'

   sp_inside_fparens:		IARF
	Space inside 'foo( )' vs 'foo()'

   sp_inside_paren:		IARF
	space inside '+ ( xxx )' vs '+ (xxx)'

   sp_inside_square:		IARF
	space inside 'byte[ 5 ]' vs 'byte[5]'

   sp_inside_sparen:		IARF
	Space inside 'if( xxx )' vs 'if(xxx)'

   sp_inside_angle:		IARF
	Space inside '<>'
	'<class T>' vs '< class T >'

   sp_before_sparen:		IARF
	Space before '(' of 'if/for/while/switch'.
	Example: "if (" vs "if("

   sp_after_sparen:		IARF
	Space after  ')' of 'if/for/while/switch'
	Example "if (a) a--;" vs "if (a)a--;"

   sp_before_angle:		IARF
	Space before '<>'
	'Foo<class T>' vs 'Foo <class T>'

   sp_after_angle:		IARF
	Space after '<>'
	'<class T>(' vs '<class T> ('

   sp_before_square:		IARF
	space before all '[', except '[]'

   sp_before_squares:		IARF
	space before '[]'

   sp_paren_paren:		IARF
	space between nested parens - '( (' vs '(('

   sp_return_paren:		IARF
	space between 'return' and '('

   sp_sizeof_paren:		IARF
	space between 'sizeof' and '('

   sp_after_comma:		IARF
	space after ','

   sp_arith:			IARF
	space around + - / * etc

   sp_bool:			IARF
	space around || &&

   sp_compare:			IARF
	space around < > ==, etc

   sp_assign:			IARF
	space around =, +=, etc

   sp_func_def_paren:		IARF
	space between 'func' and '(' - "foo (" vs "foo("

   sp_func_call_paren:		IARF
	space between 'func' and '(' - "foo (" vs "foo("

   sp_func_proto_paren:		IARF
	space between 'func' and '(' - "foo (" vs "foo("

   sp_type_func:		IARF
	Space between return type and 'func'
	A minimum of 1 is forced except for '*'

   sp_special_semi:		IARF
	Space empty stmt ';' on while, if, for
	example "while (*p++ = ' ') ;"

   sp_before_semi:		IARF
	Space before all ';'

   sp_inside_braces:		IARF
	Space inside '{' and '}' - "{ 1, 2, 3 }"

   sp_inside_braces_enum:	IARF
	Space inside enum '{' and '}' - "{ a, b, c }"

   sp_inside_braces_struct:	IARF
	Space inside struct/union '{' and '}'

   sp_fparen_brace:		IARF
	Space between function close paren and open brace

   sp_macro:			IARF
	Space between macro and value.
	REMOVE is the same as FORCE
	#define MACRO   value
	             ^^^
   sp_marco_func:		IARF
	Space between macro function close paren and value.
	REMOVE is the same as FORCE
	#define MACRO_FUNC(x)   ((x) * 3)
	                     ^^^

   sp_after_tag:		IARF
	PAWN only.  Control the space after the tag colon.


#
#  Code alignment (not left column spaces/tabs)
#

   align_with_tabs:		bool
	Use tabs for aligning.
	Doesn't work quite right, yet.

   align_keep_tabs:		bool
	Keep non-indenting tabs.
	Useful to minimize changes if not aligning anything.

   align_on_tabstop:		bool
	When aligning, bump out to the next tabstop.

   align_nl_cont:		bool
	Align the back-slash \n combo (macros)

   align_enum_equ_span:		number
	 The span for aligning on '=' in enums. 0=don't align

   align_enum_equ_thresh:	number
	 The threshold for aligning on '=' in enums. 0=no limit

   align_assign_span:		number
	 The span for aligning on '=' in assignments. 0=don't align

   align_assign_thresh:		number
	 The threshold for aligning on '=' in assignments. 0=no limit

   align_right_cmt_span:	number
	Span for aligning comments that end lines. 0=don't align

   align_var_def_span		number
	Span for aligning variable definitions

   align_var_def_inline:	bool
	Whether to align inline struct/enum/union var defs

   align_var_def_star:		bool
	Whether the star is part of the variable name or not.
	"int *   var;" vs "int    *var;"

   align_var_def_colon:		bool
	Align the colon in struct bit fields

   align_var_struct_span:	number
	Span for struct/union (0=don't align)

   align_pp_define_span:	number
	align bodies in #define statments

   align_pp_define_gap:		number
	Min space between define label and value "#define a <---> 16"

   align_struct_init_span:	number
	Align structure initializer values

   align_func_proto_span:	number
	Align function prototypes

   align_number_left:		bool		* a little buggy *
	left-align numbers

   align_typedef_span:		number
	align single-line typedefs

   align_typedef_gap:		number
	minimum spacing

   align_typedef_star_style:	number
	Start aligning style
	  0: '*' not part of type
	  1: '*' part of the type - no space
	  2: '*' part of type, dangling

	Example: 0
	typedef int *     PINT;
	typedef char **   PPCHAR;

	Example: 1
	typedef int       *PINT;
	typedef char      **PPCHAR;

	Example: 2
	typedef int      *PINT;
	typedef char    **PPCHAR;


#
#  Newline adding and removing options
#

   nl_fdef_brace:		IARF
	"int foo() {" vs "int foo()\n{"

   nl_func_decl_starts:		IARF
	Newline after '(' in a function decl

   nl_func_decl_args:		IARF
	Newline after each ',' in a function decl

   nl_func_decl_end:		IARF
	Newline before the ')' in a function decl

   nl_func_type_name:		IARF
	Newline between return type and func name in def

   nl_func_var_def_blk:		number
	Newline after a block of variable defs

   nl_before_case:		bool
	newline before 'case' statement

   nl_after_return:		bool
	newline after return statement

   nl_after_case:		bool
	Disallow nested "case 1: a=3;"

   nl_fcall_brace:		IARF
	newline between function call and open brace
	Seems pretty useless.

   nl_squeeze_ifdef:		bool
	No blanks after #ifxx, #elxx, or before #endif

   nl_enum_brace:		IARF
	nl between enum and brace

   nl_struct_brace:		IARF
	nl between struct and brace

   nl_union_brace:		IARF
	nl between union and brace

   nl_assign_brace:		IARF
	nl between = and {

   nl_do_brace:			IARF
	nl between do and {

   nl_if_brace:			IARF
	nl between if and {

   nl_for_brace:		IARF
	nl between for and {

   nl_else_brace:		IARF
	nl between else and {

   nl_while_brace:		IARF
	nl between while and {

   nl_switch_brace:		IARF
	nl between switch and {

   nl_brace_else:		IARF
	nl between } and else

   nl_brace_while:		IARF
	nl between } and while of do stmt

   nl_define_macro:		bool
	Alter newlines in #define macros

   nl_start_of_file:		IARF
	Add or remove newlines at the start of the file

   nl_start_of_file_min:	number
	Number of newlines at the start of the file.
	Only used if nl_start_of_file is Add or Force

   nl_end_of_file:		IARF
	Add or remove newlines at the end of the file

   nl_end_of_file_min:		number
	Number of newlines at the end of the file.
	Only used if nl_end_of_file is Add or Force

   nl_class_brace:		IARF
	nl between class and {

   nl_namespace_brace:		IARF
	nl between namespace and {

   nl_elseif_brace:		IARF
	nl between else if and {
	If set to ignore, nl_if_brace is used instead.

	else if (x) {
	  vs
	else if (x)
	{

   nl_class_init_args:		IARF
	Puts a newline after each comma in the constructor arg list.
	
	Foo::Foo(int a) : classA(a), classB(a)
	{
	  vs
	Foo::Foo(int a) :
	   classA(a),
	   classB(a)
	{

   nl_collapse_empty_body:	BOOL
	If true, changes { \n } into { }.

   code_width:			number
	Try to limit code to this number of columns by adding newlines
	
#
#  Positioning options
#

   pos_bool:			POS (NONE/NC, LEAD/START, TRAIL/END)
	TRAIL: boolean ops are at the end of the line
	NONE:  do not move boolean ops (default)
	LEAD:  boolean ops are at the start of the line
	
	Example: TRAIL changes this:
		if (something
		    && somethingelse)
	into:
		if (something &&
		    somethingelse)
	LEAD does the opposite.


   pos_class_colon:		POS (NONE/NC, LEAD/START, TRAIL/END)
	TRAIL: class colon appears on the same line as close paren
	NONE:  do not move (default)
	LEAD:  class colon appears on the line after the close paren
	
	Example: LEAD changes this:
		Foo:Foo(int a) :
		    sameVar(a)
	into:
		Foo:Foo(int a)
		    : sameVar(a)
	TRAIL does the opposite.


#
#  Blank line options
#  Note that it takes 2 newlines to get a blank line.
#

   nl_before_block_comment:	number
	Minimum number of newlines before a multi-line comment.
	Doesn't apply if after a brace open.

   nl_after_func_body:		number
	Newlines after the closing brace of a function body
	
   nl_after_func_proto:		number
	Newlines after a single function prototype.
	
   nl_after_func_proto_group:	number
	Newlines after a prototype, if not followed by another prototype.
	
   nl_max:			number
	The maximum consecutive newlines.

   eat_blanks_after_open_brace:	bool
	Remove blank lines after {
	
   eat_blanks_before_close_brace: bool
	Remove blank lines before }

#
#  code modifying options (non-whitespace)
#

   mod_paren_on_return:		IARF
	Add or remove unecessary paren on return.
	"return(0);" vs "return 0;"
	
   mod_full_brace_if:		IARF
	add or remove braces on single-statement if
	
   mod_full_brace_for:		IARF
	add or remove braces on single-statement for
	
   mod_full_brace_do:		IARF
	add or remove braces on single-statement do
	
   mod_full_brace_while:	IARF
	add or remove braces on single-statement while

   mod_full_brace_nl:		number
	don't remove braces around statements that span X newlines

   mod_pawn_semicolon:		bool
	If true, change optional semicolons to real semicolons.


#
#  Comment modifications
#

   cmt_star_cont:		bool
	Put a star on subsequent comment lines

   cmt_cpp_to_c:		bool
	Change CPP comments into C comments
	Example:
	// comment
	/* comment */

   cmt_cpp_group:		bool
	Whether to group CPP comments that look like they are in a block.
	cmt_star_cont, cmt_cpp_nl_start, and cmt_cpp_nl_end affect the
	way that comments are converted.

	Assuming all sub-options are true:
	Example: // line 1
	         // line 2
	         // line 3

	Becomes: /*
	          * line 1
	          * line 2
	          * line 3
	          */

   cmt_cpp_nl_start:		bool
	Put an empty /* on the first line of the combined CPP comments

   cmt_cpp_nl_end:		bool
	Put a newline before the closing */ of the combined CPP comments

