Re: [Gnumed-devel] Placeholder clarifications - nomenclature, syntax and rules

[Karsten Hilbert]

On Fri, Aug 16, 2013 at 02:50:56PM +0000, Jim Busser wrote:

> (1) every GNUmed placeholder must be bounded by a pair of dollar symbols $ 
> within which must exist a pair of angles brackets, thus:
> 
>       $<>$

Correct but may change.

> (2) between the $<>$, the simplest placeholder expects and
> supports a single 'field',

No such placeholders anymore in 1.4 to my knowledge.

> whereas those placeholders which
> support a second and third field require a separator
> (delimiter) after the first field, in the form of a pair of
> colons, thus:
> 
>       ::

Correct.

> as a result of which, a placeholder which supports three fields would have 
> the form
> 
>       $<field_1 :: field_2 :: field_3>$
> 
> wherein
> 
>       field_1 must, in all cases, provide a valid (defined-in-GNUmed) 
> placeholder name
> 
>       field_2 provides for one (or a series of) argument(s) which, in some – 
> but not all cases – need to be supplied
> 
>       field_3 provides for an ability, or a requirement, to specify a maximum 
> number (length) of target characters

Number, not length. Length would be *string* length.

> and
> 
>       field_1 cannot be followed solely by a single pair of ::
> 
> In other words, while field_1 can, in some cases, be complete as
> 
>       $<field_1>$

Not anymore.

> it cannot be
> 
>       $<field_1::field_2>$

Correct.

> but must include
> 
>       $<field_1::::>$
> 
> even if the '::' remain "empty".

Correct.

> Lastly, those placeholders which do not require the third
> field (max num of characters)

Which would those be ?  All of them output text so the max
number of characters can be applied to all of them.

> nevertheless, in all cases,
> support the third field to be included, whether the value
> within is null (empty) or whether it consists of a valid
> integer. Thus you can have $<field_1:::integer:>$

Typo !

        $<field_1::::integer>$

> or you can have $<field_1::::>$


> (which is the same as $<field_1>$).

Not anymore.

> Spaces, such as might make a placeholder's incarnation
> more readable, are not harmless.

... may not be harmless ...

> Within a placeholder, spaces – except when part of a
> valid and properly formatted argument – will break the
> placeholder, as in
> 
>       $< field_1::::60 >$.

This, however, is valid:

        $<field_1:::: 60>$

as is this:

        $<field_1:::: 60 >$

or this

        $<field_1::::60 >$

(because the 3rd field integer is [should be] detected just fine)

> In the situation where a properly-formatted placeholder
> cannot resolve to a value, such as in the case where no
> value had yet been created for a patient, the resulting
> output will depend whether or not the instance of GNUmed is
> running with --debug on.

Correct.

> If yes, it will return "no URL for
> …" and otherwise u'' (IOW, an empty value).

I believe that's correct.

Karsten
-- 
GPG key ID E4071346 @ gpg-keyserver.de
E167 67FD A291 2BEA 73BD  4537 78B9 A9F9 E407 1346