1 /* SwordModule.h - Sword API wrapper for Modules. 2 3 Copyright 2008 Manfred Bergmann 4 Based on code by Will Thimbleby 5 6 This program is free software; you can redistribute it and/or modify it under the terms of the 7 GNU General Public License as published by the Free Software Foundation version 2. 8 9 This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without 10 even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 11 General Public License for more details. (http://www.gnu.org/licenses/gpl.html) 12 */ 13 14 #import <Foundation/Foundation.h> 15 16 #ifdef __cplusplus 17 #import "swmodule.h" 18 #endif 19 20 // defines for dictionary entries for passage study 21 #define ATTRTYPE_TYPE @"type" 22 #define ATTRTYPE_PASSAGE @"passage" 23 #define ATTRTYPE_MODULE @"modulename" 24 #define ATTRTYPE_NOTENUMBER @"notenumber" 25 #define ATTRTYPE_ACTION @"action" 26 #define ATTRTYPE_VALUE @"value" 27 28 // positions 29 #define SWPOS_BOTTOM 2 30 #define SWPOS_TOP 1 31 32 33 @class SwordManager, SwordModuleTextEntry, SwordKey, SwordFilter; 34 35 typedef enum { 36 TextTypeStripped = 1, 37 TextTypeRendered 38 }TextPullType; 39 40 /** These are the main module types as returned in -typeString */ 41 typedef enum { 42 All = 0x0000, 43 Bible = 0x0001, 44 Commentary = 0x0002, 45 Dictionary = 0x0004, 46 Genbook = 0x0008 47 }ModuleType; 48 49 /** 50 These are the main module categories as returned in -categoryString 51 Remember that modules type bible, commentary, dictionary and genbook not necessarily have a category 52 */ 53 typedef enum { 54 Unset = -1, 55 NoCategory = 0, 56 DailyDevotion = 0x0001, 57 Maps = 0x0002, 58 Glossary = 0x0004, 59 Images = 0x0008, 60 Essays = 0x0010, 61 Cults = 0x0011 62 }ModuleCategory; 63 64 65 @interface SwordModule : NSObject { 66 67 ModuleCategory category; 68 69 /** yes, we have a delegate to report any action to */ 70 id delegate; 71 72 #ifdef __cplusplus 73 sword::SWModule *swModule; 74 #endif 75 } 76 77 // ------------- properties --------------- 78 @property (readwrite) ModuleType type; 79 @property (readwrite) int status; 80 @property (strong, readwrite) SwordManager *swManager; 81 @property (strong, readwrite) NSLock *indexLock; 82 @property (strong, readwrite) NSRecursiveLock *moduleLock; 83 @property (strong, readwrite) NSMutableDictionary *configEntries; 84 85 #ifdef __cplusplus 86 87 /** 88 Convenience initializer 89 */ 90 + (id)moduleForSWModule:(sword::SWModule *)aModule; 91 92 /** 93 Factory method that creates the correct module type instance for the given type 94 */ 95 + (id)moduleForType:(ModuleType)aType swModule:(sword::SWModule *)swModule; 96 97 /** 98 Initialize this module with an the SWModule. 99 This initializer should normally not need to be used. 100 */ 101 - (id)initWithSWModule:(sword::SWModule *)aModule; 102 103 /** 104 Retrieve the underlying SWModule instance 105 */ 106 - (sword::SWModule *)swModule; 107 108 #endif 109 110 /** 111 maps type string to ModuleType enum 112 @param[in] typeStr type String as in -typeString(SwordModule) 113 @return type according to ModuleType enum 114 */ 115 + (ModuleType)moduleTypeForModuleTypeString:(NSString *)typeStr; 116 117 /** 118 maps type string to ModuleType enum 119 @param[in] categoryStr category String as in -categoryString(SwordModule) 120 @return type according to ModuleCategory enum 121 */ 122 + (ModuleCategory)moduleCategoryForModuleCategoryString:(NSString *)categoryStr; 123 124 // ------------- instance methods --------------- 125 126 /** Adds a render filter to this module */ 127 - (void)addRenderFilter:(SwordFilter *)aFilter; 128 129 /** Adds a strip filter to this module */ 130 - (void)addStripFilter:(SwordFilter *)aFilter; 131 132 /** 133 Any error while processing the module? 134 */ 135 - (NSInteger)error; 136 137 /** module name */ 138 - (NSString *)name; 139 /** module description */ 140 - (NSString *)descr; 141 /** module language */ 142 - (NSString *)lang; 143 /** module type string */ 144 - (NSString *)typeString; 145 146 // --------------- Conf entries -------------- 147 /** 148 Module category as string 149 */ 150 - (NSString *)categoryString; 151 /** 152 Module category 153 */ 154 - (ModuleCategory)category; 155 /** 156 Module version 157 */ 158 - (NSString *)version; 159 /** 160 Module minimum Sword version 161 */ 162 - (NSString *)minVersion; 163 /** 164 Module about text 165 */ 166 - (NSString *)aboutText; 167 /** 168 Override to get custom behaviour. 169 */ 170 - (NSAttributedString *)fullAboutText; 171 /** 172 Module versification type 173 */ 174 - (NSString *)versification; 175 /** 176 Is module Unicode UTF-8? 177 */ 178 - (BOOL)isUnicode; 179 /** 180 Is module encrypted 181 */ 182 - (BOOL)isEncrypted; 183 /** 184 Is module locked, that is encrypted but not unlocked? 185 */ 186 - (BOOL)isLocked; 187 /** 188 Is module editable, i.e. is it's a personal commentary? 189 */ 190 - (BOOL)isEditable; 191 /** 192 Is module writing direction Right to Left? 193 */ 194 - (BOOL)isRTL; 195 /** 196 Has module this feature? 197 See SWMOD_FEATURE_* in SwordManager 198 */ 199 - (BOOL)hasFeature:(NSString *)feature; 200 /** 201 Returns a config entry for a given config key 202 */ 203 - (NSString *)configFileEntryForConfigKey:(NSString *)entryKey; 204 205 // ------------------ module access semaphores ----------------- 206 207 /** 208 Aquires a module access lock so that no other thread may access this module. 209 */ 210 - (void)lockModuleAccess; 211 /** 212 Unlock module access. Make it accessible to other threads. 213 */ 214 - (void)unlockModuleAccess; 215 216 // ----------------- module positioning ------------------------ 217 218 /** 219 Increment module key position 220 */ 221 - (void)incKeyPosition; 222 /** 223 Decrement module key position 224 */ 225 - (void)decKeyPosition; 226 /** 227 Set position key from a string 228 */ 229 - (void)setKeyString:(NSString *)aKeyString; 230 /** 231 Set position from a key 232 */ 233 - (void)setSwordKey:(SwordKey *)aKey; 234 235 /** 236 Module key. New instance created by module. 237 */ 238 - (SwordKey *)createKey; 239 /** 240 Module key. Reference only. 241 */ 242 - (SwordKey *)getKey; 243 /** 244 Module key. Reference only but cloned. 245 */ 246 - (SwordKey *)getKeyCopy; 247 248 // ------------------- module metadata processing ------------------ 249 250 /** 251 Process metadata attributes of module entry. 252 */ 253 - (void)setProcessEntryAttributes:(BOOL)flag; 254 /** 255 Are metadata attributes of module entry processed? 256 */ 257 - (BOOL)processEntryAttributes; 258 259 /** 260 returns attribute values from the engine for notes, cross-refs and such for the given link type 261 @return NSArray for references 262 @return NSString for text data 263 */ 264 - (id)attributeValueForParsedLinkData:(NSDictionary *)data; 265 - (id)attributeValueForParsedLinkData:(NSDictionary *)data withTextRenderType:(TextPullType)textType; 266 267 /** returns the pre-verse entry value */ 268 - (NSString *)entryAttributeValuePreverse; 269 - (NSString *)entryAttributeValuePreverseForKey:(SwordKey *)aKey; 270 271 - (NSString *)entryAttributeValueFootnoteOfType:(NSString *)fnType indexValue:(NSString *)index; 272 - (NSString *)entryAttributeValueFootnoteOfType:(NSString *)fnType indexValue:(NSString *)index forKey:(SwordKey *)aKey; 273 274 - (NSArray *)entryAttributeValuesLemma; 275 - (NSArray *)entryAttributeValuesLemmaNormalized; 276 277 // ----------------- Module text access ---------------------- 278 279 /** 280 Pulls all text entries for the given reference 281 @return Array of SwordModuleTextEntry 282 */ 283 - (NSArray *)textEntriesForReference:(NSString *)aReference textType:(TextPullType)textType; 284 285 /** 286 Returns a rendered text for the text at the current module position 287 */ 288 - (NSString *)renderedText; 289 /** 290 Renders the given string with the modules render filters 291 */ 292 - (NSString *)renderedTextFromString:(NSString *)aString; 293 /** 294 Returns a stripped text for the text at the current module position 295 */ 296 - (NSString *)strippedText; 297 /** 298 Strips the given string with the modules strip filters 299 */ 300 - (NSString *)strippedTextFromString:(NSString *)aString; 301 302 /** 303 abstract method, override in subclass 304 This method generates stripped text string for a given reference. 305 @param[in] reference bible reference 306 @return Array of SwordModuleTextEntry instances 307 */ 308 - (NSArray *)strippedTextEntriesForRef:(NSString *)reference; 309 310 /** 311 abstract method, override in subclass 312 This method generates HTML string for a given reference. 313 @param[in] reference bible reference 314 @return Array of SwordModuleTextEntry instances 315 */ 316 - (NSArray *)renderedTextEntriesForRef:(NSString *)reference; 317 318 - (SwordModuleTextEntry *)renderedTextEntryForRef:(NSString *)reference; 319 - (SwordModuleTextEntry *)strippedTextEntryForRef:(NSString *)reference; 320 321 /** 322 number of entries 323 abstract method, should be overriden by subclasses 324 */ 325 - (long)entryCount; 326 327 /** 328 Write text to module position 329 */ 330 - (void)writeEntry:(SwordModuleTextEntry *)anEntry; 331 332 @end 333