Feature Proposal: Add an API for INCLUDE sections to Foswiki::Meta


Plugin authors would like to work with topic sections more easily. In addition, there is an inefficiency in that every occurrence of an INCLUDE macro re-parses the INCLUDEd topic all over again, every single time, for topic sections.

Moving the functionality to Foswiki::Meta standardises the way we work with sections from perl code and allows for the possibility of Foswiki Store implementations to possibly cache pre-parsed topic sections (or offsets) to make retrieval of section text/offsets much quicker.

Description and Documentation

Existing functionality is in Foswiki::parseSections($text) => ($ntext, \@foswikiAttrs). The arrayref of Foswiki::Attr objects contain {type, name, start, end}. $ntext is the topic text on which the offsets may be applied (START/ENDSECTION macros are removed).

  1. Let's make START/(END|STOP)INCLUDE an alias for %START/ENDSECTION{type="_INCLUDE"}%.
  2. Addtional Foswiki::Meta methods
    1. ObjectMethod Foswiki::Meta::sectionText($name[, $type]) => $text
      • If $name is undef, returns (almost) the same as $ntext (START/ENDSECTIONs, START/STOPINCLUDEs removed; the text on which the \@foswikiAttrs offsets apply)
      • If $type is omitted, defaults to section.
    2. ObjectMethod Foswiki::Meta::sectionAttrs() => \@foswikiAttrs
      • Returns the arrayref of Foswiki::Attrs containing {type, name, start, end}.
    3. ClassMethod Foswiki::Meta::parseSections($text) => ($ntext, \@foswikiAttrs)
      • Usually called only once (cache the result behind Foswiki::Meta::sectionText() and Foswiki::Meta::sectionAttrs(). Setting any new text via Foswiki::Meta::text() etc. should invalidate that cache.


my ($ntext) = Foswiki::parseSections($topicObj->text());

my $ntext = $topicObj->sectionText();

my (undef, $sections) = Foswiki::parseSections($topicObj->text());

my (undef, $sections) = $topicObj->sectionAttrs();

my $section = Foswiki::Func::expandCommonVariables('%INCLUDE{"Web.Topic" section="mysection"}%');

my $section = $topicObj->sectionText('mysection');




-- Contributors: PaulHarvey - 01 May 2011


its certainly a better place for it than in Foswiki.pm.

-- SvenDowideit - 12 May 2011

I do wonder one thing - would it not be useful to have a QUERY address for a section, and thus the 'API' might be related to getField?

-- SvenDowideit - 19 Aug 2011

Indeed; and Foswiki::Address pretends to implement a QuerySearch notation for topic sections. But we still have Foswiki::Meta->get() and Foswiki::Meta->put() - are we looking to supersede all this with Foswiki::Address objects?

-- PaulHarvey - 20 Aug 2011

yes? tbh, I am hoping that we can coaless lots of the similar functionalities into fewer interfaces and methods.

-- SvenDowideit - 20 Aug 2011

Raising a concern because this proposal seems to have been left floating. When it is hardened up (and ready for acceptance), please remove my concern.

-- CrawfordCurrie - 24 Feb 2012

Indeed. I suspect things will be clearer once store2 is fleshed out.

-- PaulHarvey - 24 Feb 2012

Changing to parked proposal. Developers are no longer active.

-- Main.GeorgeClark - 12 Jan 2016 - 02:37
Topic revision: r11 - 12 Jan 2016, GeorgeClark
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy