Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Item14375: limit meta parameter names to perl word characters, fix th…
…e doc
  • Loading branch information
cdot committed Apr 10, 2017
1 parent f7c1158 commit 12511db
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 17 deletions.
35 changes: 20 additions & 15 deletions core/data/System/MetaData.txt
@@ -1,27 +1,29 @@
%META:TOPICINFO{author="ProjectContributor" date="1489206078" format="1.1" version="1"}%
%META:TOPICINFO{author="ProjectContributor" date="1491830850" format="1.1" version="1"}%
%META:TOPICPARENT{name="DeveloperDocumentationCategory"}%
%STARTINCLUDE%
#MetaData
---+ Meta data

Additional data, Foswiki-generated or from [[DataForms][forms]], may be embedded in the topic text using =META:= macros
Additional data, Foswiki-generated or from [[DataForms][forms]], may be embedded in the topic text using _embedded meta-data_.

%TOC%

---++ Overview

The default store engines store topics in plain-text files on disk, in a simple and obvious directory structure. The big advantage of this approach is that it makes it very easy to manipulate topics from outside Foswiki, and it is also very robust; there are no complex binary indexes to maintain, and moving a topic from one installation to another is as simple as copying a couple of text files.
The default store engine stores topics in plain-text files on disk, in a simple and obvious directory structure. The big advantage of this approach is that it makes it very easy to manipulate topics from outside Foswiki, and it is also very robust; there are no complex binary indexes to maintain, and moving a topic from one installation to another is as simple as copying a couple of text files.

To keep everything together in one place, meta-data (Foswiki-generated or from [[DataForms][forms]]) is embedded directly in topics, using special macros. These macros are easy to spot, as they all start with the reserved =META:= prefix.

=META:= data includes information such as file attachments, topic movement history, and [[DataForms][form field]] values. For efficiency reasons, the topic history is *not* stored in this meta-data, but is expected to be implemented elsewhere by the store engine.
To keep everything together in one place, meta-data (Foswiki-generated, or from [[DataForms][forms]]) is embedded directly in topic text, using a special syntax.

---++ Meta data syntax
* Format is the same as for any other [[%SYSTEMWEB%.Macros][macros]] *except* that each meta-data macro *must* be on a line on its own.
* =%<nop>META:&lt;type&gt;{key1="value1" key2="value2" ...}%=
* The characters =%"\r\n{}= are encoded in argument values, using the standard URL encoding.
* Meta-data is divided into _core_ meta-data, described below, and _extension_ meta-data, which shares the same syntax but is used by extensions.
* Dates are stored as "epoch times" i.e. the integer number of seconds since 1st January 1970.
* Each meta-data statement *must* be on a line on its own. The format of a meta-data line is:
* =%<nop>META:&lt;type&gt;{key1="value 1" key2="value 2" ...}%=
* The type name and key names may contain any Perl unicode "word" character (see http://perldoc.perl.org/perlrecharclass.html for more information)
* The only space outside of parameter values is a single space between each key-value pair.
* Parameter values support the standard URL encoding for characters, which will be used for all characters such as ", }, newlines, and %. Note that the range of representable characters might be limited by the ={Store}{Encoding}= set in the Foswiki configuration.

Meta-data includes information such as file attachments, topic movement history, and [[DataForms][form field]] values. The topic history is *not* stored in this meta-data, but is expected to be implemented elsewhere by the store engine.

Meta-data is divided into _core_ meta-data, described below, and _extension_ meta-data, which shares the same syntax but is used by extensions.

*Example of core meta-data*
<pre class="tml">
Expand All @@ -41,13 +43,13 @@ To keep everything together in one place, meta-data (Foswiki-generated or from [

---++ Core meta-data

The following meta-data macros are supported by the Foswiki core. Other macros may be used by extensions; see the extension documentation for more details. The core will read and write these extension macros, but will otherwise ignore them.
The following meta-data are used by the Foswiki core. Other meta-data may be used by extensions; see the extension documentation for more details. The core will read and write these extension meta-data, but will otherwise ignore them.

Some fields are required by macros, while others are optional. Required fields are marked with a %REG% symbol. The %REG% character is *not* part of the attribute name.
Some fields are required by meta-data, while others are optional. Required fields are marked with a %REG% symbol. The %REG% character is *not* part of the attribute name.

---+++ META:TOPICINFO

This macro caches some of the information that would normally be derived from the underlying store engine. It does this for efficiency reasons.
This meta-datum caches some of the information that would normally be derived from the underlying store engine. It does this for efficiency reasons.

| *Key* | *Comment* |
| author%REG% | Canonical user identifier of last user to change the topic. The exact format of this depends on the user mapping manager. |
Expand Down Expand Up @@ -125,7 +127,7 @@ Out-of-band [[PreferenceSettings][preference]].

---+++ Recommended sequence

There is no absolute need for meta-data macros to be listed in a specific order within a topic, but it makes sense to do so, because form fields are displayed in the order they are defined when the topic is viewed.
There is no absolute need for meta-data to be listed in a specific order within a topic, but it makes sense to do so, because form fields are displayed in the order they are defined when the topic is viewed.

The recommended sequence is:

Expand Down Expand Up @@ -158,6 +160,9 @@ The =%FORMFIELD= macro lets you inspect the values of form field meta-data in ot
Extensions can extend meta-data with information of their own. See
[[%SCRIPTURL{"view" topic="%SYSTEMWEB%.PerlDoc" module="Foswiki::Func"}%#StaticMethod_registerMETA_40_36name_44_37syntax_41][Foswiki::Func]] for more information.

---++ Meta-data and Plugin Handlers
A few plugin handlers (=beforeSaveHandler=, =afterSaveHandler=, =beforeEditHandler=,) are passed text containing embedded meta-data, as described here. However plugin authors are recommended not to rely on embedded meta-data if it can be avoided, as it will be removed at some point in the future.

---
*Related Topics:* DeveloperDocumentationCategory
<!-- %JQREQUIRE{"chili"}% -->
Expand Down
4 changes: 2 additions & 2 deletions core/lib/Foswiki/Serialise/Embedded.pm
Expand Up @@ -174,8 +174,8 @@ sub _readKeyValues {
my %res;

# Format of data is name='value' name1='value1' [...]
$args =~ s/\s*([^=]+)="([^"]*)"/
$res{$1} = Foswiki::Meta::dataDecode( $2 ), ''/ge;
$args =~ s/\s*(\w+)="([^"]*)"/
$res{$1} = Foswiki::Meta::dataDecode( $2 ), ''/ige;

return \%res;
}
Expand Down

0 comments on commit 12511db

Please sign in to comment.