shapetcl.c

#include <stdio.h>
#include <string.h>
#include "shapefil.h"
#include <tcl.h>

enum {
	BASE_POINT,
	BASE_ARC,
	BASE_POLYGON,
	BASE_MULTIPOINT
};

enum {
	DIM_XY,
	DIM_XYM,
	DIM_XYZM
};

/*
 * ShapefilePtr
 * 
 * Structure containing shapefile geometry and attribute table handles as well
 * as other metadata. Allocated by [shapefile] command on successful open or
 * create and subsequently passed to Shapetcl command handlers as ClientData.
 */
struct shapefile_data {
	SHPHandle shp;
	DBFHandle dbf;
	
	/* Metadata: */
	
	/* True if shapefile is readonly; set by [shapefile] on open/create. */
	int readonly;
	
	/* One of the SHPT_ types defined by Shapelib */
	int shapeType;
	
	/* Base shape type (point, arc, polygon, or multipoint) */
	int baseType;
	
	/* Dimension (XY, XYM, or XYZM) */
	int dimType;
	
	/* Base path of shapefile */
	char *path;
	
	/* Config Options: */
	
 	/* Attempt to write double values that don't fit within field width using
	   scientific notation. Allows larger values, but may lose sig. digits.
	   True by default. */
	int allowAlternateNotation;

	/* Read all four coordinate dimensions (X, Y, Z, and M) regardless of shape
	   type. Applies to [coords read] and [bounds] commands. False by default.
	   Only one of getAllCoords and getOnlyXyCoords may be true. */
	int getAllCoords;

	/* Read only the X and Y coordinate dimensions regardless of shape type.
	   Applies to [coords read] and [bounds] commands. False by default.
	   Only one of getAllCoords and getOnlyXyCoords may be true. */
	int getOnlyXyCoords;
	
	/* Read all attribute values as strings regardless of field type. Intended
	   as an aid to debugging attribute table issues. False by default. */
	int readRawStrings;
	
	/* Append a final vertex to polygon parts if provided last vertex is not
	   identifical to first vertex OR if only 3 vertices are given. Appended
	   vertex is a copy of the part's first vertex. False by default. */
	int autoClosePolygons;
	
	/* Allow attribute values that exceed the allocated field width to be
	   truncated when written, rather than generating an error. If both
	   allowTruncation and allowAlternateNotation are true, alternate notation
	   will be attempted before truncating large double values. */
	int allowTruncation;
};
typedef struct shapefile_data * ShapefilePtr;

/* 
 * Counter used to generate unique names for the ensemble command identifiers
 * generated by the [shapefile] command. Incremented by [shapefile] after open.
 */
static int COMMAND_COUNT = 0;
TCL_DECLARE_MUTEX(COMMAND_COUNT_MUTEX);

/*
 * Size of string buffer to use for formatting and measuring numeric values.
 * Should be sufficiently big to fit any encountered value, including decimals.
 */
#define NUMERIC_BUFFER_SIZE 64

int Shapetcl_Init(Tcl_Interp *interp);
int shapefile_cmd(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);
int shapefile_typeSupported(int shpType);
int shapefile_typeCode(const char *shpTypeName);
int shapefile_typeBase(int shpType);
int shapefile_typeDimension(int shpType);
int cmd_dispatcher(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);

int cmd_close(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);
void shapefile_exit_handler(ClientData clientData);
void shapefile_delete_handler(ClientData clientData);

int cmd_config(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);
int cmd_file(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);
int cmd_info(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);
int cmd_info_count(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);
int cmd_info_type(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);
int cmd_info_bounds(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);

int cmd_fields(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);
int cmd_fields_add(Tcl_Interp *interp, DBFHandle dbf, int validate, Tcl_Obj *definitions, Tcl_Obj *attrList, ShapefilePtr shapefile);
int cmd_fields_validate(Tcl_Interp *interp, Tcl_Obj *definitions, DBFHandle dbf);
int cmd_fields_validateField(Tcl_Interp *interp, const char *type, const char *name, int width, int precision);
int cmd_fields_validateFieldName(Tcl_Interp *interp, const char *name);
int cmd_fields_description(Tcl_Interp *interp, ShapefilePtr shapefile, int fieldId);
int cmd_fields_index(Tcl_Interp *interp, ShapefilePtr shapefile, const char *fieldName);

int cmd_coordinates(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);
int cmd_coordinates_write(Tcl_Interp *interp, ShapefilePtr shapefile, int featureId, Tcl_Obj *coordParts);
int cmd_coordinates_writeNull(Tcl_Interp *interp, ShapefilePtr shapefile, int featureId);
int cmd_coordinates_readAll(Tcl_Interp *interp, ShapefilePtr shapefile);
int cmd_coordinates_read(Tcl_Interp *interp, ShapefilePtr shapefile, int featureId);

int cmd_attributes(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);
int cmd_attributes_write(Tcl_Interp *interp, ShapefilePtr shapefile, int recordId, int validate, Tcl_Obj *attrList);
int cmd_attributes_writeNull(Tcl_Interp *interp, ShapefilePtr shapefile, int recordId);
int cmd_attributes_writeField(Tcl_Interp *interp, ShapefilePtr shapefile, int recordId, int fieldId, int validate, Tcl_Obj *attrValue);
int cmd_attributes_validate(Tcl_Interp *interp, ShapefilePtr shapefile, Tcl_Obj *attrList);
int cmd_attributes_validateField(Tcl_Interp *interp, ShapefilePtr shapefile, int fieldId, Tcl_Obj *attrValue);
int cmd_attributes_readAll(Tcl_Interp *interp, ShapefilePtr shapefile);
int cmd_attributes_read(Tcl_Interp *interp, ShapefilePtr shapefile, int recordId);
int cmd_attributes_readField(Tcl_Interp *interp, ShapefilePtr shapefile, int recordId, int fieldId);
int cmd_attributes_search(Tcl_Interp *interp, ShapefilePtr shapefile, int fieldId, Tcl_Obj *attrValue);

int cmd_write(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);

/*
 * Shapetcl_Init
 * 
 * Invoked by Tcl when the Shapetcl extension is loaded.
 * 
 * Result:
 *   Registers the [shapefile] command used to open or create shapefiles.
 *   (Note: the [shapefile] command is created in the ::shapetcl namespace.)
 */
int Shapetcl_Init(Tcl_Interp *interp) {
	
	Tcl_Namespace *shapetclNamespace;
	
	if (Tcl_InitStubs(interp, "8.1", 0) == NULL) {
		return TCL_ERROR;
	}
	
	if (Tcl_PkgProvide(interp, "shapetcl", "0.1") != TCL_OK) {
		return TCL_ERROR;
	}
	
	(void)Tcl_CreateObjCommand(interp, "::shapetcl::shapefile", (Tcl_ObjCmdProc *)shapefile_cmd, NULL, NULL);
	shapetclNamespace = Tcl_FindNamespace(interp, "shapetcl", NULL, TCL_GLOBAL_ONLY);
	Tcl_Export(interp, shapetclNamespace, "shapefile", 0);
	
	return TCL_OK;
}

/*
 * shapefile_cmd
 * 
 * Implements the [shapefile] command used to open a new or existing shapefile.
 * 
 * Command Syntax:
 *   [shapefile PATH ?readonly|readwrite?]
 *     Open the shapefile at PATH. Default access mode is readwrite.
 *   [shapefile PATH TYPE FIELDSDEFINITION]
 *     Create a shapefile at PATH. TYPE defines feature geometry type. FIELDS
 *     defines initial attribute table format. At least one field is required.
 *     See the [fields] command for details on FIELDSDEFINITION format. 
 * 
 * Result:
 *   Name of an ensemble command for subsequent operations on the shapefile.
 */
 int shapefile_cmd(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {

	ShapefilePtr shapefile;
	const char *path;
	int readonly = 1;
	SHPHandle shp;
	DBFHandle dbf;
	int shpType;
	Tcl_Obj *cmdNameObj;
	Tcl_Namespace *ns;
	
	if (objc < 2 || objc > 4) {
		Tcl_WrongNumArgs(interp, 1, objv, "path ?mode?|?type fieldDefinitions?");
		return TCL_ERROR;
	}

	path = Tcl_GetString(objv[1]);

	if (objc == 3) {
		/* opening an existing file, and an access mode is explicitly set */
		const char *mode = Tcl_GetString(objv[2]);
		if (strcmp(mode, "readonly") == 0) {
			readonly = 1;
		} else if (strcmp(mode, "readwrite") == 0) {
			readonly = 0;
		} else {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid mode \"%s\": should be readonly or readwrite", mode));
			return TCL_ERROR;
		}
	}
	
	if (objc == 4) {
		/* create a new file; access must be readwrite. */
		readonly = 0;
		
		if ((shpType = shapefile_typeCode(Tcl_GetString(objv[2]))) == -1) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("unrecognized shape type"));
			return TCL_ERROR;
		}
		
		if (!shapefile_typeSupported(shpType)) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("unsupported shape type \"%d\"", shpType));
			return TCL_ERROR;
		}
		
		/* verify that the attribute table field definition looks sensible */
		if (cmd_fields_validate(interp, objv[3], NULL /* no dbf yet */) != TCL_OK) {
			return TCL_ERROR;
		}
		
		if ((dbf = DBFCreate(path)) == NULL) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to create attribute table for \"%s\"", path));
			return TCL_ERROR;
		}
		
		/* add pre-validated fields to the dbf */
		if (cmd_fields_add(interp, dbf, 0 /* don't validate */, objv[3], NULL, NULL) != TCL_OK) {
			DBFClose(dbf);
			return TCL_ERROR;
		}
				
		if ((shp = SHPCreate(path, shpType)) == NULL) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to create shapefile for \"%s\"", path));
			DBFClose(dbf);
			return TCL_ERROR;
		}
	}
	else {		
		
		/* open an existing shapefile */
		int shpCount, dbfCount;
		
		if ((dbf = DBFOpen(path, readonly ? "rb" : "rb+")) == NULL) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to open attribute table for \"%s\"", path));
			return TCL_ERROR;
		}
		
		if (DBFGetFieldCount(dbf) == 0) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("attribute table for \"%s\" contains no fields", path));
			DBFClose(dbf);
			return TCL_ERROR;
		}
		
		if ((shp = SHPOpen(path, readonly ? "rb" : "rb+")) == NULL) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to open shapefile for \"%s\"", path));
			DBFClose(dbf);
			return TCL_ERROR;
		}
		
		/* Only types we don't handle are SHPT_NULL and SHPT_MULTIPATCH */
		SHPGetInfo(shp, &shpCount, &shpType, NULL, NULL);
		if (!shapefile_typeSupported(shpType)) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("unsupported shape type \"%d\"", shpType));
			DBFClose(dbf);
			SHPClose(shp);
			return TCL_ERROR;
		}
		
		/* Valid shapefiles must have matching number of features and attribute records */
		dbfCount = DBFGetRecordCount(dbf);
		if (dbfCount != shpCount) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("shapefile feature count (%d) does not match attribute record count (%d)", shpCount, dbfCount));
			DBFClose(dbf);
			SHPClose(shp);
			return TCL_ERROR;
		}
	}
	
	if ((shapefile = (ShapefilePtr)ckalloc((unsigned int)sizeof(struct shapefile_data))) == NULL) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to allocate shapefile command data"));;
		DBFClose(dbf);
		SHPClose(shp);
		return TCL_ERROR;
	}
	shapefile->shp = shp;
	shapefile->dbf = dbf;	
	shapefile->readonly = readonly;
	shapefile->allowAlternateNotation = 0;
	shapefile->getAllCoords = 0;
	shapefile->getOnlyXyCoords = 0;
	shapefile->readRawStrings = 0;
	shapefile->autoClosePolygons = 0;
	shapefile->allowTruncation = 0;
	shapefile->shapeType = shpType;
	shapefile->baseType = shapefile_typeBase(shpType);
	shapefile->dimType = shapefile_typeDimension(shpType);
	
	/* save the path of the shapefile */
	shapefile->path = (char *)ckalloc((unsigned int)(strlen(path) + 1));
    strcpy(shapefile->path, path);
	
	ns = Tcl_GetCurrentNamespace(interp);
	Tcl_MutexLock(&COMMAND_COUNT_MUTEX);
	if (ns->parentPtr == NULL) {
		cmdNameObj = Tcl_ObjPrintf("::shapefile%d", COMMAND_COUNT++);
	} else {
		cmdNameObj = Tcl_ObjPrintf("%s::shapefile%d", ns->fullName, COMMAND_COUNT++);
	}
	Tcl_MutexUnlock(&COMMAND_COUNT_MUTEX);

	if (Tcl_CreateObjCommand(interp, Tcl_GetString(cmdNameObj), (Tcl_ObjCmdProc *)cmd_dispatcher, (ClientData)shapefile, (Tcl_CmdDeleteProc *)shapefile_delete_handler) == NULL) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to create command for %s", Tcl_GetString(cmdNameObj)));
		DBFClose(dbf);
		SHPClose(shp);
		ckfree((char *)shapefile);
		return TCL_ERROR;
	}
	Tcl_CreateExitHandler((Tcl_ExitProc *)shapefile_exit_handler, (ClientData)shapefile);
	Tcl_SetObjResult(interp, cmdNameObj);
	
	return TCL_OK;
}

