discussion generic import design

[Christian Stimming]

Ok, here are some thoughts from me about the generic importer's 
payee/memo-to-destination-account mapping.

Derek Atkins wrote:

> Benoit Grégoire <bock@step.polymtl.ca> writes:
>>I think the best thing you could work on is indeed (If I understand you 
>>properly) the match remembering functions I discussed in the mail I sent on 
>>the 21st:
>>
>>Account * gnc_import_find_dest_account(char * match_text) and
>>void gnc_import_set_dest_account(char * match_text, Account * dest_account).  
>>These should be implemented in a new C file and included in the generic 
>>importers public include file.


Surely we need some functions like that. But I have one principal 
suggestion here: Can we please define a data type that stores the 
mapping, and have those functions take this stored mapping as one 
argument? As long as we do not have that argument in the function 
declaration, it comes "out of the blue", and for the implementer (read: 
me) it is totally unclear what this function depends on or not. (Note 
that this is actually one issue that I have with the other generic 
importer functions as well, but I'll mention them as we go along.) 
Therefore:

typedef struct _GncImportMatchMap GncImportMatchMap;
Account * gnc_import_find_dest_account(GncImportMatchMap *map, char * 
match_text);
void gnc_import_matchmap_set_dest_account(GncImportMatchMap *map, char * 
match_text, Account * dest_account);

and there have to be other functions around the type GncImportMatchMap:

GncImportMatchMap *gnc_import_matchmap_new() /* Constructor */
void gnc_import_matchmap_delete(GncImportMatchMap *) /* Destructor */
GncImportMatchMap *gnc_import_matchmap_from_book(GNCBook *); /* Obtain 
it from book */
void gnc_import_matchmap_to_book(GNCBook *, GncImportMatchMap *) /* 
Store it in book */

and so on and so forth; the last functions should exist for an Account 
as well, probably. My point is that the above functions will *never* 
have any "static" data anywhere, so their behaviour is *fully* specified 
by the input arguments and they don't do anything "out of the blue". 
Additionally, the body of the  find_dest_account function will be 
restricted to really only do that: find the destination account. That 
function is not supposed to care (and really should not care!) about 
where to get the stored MatchMap from.

Now Derek proposed to have


>         typedef enum {
>                 GNCIMPORT_MATCH_PAYEE = 1,
>                 GNCIMPORT_MATCH_MEMO,
>                 GNCIMPORT_MATCH_CATEGORY,
>                 GNCIMPORT_MATCH_CLASS,
>         } GncImportMatchType;
> 
>         Account* gnc_import_find_map_account(GNCBook*, GncImportMatchType);
>         void gnc_import_add_map_account(GNCBook*, GncImportMatchType, Account*);


but these prototypes don't have any char* anymore, so there's nothing to 
match against. I guess the point is much more general here: Against what 
should that find_dest_account match? If we want to match against *one* 
string, then one char* argument as proposed by Benoit is enough. On the 
other hand, I guess that one string doesn't really fit the data that we 
have. In HBCI, I have definitely 2-3 different strings with slightly 
different meanings. All of these 3 strings can be used for matching, and 
ideally I can tell a descending order of matching importance. (Example: 
"transaction description", "transaction memo", "recipient's name"). It 
would *not* work well if we just toss different strings into one long 
string, since that doesn't pay attention to different levels of matching 
importance. So maybe we just agree on the number of different strings, 
and I'd propose two.

On the other hand, the name of those strings in the protocol-specific 
code (i.e. payee, memo, category etc.) IMHO doesn't matter at all, and 
of course those names are different in HBCI than they are in QIF or OFX.

That would result in

Account * gnc_import_find_dest_account(GncImportMatchMap *map, char 
*important_textkey, char *less_important_textkey);
void gnc_import_matchmap_set_dest_account(GncImportMatchMap *map, char * 
important_textkey, char *less_important_textkey, Account * dest_account);

Regards,

Christian

PS: /me is away from email until Sunday, Nov 10.