Initial commit

1 files changed, 97 insertions, 0 deletions

diff --git a/src/syntaxParser/README b/src/syntaxParser/README
new file mode 100644
index 0000000..56a50da
--- /dev/null
+++ b/src/syntaxParser/README
@@ -0,0 +1,97 @@
+============================================================= README file ============================================================= 
+
+WCPS Abstract Parser and ProcessCoverage XML transformer tool
+Author: Mattia Parigiani
+
+
+
+
+The application folder contains the following:
+
+- Java CUP grammar specification file: "wcps.cup"
+- JLex Lexycal Analyzer / Scanner specification file: "wpcs.lex"
+- Utility Java classes for non-terminal symbols of grammar needed for XML conversion routines
+- batch file for parser generation under Windows OS: "run.bat"
+- Text files containing sample tested WCPS requests: "SAMPLE_REQUESTS.txt", "test_requests.txt"
+- JLex runtime executables directory: in sub directory "./JLex"
+- Java CUP runtime jar library : "java-cup-11a.jar"
+- Java CUP runtime executables directory: in sub directory "./java_cup"
+- Lexycal scanner generated source code and executable: respectevely "wcps.lex.java" and "WCPSScanner.class"
+- Parser generated source code and executable: respectevely "WCPSParser.java" and "WCPSParser.class"
+- Symbols generate source code and executable: respectevely "WCPSSymbol.java" and "WCPSSymbol.class"
+- README.txt file
+
+
+
+
+
+The tool may be used in the following two ways:
+1) Simple Usage
+2) Further developments
+
+
+
+======================================================================================================================================
+1) Simple Usage:
+
+Users that want to only use the WCPS Parser/Transformer utility need to do the following operations:
+
+	- Edit the "request.wcps" file and enter a valid WCPS request
+		The syntax will be considered to be valid if it can be parsed with no errors and if it is conformant to the 
+		Java CUP grammar specification.
+	
+	- Execute the WCPSRequestProcessor program:
+		This will produce the appropriate ProcessCoverage XMl request file is the parsed request does not contain
+		any syntax errors.
+	
+	- Open the "wcpsRequest.xml" to see the output XML request file.
+	
+	- Optionally connect to the WCPS service at http://mango.eecs.jacob-university.de:8080/wcps_0.3.5/ and submit the XML file
+	  using the file upload field.
+	  The coverage data will be returned only if the specified sets in the request exist on the server side.
+	  
+	  
+	  
+	  
+======================================================================================================================================
+2) Further Development:
+
+Users that may want to bring modification to the utility will mainly need to edit the CUP specification file and the JLex specification.
+- The CUP specification is within the "wcps.cup" file
+- The JLex specification is within the "wcps.lex" file
+
+Once modifications have been made the new parser can be generated by executing the following sequence of commands:
+
+- java JLex.Main wcps.lex
+		This generates the lexycal analyzer and scanner using JLex technology
+		
+- java java_cup.Main -parser WCPSParser -symbols WCPSSymbol <wcps.cup 
+		This generates the source for the parser and symbol class using Java CUP technology.
+		The sources are renamed WCPSParser.java and WCPSSymbol.java.
+		Different names may be used as long as the calling program also considers these changes
+
+- javac wcps.lex.java
+		This compiles the Scanner class generated by the JLex technology. The class is named wcps.lex.java by default.
+		This name is conventional and comes directly from the fact that the JLex specification file is called "wcps.lex"
+		
+- javac WCPSParser.java WCPSSymbol.java WCPSRequestProcessor.java
+		This compiles the parser and the symbol sources together with the calling program (WCPSRequestProcessor).
+		Please see the source code for WCPSRequestProcessor.java to see the exact usage.
+		
+At this moment, the parser is ready for any WCPS request. The WCPSRequestProcessor.java code is an example for how the parser can be invoked by 
+reading a WCPS request string from a file (namely, "request.wcps"). To invoke the WCPSRequestProcessor.java example program simply call: 
+
+- java WCPSRequestProcessor
+
+This is mainly what is specified in the previous section of this README file (Simple Usage)
+
+
+NOTE:
+Windows users can get the cascading effect of executing all these commands in a row by using the provided batch file (namely, "run.bat" ).
+From the windows command prompt, enter the application folder and type:
+
+- run
+
+Please have a look at the "run.bat" for further clarification
+
+======================================================================================================================================
\ No newline at end of file