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

Motivation

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.

Examples

Before:

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

After:

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

Before:

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

After:

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

Before:

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

After:

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

Impact

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

-- Contributors: PaulHarvey - 01 May 2011

Discussion

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