User:Scsbot/formtools

This is a set of "helper" scripts for processing HTML forms from shell scripts.

Since several calls will be required to several of these tools during the course of form processing, there needs to be some way for the scripts to maintain context across calls. To help the scripts do this, the caller is obliged to invent a unique token and pass it as one of the command line arguments in each invocation. The token is typically just some guaranteed-unique string like "token$$" (where of course the shell will replace "$$" with the current pid). [It would also be possible to have the first-called script choose the token string and return it, and I may rewrite the scripts to use that style.]

The scripts are:

formsetup

Perform the initial parse of an HTML page containing one or more forms. Code: formsetup. Invocation:

formsetup token htmlfile

formselect

In case a page contains multiple forms, select the form that the calling script intends to use. Forms can be identified by their id attribute. Code: formselect. Invocation:

formselect token form_id

formcheckfields

Confirm that the selected form contains the particular input fields that the calling script expects to see. (This is an optional step, since the script to access an individual field, described next, also checks that the requested field exists and returns an error code if it does not. formcheckfields is provided as a convenience so that the calling script doesn't have to check for every possible missing-field error later.) Code: formcheckfields. Invocation:

formcheckfields token fieldname1 [fieldname2 ...]

formgettmpfile

Return the name of the temporary file containing a field's current value. The calling script may either inspect, alter, or overwrite this file. (In doing so the calling script emulates a human user with an actual web browser who is either looking at, editing, or typing into a form field.) Code: formgettmpfile. Invocation:

formgettmpfile token fieldname

formsubmitbutton

Prior to actually submitting a form, indicate which submit button the calling script intends to press. Code: formsubmitbutton. Invocation:

formsubmitbutton token submitfieldname

formsubmit

Actually submit the completed form back to the server. While the rest of these scripts are all written on top of xmlsed, formsubmit invokes httpget. formsubmit requires two parameters besides the usual token: it needs the base URL which the form was originally fetched from (in case the submission URL is relative to it), and it needs the httpget cookie file. Code: formsubmit. Invocation:

formsubmit token baseurl cookiefile

formfinish

Clean up all temporary files and other saved state associated with a form being processed. Code: formfinish. Invocation:

formfinish token