From a5a84c429ac548eafd1d3903225a4ce72104201f Mon Sep 17 00:00:00 2001
From: Jan Breuer <jan.breuer@jaybee.cz>
Date: 周三, 22 4月 2015 03:50:26 +0800
Subject: [PATCH] Support RESPONSE MESSAGE UNIT SEPARATOR, issue #21

---
 README.md |   94 +++++++++++++++++++++++++++++++++++-----------
 1 files changed, 71 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 14d65b1..2a2e9c4 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,60 @@
 SCPI parser library
 ===========
 
+[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_beta1 - https://github.com/j123b567/scpi-parser/archive/v2.0_beta1.zip
+ - v1.2 - https://github.com/j123b567/scpi-parser/archive/v1.2.zip
+ - v1.1 - https://github.com/j123b567/scpi-parser/archive/v1.1.zip
+ - v1.0 - https://github.com/j123b567/scpi-parser/archive/v1.0.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 v1.0 released 24.6.2013
+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
 
-Future Version v2.0 released ????????
- - parsing more compliant with SCPI-1999
- - support all parameter types defined in the spec - separate them and identifie them
- - support for optional command headers (Richard.hmm)
-
-
-
-
-
-[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.
 
 Command pattern definition
 -----------
@@ -48,7 +83,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 ",".
 
@@ -77,6 +112,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	
@@ -88,19 +126,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
@@ -119,7 +156,6 @@
 	.interface = &scpi_interface,
 	.registers = scpi_regs,
 	.units = scpi_units_def,
-	.special_numbers = scpi_special_numbers_def,
 };
 ```
 
@@ -144,7 +180,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);
@@ -179,17 +215,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.
+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