/*
 * shapefile_typeSupported
 * 
 * Boolean check whether Shapetcl supports the specified shapefile type code. 
 * 
 * Result:
 *   1 if supported (any point/arc/polygon/multipoint xy/xym/xyzm combination)
 *   0 if unsupported (null, multipatch, or any other value)
 */
int shapefile_typeSupported(int shpType) {
	if (	   shpType == SHPT_POINT
			|| shpType == SHPT_POINTM
			|| shpType == SHPT_POINTZ
			|| shpType == SHPT_ARC
			|| shpType == SHPT_ARCM
			|| shpType == SHPT_ARCZ
			|| shpType == SHPT_POLYGON
			|| shpType == SHPT_POLYGONM
			|| shpType == SHPT_POLYGONZ
			|| shpType == SHPT_MULTIPOINT
			|| shpType == SHPT_MULTIPOINTM
			|| shpType == SHPT_MULTIPOINTZ) {
		return 1;
	}
	return 0;
}

/*
 * shapefile_typeCode
 * 
 * Look up the shapefile type code corresponding to the given type name.
 * 
 * Result:
 *   One of the SHPT_ type codes defined in shapefil.h, or -1 if unrecognized.
 */
int shapefile_typeCode(const char *shpTypeName) {
	if (strcmp(shpTypeName, "point") == 0) {
		return SHPT_POINT;
	} else if (strcmp(shpTypeName, "arc") == 0) {
		return SHPT_ARC;
	} else if (strcmp(shpTypeName, "polygon") == 0) {
		return SHPT_POLYGON;
	} else if (strcmp(shpTypeName, "multipoint") == 0) {
		return SHPT_MULTIPOINT;
	} else if (strcmp(shpTypeName, "pointm") == 0) {
		return SHPT_POINTM;
	} else if (strcmp(shpTypeName, "arcm") == 0) {
		return SHPT_ARCM;
	} else if (strcmp(shpTypeName, "polygonm") == 0) {
		return SHPT_POLYGONM;
	} else if (strcmp(shpTypeName, "multipointm") == 0) {
		return SHPT_MULTIPOINTM;
	} else if (strcmp(shpTypeName, "pointz") == 0) {
		return SHPT_POINTZ;
	} else if (strcmp(shpTypeName, "arcz") == 0) {
		return SHPT_ARCZ;
	} else if (strcmp(shpTypeName, "polygonz") == 0) {
		return SHPT_POLYGONZ;
	} else if (strcmp(shpTypeName, "multipointz") == 0) {
		return SHPT_MULTIPOINTZ;
	} else if (strcmp(shpTypeName, "multipatch") == 0) {
		return SHPT_MULTIPATCH;
	} else if (strcmp(shpTypeName, "null") == 0) {
		return SHPT_NULL;
	}
	return -1;
}

/*
 * shapefile_typeBase
 * 
 * Return the base type (BASE_POINT, BASE_ARC, BASE_POLYGON, or BASE_MULTIPOINT)
 * of the specified shape type, regardless of dimension. 
 */
int shapefile_typeBase(int shpType) {
	int base = -1;
	switch (shpType) {
		case SHPT_POINT:
		case SHPT_POINTM:
		case SHPT_POINTZ:
			base = BASE_POINT;
			break;
		case SHPT_ARC:
		case SHPT_ARCM:
		case SHPT_ARCZ:
			base = BASE_ARC;
			break;
		case SHPT_POLYGON:
		case SHPT_POLYGONM:
		case SHPT_POLYGONZ:
			base = BASE_POLYGON;
			break;
		case SHPT_MULTIPOINT:
		case SHPT_MULTIPOINTM:
		case SHPT_MULTIPOINTZ:
			base = BASE_MULTIPOINT;
			break;
	}
	return base;
}

/*
 * shapefile_typeDimension
 * 
 * Return the dimension (DIM_XY, DIM_XYM, or DIM_XYZM) of the specified shape
 * type, regardless of base type. 
 */
int shapefile_typeDimension(int shpType) {
	int dimension = -1;
	switch (shpType) {
		case SHPT_POINT:
		case SHPT_ARC:
		case SHPT_POLYGON:
		case SHPT_MULTIPOINT:
			dimension = DIM_XY;
			break;
		case SHPT_POINTM:
		case SHPT_ARCM:
		case SHPT_POLYGONM:
		case SHPT_MULTIPOINTM:
			dimension = DIM_XYM;
			break;
		case SHPT_POINTZ:
		case SHPT_ARCZ:
		case SHPT_POLYGONZ:
		case SHPT_MULTIPOINTZ:
			dimension = DIM_XYZM;
			break;
	}
	return dimension;
}

/*
 * cmd_dispatcher
 * 
 * Ensemble command dispatcher handles the shapefile identifier [$shp] returned
 * by shapefile_cmd. The clientData is a ShapefilePtr associated with identifier.
 * 
 * Command Syntax:
 *   [$shp attributes|close|configure|coordinates|fields|info|mode|write ?args?]
 *     Invokes the function handler associated with selected subcommand.
 *     Unambiguous abbreviations such as [$shp attr] or [$shp coord] are valid.
 * 
 * Result:
 *   Result of the selected subcommand.
 */
int cmd_dispatcher(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {

	int subcommandIndex;
	static const char *subcommandNames[] = {
			"attributes",
			"close",
			"configure",
			"coordinates",
			"fields",
			"info",
			"file",
			"write",
			NULL
	};
	int result;
	
	if (objc < 2) {
		Tcl_WrongNumArgs(interp, 1, objv, "subcommand ?args?");
		return TCL_ERROR;
	}
	
	/* identify subcommand, or set result to error message w/valid cmd list */
	if (Tcl_GetIndexFromObj(interp, objv[1], subcommandNames, "subcommand",
			0 /* not TCL_EXACT */, &subcommandIndex) != TCL_OK) {
		return TCL_ERROR;
	}
	
	switch (subcommandIndex) {
		case 0: result = cmd_attributes (clientData, interp, objc, objv); break;
		case 1: result = cmd_close      (clientData, interp, objc, objv); break;
		case 2: result = cmd_config     (clientData, interp, objc, objv); break;
		case 3: result = cmd_coordinates(clientData, interp, objc, objv); break;
		case 4: result = cmd_fields     (clientData, interp, objc, objv); break;
		case 5: result = cmd_info       (clientData, interp, objc, objv); break;
		case 6: result = cmd_file       (clientData, interp, objc, objv); break;
		case 7: result = cmd_write      (clientData, interp, objc, objv); break;
		default:
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid subcommand index (%d)", subcommandIndex));
			result = TCL_ERROR;
			break;
	}
	
	return result;
}

/*
 * cmd_close
 * 
 * Implements the [$shp close] command used to close shapefile and save changes.
 * 
 * Command Syntax:
 *   [$shp close]
 * 
 * Result:
 *   No Tcl return value. Changes to readwrite shapefiles are written to disk.
 *   $shp command is deleted and associated resources are released.
 */
int cmd_close(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {
	
	ShapefilePtr shapefile = (ShapefilePtr)clientData;

	if (objc != 2) {
		Tcl_WrongNumArgs(interp, 2, objv, NULL);
		return TCL_ERROR;
	}
	
	shapefile_exit_handler(shapefile);
	Tcl_DeleteCommand(interp, Tcl_GetString(objv[0]));
	
	return TCL_OK;
}

/*
 * shapefile_exit_handler
 * 
 * Closes the shapefile, writing changes to disk. Invoked by the [$shp close]
 * command. Also invoked as exit handler to ensure any open shapefiles are
 * properly flushed and closed when the interpreter exits.
 */
void shapefile_exit_handler(ClientData clientData) {
	ShapefilePtr shapefile = (ShapefilePtr)clientData;
	SHPClose(shapefile->shp);
	shapefile->shp = NULL;
	DBFClose(shapefile->dbf);
	shapefile->dbf = NULL;
	ckfree((void *)shapefile->path);
	shapefile->path = NULL;
}

/*
 * shapefile_delete_handler
 * 
 * Deletes exit handler and releases shapefile resources. Invoked as delete
 * handler when [$shp close] command deletes the associated shapefile command.
 */
void shapefile_delete_handler(ClientData clientData) {
	Tcl_DeleteExitHandler((Tcl_ExitProc *)shapefile_exit_handler, clientData);
	ckfree((char *)clientData);
}

/*
 * cmd_config
 *
 * Implements the [$shp config] command use to get and set shapefile IO options.
 *
 * Command Syntax:
 *   [$shp config option]
 *     Get the current value of the specified option. Option may be abbreviated.
 *   [$shp config option 0|1]
 *     Set the value of the specified option to 0 or 1 (boolean options only).
 *     Some options are incompatible, in which case setting one to true has the
 *     side effect of setting the other to false (see get*Coordinates options).
 *
 * Options (Defaults):
 *   allowAlternateNotation (0)
 *   getAllCoordinates (0)
 *   getOnlyXyCoordinates (0)
 *   readRawStrings (0)
 *   autoClosePolygons (0)
 *   allowTruncation (0)
 *   (See notes in ShapefilePtr struct definition for option details.)
 *
 * Result:
 *   Returns boolean value of specified option.
 */
int cmd_config(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {
	
	ShapefilePtr shapefile = (ShapefilePtr)clientData;
	int optionValue = 0;
	int optionIndex;
	static const char *optionNames[] = {
			"allowAlternateNotation",
			"getAllCoordinates",
			"getOnlyXyCoordinates",
			"readRawStrings",
			"autoClosePolygons",
			"allowTruncation",
			NULL
	};
	
	if (objc < 3 || objc > 4) {
		Tcl_WrongNumArgs(interp, 2, objv, "option ?booleanValue?");
		return TCL_ERROR;
	}
	
	if (Tcl_GetIndexFromObj(interp, objv[2], optionNames, "option", 0, &optionIndex) != TCL_OK) {
		return TCL_ERROR;
	}
	
	if (objc == 4) {
		/* all options expected to be boolean */
		if ((Tcl_GetIntFromObj(interp, objv[3], &optionValue) != TCL_OK)
				|| (optionValue != 0 && optionValue != 1)) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid option value \"%s\" (should be 0 or 1)", Tcl_GetString(objv[3])));
			return TCL_ERROR;
		}
	}
	
	switch (optionIndex) {
		case 0: /* allowAlternateNotation */
			if (objc == 4) {
				shapefile->allowAlternateNotation = optionValue;
			}
			Tcl_SetObjResult(interp, Tcl_NewIntObj(shapefile->allowAlternateNotation));
			break;
		case 1: /* getAllCoords */
			if (objc == 4) {
				shapefile->getAllCoords = optionValue;
				if (optionValue == 1) {
					shapefile->getOnlyXyCoords = 0;
				}
			}
			Tcl_SetObjResult(interp, Tcl_NewIntObj(shapefile->getAllCoords));
			break;
		case 2: /* getOnlyXyCoords */
			if (objc == 4) {
				shapefile->getOnlyXyCoords = optionValue;
				if (optionValue == 1) {
					shapefile->getAllCoords = 0;
				}
			}
			Tcl_SetObjResult(interp, Tcl_NewIntObj(shapefile->getOnlyXyCoords));
			break;
		case 3: /* readRawStrings */
			if (objc == 4) {
				shapefile->readRawStrings = optionValue;
			}
			Tcl_SetObjResult(interp, Tcl_NewIntObj(shapefile->readRawStrings));
			break;
		case 4: /* autoClosePolygons */
			if (objc == 4) {
				shapefile->autoClosePolygons = optionValue;
			}
			Tcl_SetObjResult(interp, Tcl_NewIntObj(shapefile->autoClosePolygons));
			break;
		case 5: /* allowTruncation */
			if (objc == 4) {
				shapefile->allowTruncation = optionValue;
			}
			Tcl_SetObjResult(interp, Tcl_NewIntObj(shapefile->allowTruncation));
			break;
	}
	
	return TCL_OK;
}

/*
 * cmd_file
 *
 * Implements the [$shp file] command use to query read-only information about
 * the shapefile itself. See cmd_info for queries about the shapefile content.
 *
 * Command Syntax:
 *   [$shp file mode]
 *     Get shapefile access mode. Result is one of readonly or readwrite.
 *   [$shp file path]
 *     Get shapefile path. Not normalized; returned as initially provided.
 *
 * Result:
 *   As described under Command Syntax.
 */
