Feature Proposal: Configure .spec file syntax needs improvments

Motivation

The spec file syntax is gettng involved, with DISPLAY_IF, ENABLE_IF, FEEDBACK, CHECK, LABEL and AUDIT extensions, to name a few. Many of these have string or expressions as arguments; some quite lengthy and complex.

This makes the lines long, difficult to read/edit, and hard to document.

The AUDIT.spec file introduced syntax to address thes issues that I'd like to port to the config file parser.

Description and Documentation

The new syntax supports:

• Continued lines - lines ending in \ are continued to the next line. leading whitespace, and any line starting with '#' is removed.
  • When a 'comment' line - one beginning with '#' - is continued, a '#' at the start of continuation lines is ignored
• Embedded comments - lines beginning with #! are comments, everywhere in the file.
• Blank lines - are ignored

This is compatible with current spec files, unless somone has #! in a description - which seems unlikely...

As the spec files are directly required (actually "do"ne), the continuation syntax is meaningless for non-(perl)comment lines.

Examples

Here are a couple of lines from Foswiki.spec that illustrate the problems (they are by no means the worst cases):

# **PATH AUDIT="DIRS" FEEDBACK="Validate Permissions" CHECK="guess:data perms:rwpd filter:',v$'" CHECK="perms:r filter:'\\\\.txt$'" M**

# **NUMBER FEEDBACK=AUTO EXPERT DISPLAY_IF {UseClientSessions} && {LoginManager}=='Foswiki::LoginManager::TemplateLogin'**

With the new syntax, these could be:

# **PATH AUDIT="DIRS"  \
#        FEEDBACK="Validate Permissions" \
#!       Validate RCS files: readable, writable, pref must exist, directory perms
#        CHECK="guess:data perms:rwpd filter:',v$'" \
#!       Validate topic files: readable
#        CHECK="perms:r filter:'\\\\.txt$'" M**

# **NUMBER FEEDBACK=AUTO \
#          EXPERT \
#          DISPLAY_IF {UseClientSessions} && {LoginManager}=='Foswiki::LoginManager::TemplateLogin'**

Here is an example from AUDIT.spec that uses the new syntax in context. (note that it's syntax is different, but the use model and many elements are the same)

#---++ Web server & Environment
# These action buttons analyze the webserver and Foswiki environments.
#!
#! CGISetup is both an auditor and an item checker.  The items are checked with
#! virtual buttons >= 100.
#!
#! The audit groups for the auditor use the standard button numbers.
#! Note that other items can be added by making them a member of one of these
#! audit groups.  (e.g. to add {foo} checker to the Webserver audit, in
#! Foswiki.spec, declare {foo} with AUDIT="CGI:0"

{CGISetup} [CGI CORE:2 EXTN:3] NOLABEL AUDIT="CGI:101 CORE:102 EXTN:103" \
                                       FEEDBACK="~p[/test/pathinfo]Web server" \
                                       FEEDBACK="Foswiki" \
                                       FEEDBACK="Extensions" 

#! Buttons can control overlapping groups, which can be useful for a series of tests that
#! include supersets.
#!{CGISetup} [CGI CORE:2 EXTN:3 CGI:4 CORE:4 EXTN:4] NOLABEL AUDIT="CGI:101 CORE:102 EXTN:103" \
#!                                                           FEEDBACK="~p[/test/pathinfo]Web server" \
#!                                                           FEEDBACK="Foswiki" \
#!                                                           FEEDBACK="Extensions" \
#!                                                           FEEDBACK="~p[/test/pathinfo]Everything"

Impact

I expect the impact to be purely positive, and would ordinarly bundle this into the other work. But since it is technically independed of that work, and there is the remote possiblity of #! creating an issue, I thought it safest to raise this as a separate proposal.

It would be good to get this into 1.2 as the job of making the .spec file changes for feedback would be a lot more pleasant. So early feedback would be appreciated...

It's a very small change - and would be easy to backport into earlier releases if one wanted to assist extensions using the newer syntax.

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

-- Contributors: TimotheLitt - 19 Nov 2012

Discussion

Accepted by 14 day rule.

-- TimotheLitt - 03 Dec 2012

I'm not sure where this stands with the updated 1.2 configure. It probably should be deferred to 2.0, and also evaluated for the move to a configure plugin.

-- GeorgeClark - 02 Apr 2014

It is mostly implemented in 1.2 - see HowToWriteASpecFile. I have re-used most of Timothe's work, though radically simplified it.

-- CrawfordCurrie - 28 Aug 2014

Marking this implemented for 1.2.

-- GeorgeClark - 15 Jun 2015

Commenting is disabled while not logged in