EziEditDat

Easilly edit .dat and .csv files.

Introduction

For Developers

Do you need to allow users to update lists of values for your software? Do you hate getting a great program written only to then spend hours writing code to allow users to configure it? I know I do.

EziEditDat can solve that problem for you. Rather than designing edit screens and writing code to make it all happen, you can simply have your "Edit" / "Update" / "Settings" / etc, button run EziEditDat.

In VB6 it can look as simple as:

Private Sub cmdUpdateAuthorizedUsers_Click() Shell "EziEditDat.exe Users.dat" End Sub

In C++ it would be:
... shell("EziEditDat.exe Users.dat");

What Does It Cost?

EziEditDat is Freeware. It costs you nothing to use it. It costs you nothing to distribute it.

You can use it in your free, or commercial, application without paying any royalties.

If it is of use to you; you can use it.

But It Says "Ezi ... Edit"

The title bar can be changed to fit in with your program. e.g. "(Your App) - Update Authorized Users".

Configuration

Data File Format

The tool can be used with a specific .DAT file format, or with two .CSV file formats. The formats supported are:

DAT
This is the default format. It consists of a series of lines of comma separated values in the following format:

rows, columns r1c1, r1c2, r1c3, ..., r1c(columns) r2c1, r2c2, r2c3, ..., r2c(columns) ... r(rows)c1, r(rows)c2, r(rows)c3, ..., r(rows)c(columns)

This format is particularly good as it tells you early on, how much space to allocate to read the entire table. I recommend it. It is easy to code, or update, your program to use this format. EziEditDat will update the header row for you as rows are added or deleted.
CSV
This is ordinary ".csv" format. It is the same as the DAT format, but without the initial "rows" and "columns" line. i.e.

r1c1, r1c2, r1c3, ..., r1c(columns) r2c1, r2c2, r2c3, ..., r2c(columns) ... r(rows)c1, r(rows)c2, r(rows)c3, ..., r(rows)c(columns)

This format is very common so you may already be using it in your program. The number of columns involved is determined by reading the first row, and looking (counting the number of values). The number of rows is determined by reading each line until the end or until a line without [the correct number of] values is found. It can be a pain in the neck because you either have to read the file twice - to find out how much information is in it, and then to read the information; or you have to guess, read some, and resize as you find more than you guessed.
CSVH
This is a ".csv" format file with a header line. i.e.

hdr1, hdr2, hdr3, ..., hdr(columns) r1c1, r1c2, r1c3, ..., r1c(columns) r2c1, r2c2, r2c3, ..., r2c(columns) ... r(rows)c1, r(rows)c2, r(rows)c3, ..., r(rows)c(columns)

This has the same benefits (common) and disadvantages (read twice or resize) as CSV. Some programs generate .csv files with headers. Some don't. Some allow choosing. EziEditDat will work with either format - you just have to specify whether to skip over the header to get to the actual information, or not.

Column Names

So it reads and writes information from or to a table in a text file. But, aside from the CSVH format which has header names built in, how does it know what to use as the headings for each of the columns?

EziEditDat uses a specification file that tells it: how many columns there should be, what the column names are, how wide the columns should be, and what types of values should go in each column.

There is one specification file for each data file type. For example, your program may maintain a list of visited websites. You could have a separate data file for each user, or one for each "project" for each user. However, all of these files have the same structure - the same number and type of columns. A single specification file would cover all of these files.

What about CSVH - files with headers already in them? Sorry, but these are ignored. If the user was creating a brand new CSVH file EziEditDat would have no way of telling what headers to use. It would need to get them from somewhere. It does this from the specification file, whether there are already headers in the CSVH file or not. This means that EXISTING HEADERS in CSVH files will be OVERWRITTEN.

Specification File

The specification file is a text file in DAT format. It always has four columns and it has a row for each data file column that is being specified. It looks like this:

8,4 Name,15,1,- Surname,15,1,- Address1,15,1,- Address2,15,1,- City,15,0,- State,8,2,State.txt Postcode,8,1,- Country,9,2,Country.txt

The first column is the data file's column names (Name, Surname, Address1, etc in this example).

The second column is the data file's column widths (15, 15, ..., 9). The widths are in hundredths of the available width. Think of them as percentages. If EziEditDat is resized, all of the columns resize proportionally. Ideally, the widths would add up to 100(%) but they don't have to. If they exceed 100 you will get a horizontal scroll bar.

The third column is the ComboBox Mode. This is only used if you provide a list of values that a user can choose from (see next paragraph). The allowed modes are:

0 - Allow the user to choose any value from the list, OR to enter any other value.
1 - The user can only choose values from the list.
2 - The user can only choose values from the list, but search through the combo box list as the user presses keys. (This works best if the list values are in alphabetic order.)

The fourth column is a list of values that the user can pick from when choosing a value, or it is "-" for "no list of values". If "-" is used the user is presented with a TextBox for entering or updating column values. Otherwise, a ComboBox is displayed. This allows the user to enter a value or choose from a list. If a filename is used for this value then the combo box list is loaded with each line from the file.

An example list file is:

ACT NSW NT QLD SA TAS VIC WA

This is the contents of the sample file: "State.txt". It is a list of the Australian states, sorted alphabetically. Each list file is just lines of text. You can use Notepad (or any other text-based editor) to create them.

List files should be either in the "current directory" when you run EziEditDat, or in the directory from which EziEditDat runs. The "current directory" is whatever you set in your program, if you do; or you can set it in the properties of a desktop shortcut which runs your program (see the "Start in" value). You can also specify a subdirectory if you like. You just use "...,(subdirectory)\State.txt" in the specification file instead of "...,State.txt". EziEditDat will check for (subdirectory)\State.txt in the current directory and, if not found there, in the directory containing EziEditDat.

How To Create A Specification File

You can use Notepad (or any other text-based editor) to create a specification file. You can also use the SpecEditor program provided. This is EziEditDat for EziEditDat Specification files. Just run SpecEditor.exe, fill in the grid, and press "Save As".

How To Use A Specification File

The command line for EziEditDat is:

EziEditDat [[specFile] datafile] [options]

This means:

If you specify two filenames on the command line, the first is used as the specification file and the second is the file for the user to edit.
If you only mention one filename, this is taken as the file to be edited.

The specification file used will have the same name as the program (EziEditDat) with a ".dat" extension (EziEditDat.dat).

This means you can rename the EziEditDat.exe file, if you like, to something specific for your program (e.g. EditUsers.exe or WebsiteEditor.exe) and have it automatically use a specification file for those sorts of files.

SpecEditor is simply EziEditDat renamed. You will also find a "SpecEditor.dat" file which is a specification file for specification files! You can look at this in Notepad (or SpecEditor) if you are interested in how this works.
If you don't mention any filenames at all, the "File / Open" menu option is enabled and you can choose a file to edit that way. Again, the specification file used will be the program name with a ".dat" extension.

The options are:

/t title

This allows you to change the EziEditDat title bar to something more appropriate for your application. If you include spaces in the title, you should place quotes around it (/t "my app - Update Music Choices")
/csv

This tells EziEditDat to read and write datafiles in headerless CSV format. It also causes the "File / Open" and "Save As" dialog boxes to only show CSV files (instead of DAT files)
/csvh

This is as per "/csv" but it skips the first row read, and writes the column headers to the first row written.

Use

Integrating It Into Your Program

Create a specification file (see above) describing your files.

Decide whether you will just run EziEditDat with the specification file on the command line, or if you'd like to rename it (e.g. to (App)Edit(FileType).exe or (FileType)Editor.exe). If you rename it, make sure you used the same name for the specification file you created in the last step, or update its name to match.

Decide where you will put EziEditDat.exe (or its renamed equivalent).

Create text files for any ComboBox lists and save these in what will be your current directory or with EziEditDat.exe (or as renamed).

Try running it. Verify all is well, or fix any problems.

Update your program to have the relevant button(s) and / or menu item(s) run EziEditDat (or as renamed).

Integrating It Into Your Help

EziEditDat comes with uncompiled HTML help. This is what you are reading.

The program's Help / Contents menu option opens a file in the Help subdirectory of wherever you put the executable. This means that if you renamed EziEditDat.exe to EditUser.exe and install it into "C:\Program Files\(your company)\(your app)"" then it will display help from "C:\Program Files\(your company)\(your app)\Help".

The file it opens is "(its name).html" if that exists, or "EziEditDat.html", or if that fails, "index.html".

This means you can tailor the help to suit each editor, use a common help page (EziEditDat.html) for all editors, or link into your application's help (if you place it in the Help subdirectory and start it with "index.html").

The overall help for EziEditDat includes a User's Guide page. That would make a good starting point for an EziEditDat.html page for your application. Writing Help pages is another time consumer for developers. Wouldn't it be nice if you could just drop the existing page in, and use that.

Issues

EziEditDat does not cope with embedded quotes in DAT format files. EziEditDat reads the CSV formats using a different process and two quotes next to each other within a string are treated, in the CSV formats, as an embedded quote.