int cmd_file(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {
	
	ShapefilePtr shapefile = (ShapefilePtr)clientData;
	int actionIndex;
	static const char *actionNames[] = {"mode", "path",	NULL};
	
	if (objc != 3) {
		Tcl_WrongNumArgs(interp, 2, objv, "option");
		return TCL_ERROR;
	}
	
	if (Tcl_GetIndexFromObj(interp, objv[2], actionNames, "option",
			0 /* not TCL_EXACT */, &actionIndex) != TCL_OK) {
		return TCL_ERROR;
	}
	
	switch (actionIndex) {
		case 0: /* mode */
			if (shapefile->readonly) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("readonly"));
			} else {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("readwrite"));
			}
			break;
		case 1: /* path */
			Tcl_SetObjResult(interp, Tcl_NewStringObj(shapefile->path, -1));
			break;
	}
	
	return TCL_OK;
}

/*
 * cmd_info
 *
 * Implements the [$shp info] command used to query read-only information about
 * the shapefile content. A dispatcher for subcommand actions.
 *
 * Command Syntax:
 *   [$shp info bounds]
 *     See cmd_info_bounds for details.
 *   [$shp info count]
 *     See cmd_info_count for details.
 *   [$shp info type]
 *     See cmd_info_type for details.
 *
 * Result:
 *   Result of the selected subcommand.
 */
int cmd_info(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {

	int result = TCL_OK;
	int optionIndex;
	static const char *optionNames[] = {"bounds", "count", "type", NULL};

	if (objc < 3) {
		Tcl_WrongNumArgs(interp, 2, objv, "option ?args?");
		return TCL_ERROR;
	}
	
	if (Tcl_GetIndexFromObj(interp, objv[2], optionNames, "option",
			0 /* not TCL_EXACT */, &optionIndex) != TCL_OK) {
		return TCL_ERROR;
	}
	
	switch (optionIndex) {
		case 0: /* bounds */
			result = cmd_info_bounds(clientData, interp, objc, objv);
			break;
		case 1: /* count */
			result = cmd_info_count(clientData, interp, objc, objv);
			break;
		case 2: /* type */
			result = cmd_info_type(clientData, interp, objc, objv);
			break;
	}
	
	return result;
}

/*
 * cmd_info_count
 * 
 * Implements the [$shp info count] action used to get the feature/record count.
 * 
 * Command Syntax:
 *   [$shp info count]
 * 
 * Result:
 *   Number of features in shapefile.
 */
int cmd_info_count(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {
	
	ShapefilePtr shapefile = (ShapefilePtr)clientData;
	int shpCount, dbfCount;
	
	if (objc != 3) {
		Tcl_WrongNumArgs(interp, 3, objv, NULL);
		return TCL_ERROR;
	}
	
	SHPGetInfo(shapefile->shp, &shpCount, NULL, NULL, NULL);
	
	dbfCount = DBFGetRecordCount(shapefile->dbf);
	
	if (shpCount != dbfCount) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("shapefile feature count (%d) does not match attribute table record count (%d)", shpCount, dbfCount));
		return TCL_ERROR;
	}
	
	Tcl_SetObjResult(interp, Tcl_NewIntObj(shpCount));
	return TCL_OK;
}

/*
 * cmd_info_type
 * 
 * Implements the [$shp info type] action used to query feature type.
 * 
 * Command Syntax:
 *   [$shp info type]
 *     Get the geometry type (one of point, multipoint, arc, polygon, pointm,
 *     multipointm, arcm, polygonm, pointz, multipointz, arcz, or polygonz).
 *   [$shp info type numeric]
 *     Get the (non-sequential id) number of the geometry type.
 *   [$shp info type base]
 *     Get the base geometry type (one of point, multipoint, arc, or polygon).
 *   [$shp info type dimension]
 *     Get the geometry dimension (one of xy, xym, or xyzm).
 *
 * Result:
 *   Shapefile geometry type, as described under Command Syntax above.
 */
int cmd_info_type(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {
	
	ShapefilePtr shapefile = (ShapefilePtr)clientData;
	int actionIndex;
	static const char *actionNames[] = {
			"base",
			"dimensions",
			"numeric",
			NULL
	};
	
	if (objc > 4) {
		Tcl_WrongNumArgs(interp, 3, objv, "?option?");
		return TCL_ERROR;
	}
	
	if (objc == 3) {
		/* actionIndex 3 for default case of no special type requested */
		actionIndex = 3;
	} else {
		if (Tcl_GetIndexFromObj(interp, objv[3], actionNames, "option", 0, &actionIndex) != TCL_OK) {
			return TCL_ERROR;
		}
	}
	
	switch (actionIndex) {
		case 0:
			/* base */
			switch (shapefile->baseType) {
				case BASE_POINT:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("point"));
					break;
				case BASE_ARC:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("arc"));
					break;
				case BASE_POLYGON:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("polygon"));
					break;
				case BASE_MULTIPOINT:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("multipoint"));
					break;
			}
			break;
		case 1:
			/* dimension */
			switch (shapefile->dimType) {
				case DIM_XY:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("xy"));
					break;
				case DIM_XYM:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("xym"));
					break;
				case DIM_XYZM:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("xyzm"));
					break;
			}
			break;
		case 2:
			/* numeric */
			Tcl_SetObjResult(interp, Tcl_NewIntObj(shapefile->shapeType));
			break;
		case 3:
		default:
			/* normal */
			switch (shapefile->shapeType) {
				case SHPT_POINT:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("point"));
					break;
				case SHPT_ARC:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("arc"));
					break;
				case SHPT_POLYGON:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("polygon"));
					break;
				case SHPT_MULTIPOINT:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("multipoint"));
					break;
				case SHPT_POINTM:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("pointm"));
					break;
				case SHPT_ARCM:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("arcm"));
					break;
				case SHPT_POLYGONM:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("polygonm"));
					break;
				case SHPT_MULTIPOINTM:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("multipointm"));
					break;
				case SHPT_POINTZ:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("pointz"));
					break;
				case SHPT_ARCZ:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("arcz"));
					break;
				case SHPT_POLYGONZ:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("polygonz"));
					break;
				case SHPT_MULTIPOINTZ:
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("multipointz"));
					break;
			}
			break;
	}
	
	return TCL_OK;
}

/*
 * cmd_info_bounds
 * 
 * Implements the [$shp info bounds] action used to get file or feature extent.
 * 
 * Command Syntax:
 *   [$shp info bounds]
 *     Get the bounding box of all features in the shapefile.
 *   [$shp info bounds FEATURE]
 *     Get the bounding box of the specified feature.
 * 
 * Config Options:
 *   Bounds are normally given as minimum and maximum XY, XYM, or XYZM coords
 *   depending on feature type. However, if the getAllCoords or getOnlyXyCoords
 *   config options are true, the requested coordinate bounds will be returned
 *   regardless of feature type.
 * 
 * Result:
 *   List containing the minimum and maximum vertex values.
 * 
 *   Example:
 *     {Xmin Ymin Xmax Ymax}
 */
int cmd_info_bounds(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {
	
	ShapefilePtr shapefile = (ShapefilePtr)clientData;
	double min[4], max[4];
	Tcl_Obj *bounds;
	int shpCount;
	
	if (objc != 3 && objc != 4) {
		Tcl_WrongNumArgs(interp, 3, objv, "?index?");
		return TCL_ERROR;
	}
	
	/* get the file count & bounds now; we'll need the count to validate the
	   feature index, if given, in which case we'll replace min & max result. */
	SHPGetInfo(shapefile->shp, &shpCount, NULL, min, max);
	
	if (objc == 4) {
		int featureId;
		SHPObject *obj;
		
		if (Tcl_GetIntFromObj(interp, objv[3], &featureId) != TCL_OK) {
			return TCL_ERROR;
		}
		
		if (featureId < 0 || featureId >= shpCount) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid feature index %d", featureId));
			return TCL_ERROR;
		}
		
		if ((obj = SHPReadObject(shapefile->shp, featureId)) == NULL) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to read feature %d", featureId));
			return TCL_ERROR;
		}
		
		if (obj->nSHPType == SHPT_NULL) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("no bounds for null feature"));
			SHPDestroyObject(obj);
			return TCL_ERROR;
		}
		
		min[0] = obj->dfXMin; min[1] = obj->dfYMin; min[2] = obj->dfZMin; min[3] = obj->dfMMin;
		max[0] = obj->dfXMax; max[1] = obj->dfYMax; max[2] = obj->dfZMax; max[3] = obj->dfMMax;
		
		SHPDestroyObject(obj);
	}
	
	bounds = Tcl_NewListObj(0, NULL);
	Tcl_ListObjAppendElement(interp, bounds, Tcl_NewDoubleObj(min[0]));
	Tcl_ListObjAppendElement(interp, bounds, Tcl_NewDoubleObj(min[1]));
	if (!shapefile->getOnlyXyCoords) {
		if (shapefile->getAllCoords
				|| shapefile->dimType == DIM_XYZM) {
			Tcl_ListObjAppendElement(interp, bounds, Tcl_NewDoubleObj(min[2]));
		}
		if (shapefile->getAllCoords
				|| shapefile->dimType == DIM_XYZM
				|| shapefile->dimType == DIM_XYM) {
			Tcl_ListObjAppendElement(interp, bounds, Tcl_NewDoubleObj(min[3]));
		}
	}
	Tcl_ListObjAppendElement(interp, bounds, Tcl_NewDoubleObj(max[0]));
	Tcl_ListObjAppendElement(interp, bounds, Tcl_NewDoubleObj(max[1]));
	if (!shapefile->getOnlyXyCoords) {
		if (shapefile->getAllCoords
				|| shapefile->dimType == DIM_XYZM) {
			Tcl_ListObjAppendElement(interp, bounds, Tcl_NewDoubleObj(max[2]));
		}
		if (shapefile->getAllCoords
				|| shapefile->dimType == DIM_XYZM
				|| shapefile->dimType == DIM_XYM) {
			Tcl_ListObjAppendElement(interp, bounds, Tcl_NewDoubleObj(max[3]));
		}	
	}
	
	Tcl_SetObjResult(interp, bounds);
	return TCL_OK;
}

/*
 * cmd_fields
 * 
 * Implements the [$shp fields] command used to query attribute table format.
 * Also used to modify attribute table format, eg. by adding fields.
 * 
 * Command Syntax:
 *   [$shp fields count]
 *     Get the number of fields in the attribute table.
 *   [$shp fields list ?FIELD?]
 *     Get the field definitions for all or one attribute field.
 *   [$shp fields add FIELDDEFINITIONS ?DEFAULTVALUELIST?]
 *     Add one or more fields to the attribute table. New fields of existing
 *     attribute records are populated with values from DEFAULTVALUELIST, if
 *     given, otherwise NULL values are assigned.
 *   [$shp field index FIELDNAME]
 *     Get the index of a field with the given name.
 * 
 * Field Definitions:
 *   Each field is defined by four properties: type, name, width, and precision.
 *   Supported types are string, integer, and double (floating-point numbers).
 *   Names are strings up to 10 characters long. Width specifies field width:
 *   the number of characters reserved for string fields, or the maximum number
 *   of digits for numeric fields (including the decimal point). Precision gives
 *   the number of digits to the right of the decimal point for doubles, and
 *   should be given as 0 for all other field types. A field definition list is
 *   a sequence of these four properties repeated for each field.
 * 
 *   Examples:
 *     {integer ID 5 0}
 *       An integer field titled "ID". 5 digit maximum (NNNNN).
 *     {string Name 30 0 double Measure 12 4}
 *       A 30-character max "Name" and a 7.4 digit "Measure" (NNNNNNN.NNNN).
 * 
 * Result:
 *   count action returns number of fields.
 *   list action returns a Field Definitions list (see above).
 *   add action returns field index of last new field added.
 *   name action returns named field index or error if none
 */
