[Edit] Vastly improved version 0.3 released Aug 31, 2012. Now with more data types and cleaned up error handling.
[Edit] Sept 4, 2012. Fixed the linking problem that was causing VIs to be broken on your machines.
[Edit] Sept 12, 2012. Full support for variants. More array data types. Problem with serializing time stamps solved so they maintain full precision in JSON. Still haven't tackled the UTF+8 issue for JSON.
[Edit] Oct 30, 2012. All data types now included. Test suite refined. INCLUDES CIRCULAR GRAPH OF DATA VALUE REFERENCES (unexpectedly easy solution).
[Edit] August 2, 2013. Large number of changes to framework. Expect documentation and changelog to come. Package built for LabVIEW 2013.
[Edit] March 4, 2014. Continued refinement of framework. 2D arrays and Filter removed to reduce bloat of the framework (2D arrays still addable as extended types if you want one in your serialization). Binary Serialize/Deserialize added. Split into two packages.
Introducing draft version of the AQ Character Lineator, a library for taking LabVIEW objects and reducing them to character sequences and then restoring the objects back later. Why the strange name? Because I got multiple people all having different opinions on what I should call this and I went with a name that has zero hits on Google (a true Googlewhack until someone mirrors this post).
These VIs or their evolution may become part of LabVIEW in the future. National Instruments reserves all rights necessary to allow their distribution as part of LabVIEW. Any modifications made may only be shared by posting back to ni.com. You agree that all modified versions posted may become part of LabVIEW in the future without any compensation to you.
Package is built for 2013 due to a new vi that the framework takes advantage of. It is possible to save it in previous versions but we lose some speed and efficiency.
So... what does this library do?
- You can create new LabVIEW classes that inherit from Serializable.lvclass, give those classes ONLY TWO FUNCTIONS -- "To Serial Form.vi" and a "From Serial Form.vi" -- and then be able to flatten and unflatten from any supported file format. These two VIs use a could-be-easily-scripted pattern. Autogeneration of these two VIs is a desired feature for the future.
- In the library, you will find serializers for JSON and Funky XML. The XML is a weird dialect that I made up to test edge cases of file formatting. The JSON is actual UTF-8 encoded JSON.
- You will find a deserializer for JSON only. Parsing strings is very hard to do in any programming language because of the extreme attention to detail required. The Lineator helps as it gives you a good framework for knowing when you've covered all the cases that a parser must handle. My goal in creating this library is not to support all the world's file formats but rather to enable others to support file formats as needed. I made the JSON work. Writing a deserializer for any other format is something I hope someone else will take on. I have done a proof of concept for Binary String enough to know that it is possible to support unnamed formats like that. If I write another deserializer, it will be for the binary format. A proper XML serializer and deserializer is a substantial project that I hope someone volunteers for.
- The following data types are supported:
- Analog Waveform
- Digital Waveform
- Digital Data
- Boolean
- Complex (Single/Double/Extended)
- Float (Single/Double/Extended)
- All Integer Types (signed & unsigned)
- Path
- Serializable (recursively)
- DVR of Serializable (recursively AND circularly linked if necessary)
- String (No need to include Picture String since the Type Cast node will allow you to cast one as the other)
- Timestamp
- Variant (containing any of the other types except Serializable)
- AND ARRAYS OF ALL OF THE ABOVE
- The Formatter class can provide you with facilities to reformat data for localization. The FXML serializer uses the formatter. The JSON serializer ignores the formatter (JSON defines strict rules for all its data types).
- You can do load from previous and save to previous mutations in your Serializable's To Serial Form and From Serial Form. Mutations can include renaming the classes.
- The class paths can be embedded in the string in a few different ways, and there is built-in support for dynamic loading of classes into memory as the string is parsed, provided all the classes that you want to dynamically load are under a common root path.
There's pretty much zero documentation. VIs and classes are named with a fair amount of detail, but after that, well, it's a barren landscape. I will be filling this in in the next revision.
You're going to see some fairly non-standard error handling on these VIs... I've become opposed to putting "error in" on dynamic dispatch VIs, so I've got a lot more "merge error" nodes than normal whose only purpose is to preserve warnings. I hate warnings propagating on error wires... I'd throw them out of the language if I had my way. The error handling on these diagrams would be a lot cleaner if I stopped trying to preserve warnings. The whole error system may get reworked in a future revision of this library, but it works fully as it stands and I may leave it, depending upon your feedback.
How do you start:
Package installs into the vi.lib under the folder NI. Open the enclosed project file. Inside, you'll see a virtual folder for "Test". That is where you will find a partial test plan for the library. Open and run "BIG TEST To String.vi" for a sample of most of the data types in both FXML and JSON and to see how the mutation works across version bumps of your classes. Open any of the "TEST_ME.vi" files to test specific subsets of the type functionality. I am still finishing out the test suite. Any type that does not have a named test suite is not fully tested and is much more likely to have bugs at this time. The ones with named test suites are pretty solid.
The Test....lvclass files are examples of the types of classes you would create to be serialized. That's the part 90% of you are interested in. The two inherited functions in those classes are the ones that we want to have a nice scripting tool to generate (the magic scripting tool mentioned in the design document).
The JSON Serializer class and the JSON Deserializer class are of interest to the next 9% of you who want to create custom file formats. You can judge for yourselves the amount of labor that will be needed to support a new case.
The next 0.9% of you may be interested in localization for human cultures. Take a look at the Formatter class.
The remaining 0.1% who actually want to figure out *how* it all works and make comments about the under-the-hood stuff are free to wander where you will. I have added limited comments at this point, but certain sections, like the handling of variants, will require some study to understand.
Comments welcome!
