I Need a Human Readable, Yet Parse-able Document Format

Question

I'm working on one of those projects where there are a million better ways to accomplish what I need but I have no choice and I have to do it this way. Here it is:

There is a web form, when the user fills it out and hits a submit a human readable text file is created using the form data. It looks like this:

field_1: value for field one

field_2: value for field two
more data for field two (field two has a newline in it!)

field3: some more data

My problem is this: I need to parse this text file back into the web form so that the user can edit it.

How could I, in a foolproof way, accomplish this? A database is not an option, I have to use these text files.

My Questions:

Is there a foolproof way to do this using the format in the example above?
What human readable format would work better (in other words I can change the format)
Human readable means that a non programmer could read it and know what is what.

This project uses PHP.

UPDATE

By human readable I mean that anyone could read the text and not be overwhelmed by it, including your grandmother.

That's pretty much what XML is...human readable but can be easily parsed. That said, raw XML isn't the prettiest. I'd suggest using XML for the data file, then link to an XSLT file to format it for the human-readable view. — DA., Apr 07 '10 at 21:07
@DA By human readable I mean that my mom could read it and not be confused or overwhelmed. — joshwbrick, Apr 07 '10 at 21:09
@macinjosh: I love your nic. When I was 12 I wanted to start a company called "The Mac & Josh" :-) — Josh, Apr 07 '10 at 21:15
@Josh ha, thanks. You lucked out getting your first name as your handle! — joshwbrick, Apr 07 '10 at 21:18
@macinjosh: It's because my openid is josh.gitlin.name. I've seen at least one other "Josh" on here, so apparently handles don't need to be unique :-) — Josh, Apr 07 '10 at 21:22
@macinjosh hence the XSLT part. Make it look anyway you want for your Mom. — DA., Apr 07 '10 at 21:24
Out of curiosity, if users can see the data in their form, why can't grandma? Just give her a form view as well (perhaps with disabled form elements) — DA., Apr 07 '10 at 21:31
@DA XSLT is a good suggestion, unfortunately this client has a shared hosting account and I don't have any access to an XSLT program. And about the form view suggestion the document needs to be downloaded and passed around. — joshwbrick, Apr 08 '10 at 15:29
@macinjosh note that you don't need an XSLT program if they have a relatively new web browser. Newer browsers will load an XML file and if there is an XSLT file linked, will parse is properly. However, that would require an internet connection (to grab the XSLT file) thus perhaps making it more difficult to pass around. — DA., Apr 08 '10 at 18:27

score 21 · Accepted Answer · answered Apr 07 '10 at 21:08

I Need a Human Readable, Yet Parse-able Document Format

This is what YAML was designed to be. You can read more about it on their site or on Wikipedia.

To quote Wikipedia:

YAML syntax was designed to be easily mapped to data types common to most high-level languages: list, hash, and scalar. Its familiar indented outline and lean appearance makes it especially suited for tasks where humans are likely to view or edit data structures, such as configuration files, dumping during debugging, and document headers

The advantage over XML is that it doesn't use tags which might confuse users. And I think it's cleaner than INI (which was also mentioned) because it simply uses colons instead of equals signs, semicolons and quotes.

Sample YAML looks like:

invoice: 34843
date   : 2001-01-23
bill-to: &id001
    given  : Chris
    family : Dumars
    address:
        lines: |
            458 Walkman Dr.
            Suite #292
        city    : Royal Oak
        state   : MI
        postal  : 48046
ship-to: *id001
product:
    - sku         : BL394D
      quantity    : 4
      description : Basketball
      price       : 450.00
    - sku         : BL4438H
      quantity    : 1
      description : Super Hoop
      price       : 2392.00
tax  : 251.42
total: 4443.52
comments: >
    Late afternoon is best.
    Backup contact is Nancy
    Billsmer @ 338-4338.

Oh, and there's at least two PHP libraries for reading/writing YAML — Josh, Apr 07 '10 at 21:14
Great answer for a great question. I didn't know about YAML. — Leniel Maccaferri, Apr 07 '10 at 21:21
I called my grandmother about this. She's totally cool with it. — webbiedave, Apr 07 '10 at 21:26

score 11 · Answer 2 · answered Apr 07 '10 at 21:11

11

I'd say either use

or just about any lightweight markup language you deem appropriate.

answered Apr 07 '10 at 21:11

Gordon

312,688
75
539
559

I would argue that the lightweight markup languages mentioned, other than ini and yaml are not relevant to the original post since they are geared toward structured text vs. structured data. – JJ Rohrer Jan 29 '14 at 14:14

score 5 · Answer 3 · answered Apr 07 '10 at 21:10

5

You might want to look into YAML

http://www.yaml.org/

I agree with Pablo Fernandez response. I think JSON might be a good choice as well.

answered Apr 07 '10 at 21:10

Frank Hale

1,886
1
17
31

score 1 · Answer 4 · answered Apr 07 '10 at 21:08

1

XML is an option.

answered Apr 07 '10 at 21:08

Leniel Maccaferri

100,159
46
371
480

score 0 · Answer 5 · answered Apr 07 '10 at 21:07

0

I'm just gonna say that an INI string is pretty readable:

Pet_Name = "Fred"

But, you could always roll your own format. Something like:

Key: ValueValueValueValueValueValue
Key: ValueValue

Basically, you would explode the string by newlines, look for text strings infront of colons and use that as the key, and the data after the colon and before the newline is the value.

answered Apr 07 '10 at 21:07

Tyler Carter

60,743
20
130
150

Thats what I'm doing now, but I've ran into some parsing problems where the data included text that messed up the convention like a new line followed by a word and a colon. Not foolproof enough. – joshwbrick Apr 07 '10 at 21:11

I Need a Human Readable, Yet Parse-able Document Format

5 Answers5

Linked