int cmd_fields(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {
	
	ShapefilePtr shapefile = (ShapefilePtr)clientData;
	int fieldCount, fieldId;
	int actionIndex;
	static const char *actionNames[] = {
			"add",
			"count",
			"list",
			"index",
			NULL
	};
	
	if (objc < 3) {
		Tcl_WrongNumArgs(interp, 2, objv, "action ?args?");
		return TCL_ERROR;
	}
	if (Tcl_GetIndexFromObj(interp, objv[2], actionNames, "action", TCL_EXACT, &actionIndex) != TCL_OK) {
		return TCL_ERROR;
	}
	
	fieldCount = DBFGetFieldCount(shapefile->dbf);

	switch (actionIndex) {
		case 0: /* add */
			if (objc > 5) {
				Tcl_WrongNumArgs(interp, 3, objv, "fieldDefinitions ?defaultValueList?");
				return TCL_ERROR;
			}
			if (shapefile->readonly) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("cannot add field to readonly shapefile"));
				return TCL_ERROR;
			}
			/* sets interp result to index of last added field */
			if (objc == 4) {
				if (cmd_fields_add(interp, shapefile->dbf, 1 /* validate */, objv[3], NULL, NULL) != TCL_OK) {
					return TCL_ERROR;
				}
			} else if (objc == 5) {
				/* if a default value list is provided, pass it along */
				if (cmd_fields_add(interp, shapefile->dbf, 1 /* validate */, objv[3], objv[4], shapefile) != TCL_OK) {
					return TCL_ERROR;
				}
			}
			break;
		case 1: /* count */
			if (objc > 3) {
				Tcl_WrongNumArgs(interp, 3, objv, NULL);
				return TCL_ERROR;
			}
			Tcl_SetObjResult(interp, Tcl_NewIntObj(fieldCount));
			break;
		case 2: /* list */
			if (objc > 4) {
				Tcl_WrongNumArgs(interp, 3, objv, "?fieldIndex?");
				return TCL_ERROR;
			}
			if (objc == 4) {
				/* list a specific field's definition */
				if (Tcl_GetIntFromObj(interp, objv[3], &fieldId) != TCL_OK) {
					return TCL_ERROR;
				}
				if (fieldId < 0 || fieldId >= fieldCount) {
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid field index %d", fieldId));
					return TCL_ERROR;
				}
				if (cmd_fields_description(interp, shapefile, fieldId) != TCL_OK) {
					return TCL_ERROR;
				}
			} else {
				/* list all field definitions */
				Tcl_Obj *descriptions = Tcl_NewListObj(0, NULL);
				for (fieldId = 0; fieldId < fieldCount; fieldId++) {
				
					/* get information about this field */
					if (cmd_fields_description(interp, shapefile, fieldId) != TCL_OK) {
						return TCL_ERROR;
					}
				
					/* append information about this field to our list of information about all fields */
					if (Tcl_ListObjAppendList(interp, descriptions, Tcl_GetObjResult(interp)) != TCL_OK) {
						return TCL_ERROR;
					}
				
					Tcl_ResetResult(interp);
				}
			
				Tcl_SetObjResult(interp, descriptions);
			}
			break;
		case 3: /* index */
			if (objc != 4) {
				Tcl_WrongNumArgs(interp, 3, objv, "fieldName");
				return TCL_ERROR;
			}
			/* sets interp result to field index, or not-found error message */
			if (cmd_fields_index(interp, shapefile, Tcl_GetString(objv[3])) != TCL_OK) {
				return TCL_ERROR;
			}
			break;
	}

	return TCL_OK;
}

/*
 * cmd_fields_add
 * 
 * Implements the [$shp fields add FIELDDEFINITIONS ?DEFAULTVALUELIST?] action
 # of the [$shp fields] command, used to add new fields to an existing attribute
 # table. Also used by the [shapefile] command to add initial fields to new
 # attribute tables. Field values in DEFAULTVALUELIST used for existing records.
 * 
 * Note that this function takes a DBFHandle argument, instead of a ShapefilePtr
 * like most other util functions, because it may be used by [shapefile] before
 * the ShapefilePtr structure is allocated.
 * 
 * Result:
 *   Index number of the last field added to the attribute table.
 */
int cmd_fields_add(
		Tcl_Interp *interp,
		DBFHandle dbf,
		int validate,
		Tcl_Obj *definitions,
		Tcl_Obj *attrList,
		ShapefilePtr shapefile) {
			
	Tcl_Obj **definitionElements;
	int definitionElementCount, i, field, fieldCount, attrCount;
	const char *type, *name;
	int width, precision;
	int fieldId = 0;
	Tcl_Obj *attr;
	int record, recordCount;
	
	/* check field definition list formatting if not already validated */
	if (validate && (cmd_fields_validate(interp, definitions, dbf) != TCL_OK)) {
		return TCL_ERROR;
	}
	
	if (Tcl_ListObjGetElements(interp, definitions, &definitionElementCount, &definitionElements) != TCL_OK) {
		return TCL_ERROR;
	}
	
	fieldCount = definitionElementCount / 4;

	/* validate default attribute value list, if given */
	if (attrList != NULL && shapefile != NULL) {
		
		/* count how many values are in the attribute list */
		if (Tcl_ListObjLength(interp, attrList, &attrCount) != TCL_OK) {
			return TCL_ERROR;
		}
		
		/* assert that there is one and one only value for each new field */
		if (attrCount != fieldCount) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("default attribute value count (%d) does not match new field count (%d)", attrCount, fieldCount));
			return TCL_ERROR;
		}
		
		recordCount = DBFGetRecordCount(dbf);
	}

	/* add fields to the dbf. field variable indexes the new field/attrs. */
	for (i = 0, field = 0; i < definitionElementCount; i += 4, field++) {
		if (((type = Tcl_GetString(definitionElements[i])) == NULL)
				|| ((name = Tcl_GetString(definitionElements[i + 1])) == NULL)
				|| (Tcl_GetIntFromObj(interp, definitionElements[i + 2], &width) != TCL_OK)
				|| (Tcl_GetIntFromObj(interp, definitionElements[i + 3], &precision) != TCL_OK)) {
			return TCL_ERROR;
		}
				
		if (strcmp(type, "integer") == 0) {
			if ((fieldId = DBFAddField(dbf, name, FTInteger, width, 0)) == -1) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to create integer attribute field \"%s\"", name));
				return TCL_ERROR;
			}
		}
		else if (strcmp(type, "double") == 0) {
			if ((fieldId = DBFAddField(dbf, name, FTDouble, width, precision)) == -1) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to create double attribute field \"%s\"", name));
				return TCL_ERROR;
			}
		}
		else if (strcmp(type, "string") == 0) {
			if ((fieldId = DBFAddField(dbf, name, FTString, width, 0)) == -1) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to create string attribute field \"%s\"", name));
				return TCL_ERROR;
			}
		}
		else {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("unsupported field type: \"%s\"", type));
			return TCL_ERROR;
		}
		
		/* write default value for this field to all existing records */
		if (attrList != NULL && shapefile != NULL) {

			/* arguably the validation should occur before the fields are added,
			   so that if any of the default values are bogus, the function call
			   fails without adding fields that lack intended default values. */
			
			/* get the default attribute value for this new field. */
			if (Tcl_ListObjIndex(interp, attrList, field, &attr) != TCL_OK) {
				return TCL_ERROR;
			}
			
			/* validate that it is compatible with the new field definition */
			if (cmd_attributes_validateField(interp, shapefile, fieldId, attr) != TCL_OK) {
				return TCL_ERROR;
			}
			
			/* write it to every record we have so far. */
			for (record = 0; record < recordCount; record++) {
				if (cmd_attributes_writeField(interp, shapefile, record, fieldId, 0, attr) != TCL_OK) {
					return TCL_ERROR;
				}
			}
		}
	}
	
	Tcl_SetObjResult(interp, Tcl_NewIntObj(fieldId));
	return TCL_OK;
}

/*
 * cmd_fields_validate
 * 
 * Check that a field definitions list contains valid field definitions. Used
 * by the [$shp fields add] action in contexts where field definitions have not
 * been pre-validated, as when invoked by the [shapefile] command when creating
 * new shapefiles. If dbf parameter is non-null, new field names are checked
 * for uniqueness against extant fields in dbf as well as in definitions.
 * 
 * Result:
 *   No Tcl result if the field definitions are valid. Otherwise, throws error.
 */
int cmd_fields_validate(
		Tcl_Interp *interp,
		Tcl_Obj *definitions,
		DBFHandle dbf) {
			
	Tcl_Obj **definitionElements;
	int definitionElementCount, i, j;
	const char *type, *name;
	char *preName, dbfName[12];
	int width, precision;
	
	if (Tcl_ListObjGetElements(interp, definitions, &definitionElementCount, &definitionElements) != TCL_OK) {
		return TCL_ERROR;
	}
	
	if (definitionElementCount % 4 != 0) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("malformed field definition: type, name, width, and precision expected"));
		return TCL_ERROR;
	}
	
	if (definitionElementCount == 0) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("missing field definition: at least one field definition is required"));
		return TCL_ERROR;
	}

	/* validate field specifications before creating dbf */	
	for (i = 0; i < definitionElementCount; i += 4) {
		
		if (       ((type = Tcl_GetString(definitionElements[i])) == NULL)
				|| ((name = Tcl_GetString(definitionElements[i + 1])) == NULL)
				|| (Tcl_GetIntFromObj(interp, definitionElements[i + 2], &width) != TCL_OK)
				|| (Tcl_GetIntFromObj(interp, definitionElements[i + 3], &precision) != TCL_OK)) {
			return TCL_ERROR;
		}
		
		if (cmd_fields_validateField(interp, type, name, width, precision) != TCL_OK) {
			return TCL_ERROR;
		}
		
		/* check that this name is not a duplicate of others given here */
		for (j = 0; j < i; j+= 4) {
			preName = Tcl_GetString(definitionElements[j + 1]);
			if (strcasecmp(preName, name) == 0) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid field name: duplicate names disallowed (%s)", name));
				return TCL_ERROR;
			}
		}
		
		/* also check that this name is not a dupe of any existing fields */
		if (dbf != NULL) {
			for (j = 0; j < DBFGetFieldCount(dbf); j++) {
				(void)DBFGetFieldInfo(dbf, j, dbfName, NULL, NULL);
				if (strcasecmp(dbfName, name) == 0) {
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid field name: duplicate names disallowed (%s)", name));
					return TCL_ERROR;
				}
			}
		}
	}
	
	return TCL_OK;
}

/*
 * cmd_fields_validateField
 * 
 * Check that a single field definition describes a valid attribute table
 * field. Used by the cmd_fields_validate function.
 * 
 * Result:
 *   No Tcl result if the field definition is valid. Otherwise, throws error.
 */
int cmd_fields_validateField(
		Tcl_Interp *interp,
		const char *type,
		const char *name,
		int width,
		int precision) {
	
	if (strcmp(type, "string") != 0 && strcmp(type, "integer") != 0 && strcmp(type, "double") != 0) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid field type \"%s\": should be string, integer, or double", type));
		return TCL_ERROR;
	}
	
	if (cmd_fields_validateFieldName(interp, name) != TCL_OK) {
		return TCL_ERROR;
	}
	
	if (strcmp(type, "integer") == 0 && width > 11) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid integer field definition: maximum signed 32-bit integer width is 11 digits (%d is too wide)", width));
		return TCL_ERROR;
	}
	
	if (strcmp(type, "double") == 0 && width <= 11 && precision == 0) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid double field definition: numeric field with width <=11 digits (%d) and 0 precision is an integer", width));
		return TCL_ERROR;
	}
	
	return TCL_OK;
}

/*
 * cmd_fields_validateFieldName
 * 
 * Confirm that candidate field name conforms to convention. Note that Shapelib
 * does not impose any limits on field name format other than truncating long
 * names, but other [older] DBF/GIS applications may have trouble reading names
 * that do not conform, so we err on the strictness to ensure compatibility.
 * 
 * Result:
 *   No Tcl result if field name is valid. Otherwise, throws error.
 */
int cmd_fields_validateFieldName(
		Tcl_Interp *interp,
		const char *name) {
		
	/* check for maximum name length */
	if (strlen(name) > 10) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid field name \"%s\": too long (10 characters maximum)", name));
		return TCL_ERROR;
	}
	
	/* check for minimum field length */
	if (strlen(name) < 1) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid field name: too short (1 character minimum)"));
		return TCL_ERROR;
	}
	
	/* check for legal characters */
	if (strspn(name, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_") != strlen(name)) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid field name: only alphanumeric and underscore characters allowed"));
		return TCL_ERROR;
	}
	
	/* check for alphabetic starting character */
	if (strchr("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ", name[0]) == NULL) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid field name: first character must be alphabetic"));
		return TCL_ERROR;
	}
	
	return TCL_OK;
}

/*
 * cmd_fields_description
 * 
 * Get field definition list of specified attribute table field. Used by the
 * [$shp fields list ?FIELD?] action. See [$shp fields] command for details.
 * 
 * Result:
 *   Field definition list for the specified field.
 */
int cmd_fields_description(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		int fieldId) {
	
	char name[12];
	int width, precision;
	DBFFieldType type;
	Tcl_Obj *description;
	
	description = Tcl_NewListObj(0, NULL);
	type = DBFGetFieldInfo(shapefile->dbf, fieldId, name, &width, &precision);
	
	switch (type) {
		case FTString:
			if (Tcl_ListObjAppendElement(interp, description, Tcl_NewStringObj("string", -1)) != TCL_OK) {
				return TCL_ERROR;
			}
			break;
		case FTInteger:
			if (Tcl_ListObjAppendElement(interp, description, Tcl_NewStringObj("integer", -1)) != TCL_OK) {
				return TCL_ERROR;
			}
			break;
		case FTDouble:
			if (Tcl_ListObjAppendElement(interp, description, Tcl_NewStringObj("double", -1)) != TCL_OK) {
				return TCL_ERROR;
			}
			break;
		default:
			/* represent unsupported field types by numeric type ID instead of descriptive name */
			if (Tcl_ListObjAppendElement(interp, description, Tcl_NewIntObj((int)type)) != TCL_OK) {
				return TCL_ERROR;
			}
			break;
	}
	
	if (Tcl_ListObjAppendElement(interp, description, Tcl_NewStringObj(name, -1)) != TCL_OK) {
		return TCL_ERROR;
	}
	if (Tcl_ListObjAppendElement(interp, description, Tcl_NewIntObj(width)) != TCL_OK) {
		return TCL_ERROR;
	}
	if (Tcl_ListObjAppendElement(interp, description, Tcl_NewIntObj(precision)) != TCL_OK) {
		return TCL_ERROR;
	}
	
	Tcl_SetObjResult(interp, description);
	return TCL_OK;
}

