Settings Object

I just uploaded my first object to the obex, and I wanted to mention it here because I think a lot of people would find it to be extraordinarily useful.

"settings" - obex.parallax.com/objects/314/ (Object is attached to bottom of this post if that URL doesn't work)

the description said...
This object handles the storage and retreval of variables (indexed by arbitrary word-sized integers) and data which need to persist across power cycles. Very easy to use, and thread safe. Since it is effectively a "singleton" type of object, it allows for some rudamentry cross-object communication.

Data can be stored and retrieved with a "key", which is a word-sized integer. Settings can be easily written to EEPROM for persistent storage. Has some convenient methods for storing longs, words, and bytes, as well as strings.

Here is the documentation:

Settings Object v1.0
        Robert Quattlebaum <darco@deepdarc.com>
        PUBLIC DOMAIN
        
        This object handles the storage and retreval of variables
        and data which need to persist across power cycles.

        By default requires a 64KB EEPROM to save things persistantly.
        You can make it work with a 32KB EEPROM by changing the
        EEPROMOffset constant to zero.

        Also, since it is effectively a "singleton" type of object,
        it allows for some rudamentry cross-object communication.
        It is not terribly fast though, so it should be read-from
        and written-to sparingly.

        The data is stored at the end of hub ram, starting at $8000
        and expanding downward.

        The format is as follows (in reverse!):

        1 Word                  Key Value
        1 Byte                  Data Length
        1 Byte                  Check Byte (Ones complement of key length)
        x Bytes                 Data
        1 Byte (Optional)       Padding, if size is odd

        The data is filled in from back to front, so that the
        size of settings area can be adjusted later without
        causing problems. This means that the actual order
        of things in memory is reverse of what you see above.

        Even though it is written stored from the top-down, the
        data is stored in its original order. In other words,
        the actual data contained in a variable isn't stored
        backward. Doing so would have made things more complicated
        without any obvious benefit.

Object "settings" Interface:

PUB  start
PUB  revert
PUB  purge
PUB  stop
PUB  commit
PUB  size
PUB  findKey(key) : retVal
PUB  firstKey
PUB  nextKey(key)
PUB  getData(key, ptr, size_)
PUB  removeKey(key) : iter
PUB  setData(key, ptr, size_) : iter
PUB  getString(key, ptr, size_) : strlen
PUB  setString(key, ptr)
PUB  getLong(key) : retVal
PUB  setLong(key, value)
PUB  getWord(key) : retVal
PUB  setWord(key, value)
PUB  getByte(key) : retVal
PUB  setByte(key, value)

Program:     286 Longs
Variable:      0 Longs

__________
PUB  start

 Initializes the object. Call only once. 
___________
PUB  revert

 Retrieves the settings from EEPROM, overwriting any changes that were made. 
__________
PUB  purge

 Removes all settings. 
_________
PUB  stop


___________
PUB  commit

 Commits current settings to EEPROM 
_________
PUB  size

 Returns the current size of all settings 
__________________________
PUB  findKey(key) : retVal

 Returns non-zero if the given key exists in the store 
_____________
PUB  firstKey

 Returns the key of the first setting 
_________________
PUB  nextKey(key)

 Finds and returns the key of the setting after the given key 
_____________________________
PUB  getData(key, ptr, size_)


__________________________
PUB  removeKey(key) : iter


____________________________________
PUB  setData(key, ptr, size_) : iter


________________________________________
PUB  getString(key, ptr, size_) : strlen


________________________
PUB  setString(key, ptr)


__________________________
PUB  getLong(key) : retVal


________________________
PUB  setLong(key, value)


__________________________
PUB  getWord(key) : retVal


________________________
PUB  setWord(key, value)


__________________________
PUB  getByte(key) : retVal


________________________
PUB  setByte(key, value)

I wrote this object primarily for my ybox2 project, but I thought it was useful enough to spin off into the world on its own.

Feedback is welcome!

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
—
darco
www.deepdarc.com/
[url=mailto:xmpp:darco@deepdarc.com]xmpp:darco@deepdarc.com[/url]

Post Edited (darco) : 5/7/2008 6:11:36 PM GMT