From e75066cc9261c65e835c7caf2e7bc89c7f468bfa Mon Sep 17 00:00:00 2001
From: Jan Breuer <jan.breuer@jaybee.cz>
Date: 周四, 27 8月 2015 23:23:35 +0800
Subject: [PATCH] Try to fix travis build

---
 README.md |  120 +++++++++++++++++++++++++++++++++++++++++++++++-------------
 1 files changed, 94 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 0c3b6dc..a1428a2 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,65 @@
-SCPI parser library
+SCPI parser library v2
 ===========
 
-[SCPI](http://en.wikipedia.org/wiki/Standard_Commands_for_Programmable_Instruments) Parser library aims to provide parsing ability of SCPI commands on instrument side. All commands are defined by its patterns eg: "STATus:QUEStionable:EVENt?".
+[SCPI](http://en.wikipedia.org/wiki/Standard_Commands_for_Programmable_Instruments) Parser library aims to provide parsing ability of SCPI commands on **instrument side**. All commands are defined by its patterns eg: "STATus:QUEStionable:EVENt?".
 
 Source codes are published with open source Simplified BSD license.
+
+SCPI parser library is based on these standards
+ - [SCPI-99](http://www.ivifoundation.org/docs/scpi-99.pdf)
+ - [IEEE 488.2-2004](http://dx.doi.org/10.1109/IEEESTD.2004.95390)
+
+
+Migration from v1 to v2
+-----------------------
+Functions `SCPI_ParamNumber` and `SCPI_NumberToStr` has one more parameter - array of special values. It is still possible to use provided `scpi_special_numbers_def`, but you are free to use different deffinition per parameter.
+
+Function `SCPI_ParamChoice` has different type of choice list. It is now array of `scpi_choice_def_t` and not array of `const char *`. It is now possible to define `tag`. `SCPI_ParamChoice` will now return value of this tag and not index to array. If you want print the name of the choice value, you should now use `SCPI_ChoiceToName` instead of direct indexing of the array.
+
+Reading strings is now more correct but it needs secondary copy buffer. You can use function `SCPI_ParamCopyText` to correctly handle strings like `"normal ""quoted"" normal"` will be converted to `normal "quoted" normal`.
+
+It is now possible to use `SCPI_ParamArbitraryBlock` and `SCPI_ResultArbitraryBlock` to work with binary data input and output.
+
+Test callback is removed from context. You should now reimplement whole `*TST?` command callback.
+ 
+Usage
+---------------
+Download source package or clone repository
+ - v2.0 - https://github.com/j123b567/scpi-parser/archive/v2.0.zip
+ - v1.2 - https://github.com/j123b567/scpi-parser/archive/v1.2.zip
+ - latest - https://github.com/j123b567/scpi-parser/archive/master.zip
+ - git clone https://github.com/j123b567/scpi-parser.git
+
+Library is in folder `libscpi` and you can use it directly in your embedded project.
+
+You can try to make examples so just run `make`.
+
+In folder `examples` there are several examples using console or TCP connection to emulate SCPI instrument.
+
+
+Version history
+----------------
+Version v2.0 2015-01-18
+ - better AVR support
+ - implementation of traversal of header tree - it is possible to write `CONF:VOLT:DC 1; AC 2` instead of `CONF:VOLT:DC 1; CONF:VOLT:AC 2`
+ - resolve issue with multiple commands with result separated by `;`
+ - add support for Multiple Identical Capabilities - e.g. `OUT:FREQ`, `OUT2:FREQ` by pattern `OUTput#:FREQuency`
+
+Version v2.0_beta1 2015-01-18
+ - parsing more compliant with SCPI-1999
+ - support all parameter types defined in the spec - separate them and identifie them
+ - support for Arbitrary program data
+ - support for tagging command patterns (useful for common handler)
+ - support for extending any parameter type using SCPI_Parameter
+ - general support for number or text value (e.g. 1, 6, DEF, INF) not limited to one array of special numbers
+ - support for optional command headers (Richard.hmm)
+
+
+Version v1.0 released 2013-06-24
+ - support basic command pattern matching (no optional keywoards)
+ - support basic data types (no expressions, no nondecimal numbers, no arbitrary program data, ...)
+ - last version before refactoring of the parser and before extending parameter handling
+
 
 Command pattern definition
 -----------
@@ -15,13 +71,9 @@
 
     Pattern "SYSTem:VERsion?" mathes strings "SYST:version?", "system:ver?", "SYST:VER?", ...
 
-SCPI standard also uses brackets "[]" to define unnecesery parts of command. This behaviour is not implemented yet.
+SCPI standard also uses brackets "[]" to define unnecesery parts of command.
 
-    Pattern "SYSTem:ERRor[:NEXT]?" should match "SYST:ERR?", "system:err?" and also "system:error:next?", ...
-
-In current implementation, you should write two patterns to implement this behaviour
-
-    Pattern "SYSTem:ERRor?" and "SYSTem:ERRor:NEXT?"
+    Pattern "SYSTem:ERRor[:NEXT]?" matches strings  "SYST:ERR?", "system:err?" and also "system:error:next?", ...
 
 
 Command callback
@@ -36,7 +88,7 @@
 
 The command callback can use predefined function to parse input parameters and to write output.
 
-Reading input parameter is done by functions `SCPI_ParamInt`, `SCPI_ParamDouble`, `SCPI_ParamString` adn `SCPI_ParamNumber`.
+Reading input parameter is done by functions `SCPI_ParamInt`, `SCPI_ParamDouble`, `SCPI_ParamString`, `SCPI_ParamNumber`, `SCPI_ParamArbitraryBlock`, `SCPI_ParamCopyText`, `SCPI_ParamBool` and `SCPI_ParamChoice`
 
 Writing output is done by functions `SCPI_ResultInt`, `SCPI_ResultDouble`, `SCPI_ResultString`, `SCPI_ResultText`. You can write multiple output variables. They are automaticcaly separated by coma ",".
 
@@ -45,14 +97,17 @@
 
 Source codes are devided into few files to provide better portability to other systems.
 
-- *libscpi/parser.c* - provides the core parser library
-- *libscpi/error.c* - provides basic error handling (error queue of the instrument)
-- *libscpi/ieee488.c* - provides basic implementation of IEEE488.2 mandatory commands
-- *libscpi/minimal.c* - provides basic implementation of SCPI mandatory commands
-- *libscpi/utils.c* - provides string handling routines and conversion routines
-- *libscpi/units.c* - provides handling of special numners (DEF, MIN, MAX, ...) and units
-- *libscpi/fifo.c* - provides basic implementation of error queue FIFO
-- *libscpi/debug.c* - provides debug functions
+- *libscpi/src/parser.c* - provides the core parser library
+- *libscpi/src/lexer.c* - provides identification of keywoards and data types
+- *libscpi/src/error.c* - provides basic error handling (error queue of the instrument)
+- *libscpi/src/ieee488.c* - provides basic implementation of IEEE488.2 mandatory commands
+- *libscpi/src/minimal.c* - provides basic implementation of SCPI mandatory commands
+- *libscpi/src/utils.c* - provides string handling routines and conversion routines
+- *libscpi/src/units.c* - provides handling of special numners (DEF, MIN, MAX, ...) and units
+- *libscpi/src/fifo.c* - provides basic implementation of error queue FIFO
+- *libscpi/src/debug.c* - provides debug functions
+
+- *libscpi/test/* - Unit test for the library
 
 - *examples/test-parser* - is the basic non-interactive demo of the parser
 - *examples/test-interactive* - is the basic interactive demo of the parser
@@ -62,6 +117,9 @@
 
 Implementation to your instrument
 -------------
+
+Look inside `examples/common/scpi-def.c`. Here is basic instrument implementation. You can take it as a template for future development.
+
 First of all you need to fill structure of SCPI command definitions
 
 ```c	
@@ -73,19 +131,18 @@
 };
 ```
 
-Than you need to initialize interface callbacks structure. If you don't want to provide some callbacks, just initialize it as `NULL`. write callback is mandatory and is used to output data from the library.
+Than you need to initialize interface callbacks structure. If you don't want to provide some callbacks, just initialize them as `NULL`. write callback is mandatory and is used to output data from the library.
 
 ```c
 scpi_interface_t scpi_interface = {
 	.write = myWrite,
 	.error = NULL,
 	.reset = NULL,
-	.test = NULL,
 	.srq = NULL,
 };
 ```
 
-Important thing is command buffer. Maximum size is up to you and it should be larger than any possible largest command. 
+Important thing is command buffer. Maximum size is up to you and it should be larger than any possible largest command.
 
 ```c
 #define SCPI_INPUT_BUFFER_LENGTH 256
@@ -104,7 +161,6 @@
 	.interface = &scpi_interface,
 	.registers = scpi_regs,
 	.units = scpi_units_def,
-	.special_numbers = scpi_special_numbers_def,
 };
 ```
 
@@ -129,7 +185,7 @@
 Interactive demo can beimplemented using this loop
 
 ```c
-#define SMALL_BUFFER_LEN
+#define SMALL_BUFFER_LEN 10
 char smbuffer[SMALL_BUFFER_LEN];
 while(1) {
 	fgets(smbuffer, SMALL_BUFFER_LEN, stdin);
@@ -164,17 +220,29 @@
 
 If you discard some parameters, there is no way to recover them.
 
+Specifying `mandatory` parameter will introduce SCPI Error -109 "Missing parameter"
+
 These are the functions, you can use to read parameters
+ - `SCPI_Parameter` - read parameter to scpi_parameter_t. This structure contains pointer to buffer and type of the parameter (program mnemonic, hex number, ....)
  - `SCPI_ParamInt` - read signed 32bit integer value (dec or hex with 0x prefix)
  - `SCPI_ParamDouble` - read double value
  - `SCPI_ParamNumber` - read double value with or without units or represented by special number (DEF, MIN, MAX, ...). This function is more universal then SCPI_ParamDouble.
- - `SCPI_ParamText` - read text value - may be encapsuled in ""
- - `SCPI_ParamString` - read unspecified parameter not encapsulated in ""
+ - `SCPI_ParamCopyText` - read text value - must be encapsuled in ""
+ - `SCPI_ParamBool` - read boolean value (0, 1, on, off)
+ - `SCPI_ParamChoice` - read value from predefined constants
+ 
 
 These are the functions, you can use to write results
  - `SCPI_ResultInt` - write integer value
  - `SCPI_ResultDouble` - write double value
  - `SCPI_ResultText` - write text value encapsulated in ""
- - `SCPI_ResultString` - directly write string value
+ - `SCPI_ResultMnemonic` - directly write string value
+ - `SCPI_ResultArbitraryBlock` - result arbitrary data
+ - `SCPI_ResultIntBase` - write integer in special base
+ - `SCPI_ResultBool` - write boolean value
 
-You can use function `SCPI_NumberToStr` to convert number with units to textual representation and then use `SCPI_ResultString` to write this to the user.
\ No newline at end of file
+You can use function `SCPI_NumberToStr` to convert number with units to textual representation and then use `SCPI_ResultMnemonic` to write this to the user.
+
+You can use `SCPI_Parameter` in conjuction with `SCPI_ParamIsNumber`, `SCPI_ParamToInt`, `SCPI_ParamToDouble`, `SCPI_ParamToChoice` in your own parameter type handlers.
+
+`SCPI_ParamNumber` is now more universal. It can handle number with units, it can handle special numbers like `DEF`, `INF`, ... These special numbers are now defined in parameter and not in context. It is possible to define more general usage with different special numbers for different commands.

--
Gitblit v1.9.1