/*
 * cmd_fields_index
 *
 * Implements the [$shp fields index] action used to look up a field by name.
 * Field name search is case insensitive. Finds the first field of given name.
 *
 * Result:
 *   Index of named field, or error if no such field is found.
 *
 */
int cmd_fields_index(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		const char *fieldName) {
	
	int fieldIndex;
	
	if (fieldName == NULL || strlen(fieldName) == 0) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("missing field name"));
		return TCL_ERROR;
	}
	
	fieldIndex = DBFGetFieldIndex(shapefile->dbf, fieldName);
	
	if (fieldIndex == -1) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("field named \"%s\" not found", fieldName));
		return TCL_ERROR;
	}
	
	Tcl_SetObjResult(interp, Tcl_NewIntObj(fieldIndex));
	return TCL_OK;
}

/*
 * cmd_coordinates
 * 
 * Implements the [$shp coordinates] command used to get/set feature geometry.
 * 
 * Command Syntax:
 *   [$shp coordinates read FEATURE]
 *     Get the coordinates of one feature.
 *   [$shp coordinates read]
 *     Get the coordinates of all features.
 *   [$shp coordinates write FEATURE COORDINATES]
 *     Set the coordinates of one feature.
 *   [$shp coordinates write COORDINATES]
 *     Set the coordinates of a new feature. The feature is appended to the
 *     shapefile. A new attribute record is also created, populated with NULLs.
 * 
 * Coordinate Lists:
 *   Features are comprised of parts; a coordinate list is a list of parts,
 *   each of which is a list of the vertices which comprise the part. Each
 *   vertex of a feature part is represented by 2, 3, or 4 coordinate values,
 *   depending on the feature type (XY, XYM, or XYZM) - but see Config Options.
 *   Point feature types only have one part, but others may have multiple.
 *   Clockwise or counterclockwise vertex order of polygon parts indicates
 *   whether the part represents an outer or inner ring (islands or holes).
 *   Polygon parts must be closed and have at least four vertices. 
 *
 *   2D Examples:
 *     Point:      {{X Y}}
 *     Multipoint: {{X1 Y1} {X2 Y2}}
 *     Arc:        {{X1 Y1 X2 Y2 X3 Y3}}
 *     Polygon:    {{X1 Y1 X2 Y2 X3 Y3 X1 Y1} {X1' Y1' X3' Y3' X2' Y2' X1' Y1'}}
 * 
 * Config Options:
 *   The format of coordinate lists returned by [$shp coordinates read] may be
 *   overruled if the getAllCoords or getOnlyXyCoords config options are true.
 * 
 * Result:
 *   Read actions return coordinate lists or lists of coordinate lists.
 *   Write actions return the index of the written feature.
 */
int cmd_coordinates(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {
	
	ShapefilePtr shapefile = (ShapefilePtr)clientData;
	int featureId;
	int subcommandIndex;
	static const char *subcommandNames[] = {
			"read",
			"write",
			NULL
	};
	
	if (objc < 3) {
		Tcl_WrongNumArgs(interp, 2, objv, "action ?args?");
		return TCL_ERROR;
	}
	if (Tcl_GetIndexFromObj(interp, objv[2], subcommandNames, "action",
			TCL_EXACT, &subcommandIndex) != TCL_OK) {
		return TCL_ERROR;
	}
	
	if (subcommandIndex == 0) {
		/* read coords */
		
		if (objc == 3) {
			/* return coords of all features */
			if (cmd_coordinates_readAll(interp, shapefile) != TCL_OK) {
				return TCL_ERROR;
			}
		} else if (objc == 4) {
		
			/* get feature index to read */			
			if (Tcl_GetIntFromObj(interp, objv[3], &featureId) != TCL_OK) {
				return TCL_ERROR;
			}
			
			/* return coords of specified feature index */
			if (cmd_coordinates_read(interp, shapefile, featureId) != TCL_OK) {
				return TCL_ERROR;
			}
			
		} else {
			Tcl_WrongNumArgs(interp, 3, objv, "?index?");
			return TCL_ERROR;
		}
	} else if (subcommandIndex == 1) {
		/* write coords */
		
		if (objc == 4) {
			/* write coords to a new feature; create complementary blank attribute record */
			int recordId;
			
			/* write coords to a new feature */
			if (cmd_coordinates_write(interp, shapefile, -1, objv[3]) != TCL_OK) {
				return TCL_ERROR;
			}
			
			Tcl_GetIntFromObj(interp, Tcl_GetObjResult(interp), &featureId);
			Tcl_ResetResult(interp);
			
			/* interp result is new feature id; create a null attribute record to match */
			if (cmd_attributes_write(interp, shapefile, -1, 0, NULL) != TCL_OK) {
				return TCL_ERROR;
			}
			
			Tcl_GetIntFromObj(interp, Tcl_GetObjResult(interp), &recordId);
			if (featureId != recordId) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("new feature index (%d) does not match new empty attribute record index (%d)", featureId, recordId));
				return TCL_ERROR;
			}
				
		} else if (objc == 5) {
			/* write coords to a specific feature index */
			
			/* get feature index to overwrite */
			if (Tcl_GetIntFromObj(interp, objv[3], &featureId) != TCL_OK) {
				return TCL_ERROR;
			}

			if (featureId == -1) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid feature index %d (use write command)", featureId));
				return TCL_ERROR;
			}
			
			/* if shape output is successful, interp result is set to output feature id */
			if (cmd_coordinates_write(interp, shapefile, featureId, objv[4]) != TCL_OK) {
				return TCL_ERROR;
			}
		} else {
			Tcl_WrongNumArgs(interp, 3, objv, "?index? coordinates");
			return TCL_ERROR;
		}
	}
		
	return TCL_OK;
}

/*
 * cmd_coordinates_write
 * 
 * Implements the [$shp coordinates write ?FEATURE? COORDINATELIST] actions of
 * the [$shp coordinates] command, used to set the coordinates of a new feature
 * or to overwrite the coordinates of an existing feature.
 * 
 * Result:
 *   Index number of the feature that was written.
 */
int cmd_coordinates_write(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		int featureId,
		Tcl_Obj *coordParts) {
	
	int featureCount;
	int outputFeatureId;
	int *partStarts;
	Tcl_Obj *coords, *coord;
	int part, partCount, partCoord, partCoordCount;
	int vertex, vertexCount, partVertexCount;
	double *xCoords, *yCoords, *zCoords, *mCoords;
	double x, y, z, m;
	SHPObject *shape;
	int returnValue = TCL_OK;
	int coordinatesPerVertex;
	
	if (shapefile->readonly) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("cannot write coordinates to readonly shapefile"));
		return TCL_ERROR;
	}
	
	SHPGetInfo(shapefile->shp, &featureCount, NULL, NULL, NULL);
	if (featureId < -1 || featureId >= featureCount) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid feature index %d", featureId));
		return TCL_ERROR;
	}
	/* a featureId of -1 indicates a new feature should be output */
	
	/* write a null feature if the coordinate list is a NULL pointer */
	if (coordParts == NULL) {
		return cmd_coordinates_writeNull(interp, shapefile, featureId);
	}
	
	if (Tcl_ListObjLength(interp, coordParts, &partCount) != TCL_OK) {
		return TCL_ERROR;
	}
	
	/* also write a null feature if the if the coordinate list is empty */
	if (partCount == 0) {
		return cmd_coordinates_writeNull(interp, shapefile, featureId);
	}
	
	/* validate feature by number of parts according to shape type */
	if (partCount > 1
			&& (shapefile->baseType == BASE_POINT
				|| shapefile->baseType == BASE_MULTIPOINT)) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid part count (%d): point and multipoint features must have exactly 1 part", partCount));
		return TCL_ERROR;
	}
	
	/* determine how many coordinates to expect for each vertex */
	if (shapefile->dimType == DIM_XYZM) {
		coordinatesPerVertex = 4;
	} else if (shapefile->dimType == DIM_XYM) {
		coordinatesPerVertex = 3;
	} else {
		coordinatesPerVertex = 2;
	}
		
	if ((partStarts = (int *)ckalloc((unsigned int)(sizeof(int) * partCount))) == NULL) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to allocate coordinate part index array"));
		return TCL_ERROR;
	}
	xCoords = NULL; yCoords = NULL; zCoords = NULL; mCoords = NULL;

	vertex = 0;
	vertexCount = 0;
	
	for (part = 0; part < partCount; part++) {
		partStarts[part] = vertex;
		
		/* get the coordinates that comprise this part */
		if (Tcl_ListObjIndex(interp, coordParts, part, &coords) != TCL_OK) {
			returnValue = TCL_ERROR;
			goto cwRelease;
		}
		
		/* verify that the coordinate list has a valid number of elements */
		if (Tcl_ListObjLength(interp, coords, &partCoordCount) != TCL_OK) {
			returnValue = TCL_ERROR;
			goto cwRelease;
		}
		if (partCoordCount % coordinatesPerVertex != 0) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("%d coordinate values are expected for each vertex", coordinatesPerVertex));
			returnValue = TCL_ERROR;
			goto cwRelease;
		}
		partVertexCount = partCoordCount / coordinatesPerVertex;
		
		/* validate part by number of vertices according to shape type */
		if (partVertexCount != 1 && shapefile->baseType == BASE_POINT) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid vertex count (%d): point features must have exactly one vertex per part", partVertexCount));
			returnValue = TCL_ERROR;
			goto cwRelease;
		}
		if (partVertexCount < 1 && shapefile->baseType == BASE_MULTIPOINT) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid vertex count (%d): multipoint features must have at least one vertex per part", partVertexCount));
			returnValue = TCL_ERROR;
			goto cwRelease;
		}
		if (partVertexCount < 2 && shapefile->baseType == BASE_ARC) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid vertex count (%d): arc features must have at least 2 vertices per part", partVertexCount));
			returnValue = TCL_ERROR;
			goto cwRelease;
		}
		if (shapefile->baseType == BASE_POLYGON
				&& ((partVertexCount < 3 && shapefile->autoClosePolygons)
				|| (partVertexCount < 4 && !shapefile->autoClosePolygons))) {
			/* 3 vertices per part is ok if autoClosePolygons is enabled */
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid vertex count (%d): polygon features must have at least 4 vertices per part", partVertexCount));
			returnValue = TCL_ERROR;
			goto cwRelease;
		}
				
		/* add space for this part's vertices */
		vertexCount += partVertexCount;
		xCoords = (double *)ckrealloc((char *)xCoords, (unsigned int)(sizeof(double) * vertexCount));
		yCoords = (double *)ckrealloc((char *)yCoords, (unsigned int)(sizeof(double) * vertexCount));
		if (shapefile->dimType == DIM_XYZM) {
			zCoords = (double *)ckrealloc((char *)zCoords, (unsigned int)(sizeof(double) * vertexCount));
		}
		if (shapefile->dimType == DIM_XYZM || shapefile->dimType == DIM_XYM) {	
			mCoords = (double *)ckrealloc((char *)mCoords, (unsigned int)(sizeof(double) * vertexCount));
		}
		if (xCoords == NULL || yCoords == NULL ||
				(shapefile->dimType == DIM_XYZM && zCoords == NULL) ||
				((shapefile->dimType == DIM_XYZM || shapefile->dimType == DIM_XYM) && mCoords == NULL)) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to reallocate memory for coordinate arrays"));
			returnValue = TCL_ERROR;
			goto cwRelease;
		}
		
		for (partCoord = 0; partCoord < partCoordCount; partCoord += coordinatesPerVertex) {
			
			/* x */
			if (Tcl_ListObjIndex(interp, coords, partCoord, &coord) != TCL_OK) {
				returnValue = TCL_ERROR;
				goto cwRelease;
			}
			if (Tcl_GetDoubleFromObj(interp, coord, &x) != TCL_OK) {
				returnValue = TCL_ERROR;
				goto cwRelease;
			}
			xCoords[vertex] = x;
			
			/* y */
			if (Tcl_ListObjIndex(interp, coords, partCoord + 1, &coord) != TCL_OK) {
				returnValue = TCL_ERROR;
				goto cwRelease;
			}
			if (Tcl_GetDoubleFromObj(interp, coord, &y) != TCL_OK) {
				returnValue = TCL_ERROR;
				goto cwRelease;
			}
			yCoords[vertex] = y;
			
			/* z & m */
			if (shapefile->dimType == DIM_XYZM) {
				if (Tcl_ListObjIndex(interp, coords, partCoord + 2, &coord) != TCL_OK) {
					returnValue = TCL_ERROR;
					goto cwRelease;
				}
				if (Tcl_GetDoubleFromObj(interp, coord, &z) != TCL_OK) {
					returnValue = TCL_ERROR;
					goto cwRelease;
				}
				zCoords[vertex] = z;
				
				if (Tcl_ListObjIndex(interp, coords, partCoord + 3, &coord) != TCL_OK) {
					returnValue = TCL_ERROR;
					goto cwRelease;
				}
				if (Tcl_GetDoubleFromObj(interp, coord, &m) != TCL_OK) {
					returnValue = TCL_ERROR;
					goto cwRelease;
				}
				mCoords[vertex] = m;
			}
			
			/* m only */
			if (shapefile->dimType == DIM_XYM) {
				if (Tcl_ListObjIndex(interp, coords, partCoord + 2, &coord) != TCL_OK) {
					returnValue = TCL_ERROR;
					goto cwRelease;
				}
				if (Tcl_GetDoubleFromObj(interp, coord, &m) != TCL_OK) {
					returnValue = TCL_ERROR;
					goto cwRelease;
				}
				mCoords[vertex] = m;
			}
			
			vertex++;
		}
				 
		/* polygon coordinate lists with only 3 vertices are allowed if
		 * autoClosePolygons is enabled since we might add a fourth closing
		 * vertex. However, if it is already closed, it is really only two
		 * points - a line segment, which has zero area, invalid for a polygon.
		 * Adding a copy of one endpoint as a 4th vertex won't change that. */
		if (	(shapefile->baseType == BASE_POLYGON)
			 && (partVertexCount == 3)
			 && ((xCoords[partStarts[part]] == xCoords[vertex-1])
			  && (yCoords[partStarts[part]] == yCoords[vertex-1])
			  && (shapefile->dimType == DIM_XYZM ? (zCoords[partStarts[part]] == zCoords[vertex-1]) : 1)
			  && ((shapefile->dimType == DIM_XYZM || shapefile->dimType == DIM_XYM) ? (mCoords[partStarts[part]] == mCoords[vertex-1]) : 1))) {
			 Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid part geometry: closed ring with only 3 vertices"));
			 returnValue = TCL_ERROR;
			 goto cwRelease;
		}
		
		/* validate that the first and last vertex of polygon parts match */
		if ((shapefile->baseType == BASE_POLYGON)
				&& ((xCoords[partStarts[part]] != xCoords[vertex-1])
				|| (yCoords[partStarts[part]] != yCoords[vertex-1])
				|| (shapefile->dimType == DIM_XYZM && (zCoords[partStarts[part]] != zCoords[vertex-1]))
				|| ((shapefile->dimType == DIM_XYZM || shapefile->dimType == DIM_XYM) && (mCoords[partStarts[part]] != mCoords[vertex-1])))) {
			if (shapefile->autoClosePolygons) {
				/* close the part automatically by appending the first vertex */
				partVertexCount++;
				vertexCount++;
				xCoords = (double *)ckrealloc((char *)xCoords, (unsigned int)(sizeof(double) * vertexCount));
				yCoords = (double *)ckrealloc((char *)yCoords, (unsigned int)(sizeof(double) * vertexCount));
				if (shapefile->dimType == DIM_XYZM) {
					zCoords = (double *)ckrealloc((char *)zCoords, (unsigned int)(sizeof(double) * vertexCount));
				}
				if (shapefile->dimType == DIM_XYZM || shapefile->dimType == DIM_XYM) {
					mCoords = (double *)ckrealloc((char *)mCoords, (unsigned int)(sizeof(double) * vertexCount));
				}
				if (xCoords == NULL || yCoords == NULL ||
						(shapefile->dimType == DIM_XYZM && zCoords == NULL) ||
						((shapefile->dimType == DIM_XYZM || shapefile->dimType == DIM_XYM) && mCoords == NULL)) {
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to reallocate coordinate arrays for closing vertex"));
					returnValue = TCL_ERROR;
					goto cwRelease;
				}
				xCoords[vertex] = xCoords[partStarts[part]];
				yCoords[vertex] = yCoords[partStarts[part]];
				if (shapefile->dimType == DIM_XYZM) {
					zCoords[vertex] = zCoords[partStarts[part]];
				}
				if (shapefile->dimType == DIM_XYZM || shapefile->dimType == DIM_XYM) {
					mCoords[vertex] = mCoords[partStarts[part]];
				}
				vertex++;
			} else {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid part geometry: polygon rings must be closed (begin and end with the same vertex)"));
				returnValue = TCL_ERROR;
				goto cwRelease;
			}
		}
	}
	
	/* assemble the coordinate lists into a new shape (z & m may be NULL) */
	if ((shape = SHPCreateObject(shapefile->shapeType, featureId, partCount,
			partStarts, NULL, vertexCount, xCoords, yCoords, zCoords, mCoords)) == NULL) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to create shape object"));
		returnValue = TCL_ERROR;
		goto cwRelease;
	}
	
	/* correct the shape's vertex order, if necessary */
	SHPRewindObject(shapefile->shp, shape);
	
	/* write the shape to the shapefile */
	if ((outputFeatureId = SHPWriteObject(shapefile->shp, featureId, shape)) == -1) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to write shape object"));
		returnValue = TCL_ERROR;
		goto cwDestroyRelease;
	}

	Tcl_SetObjResult(interp, Tcl_NewIntObj(outputFeatureId));
	
   cwDestroyRelease:
	SHPDestroyObject(shape);
	
   cwRelease:
	if (partStarts != NULL) ckfree((char *)partStarts);
	if (xCoords != NULL) ckfree((char *)xCoords);
	if (yCoords != NULL) ckfree((char *)yCoords);
	if (zCoords != NULL) ckfree((char *)zCoords);
	if (mCoords != NULL) ckfree((char *)mCoords);
	
	return returnValue;
}

