#-------------------------------------------------------------------------------
# Copyright (c) 2011 Martin Schwengerer.
# All rights reserved. This program and the accompanying materials
# are made available under the terms of the GNU Public License v3.0
# which accompanies this distribution, and is available at
# http://www.gnu.org/licenses/gpl.html
# 
# Contributors:
#     Martin Schwengerer - initial API and implementation
#-------------------------------------------------------------------------------
=============================================================================================
					User manual
=============================================================================================

*****************************************
Usage
*****************************************

Usage: AspModificator -configFile <file> [options] 
				  Possible Starting Arguments for AspModificator:
				  
				-i <file>	
				-input <file>	
				-inputFile <file>				file containing an asp-program which should be 
												the base program for the modifications
				-logging <logginglevel>			logging options - one of the following logging-levels:
						"all", "debug", "error", "fatal", 
						"info", "off", "trace", "warn"
				-noComments						disables writing comments in the modified programs
				-noCopies <number>				number of modified output-programs
				-outputDir <dir>				the directory where the modified programs should be saved
				-randomInit <number>			initialization-seed for the random-number generator


*****************************************
Config-File
*****************************************

The config-file is an XML-file containing general config-settings (optional) and 
the so called "modification rules". An example for a config-file is at the end of this file.

=========================================
NOTE: all attribute-values must be enclosed by ", otherwise the XML-file may not be read correct!!!!!
==========================================
=========================================
NOTE: configuration settings passed via command-line options always override configuration settings in the XML-file
==========================================


+++++++++++++++++++++++++++++++
General config settings
+++++++++++++++++++++++++++++++
The general configuration settings are specified inside the "configuration" tag. This 
"configuration"-element is optional (as the configuration-settings at all).
Inside the element, the following tags can be used:

Tag						Attributes					Description
-----------------------------------------------------------
"ruleApplication"		application				Defines how the modification rules should
												be applied. Possible values are "all" (=default)
												or "oneOfMany"
"writeComments"			value					"true" or "false" - Defines if AspModificator should write 
												comments about the modifications into the modifies program
"outputDirectory"		value					defines the directory where the modified programs should be
												saved, default is "."
"inputFile"				value					defines the file containing an asp-program which should be 
												the base program for the modifications
"randomInit"			value					initialization-seed for the random-number generator
"noCopies"				value					number of modified output-programs
"useMemory"				value					"true" or "false" - Defines if AspModificator should use a  
												memory to reduce the number of equal mutants. This only works
												when only one modification operator per mutant is used.


+++++++++++++++++++++++++++++++
Modification rules
+++++++++++++++++++++++++++++++
The modification rules are represented using the "modificationRules"-tag. This tag has three 
mandatory attributes: "type", "min" and "max". "type" specifies the type of the rule while 
"min" and "max" define the minimal and maximal application of the rule (if possible).
In addition, the optional attribute "name" can be used to give certain rules a name.

For example, 

  <modificationRules>
    <modificationRule name="rule1" type="swapTerms" min="1" max="1" />
    <modificationRule name="rule2" type="changeMathOperators" min="1" max="1" />
    <modificationRule name="rule3" type="deleteLiteral" min="1" max="1" />
  </modificationRules>

defines three rules.


Further, the attribute "targetLiterals" with the possible values {ALL, HEAD, BODY} can be used to specify
the potential effected literals of a rule. "HEAD" for example indicates that the rule is only targeting head literals.
Note that for some rules (e.g., introducing default negation), this attribute is fixed (ignored). 


At the moment, AspModificator supports the following rule types:

Type							Modification Rule
--------------------------------------------------------------------------
"deleteRule"					Deletes rules from the program
"deleteLiteral"					Deletes literals from rules. By default, only terms from the 
								body of a rule will be deleted. To disable this feature (and 
								include also head-literals to be deleted), use the additional 
								attribute "onlyBodyLiterals" which must be set to false 
								(onlyBodyLiterals="false"). This rule 
								may optional also delete terms from aggregates. To enable this
								feature, the additional attribute "includeInsideLiterals" must 
								be set to true (includeInsideLiterals="true").
"changeRangeTerms"				Modifies RangeTerms like e.g., a(1..5) to a(0..5)
"changeRelationOperators"		Modifies relation operators like >,<, !=
								The additional attribute "avoidNearlyInequalOperators" indicates
								if the possible exchange candidates of some operators should be limited
								(if the literal is !=, > or <, it should not be changed to one
								of those)
"swapTerms"						Swaps terms of predicates, e.g. a(X,Y) to a(Y,X)
"changeAggregats"				Modifies aggregates, e.g. "0 { enroll(C) : course(C,S,H) } 1" to 
								"1 { enroll(C) : course(C,S,H) } 1"
"changeMathOperators"			Modifies mathematical operators like +,-,/ by replacing them with 
								an other operator
"swapDefaultNegation"			Adds or removes default-negation to literals
"swapStrongNegation"			Adds or removes strong-negation to literals
"changeVariableToConstant"		Changes variables to constants, e.g. a(X) -> a(x)
"changeConstantToVariable"		Changes constants to variables, e.g. a(x) -> a(X)
"renamePredicates"				Renames predicates using a name of an other predicate (used in the 
								program with the same arity)
"replaceConstants"				Replaces constant terms or facts with other, already used terms, e.g.
								a(x) -> a(y)
"replaceGroundedLiterals"		Replaces grounded literals (literals without variables) with other, already used terms, e.g.
								a(x,y) -> b(z)
"addStrongNegation"				Adds strong negation to literals
"removeStrongNegation"			Removes strong negation to literals
"addDefaultNegation"			Adds default-negation to literals
"removeDefaultNegation"			Removes default-negation to literals
"twiddleMathStatement"			Adds +1 or -1 to mathematic statements. The optional attributes "includeRelations"
								indicates if also relations should be considered (e.g. change X < Y to X+1 < Y) while
								"includeMathTerms" is a similar attribute for mathematic statements (e.g. A + B = C to
								A - 1 + B = C). By default, both attributes are set to true.
"twiddleAggregateWeight"		Adds +1 or -1 to aggregate weights.

								
Shortcut-Rules (these rules are similar to those above, but use some predefined settings, e.g. targetLiterals)

Type							Modification Rule
--------------------------------------------------------------------------
	"RDP"							delete proper rule
	"RDC"							delete constraint
	"RDF"							delete fact
	"LDB"							delete body literal
	"LDH"							delete head literal
	"LAD"							add default negation
	"LRD"							remove default negation
	"LAS"							add strong negation
	"LRS"							remove strong negation
	"LRP"							rename predicate
	"LRC"							replace comparison relation
	"ARO"							replace arithmetic operator
	"ATV"							twiddle variable domain
	"ATA"							twiddle aggregate bound
	"ATW"							twiddle aggregate weight
	"TST"							swap terms in literals
	"TVC"							change variable to constant
	"TRV"							rename variable
	"TCV"							change constant to variable
	"TRC"							rename constant

=========================================
Example
=========================================
<?xml version="1.0" encoding="UTF-8" ?>
<aspmodificator>
  <configuration>
    <ruleApplication application="all"/>   
    <randomInit value = "0"/>
  </configuration>
  <modificationRules>
    <modificationRule name="rule1" type="swapTerms" min="1" max="1" />
    <modificationRule name="rule2" type="changeMathOperators" min="1" max="1" />
    <modificationRule name="rule3" type="deleteLiteral" min="1" max="1" />
  </modificationRules>
</aspmodificator>


***************************************************************************************
					End of documentation - in case of questions, contact
							mschweng at kr.tuwien.ac.at
***************************************************************************************

