[sword-devel] Tagging verses and verse lists

[Troy A. Griffitts]

Martin Gruner wrote:
> Will this be a part of Sword?
> 
> Troy, what do you say?

Since most of our frontends have some type of verse list functionality, 
I would like for us to have something common in the engine we can all 
use.  This will also benefit our users, allowing them to share these 
between applications.  We would all have to agree on an interface 
though, so I'd appreciate hearing from other frontend developers on the 
proposed functionality and interface.  I would be particularly 
interested in whether you think a 'list' concept meets enough needs to 
warrant a mechanism.  BibleCS has basic verse lists, and also bookmark 
trees.  The bookmark trees seem more useful to me, but I would not have 
a straight forward path to modify BibleCS to use a 'PassageList' 
mechanism for trees.

I have some other comments below.


SWMgr is probably not the best place for this functionality.  SWMgr was 
our first 'manager' create 15+ years ago, and now that the engine has 
grown considerably, this should probably be renamed to something like 
SWModuleMgr, as its main purpose is to be a factory to hand back virtual 
base SWModule * objects.

Are we planning to handle any type of key lists with this interface? 
e.g., both Verse and GenBook references?

We also try to keep the std namespace out of the public interfaces the 
best we can.  It makes bindings easier to implement, thus, where the 
interface methods accept std::string, they should accept const char * or 
SWBuf if they are intentionally non-const.


I would suggest something like:

class KeyListMgr {
public:
	KeyListMgr(cont char *configPath);
}

modeled after the LocaleMgr.

This would add a new subdirectory to our config root (along with 
mods.d/, modules/, locales.d/), something like keylists.d/, and I'm sure 
everyone would like to honor a ~/.sword/keylists.d/ as well.

If we are planning to go all out and extend the list interface to a tree 
interface, maybe a more generic name like BookmarkMgr would be better 
suited.

I realize this doesn't map directly to the purpose that Jonathan 
intended.  I don't know if there is an easy delineation to give us 
multiple uses.

Just my initial thoughts.  Looking forward to the conversation.

	-Troy.




>> PassageList API:
>> typedef PassageListMap std::map<std::string, sword::PassageList>;
>>
>> /**
>> Returns the passage list map, which maps unique names to passage lists.
>> */
>> PassageListMap SWMgr::getPassageLists();
>>
>> /**
>> Creates a new passage list with the given name, and adds it to the
>> passage list map.
>> There must not already be a passage list with the given name.
>> */
>> PassageList SWMgr::addPassageList(std::string name);
>>
>> /**
>> Creates a new passage list with the given name, and initialises it with the
>> given list of passages.
>> */
>> PassageList SWMgr::addPassageList(std::string name, ListKey passages);
>>
>> /**
>> Removes the given passage list.
>> Returns true on success, and false on failure.
>> */
>> bool SWMgr::removePassageList(PassageList);
>>
>> /**
>> Removes the passage list with the given name.
>> Returns true on success, and false on failure.
>> */
>> bool SWMgr::removePassageList(std::string name);
>>
>> /**
>> A passage list must have a unique name to identify itself.
>> It may also have a description of the list, which can be used by the user.
>> */
>> PassageList
>> ===========
>> PassageList::get/setName()
>> PassageList::get/setDescription()
>>
>> /**
>> Adds the given passage to the end of the passage list.
>> */
>> PassageList::addPassage(PassageEntry passage);
>> PassageList::addPassage(VerseKey passage);
>> PassageList::moveUp(int index);
>> PassageList::moveDown(int index);
>>
>> /**
>> Removes the given passage entry from the list.
>> */
>> PassageList::removePassage(PassageEntry passage)
>> PassageList::removePassage(int index)
>>
>> /**
>> Sorts the passage list.  At present, this will only support sorting it in
>> canonical order, but in the future, other sort orders may be supported.
>> */
>> void PassageList::sort(PassageListSortOrder order)
>>
>> /**
>> Gets a list key with all the passages in the passage list.
>> */
>> ListKey PassageList::getListKey();
>>
>> /**
>> Creates a new passage list with the same passages as this passage list, but
>> with the given new name.
>> */
>> PassageList PassageList::clone(std::string newName)
>>
>> /**
>> Returns true if the given verse is contained in the passage list.
>> */
>> boolean PassageList::containsVerse(VerseKey verse)
>>
>> /**
>> This class wraps around a VerseKey to allow additional attributes to be
>> attached to an entry in a passage list.  At present, the main addition that
>> is planned is attaching comments to passage entries.
>> */
>> PassageEntry
>> ============
>> /**
>> Creates a passage entry from the given verse.
>> */
>> PassageEntry(VerseKey verse)
>>
>> /**
>> VerseKey PassageEntry::get/setPassage()
>>
>> /**
>> For later extension.
>> */
>> std::string PassageEntry::get/setComment()
>>
>> _______________________________________________
>> sword-devel mailing list: sword-devel at crosswire.org
>> http://www.crosswire.org/mailman/listinfo/sword-devel
>> Instructions to unsubscribe/change your settings at above page
> 
> 
> 
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page