/*
 * cmd_coordinates_writeNull
 *
 * Write a null feature (a no-geometry placeholder); used by [$shp coordinates]
 * when no coordinate list is present.
 *
 * Result:
 *   Index number of the null feature that was written.
 */
int cmd_coordinates_writeNull(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		int featureId) {
	
	int outputFeatureId;
	SHPObject *shape;
	
	if ((shape = SHPCreateSimpleObject(SHPT_NULL, 0, NULL, NULL, NULL)) == NULL) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to create NULL shape object"));
		return TCL_ERROR;
	}

	if ((outputFeatureId = SHPWriteObject(shapefile->shp, featureId, shape)) == -1) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to write shape object"));
		return TCL_ERROR;
	}

	Tcl_SetObjResult(interp, Tcl_NewIntObj(outputFeatureId));
	return TCL_OK;
}

/*
 * cmd_coordinates_readAll
 * 
 * Implements the [$shp coordinates read] action of the [$shp coordinates]
 * command, used to get a list of coordinate lists for all shapefile features.
 * 
 * Result:
 *   List containing a coordinate list for each feature in shapefile.
 */
int cmd_coordinates_readAll(
		Tcl_Interp *interp,
		ShapefilePtr shapefile) {
	
	Tcl_Obj *featureList;
	int shpCount, featureId;
	
	featureList = Tcl_NewListObj(0, NULL);
	SHPGetInfo(shapefile->shp, &shpCount, NULL, NULL, NULL);
	
	for (featureId = 0; featureId < shpCount; featureId++) {
		
		if (cmd_coordinates_read(interp, shapefile, featureId) != TCL_OK) {
			return TCL_ERROR;
		}
		
		if (Tcl_ListObjAppendElement(interp, featureList, Tcl_GetObjResult(interp)) != TCL_OK) {
			return TCL_ERROR;
		}
		
		Tcl_ResetResult(interp);
	}
	
	Tcl_SetObjResult(interp, featureList);
	return TCL_OK;
}

/*
 * cmd_coordinates_read
 * 
 * Implements the [$shp coordinates read FEATURE] action of the [$shp
 * coordinates] command, used to get coordinate list of the specified featured.
 * Also used by the [$shp coordinates read] action to get each feature's coords.
 * 
 * Result:
 *   Coordinate list for the specified feature.
 */
int cmd_coordinates_read(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		int featureId) {
	
	SHPObject *shape;
	Tcl_Obj *coordParts;
	int featureCount, part, partCount, vertex, vertexStart, vertexStop;
	int returnValue = TCL_OK;
	
	SHPGetInfo(shapefile->shp, &featureCount, NULL, NULL, NULL);
	if (featureId < 0 || featureId >= featureCount) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid feature index %d", featureId));
		return TCL_ERROR;
	}
	
	if ((shape = SHPReadObject(shapefile->shp, featureId)) == NULL) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to read feature %d", featureId));
		return TCL_ERROR;
	}
	
	/* If this is a NULL shape, return empty list {} explicitly (just leaving
	   coordParts empty would return a list containing an empty list). */
	if (shape->nSHPType == SHPT_NULL) {
		Tcl_SetObjResult(interp, Tcl_NewObj());
		return TCL_OK;
	}
	
	/* prepare a list of coordinate lists; each member list represents one part
	   (a "ring") of the feature. Some features only have one part. */
	coordParts = Tcl_NewListObj(0, NULL);
	
	/* initialize vertex indices. if there's only one part, add all vertices;
	   if there are multiple parts, stop adding vertices at 1st part boundary */
	part = 0;
	vertexStart = 0;
	if (shape->nParts < 2) {
		partCount = 1;
		vertexStop = shape->nVertices;
	} else {
		partCount = shape->nParts;
		vertexStop = shape->panPartStart[1];
	}
	
	while (part < partCount) {
		
		/* prepare a coordinate list for this part */
		Tcl_Obj *coords = Tcl_NewListObj(0, NULL);
		
		/* get the vertex coordinates for this part */
		for (vertex = vertexStart; vertex < vertexStop; vertex++) {
			if (Tcl_ListObjAppendElement(interp, coords, Tcl_NewDoubleObj(shape->padfX[vertex])) != TCL_OK) {
				returnValue = TCL_ERROR;
				goto crRelease;
			}
			if (Tcl_ListObjAppendElement(interp, coords, Tcl_NewDoubleObj(shape->padfY[vertex])) != TCL_OK) {
				returnValue = TCL_ERROR;
				goto crRelease;
			}
			
			/* don't bother considering Z or M coords if only xy is requested */
			if (shapefile->getOnlyXyCoords) {
				continue;
			}
			
			/* for Z type features, append Z coordinate before Measure */
			if (shapefile->getAllCoords
					|| shapefile->dimType == DIM_XYZM) {
				
				if (Tcl_ListObjAppendElement(interp, coords, Tcl_NewDoubleObj(shape->padfZ[vertex])) != TCL_OK) {
					returnValue = TCL_ERROR;
					goto crRelease;
				}
			}
			
			/* for M and Z type features, append Measure (if used) last */
			if (shapefile->getAllCoords
					|| shapefile->dimType == DIM_XYZM
					|| shapefile->dimType == DIM_XYM) {
				
				/* append M coordinate, or 0.0 if unused despite type */
				if (Tcl_ListObjAppendElement(interp, coords,
						Tcl_NewDoubleObj(shape->bMeasureIsUsed ? shape->padfM[vertex] : 0.0)) != TCL_OK) {
					returnValue = TCL_ERROR;
					goto crRelease;
				}
			}			
		}
		
		/* add this part's coordinate list to the feature's part list */
		if (Tcl_ListObjAppendElement(interp, coordParts, coords) != TCL_OK) {
			returnValue = TCL_ERROR;
			goto crRelease;
		}
		
		/* advance vertex indices to the next part (disregarded if none) */
		vertexStart = vertex;
		if (part + 2 < partCount) {
			vertexStop = shape->panPartStart[part + 2];
		} else {
			vertexStop = shape->nVertices;
		}
		part++;
	}
	
	Tcl_SetObjResult(interp, coordParts);

   crRelease:
	SHPDestroyObject(shape);
	return returnValue;
}

/*
 * cmd_attributes
 * 
 * Implements the [$shp attributes] command used to get or set attribute data.
 * 
 * Command Syntax:
 *   [$shp attributes read RECORD FIELD]
 *     Get the value of one field in one record.
 *   [$shp attributes read RECORD]
 *     Get the value of all fields in one record.
 *   [$shp attributes read]
 *     Get the value of all fields in all records.
 *   [$shp attributes write RECORD FIELD VALUE]
 *     Set the value of one field in one record.
 *   [$shp attributes write RECORD VALUELIST]
 *     Set the value of all fields in one record.
 *   [$shp attributes write VALUELIST]
 *     Set the value of all fields in a new record. The record is appended to
 *     the attribute table. A new feature with NULL geometry is also created.
 *   [$shp attributes search FIELD VALUE]
 *     Return record indices of features that match the given field value.
 * 
 * Result:
 *   Read actions return attribute data in value (X), value list ({X Y Z}), or
 *   value list list ({{X Y Z} {A B C} {1 2 3}}) format, respectively.
 *   Write actions return the index of the written attribute record.
 *   The search action returns a list of record indices.
 */
