Re: [buckminster-dev] documentation error in common.xsd and PropertyElem

[Thomas Hallgren <thomas@xxxxxxx>]

Henrik Lindberg wrote:
> I would like to know more about PropertyElement and how it is supposed to be 
> used. There are things called toUpper, toLower, replace etc. What are these?
>   
PropertyElement is of a the powerful string manipulation utilities that 
sits beneath the Buckminster property system.

The following constructs will yield the same result:

 <bc:property key="someKey" value="the last"/>

same as (the bc:constant used here is a subclass of bc:Value):

 <bc:propertyElement key="someKey">
     <bc:constant value="the last"/>
 </:bc>

it could also be written like this (bc:toLower is also a subclass of 
bc:Value):

 <bc:propertyElement key="someKey">
   <bc:toLower>
     <bc:constant value="THE LAST"/>
   </bc:toLower>
 </:bc>

or, perhaps like this (bc:replace and bc:propertyRef are of course 
subclasses of bc:Value):

 <bc:property key="myText" value="extract the two words that precede 
the last word"/>

 <bc:propertyElement key="someKey">
   <bc:replace>
     <bc:propertyRef key="myText"/>
     <bc:match pattern=".*(\w+\s+\w+)\s+\w$" replacement="$1"/>
   </bc:replace>
 </:bc>

and also, using common Apache Ant style substitution, like this:

 <bc:property key="originalValue" value="the last"/>
 <bc:property key="someKey" value="${originalValue}"/>

The property system also provides a 'bc:format' capability that uses the 
semantics stipulated by java.text.MessageFormat where each parameter is 
a bc:Value element and the bc:format is a bc:Value subclass in itself.

The following example is a (somewhat mangled to avoid IP issues) excerpt 
from an 'live' rmap. It shows how component names are translated into 
specific positions in a folder structure (the folder structure in 
question came to existence long before Buckminster came into play and 
the naming is inconsistent with the actual component names so the 
mapping is a bit complex. I use it here as an example of how agile 
Buckminster can be):

<pv:uri 
format="/public/apollo/dev/sandboxes/personal/{0}/tools/{1}/-?defaultBranch=head">
   <bc:propertyRef key="buckminster.p4.user" />
   <bc:replace>
       <bc:toLower>
           <bc:replace>
               <bc:propertyRef key="buckminster.component" />
               <bc:match pattern="^(?:com\.)?(hal\..*)$" 
replacement="$1" />
               <bc:match pattern="^(?:com\.apollo\.)?(.*)$" 
replacement="$1" />
           </bc:replace>
       </bc:toLower>
       <bc:match pattern="^(util\.swing)$" replacement="$1" />
       <bc:match pattern="^ipz\.ui\.swing$" replacement="ipz/ui.swing" />
       <bc:match pattern="." replacement="/" quotePattern="true" />
   </bc:replace>
</pv:uri>

It says:

The innermost replace will see to that:
- any component that starts with "com.hal." is stripped of "com."
- any component that starts with "com.apollo" is stripped of "com.apollo"
- other component names are left as is.

a toLower makes sure that the result of the innermost replace is all 
lowercase and once that is done, the outer replace makes sure that:
- if the result is exactly "util.swing", then that will be the name of 
the folder.
- if the result is "ipz.ui.swing" then the folder will be "ipz/ui.swing"
- for all other results, replace '.' with '/'.

I hope this answered your questions and didn't complicate the 
documentation effort too much.

Regards,
Thomas Hallgren