libctags.a and mini-geany based on #2085

[masatake]

This is bease on @techee's work.
With this change, both ctags and mini-geany can be built.
This PR is just for showing the progress of my work.

[techee]

Getting rid of using the static global variable is definitely nice. However, while this concrete approach works for this example, it isn't the best interface for Geany. When we call createTags(), we already have the tag array allocated inside TMSourceFile and we need to get the existing array filled and not newly created inside preWriteEntry() and then returned by createTags().

However, I think we already have all we need. We can just call

customWriter->private = our_tag_array; //or whatever we want
createTags(NULL, 0, argv[i], getNamedLanguage("C", 0));

and pass our custom data in and out this way without any return value of createTags(). The 'result' can be removed from postWriteEntry() too.

[masatake]

I see.
However, providing the way to return results from a custom writer is a good idea.
Though, this time is not generalizing, I would like to introduce this chanage of ctags side separately.
I will make another pull request for this change.

I will not change mini-geany side.

[techee]

However, providing the way to return results from a custom writer is a good idea.

I'm not sure if it will ever be useful for anything since private can hold arbitrary user data (e.g. a struct, in Geany we'll pass TMSourceFile using it, see https://github.com/geany/geany/blob/master/src/tagmanager/tm_source_file.h#L32). Do you have any example when this might be needed?

[masatake]

The private field is designed as the place store data having rather short life type.
It is initialized with preWriteEntry method called from parseFileWithMio.
and set to NULL in postWriteEntry method called from parseFileWithMio.
This is designed for etags writer.
See postWriteEntry method of etags writer. It tells you much more than my English.

extern void writerSetup (MIO *mio)
{
	if (writer->preWriteEntry)
		writer->private = writer->preWriteEntry (writer, mio);
	else
		writer->private = NULL;
}

extern bool writerTeardown (MIO *mio, const char *filename)
{
	if (writer->postWriteEntry)
	{
		bool r;
		r = writer->postWriteEntry (writer, mio, filename);
		writer->private = NULL;
		return r;
	}
	return false;
}

Of course, you can bypass the life-cycle management done by ctags.
However, it is a kind of abuse.

Another approach is OO technique:

struct myCustomWriter {
   TagWriter base;
    extraLongLifeCycleData data;
   ...
};

This will be a good place to store TMSourceFile.

However, providing the way to return "the result of parsing a file" from ctags can make a client code a bit simple.

[techee]

I was thinking about passing custom data into createTags() rather than the data being returned by it - returning data is just a subset of what we may want to do and when we allow users to pass an arbitrary pointer inside, they have the flexibility to do about anything with the passed data. This is a pretty common pattern in various libraries, e.g.

https://developer.gnome.org/glib/stable/glib-Arrays.html#g-array-sort-with-data

where the user data is passed to the compare_func. In a similar way, createTags() could look like createTags(..., void *user_data) and it would store the user data somewhere, e.g. the extraLongLifeCycleData which would then be accessible from the writer.

[masatake]

createTags(..., void *user_data)

Oh, I see. I will update our changes here. Thank you.

[techee]

Basically this whole patch can be dropped since we can already pass all the data we need using writer->private.

[techee]

We could remove parseRawBuffer() from ctags completely and just export parseMio() which the client app would use directly.

[masatake]

It means we have to export mio API from ctags.
In the future, it is a good idea. However, in short term, it is not a good idea because, as I wrote, I introduced changes to mio ctags locally. So I think you cannot pass a mio instance in Geany to ctags.
As a temporary solution, we have to do
(1) rename mio in ctags to cmio or something, and
(2) export parseRawBuffer as non-mio API.

Here, I would like to introduce parseRawBuffer as the first step.
Is this acceptable?

[techee]

Yeah, totally. I just suggested it as an option and maybe exposing MIO really isn't a good idea at all.

[b4n]

I'm not sure exposing MIO makes much sense, it's only useful if the caller would actually do something we don't with MIO. That could include using MIO to create the buffer to be parsed (e.g. in memory), or creating it with a constructor we don't expose (e.g. mio_new_fp() in combination with fdopen()), but that's about it.

[masatake]

I've tried to remove ctags_main. However, it seems that I should keep it as it was.
I will make one more FYI PR.

[coveralls]

Coverage increased (+0.1%) to 85.483% when pulling 75c26bd on masatake:more-mini_geany into 9b28d8c on universal-ctags:master.

[masatake]

@techee, I refect the most of all your suggestions.
Can I ask you to review this again?

[techee]

@masatake I just went through the patches and tested it on my machine and everything looks pretty great! This really is a huge step towards having Geany and ctags synced - I'm really excited about this.

[masatake]

Yes, this really important step. Thank you very much for you and Geany people's efforts.

The next TODOs are
(1) introduce "libctags.h" (or "ctags-api.h"), and
(2) move code in main.c to cmd.c as much as possible.