int cmd_attributes(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {

	ShapefilePtr shapefile = (ShapefilePtr)clientData;
	int recordId;
	int actionIndex;
	static const char *actionNames[] = {
			"read",
			"write",
			"search",
			NULL
	};
	
	if (objc < 3) {
		Tcl_WrongNumArgs(interp, 2, objv, "action ?args?");
		return TCL_ERROR;
	}
	if (Tcl_GetIndexFromObj(interp, objv[2], actionNames, "action", TCL_EXACT, &actionIndex) != TCL_OK) {
		return TCL_ERROR;
	}
	
	if (actionIndex == 0) {
		/* read attributes */
		
		if (objc == 3) {
			/* return attributes of all records */
			if (cmd_attributes_readAll(interp, shapefile) != TCL_OK) {
				return TCL_ERROR;
			}
		} else if (objc == 4) {
			/* return attributes of specified index */
	
			if (Tcl_GetIntFromObj(interp, objv[3], &recordId) != TCL_OK) {
				return TCL_ERROR;
			}
			
			if (cmd_attributes_read(interp, shapefile, recordId) != TCL_OK) {
				return TCL_ERROR;
			}
			
		} else if (objc == 5) {
			/* return value of specified field of specified index */
			int fieldId;
						
			if (Tcl_GetIntFromObj(interp, objv[3], &recordId) != TCL_OK) {
				return TCL_ERROR;
			}
			
			if (Tcl_GetIntFromObj(interp, objv[4], &fieldId) != TCL_OK) {
				return TCL_ERROR;
			}
			
			/* sets interp result to field value; validates recordId and fieldId */
			if (cmd_attributes_readField(interp, shapefile, recordId, fieldId) != TCL_OK) {
				return TCL_ERROR;
			}			
		} else {
			Tcl_WrongNumArgs(interp, 3, objv, "?recordIndex ?fieldIndex??");
			return TCL_ERROR;
		}	
	} else if (actionIndex == 1) {
		/* write attributes */
		
		if (objc == 4) {
			/* write attributes to new record; create complementary null shape */
			int featureId;
			
			if (cmd_attributes_write(interp, shapefile, -1 /* new record */, 1 /* validate */, objv[3]) != TCL_OK) {
				return TCL_ERROR;
			}
			
			Tcl_GetIntFromObj(interp, Tcl_GetObjResult(interp), &recordId);
			Tcl_ResetResult(interp);
			
			if (cmd_coordinates_write(interp, shapefile, -1 /* new record */, NULL /* no coordinates */) != TCL_OK) {
				return TCL_ERROR;
			}
			
			Tcl_GetIntFromObj(interp, Tcl_GetObjResult(interp), &featureId);
			if (recordId != featureId) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("new record index (%d) does not match new null feature index (%d)", recordId, featureId));
				return TCL_ERROR;
			}
			
		} else if (objc == 5) {
			/* write attributes to record index */
			
			if (Tcl_GetIntFromObj(interp, objv[3], &recordId) != TCL_OK) {
				return TCL_ERROR;
			}
			if (recordId == -1) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid record index %d (use write command)", recordId));
				return TCL_ERROR;
			}
			
			/* if successful, sets interp's result to the recordId of the written record */
			if (cmd_attributes_write(interp, shapefile, recordId, 1 /* validate */, objv[4]) != TCL_OK) {
				return TCL_ERROR;
			}
			
		} else if (objc == 6) {
			/* write value to field index of record index */
			int fieldId;
			
			if (Tcl_GetIntFromObj(interp, objv[3], &recordId) != TCL_OK) {
				return TCL_ERROR;
			}
				
			if (Tcl_GetIntFromObj(interp, objv[4], &fieldId) != TCL_OK) {
				return TCL_ERROR;
			}
			
			if (cmd_attributes_writeField(interp, shapefile, recordId, fieldId, 1 /* validate */, objv[5]) != TCL_OK) {
				return TCL_ERROR;
			}
		} else {
			Tcl_WrongNumArgs(interp, 3, objv, "?recordIndex ?fieldIndex?? attributes");
			return TCL_ERROR;
		}
	} else if (actionIndex == 2) {
		/* search for attribute value */
		
		if (objc == 5) {
			
			int fieldId;
			
			if (Tcl_GetIntFromObj(interp, objv[3], &fieldId) != TCL_OK) {
				return TCL_ERROR;
			}
			
			if (cmd_attributes_search(interp, shapefile, fieldId, objv[4]) != TCL_OK) {
				return TCL_ERROR;
			}
			
		} else {
			Tcl_WrongNumArgs(interp, 3, objv, "FIELD VALUE");
			return TCL_ERROR;
		}
	}
			
	return TCL_OK;
}

/*
 * cmd_attributes_write
 * 
 * Implements the [$shp attributes write ?RECORD? VALUELIST] action of the
 * [$shp attributes] command, used to write values to a new or existing record.
 * 
 * Result:
 *   Index number of the attribute record that was written.
 */
int cmd_attributes_write(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		int recordId,
		int validate,
		Tcl_Obj *attrList) {
	
	Tcl_Obj *attr;
	int fieldId, fieldCount, attrCount, dbfCount;
	
	if (shapefile->readonly) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("cannot write attributes to readonly shapefile"));
		return TCL_ERROR;
	}
	
	dbfCount = DBFGetRecordCount(shapefile->dbf);
	if (recordId < -1 || recordId >= dbfCount) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid record index %d", recordId));
		return TCL_ERROR;
	}
	if (recordId == -1) {
		recordId = dbfCount;
	}
	
	fieldCount = DBFGetFieldCount(shapefile->dbf);
	
	/* write null values for all fields if attrList is NULL... */
	if (attrList == NULL) {
		return cmd_attributes_writeNull(interp, shapefile, recordId);
	}
	
	/* verify the provided attribute value list matches field count */
	if (Tcl_ListObjLength(interp, attrList, &attrCount) != TCL_OK) {
		return TCL_ERROR;
	}
	
	/* ...also write a null record if an empty list is recieved */
	if (attrCount == 0) {
		return cmd_attributes_writeNull(interp, shapefile, recordId);
	} else if (attrCount != fieldCount) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("attribute count (%d) does not match field count (%d)", attrCount, fieldCount));
		return TCL_ERROR;
	}
	
	/* in the attributes command context, we validate now; w/the write command,
	   we receive attrList pre-validated and can proceed to write it as-is. */
	if (validate && (cmd_attributes_validate(interp, shapefile, attrList) != TCL_OK)) {
		return TCL_ERROR;
	}
		
	/* output pass - once the fields are validated, write 'em out. Output is
	   performed separately from validation to avoid mangled/partial output. */
	for (fieldId = 0; fieldId < fieldCount; fieldId++) {
		
		/* grab the attr provided for this field */
		if (Tcl_ListObjIndex(interp, attrList, fieldId, &attr) != TCL_OK) {
			return TCL_ERROR;
		}
	
		/* writes value attr to field fieldId of record recordId; sets interp result to recordId */
		if (cmd_attributes_writeField(interp, shapefile, recordId, fieldId, 0 /* no validation */, attr) != TCL_OK) {
			return TCL_ERROR;
		}
	}
		
	Tcl_SetObjResult(interp, Tcl_NewIntObj(recordId));
	return TCL_OK;
}

/*
 * cmd_attributes_writeNull
 *
 * Write a null attribute record (null values are written to all fields).
 *
 * Result:
 *   Index number of the null record that was written.
 */
int cmd_attributes_writeNull(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		int recordId) {
	
	int fieldId, fieldCount;
	
	fieldCount = DBFGetFieldCount(shapefile->dbf);
	
	for (fieldId = 0; fieldId < fieldCount; fieldId++) {
		if (DBFWriteNULLAttribute(shapefile->dbf, recordId, fieldId) == 0) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to write null attribute"));
			return TCL_ERROR;
		}
	}
	
	Tcl_SetObjResult(interp, Tcl_NewIntObj(recordId));
	return TCL_OK;
}

/*
 * cmd_attributes_writeField
 * 
 * Implements the [$shp attributes write RECORD FIELD VALUE] action of the
 * [$shp attributes] command, used to set the value of a single field of a
 * specified attribute record. Also used by the [$shp attributes write
 * ?RECORD? VALUELIST] action to set each value in the record.
 * 
 * The boolean validate argument indicates whether the attribute values AND
 * recordId need to be validated. If false, they are assumed to be pre-checked.
 * 
 * Result:
 *   Index number of the record containing the value that was written.
 */
int cmd_attributes_writeField(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		int recordId,
		int fieldId,
		int validate,
		Tcl_Obj *attrValue) {
	
	int dbfCount, fieldCount;
	int intValue;
	double doubleValue;
	const char *stringValue;
	int width, precision, reserved;
	char buffer[NUMERIC_BUFFER_SIZE];
	
	if (shapefile->readonly) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("cannot write attribute value to readonly shapefile"));
		return TCL_ERROR;
	}

	dbfCount = DBFGetRecordCount(shapefile->dbf);
	if (validate && (recordId < 0 || recordId >= dbfCount)) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid record index %d", recordId));
		return TCL_ERROR;
	}
	
	fieldCount = DBFGetFieldCount(shapefile->dbf);
	if (fieldId < 0 || fieldId >= fieldCount) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid field index %d", fieldId));
		return TCL_ERROR;
	}

	if (validate && (cmd_attributes_validateField(interp, shapefile, fieldId, attrValue) != TCL_OK)) {
		return TCL_ERROR;
	}
	
	if (attrValue == NULL || Tcl_GetCharLength(attrValue) == 0) {
		if (DBFWriteNULLAttribute(shapefile->dbf, recordId, fieldId) == 0) {
			Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to write null attribute"));
			return TCL_ERROR;
		}
		Tcl_SetObjResult(interp, Tcl_NewIntObj(recordId));
		return TCL_OK;
	}
	
	switch ((int)DBFGetFieldInfo(shapefile->dbf, fieldId, NULL, &width, &precision)) {
		case FTInteger:
			if ((Tcl_GetIntFromObj(interp, attrValue, &intValue) != TCL_OK)) {
				return TCL_ERROR;
			}
			if ((DBFWriteIntegerAttribute(shapefile->dbf, recordId, fieldId, intValue) == 0) && !shapefile->allowTruncation) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to write integer attribute \"%d\"", intValue));
				return TCL_ERROR;
			}
			break;
		case FTDouble:
			if (Tcl_GetDoubleFromObj(interp, attrValue, &doubleValue) != TCL_OK) {
				return TCL_ERROR;
			}
			
			/* If the value formatted as Shapelib would will not fit in width,
			   reformat it in scientific notation, if not prohibited. */
			if (snprintf(buffer, NUMERIC_BUFFER_SIZE, "%*.*f", width, precision, doubleValue) >= NUMERIC_BUFFER_SIZE) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("fixed format double value too large for buffer"));
				return TCL_ERROR;
			}
			
			if (((int)strlen(buffer) > width) && shapefile->allowAlternateNotation) {
				reserved = 7 + (doubleValue < 0 ? 1 : 0);
				if (reserved > width) {
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("field too narrow (%d) for fixed or scientific notation representation of value \"%s\"", width, buffer));
					return TCL_ERROR;
				}
				if (snprintf(buffer, NUMERIC_BUFFER_SIZE, "%*.*e", width, width - reserved, doubleValue) >= NUMERIC_BUFFER_SIZE) {
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("exponential notation double value too large for buffer"));
					return TCL_ERROR;
				}
				if (DBFWriteAttributeDirectly(shapefile->dbf, recordId, fieldId, (void *)buffer) == 0) {
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to write double attribute \"%s\"", buffer));
					return TCL_ERROR;
				}
			} else {			
				/* Anticipate this to fail due to truncation if len(buffer) > width
				   and allowAlternateNotation and allowTruncation are false, meaning errors preferred. */
				if ((DBFWriteDoubleAttribute(shapefile->dbf, recordId, fieldId, doubleValue) == 0) && !shapefile->allowTruncation) {
					Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to write double attribute \"%lf\"", doubleValue));
					return TCL_ERROR;
				}
			}
			break;
		case FTString:
			if ((stringValue = Tcl_GetString(attrValue)) == NULL) {
				return TCL_ERROR;
			}
			if ((DBFWriteStringAttribute(shapefile->dbf, recordId, fieldId, stringValue) == 0) && !shapefile->allowTruncation) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to write string attribute \"%s\"", stringValue));
				return TCL_ERROR;
			}
			break;
		default:
			if (DBFWriteNULLAttribute(shapefile->dbf, recordId, fieldId) == 0) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("failed to write null attribute for unsupported field %d", fieldId));
				return TCL_ERROR;
			}
			break;
	}

	Tcl_SetObjResult(interp, Tcl_NewIntObj(recordId));
	return TCL_OK;
}

