User talk:Jifodus/Dwarf Fortress Utility Framework

Sphr's comments

Update: added some comments on binary version data at the end A suggestion to consider: Unify map type defninition so that it can be used in inline definitions as well as global references.

In general a map has:

@name (optional) Does not need name if inlined
@size (optional) not needed for predefined types of known size.  
    Optional for most cases except when used as valuetype in array/vector
@type (optional) name of predefined/user-defined map
@(type-specific parameters) (e.g. vector/array/pointer may have a "valuetype", 
    array may also need a "length". complex will have a "mapping" of named offsets)

An element in a "complex" 's "mapping" has

@name (required) name of mapping
@offset (required) address offset from base of map
@type (optional) name of predefined/user-defined map OR inlined defined type
@(type-specific parameters) (e.g. vector/array/pointer may have a "valuetype", 
    array may also need a "length". complex will have a "mapping" of named offsets)

Basically

• Every map definition can be used inline in another definitionwhere a "type" is expected.
• Every named map definition can be referenced wherever a "type" is expected.

The following shows some examples (may contain human errors) Pardon the bastardized lua syntax... I added the map{ ... } to mark out the part that defines a map, and I used [..] to denote a list.

E.g.

string_map = 
map{ 
   name="string",
   size=28,
   type="complex",
   mapping=[ 			// mapping is used only by "complex" type
   	{name="buffer", offset=0x04, type="array", valuetype="byte", length="16"},  
   	    // have to define length for array if arrays are used as valuetypes for other arrays/vectors
   	{name="pointer", offset=0x04, type="pointer", valuetype=map{type="array", valuetype="byte"} }, 
   	    // inline definintion of byte array as valuetype
   	{name="length", offset=0x14, type="dword"},
   	{name="capacity", offset=0x18, type="dword"}
   ]
}

creature_33b_map = 
map{
	name = "creature_33b",
	type="complex",
	mapping=[
		{ name="first_name"	, offset=0x00, type="string" }, // refers to string type, no inlined definintions
		{ name="nick_name"	, offset=0x04, type="string" }
		....
	]
}

creature_33b_ptr_map =
map{
    name = "creature_33b_ptr",
    // maybe no need to define size.  size of predefined types can be assumed to be well-known
    type="pointer",
    valuetype="creature_33b"
}

creature_vector_33b_map =
map{
    name = "creature_vector_33b",
    type="vector",
    valuetype="creature_33b_ptr"
 }

df_33b_map =  
map{
  name="df_v0_27_169_33b",
  size = ???,
  type = "complex",   
  mapping= // start of list of mappings for complex type
  [  
   { name="main_creature_vector",  offset=0x0141FA30, type = "creature_vector_33b"  },
   
    // the following is similar to "main_creature_vector" defined almost totally inlined (except string) in an alternative way
   
   { name="creature_vector_2",  offset=0x01417A48,
        type = "vector"
        valuetype = map{ 																																													
        	type = "pointer",
        	valuetype= map{
        	    type="complex",
					mapping=[
						{ name="first_name"	, offset=0x00, type="string" },
						{ name="nick_name"	, offset=0x04, type="string" }
						....
					]
	         }
        }																																													
    },

    
    ... 
    
  ] // end of list of mappings
 }

Notice that mapping defined for the whole process is no different from that defined for a structure. The process structure is just a global structure bound to address 0x0000 of the DF process at run-time.

As for version, I suggest a separate section or even separate file.

versions={
  {  version="v0_27_169_33b", 
    timstamp="????",  // include a variety of data to support different binary identification methods. 
    crc32="????",
    map="df_v0_27_169_33b"  //name of base process's memory map, as defined earlier
  }, 
  
   {  version="v0_27_169_33c", 
    timstamp="????",  // include a variety of data to support different binary identification methods. 
    crc32="????",
    map= {... } //can even define to whole monstrous structure inline!
  }, 
  ...
  
}

Sphr 02:35, 13 December 2007 (EST)