Slurp	0.9		by Zz Zimmerman

For NTK 1.0b6 (b4 will NOT work).  Slurp is a utility for sending
data to the Newton.  You use your favorite communications application
(i.e. ClarisWorks, MacTerminal) to send a text file to the Newton
over the serial port.  Slurp receives the data, converts each line
into a soup entry, and then stores the result in the soup.  This
version of Slurp only adds records to an existing soup, it does
not create one.  It also assumes that the target soup is a union
soup.

The text file tells Slurp everything it needs to know.  Basically,
the name of the soup to store into, the format of the entries in
that soup (slot names, data types), followed by a list of tab
delimited strings to be converted into entries.  Each line is
assumed to be a complete element.  For example:

	Names
	{cardType: 0, phones: ["string", "string", "string", "string"], email: "string", company: "string", address: "string", address2: "string", city: "string", region: "string", country: "string", postal_code: "string", bday: "date", name: {class: 'person, honorific: "string", first: "string", last: "string", title: "string"}}
	0	111-1111	222-2222	333-3333	444-4444	email	company1	address	address2	city	region	country	postal_code	4/23/62	person	Mr.	Bob1	ADobbs	Dudeface	
	0	111-1111	222-2222	333-3333	444-4444	email	company2	address	address2	city	region	country	postal_code	4/23/62	person	Mr.	Joe2	ADobbs	Dudeface	
	0	111-1111	222-2222	333-3333	444-4444	email	company3	address	address2	city	region	country	postal_code	4/23/62	person	Mr.	Bif3	ADobbs	Dudeface	
	É
	É
	É
	0	111-1111	222-2222	333-3333	444-4444	email	company3	address	address2	city	region	country	postal_code	4/23/62	person	Mr.	Bif3	ADobbs	Dudeface	
	BYE!


The first line:

	Names

is the name of the soup to add the entries to.  In this example, we'll
add some cards to the cardfile's Names soup.

The second line:

	{cardType: 0, phones: ["string", "string", "string", "string"], email: "string", company: "string", address: "string", address2: "string", city: "string", region: "string", country: "string", postal_code: "string", bday: "date", name: {class: 'person, honorific: "string", first: "string", last: "string", title: "string"}}

is a line of NewtonScript that specifies the format of an entry
(ie. entrySpec) for this soup.  The NewtonScript is compiled by 
Slurp, and the resulting frame is used for determining data types.

THE PROBLEM:
	Unfortunately, tab-delimited files are just text, with no real
	type specifications.  Because of this, each slot value comes
	in as a string, and must be converted to the appropriate type.
	The type for each slot value comes from the entrySpec.

The slot values in the entrySpec are sample values that have the
desired class.  For example, if a slot value was to be converted
to an integer, you could store 0 in the entrySpec.  If the slot
value is to be converted into a symbol, you could store 'symbol
in the entrySpec.  Slurp uses the ClassOf function to determine
the desired class, and then converts the string as needed.

PROBLEM #2:	
	Unfortunately, the ClassOf function doesn't always succeed.
	For example, in the case of a date value.  The file has a
	human readable version of the date in a string.  The Names
	soup stores dates as a big integer (the result of the
	StringToDate function).  Storing an integer in the entrySpec
	won't do it.  Slurp needs to know how to convert the string
	into a date.
	
The solution to this problem is less than elegant, but is very
flexible.  When the value in the entrySpec is of type 'string,
the contents of the string are used to specify the type.

For example, if the desired type is string, we use the string:

	"string"

This specifies that the data is to be converted into (or left
as) a simple string.  To specify a different type like 'date,
we use the string:

"date"

The type conversion routine inside Slurp can be extended to
support whatever types you may come up with.

The next lines are tab delimited text that contain the data for the
soup entries.  The data must be specified in the same order as the
sample soup entry.  So in the example, 0 is the cardType, 111-1111 is
the first phone number in the phones array, and so on.  Note
that all the fields are tab-delimited.  There are no braces
or brackets used to specify frames or arrays.

In order to make Slurp disconnect automatically, the last line
of the file is:

BYE!

signalling to Slurp that all the data has been received, and the
connection can now be closed.

To use Slurp, simply download it to your Newton.  Open the communications
program on the Macintosh, and open a connection with the following specs:

  Serial Tool, 9600 baud, 8 data bits, 1 stop bit, XON/XOFF handshaking

You can use the same cable that you use with NTK/Connection.

For file transfer, specify the Text Tool.

Now you are ready to slurp some soup.  

Open Slurp and tap the "Receive..." button.  

On the Mac, choose "Send File..." in the comm program, and choose the 
file to be sent.  Slurp will display the number of entries
received in a view near the top of the screen.  When the file transfer
is complete, Slurp will automatically disconnect.

As for the implementation, the main routines are in:

	protoSerialProtocol	-	InputScripts for receiving data.
	
	nextSlotValue		-	Returns the next piece of data from the
							tab delimited line of text.
							
	matchTypes			-	Coerces a string into a specified type.
							
	buildEntry			-	Recursive routine to convert each string
							from the data file into the correct type
							and store the new value in a frame/entry.
							
	newStatus			-	Displays program information in a static
							text window on the Newton.

	protoVT42			-	This is just a little auto-sizing text
							view useful for displaying status
							messages.  It's based on the "Wrap It
							Up" sample from PIE DTS.

	epInit, epConnect,	-	Global functions for instantiating,
	epDisconnect			connecting and disconnecting an I/O
							endpoint.
							
Caveats/Bugs:

The previous version of this code was pretty ugly, and this is
meant to be a much cleaner and more usable version.  Sorry for
the pre-release.

I still have not been able to call the endpoint :Dispose function
without getting errors.  Calling :Abort followed by :Release seems
to be the best.  Maybe endpoints shouldn't be disposed of?  It
doesn't seem to bother the Toolkit App, so maybe :Release is
enough...

The views in Slurp are mostly debugging windows that I used while
debugging it.  The "Slurp State:" view is the most useful.  The
"Connection State:" view display the results of the :State()
communications function after certain operations.  Tap the 
"Connection State:" label to see the current state.

							
I hope this helps,


...Zz