The file format used by the LaxFiles::Attribute class is based on indentation delimiting different fields. You can think of it as a simplified xml, where there is no difference between elements and attributes. The laxrc file uses this structure, as do all the interface data classes. Please see the interface classes for examples of how Attributes are used in practice.

Todo:

****** the IntAttribute types of functions use functions like strtol, which will stop parsing at first character that is invalid for the conversion, but for a value to be truly converted, "34" is ok but "34g" is not a pure integer, for instance. there is no default check for things like that. It should be an option.

dump_in_from_buffer(const char *buf) and dump_out_to_buffer(char *buf) ?

Todo:: update this!!!

~~~~~~~~~~ The following text should be considered mere brainstorming: ~~~~~~~~~~

*** please note that not all this is currently implemented... at the moment is only the very basic name=value, subatts is in place, not the definition parsing and applying..

Attributes are basically a name, with a value, and any number of sub-entries. The sub entries can either exist only in the entry, or they can be references to other entries (todo!). Like python, related information is indicated by a certain level of indentation, unlike XML, for instance, that uses "<tags>" that are often difficult to read through quickly.

News flash: Just found out about Yaml.org, which is a much more developed indentation based data file format, must investigate that further!

Types and Definitions

***this is not current:

Attributes can be read in assuming the basic "name value" or they can be specific types. Base level entries are begun on a single line. This line has an optional type specifier first (no indenting), followed by an entry name, followed by an optional date specification, followed by an optional value field.

If type specifier is not present, then the entry is assumed to be just a generic Attribute. Otherwise, first the entry is loaded with any default values for that type, and then any values or subattributes listed overwrite those default values.

It is assumed that the date has the format yyyy-mm-dd-hh:mm:ss.sssss. If it finds something that looks like "yyyy-mm-dd", then it assumes this is the date specifier. Otherwise that bit is read in as the start of the value. The parser will read in all of the date that is there. If you have a value that starts off like that, and you do not include a date specification, then you must put quotes around it.

Todo:: ***need some way to automatically set how many spaces a tab is equal to. it is currently 1, which is irritating when your editor automatically puts in a tab rather than spaces..

# comment
name value
subattname value

[entrytype] entryname [value]
attribute1 value
attribute2 value
attribute2.5 "1" "2" \"value\"" #<-- multiple quote blocks, value= '"all in" "quotes is the \"value\""'
attribute3 "all in quotes is the \"value\"" #<-- \" escapes the quote, value='all in quotes is the \"value\"'
subattribute1 value
subattribute2 value
subsubatt1 \ #<-- means the value is contained in the following lines
That initial '\' next to the name must be followed by either a newline or a space.
Otherwise you might simply escape a '\#' character..
Value for subsubatt1 continues
as long there are lines with the same indentation \#this is included
as the first line after the name. #this comment is not included
On any of these lines, trailing whitespace and comments are stripped.
Initial whitespace is included.
.
Blank lines are written with the correct indentation and a single '.'.
If you need a line with only a '.', then you can write '\.'. If you need a line
with '\.', then write '\\.'. A line with '\\.' is written as "\\\."...

subsubsubatt1 "The previous line broke reading that value, so this is read as a sub att.."
subsubatt2 <<< filename #<-- the value is the contents of file filename
subsubatt3 << BLAH #<-(comment not included in tag)
All the characters following the newline of the previous line until that BLAH on its own line
is encountered become the value of subsubatt2, not including any newline just before the blah.

Blank lines like the previous line are included.
The end marker doesn't have to be 'BLAH'. It can be anything without white space. #this is included.
BLAH
subsubatt4 < BLAH
Like the raw value in the previous attribute, this goes until BLAH on its own line
is encountered, but each line (non-empty) must have the standard indentation.

Blank lines need only be blank lines, proper indentation is not necessary.
Comments and trailing whitespace are not stripped, so #this is included
Really except for the indent, this is identical to the raw
value above, but it makes a file looks nicer.
BLAH
subsubsubatt1 "subatt of subsubatt4"
attribute4 value
anotherentry #<-- this places a reference to the entry with name anotherentry within this entry
# if it exists above, otherwise it is a field with null value.

How to define default types within a file:

int, uint (non-negative int), pint (positive integer),
string, date(FMTSTRING???)
real[minval,maxval]

define image
  filename: string untitled
  width: uint 0            #<--- type plus default value
  height 0                 #<--- (no colon) string type, default="0"
  caption "No caption"     #<--- (no colon) string type, default="No caption"
  referencecount: uint
  referencecount= uint #?? = instead of :?
  real1to10: real:[1,10] #<-- allow range 1 to 10, no default value, must be defined manually
  anotherreal1to10: real(5):[1,10] #<-- allow range 1 to 10, default value of 5, must be defined manually
  areal: real1to10(8)

default image
  filename "blah.jpg"
  caption "Default image"

image animage
  filename "yadda.jpg" 
   # animage then would dump out like this:
   # animage
   #   filename "yadda.jpg"
   #   caption  "Default image"
   #   width    0
   #   height   "0"
   #   areal    8
   #