/*
 * cmd_attributes_validate
 * 
 * Confirm that a list of attribute values conforms to the shapefile's field
 * definitions. Used by the [$shp write] command and [$shp attributes write]
 * action in contexts where the value list has not already been pre-validated
 * to check for obvious errors before writing attribute values to disk. Intent
 * is to minimize the chance of leaving shapefile in an invalid state.
 * 
 * An empty attribute list {} is considered valid; it represents a null record.
 * 
 * Result:
 *   No Tcl result if the attribute value list passes validation. Otherwise,
 *   errors may be thrown.
 */
int cmd_attributes_validate(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		Tcl_Obj *attrList) {
	
	int fieldId, fieldCount, attrCount;
	Tcl_Obj *attr;
	
	fieldCount = DBFGetFieldCount(shapefile->dbf);
	if (Tcl_ListObjLength(interp, attrList, &attrCount) != TCL_OK) {
		return TCL_ERROR;
	}
	if (attrCount == 0) {
		return TCL_OK;
	} else if (attrCount != fieldCount) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("attribute count (%d) does not match field count (%d)", attrCount, fieldCount));
		return TCL_ERROR;
	}

	for (fieldId = 0; fieldId < fieldCount; fieldId++) {
		
		/* grab the attr provided for this field */
		if (Tcl_ListObjIndex(interp, attrList, fieldId, &attr) != TCL_OK) {
			return TCL_ERROR;
		}
		
		/* validate this field */
		if (cmd_attributes_validateField(interp, shapefile, fieldId, attr) != TCL_OK) {
			return TCL_ERROR;
		}
	}
	
	return TCL_OK;
}

/*
 * cmd_attributes_validateField
 * 
 * Confirm that a single attribute value conforms to the specified attribute
 * table field definition. Used by the cmd_attributes_validate function and
 * by the [$shp attributes write RECORD FIELD VALUE] action in contexts where
 * VALUE has previously been pre-validated.
 * 
 * Result:
 *   No Tcl result if the attribute value passes validation. Otherwise, errors
 *   may be thrown.
 */
int cmd_attributes_validateField(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		int fieldId,
		Tcl_Obj *attrValue) {
	
	int fieldCount, width, precision, fieldType;
	int intValue;
	double doubleValue;
	const char *stringValue;
	char buffer[NUMERIC_BUFFER_SIZE];

	fieldCount = DBFGetFieldCount(shapefile->dbf);
	if (fieldId < 0 || fieldId >= fieldCount) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid field index %d", fieldId));
		return TCL_ERROR;
	}
	
	/* null fields are ok; validation doesn't need to set any result if OK */
	if (attrValue == NULL || (Tcl_GetCharLength(attrValue) == 0)) {
		return TCL_OK;
	}
	
	fieldType = (int)DBFGetFieldInfo(shapefile->dbf, fieldId, NULL, &width, &precision);
	switch (fieldType) {
		case FTInteger:
			/* can this value be parsed as an integer? */
			if (Tcl_GetIntFromObj(interp, attrValue, &intValue) != TCL_OK) {
				return TCL_ERROR;
			}
			if (shapefile->allowTruncation) {
				break;
			}
			/* does this integer fit within the field width? */
			if (snprintf(buffer, NUMERIC_BUFFER_SIZE, "%d", intValue) >= NUMERIC_BUFFER_SIZE) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("integer value too big for buffer"));
				return TCL_ERROR;
			}
			if ((int)strlen(buffer) > width) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("integer value (%s) would be truncated to field width (%d)", buffer, width));
				return TCL_ERROR;
			}
			break;
		case FTDouble:
			/* can this value be parsed as a double? */
			if (Tcl_GetDoubleFromObj(interp, attrValue, &doubleValue) != TCL_OK) {
				return TCL_ERROR;
			}
			/* does this double fit within the field width? */
			/* disabling double width check now with conditional scientific notation output */
			/*sprintf(numericStringValue, "%.*lf", precision, doubleValue);
			if (strlen(numericStringValue) > width) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("double value (%s) would be truncated to field width (%d)", numericStringValue, width));
				return TCL_ERROR;
			}*/
			break;
		case FTString:
			/* can this value be parsed as a string? */
			if ((stringValue = Tcl_GetString(attrValue)) == NULL) {
				return TCL_ERROR;
			}
			if (shapefile->allowTruncation) {
				break;
			}
			/* does this string fit within the field width? */
			if ((int)strlen(stringValue) > width) {
				Tcl_SetObjResult(interp, Tcl_ObjPrintf("string value (%s) would be truncated to field width (%d)", stringValue, width));
				return TCL_ERROR;
			}
			break;
		default:
			break;
	}

	return TCL_OK;	
}

/*
 * cmd_attributes_readAll
 * 
 * Implements the [$shp attributes read] action of the [$shp attributes]
 * command, used to get a list of attribute value lists for all records.
 * 
 * Result:
 *   List containing an attribute value list for each record in shapefile.
 */
int cmd_attributes_readAll(
		Tcl_Interp *interp,
		ShapefilePtr shapefile) {

	Tcl_Obj *recordList;
	int dbfCount, recordId;
	
	recordList = Tcl_NewListObj(0, NULL);
	dbfCount = DBFGetRecordCount(shapefile->dbf);

	for (recordId = 0; recordId < dbfCount; recordId++) {
		
		if (cmd_attributes_read(interp, shapefile, recordId) != TCL_OK) {
			return TCL_ERROR;
		}
					
		if (Tcl_ListObjAppendElement(interp, recordList, Tcl_GetObjResult(interp)) != TCL_OK) {
			return TCL_ERROR;
		}
		
		Tcl_ResetResult(interp);
	}
	
	Tcl_SetObjResult(interp, recordList);
	return TCL_OK;
}

/*
 * cmd_attributes_read
 * 
 * Implements the [$shp attributes read RECORD] action of the [$shp attributes]
 * command, used to get a list of attribute values for a specified record. Also
 * used by the [$shp attributes read] action to get each record value list.
 * 
 * Result:
 *   List containing each attribute value from the specified record.
 */
int cmd_attributes_read(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		int recordId) {
	
	Tcl_Obj *attributes = Tcl_NewListObj(0, NULL);
	int dbfCount, fieldId, fieldCount;
	
	dbfCount = DBFGetRecordCount(shapefile->dbf);
	if (recordId < 0 || recordId >= dbfCount) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid record index %d", recordId));
		return TCL_ERROR;
	}
	
	fieldCount = DBFGetFieldCount(shapefile->dbf);
	for (fieldId = 0; fieldId < fieldCount; fieldId++) {
				
		if (cmd_attributes_readField(interp, shapefile, recordId, fieldId) != TCL_OK) {
			return TCL_ERROR;
		}
		
		if (Tcl_ListObjAppendElement(interp, attributes, Tcl_GetObjResult(interp)) != TCL_OK) {
			return TCL_ERROR;
		}
		
		Tcl_ResetResult(interp);
	}
	
	Tcl_SetObjResult(interp, attributes);
	return TCL_OK;
}

/*
 * cmd_attributes_readField
 * 
 * Implements the [$shp attributes read RECORD FIELD] action of the
 * [$shp attributes] command, used to get the value of a single attribute field
 * from the specified record. Also used by the [$shp attributes read RECORD]
 * action to get each value in a record.
 * 
 * Result:
 *   Value of the specified field from the specified record. NULL values are
 *   represented as empty strings ({}). Unsupported field type values are
 *   represented as strings (as stored within the DBF file).
 */
int cmd_attributes_readField(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		int recordId,
		int fieldId) {
	
	int dbfCount, fieldCount, fieldType;
	
	dbfCount = DBFGetRecordCount(shapefile->dbf);
	if (recordId < 0 || recordId >= dbfCount) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid record index %d", recordId));
		return TCL_ERROR;
	}
	
	fieldCount = DBFGetFieldCount(shapefile->dbf);
	if (fieldId < 0 || fieldId >= fieldCount) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid field index %d", fieldId));
		return TCL_ERROR;
	}
	
	/* return an empty object for null values */
	if (DBFIsAttributeNULL(shapefile->dbf, recordId, fieldId)) {
		Tcl_SetObjResult(interp, Tcl_NewObj());
		return TCL_OK;
	}
	
	/* return an object of appropriate type for fieldId, unless raw requested */
	fieldType = (int)DBFGetFieldInfo(shapefile->dbf, fieldId, NULL, NULL, NULL);
	if (shapefile->readRawStrings) {
		fieldType = FTString;
	}
	switch (fieldType) {
		case FTInteger:
			Tcl_SetObjResult(interp, Tcl_NewIntObj(DBFReadIntegerAttribute(shapefile->dbf, recordId, fieldId)));
			break;
		case FTDouble:
			Tcl_SetObjResult(interp, Tcl_NewDoubleObj(DBFReadDoubleAttribute(shapefile->dbf, recordId, fieldId)));
			break;
		case FTString:
		default:
			Tcl_SetObjResult(interp, Tcl_NewStringObj(DBFReadStringAttribute(shapefile->dbf, recordId, fieldId), -1));
			break;
	}
	
	return TCL_OK;	
}

/*
 * cmd_attributes_search
 * 
 * Implements the [$shp attributes search FIELD VALUE] action of the [$shp
 * attributes] command, used to determine the record index of features that
 * match the given attribute field value. Matching is currently performed by
 * raw string value comparison. Matches must be exact.
 * 
 * Result:
 *   List of feature indices that match the attribute search query.
 *   Empty list if no matches.
 */
int cmd_attributes_search(
		Tcl_Interp *interp,
		ShapefilePtr shapefile,
		int fieldId,
		Tcl_Obj *attrValue) {
	
	int dbfCount, recordId, fieldCount;
	const char *searchValue, *fieldValue;
	Tcl_Obj *hitList;
	
	fieldCount = DBFGetFieldCount(shapefile->dbf);
	if (fieldId < 0 || fieldId >= fieldCount) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("invalid field index %d", fieldId));
		return TCL_ERROR;
	}
	
	if ((searchValue = Tcl_GetString(attrValue)) == NULL) {
		return TCL_ERROR;
	}
	
	hitList = Tcl_NewListObj(0, NULL);
	dbfCount = DBFGetRecordCount(shapefile->dbf);
	
	for (recordId = 0; recordId < dbfCount; recordId++) {
		
		fieldValue = DBFReadStringAttribute(shapefile->dbf, recordId, fieldId);
		
		if (strcmp(fieldValue, searchValue) == 0) {
			if (Tcl_ListObjAppendElement(interp, hitList, Tcl_NewIntObj(recordId)) != TCL_OK) {
				return TCL_ERROR;
			}
		}
	}
	
	Tcl_SetObjResult(interp, hitList);
	return TCL_OK;
}

/*
 * cmd_write
 * 
 * Implements the [$shp write] command used to add a new feature and attribute
 * record to the shapefile.
 * 
 * Command Syntax:
 *   [$shp write COORDINATES ATTRIBUTES]
 *     Append a new entity to $shp. COORDINATES contains feature geometry and
 *     ATTRIBUTES contains attribute values. See [coordinates] and [attributes]
 *     commands for details on the format of these arguments.
 * 
 * Result:
 *   Index number of the new feature.
 */
int cmd_write(
		ClientData clientData,
		Tcl_Interp *interp,
		int objc,
		Tcl_Obj *CONST objv[]) {

	ShapefilePtr shapefile = (ShapefilePtr)clientData;
	int outputFeatureId, outputAttributeId;
	
	if (objc != 4) {
		Tcl_WrongNumArgs(interp, 2, objv, "coordinates attributes");
		return TCL_ERROR;
	}
	
	if (shapefile->readonly) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("cannot write to readonly shapefile"));
		return TCL_ERROR;
	}
	
	/* pre-validate attributes before writing anything */
	if (cmd_attributes_validate(interp, shapefile, objv[3]) != TCL_OK) {
		return TCL_ERROR;
	}
	Tcl_ResetResult(interp);
	
	/* write the new feature coords (nothing written if coordWrite fails) */
	if (cmd_coordinates_write(interp, shapefile, -1, objv[2]) != TCL_OK) {
		return TCL_ERROR;
	}
	if (Tcl_GetIntFromObj(interp, Tcl_GetObjResult(interp), &outputFeatureId) != TCL_OK) {
		return TCL_ERROR;
	}
	Tcl_ResetResult(interp);
	
	/* write the pre-validated attribute record */
	if (cmd_attributes_write(interp, shapefile, -1, 0, objv[3]) != TCL_OK) {
		return TCL_ERROR;
	}
	if (Tcl_GetIntFromObj(interp, Tcl_GetObjResult(interp), &outputAttributeId) != TCL_OK) {
		return TCL_ERROR;
	}

	/* assert that the new feature and attribute record ids match */
	if (outputFeatureId != outputAttributeId) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf("new coord index (%d) does not match new attribute record index (%d)", outputFeatureId, outputAttributeId));
		return TCL_ERROR;
	}
	
	/* result is new entity id, as set by attrWrite */
	return TCL_OK;
}