X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/dae0f48e91304afcb6ebe0936360e51b22a56548..3a04e96389def78bcb873a4487b85f4d75653199:/doc/todo/firm_up_plugin_interface.mdwn diff --git a/doc/todo/firm_up_plugin_interface.mdwn b/doc/todo/firm_up_plugin_interface.mdwn index e23f2f3d6..c7553f7dd 100644 --- a/doc/todo/firm_up_plugin_interface.mdwn +++ b/doc/todo/firm_up_plugin_interface.mdwn @@ -1,72 +1,96 @@ -The plugin interface is currently that they can register hooks, and can -call any other ikiwiki internal function they desire, generally through -Ikiwiki::function calls. Also, some Ikiwiki::config etc variables can be -used. - -This is a very weak interface, and should be firmed up to something more -like a proper perl library. I've been waiting to get some idea of what bits -of ikiwiki are most useful to plugins before doing it; there are plenty of -plugins to know that now. - -IkiWiki will now export some function calls and variables when loaded. - -Functions used by many plugins, which I'm sure should be exported: - -* hook -* debug -* error -* template -* htmlpage -* add_depends -* pagespec_match -* bestlink -* htmllink -* readfile -* writefile -* pagetype -* srcfile -* pagename -* displaytime - -Functions used by only some plugins, undecided: - -* lockwiki, unlockwiki (aggregate) - Too internal to ever be exported. -* loadindex (aggregate) - Too internal to ever be exported. -* titlepage (aggregate) - Not until more than one thing uses it. -* basename (polygen, inline, search, polygen) -* dirname (linkmap, inline) - For basename and dirname, they could just use standard perl library - stuff. Howevever, ikiwiki's versions are slightly different and I'd - need to check if the standard versions work for the uses made in - these plugins. Inclined not to export. -* abs2rel (linkmap, inline) - This *is* the library version, just optimised to work around a bug. - Don't export this. -* possibly_foolish_untaint (aggregate, polygen) - Probably better to implement yourself. -* htmlize -* linkify -* preprocess -* filter - Used by several, but problimatic since plugins typically define - functions with these names.. - -Variables used by plugins: - -* %IkiWiki::config (various values; probably not worth locking down any - more, export it) -* %IkiWiki::links (many, seems clearcut to export) -* %IkiWiki::renderedfiles (orphans, inline, search) -* %IkiWiki::pagesources (pagecount, sidebar, template, inline) -* %IkiWiki::pagecase (aggregate.. will not export yet) -* %IkiWIki::backlinks (pagestats.. will not export yet) +Reopening this for 3.0, to consider adding new functions. I don't want this interface to be too firm; it's ok for a plugin like `ddate` to redefine an internal function like IkiWiki::displaytime if it wants to.. But plugins that still access stuff through IkiWiki:: should be aware that that stuff can change at any time and break them. Possibly without perl's type checking catching the breakage, in some cases. Plugins that -only use exported symbols should not break by future ikiwiki changes. +only use exported symbols should not be broken by future ikiwiki changes. + +## Most often used functions, by number of calls from plugin code + + 27 IkiWiki::possibly_foolish_untaint + +Not very happy about exporting, it's not ikiwiki-specific, +and plugins that need to untaint things should think about it, hard. + + 12 IkiWiki::userinfo_get + 5 IkiWiki::userinfo_set + +Used by only 4 plugins, all of which are fairly core, so thinking +don't export. + + 11 IkiWiki::preprocess + 8 IkiWiki::filter + 4 IkiWiki::linkify + 4 IkiWiki::htmlize + +The page rendering chain. Note that it's very common to call `preprocess(filter(text))`, +or `htmlize(linkify(preprocess(filter(text))))`, while `htmlize(linkify(preprocess(text))` +is called less frequently, and it's also not unheard of to leave out a step and do +`htmlize(preprocess(text))`. (I haven't checked if any of those cases are bugs.) + +It would be nice if the api could avoid exposing the details of the render chain, +by providing a way to say "I have filtered text, and would like html", or "I have raw +text and would like to get it up to the preprocess stage". + +Another problimatic thing is plugins often define functions named 'preprocess', etc. + + 12 IkiWiki::linkpage + 11 IkiWiki::pagetitle + 6 IkiWiki::titlepage + +These go together; linkpage is needed by all link plugins, and the others are used widely. +All should be exported. (Done) + + 7 IkiWiki::saveindex + 5 IkiWiki::loadindex + +Still too internal to ever be exported? + + 7 IkiWiki::redirect + +Only used by 4 plugins, and not in IkiWiki.pm itself, so probably not to be exported. + + 7 IkiWiki::dirname + 4 IkiWiki::basename + +Not ikiwiki-specific, don't export. + + 6 IkiWiki::refresh + +Very internal, not part of IkiWiki.pm, don't export. + + 5 IkiWiki::yesno + +Not ikiwiki-specific, but worth exporting to get a consistent localised yes/no parser +for directives. + + 5 IkiWiki::showform + 4 IkiWiki::decode_form_utf8 + +Only used by 3 fairly core plugins, not in IkiWiki.pm, don't export. + + 5 IkiWiki::rcs_update + 4 IkiWiki::rcs_prepedit + 5 IkiWiki::is_admin + 5 IkiWiki::cgi_savesession + 4 IkiWiki::cgiurl + +Not enough use, I think, to export. + + 5 IkiWiki::enable_commit_hook + 5 IkiWiki::disable_commit_hook + +Deep internal magic, if exported people will use it wrong, only used by core plugins. + + 4 IkiWiki::check_canedit + +Probably needs to evolve more and be more widely used before being exported. + +## Variables used by plugins but not exported yet + +* %IkiWiki::pagecase (aggregate) +* %IkiWiki::backlinks (pagestats) + +[[done]] (until 4.0)..