propcon

The default directory is the current directory. The default prefix is Pictools and the default result is prefix. A similar property mechanism can be implemented in Java with PropertyPack.java.

Java defines a property mechanism, but other languages do not. Propcon extends the Java property mechanism so the same set of properties is accessible to code written in many languages. Propcon checks various prefix.properties files versus the result.ext file. If any properties file is newer than the result file, propcon regenerates directory/result.ext. See Inheritance Definition Priority for the files checked.

Currently implemented ext values are

.mkinc  .php   .js  .h  .D  .csh  .sh  .ctbl .ant .properties

As described under "Supported Output Languages".

propcon reports status 0 (success) if result.ext was up-to-date or has been made so. If execution failed, the status is 1. If the file needed to be created or updated a message is printed like this

writing /home/username/websrc/adir/Pictools.php
propcon defined 35 properties in Pictools.php

Property Names

By convention, property names are in lower-case with dots between words. They start with a letter and continue with letters, digits, and periods. (In the Java definition, all characters are valid in property names; propcon tries to cope, but accepting limitations will make life easier.) For output extensions other than .php .js, and .ctbl, the keys are converted to upper case and the periods are converted to underlines. That is, the key thumbs.pictd is written in a Makefile or C file as THUMBS_PICTD.

Propcon augments the properties by defining the property propcon.directory to have the value of the target directory.

Writing Pictools.properties

Pictools.properties files must be Java properties file in the format given by java.util.Properties.java#load(java.io.Reader) Property definition lines are of the form

property-name delimiter property-value

where delimiter is colon, equal, or empty.Values may occupy multiple lines by ending all but the last with backslash, Lines whose first non-blank charactes are # are comments.

See the propcon source code for the details of output character escaping.

Trailing Blanks

When reading .properties files, Java incorporates into a value all trailing space on a line. Propcon does the same. Most of the output formats put the value in quotes, so trailing spaces are included. The 'make' program also incorporates trailing spaces from defines. The one problem is for .h files: trailing spaces are deleted from #define lines. The best solution is to not expect trailing spaces. Or define a quote mechanism and write the program to strip the quotes as values are fetched. You can also import values as a .ctbl.

Pragmas

A comment line starting #! is a pragma; the next word is interpreted by propcon. The pragma "private" indicates that the next property to be defined is not inherited by child directories. The pragma "export" means that when Pictools.mkinc is read by a Makefile--usually MakeVars--the definition of that variable will be exported to the environment that Makefile presents as the shell environment for commands run in recipes.

For instance, in the root directory, mime.xls needs to be downloadable, but this does not apply to subdirectories. Accordingly /Pictools.properties has these lines

#! private  
downloadable: mime.xls

Beware! If you make the line after the pragma a comment, you must also further quote the pragma. If you don't, the pragma will apply to the next defined property. To quote a pragma, just add an additional initial '#'.

Properties inherit from prefix.properties in successive parent directories and from directories $SRCROOT, $HOME, and $PICTOOLS. The latter three directory values should be defined in the environment before using Pictools. In the scan of directories, the first encountered definition of a property is the one retained.

Parent directory traversal stops at the first of these

-- before processing $SRCROOT, if it is defined in the environment
-- before processing the root directory /
-- after processing a directory containing file robots.txt

If $SRCROOT, $PICTOOLS or $HOME are undefined in the environment, properties will not inherit therefrom (!)

Propcon always checks all possible source properties locations. It remakes prefix.ext only when it is necessary because one of the prefix.properties files is newer than the target prefix.ext file.

Definition Priority

Properties may be defined several ways. They are listed here in priority order; a definition at one level obviates all lower level definitions. The parameters directory, prefix, and root are from the command line. $HOME and $PICTOOLS are from the shell variable on the source platform or on the server $SERVER['DOCUMENT_ROOT'] and $SERVER['PICTOOLS']; see htaccess.php.

With an assignment line (propertyname=propertyvalue) in a captions file. *
In the <head> of a page that is an instance of the PhyspicsMain template. * The syntax is unlovable:
```
$sp->setprop("propertyname", "propertyvalue");
```
$PICTOOLS/prefixOverrides.properties
$HOME/prefixOverrides.properties
directory/prefix.properties
prefix.properties in parents of directory (up to root).
$HOME/Prefix.properties
$PICTOOLS/Prefix.properties

* Not in the list visited by PropCon.java.

Usage guidance

Here are some ways to access a property, say page.background:

C code: Before compiling the C code, run "propcon Pictools.h". Then the C source code can be:
Code in a pictools Makefile: Makevars will have run "propcon Pictools.mkinc" and "include Pictools.mkinc". To export the vakue to recipes, export it:
.csh script
in an Ant script for netbeans: (In .htaccess)

Supported output languages

Currently, propcon produes output for each of the listed languages. The second column is the extension for the reult file. The third shows how each property is defined in the result.ext file.

language	*ext*	form of lines in target file
`Makefile`	`.mkinc`	`KEY ?= value`
`php`	`.php`	`$props['key']='value'; $propsource['key'] = 'source directory';`
`JavaScript`	`.js`	`props['key']='val';`
`C include`	`.h`	`#undef KEY` `#define KEY value`
`cmd arg -D`	`.D`	`-Dkey='value' \`
`csh`	`.csh`	`setenv key 'value'`
`sh`	`.sh`	`key='value'; export key`
`C`	`.ctbl`	`{"key", "value"},`
`ant`	`.ant`	`key = value`
`Java`	`.properties`	`key = value`

Notes

In Javascript and php the values are elements in associative arrays.
In .D format, a backslash ends each line.
In Pictools.php, $propsource array values are site-rooted. They can be consulted to see if a property came from the current directory. This effect is now better accomplished with the #!private pragma.
Property definitions for Makefiles are conditional, the setting will not override any prior definition. The definitions are not automatically exported for use in shell commands in recipes.
To use the ".properties" output extension, be sure to redirect the output by having the -p value differ from the result parameter.

Usage table

language	*ext*	include `result.ext` file	get value for key `kkk`
`Makefile`	`.mkinc`	`include result.mkinc`	`$(KKK)`
`php`	`.php`	`include "result.php";`	`$props['kkk']`
`JavaScript`	`.js`	`<script` `type="text/javascript"` `src="result.js"></script>`	`props['kkk']`
`C include`	`.h`	`#include "result.h"`	`X_SIZE`
`cmd arg -D`	`.D`	cmd `echo result.D` other-switches parameters	`see below`
`csh`	`.csh`	`source result.csh`	`$X_SIZE`
`sh`	`.sh`	`. result.sh`	`$X_SIZE`
`C`	`.ctbl`	see below	see below
`ant`	`.ant`	`<properties` `file="result.ant"/>`	`${key}`
`Java`	`.properties`	`Properties p` `= new Properties` `("result.properties");`	`p.get("key";`

Here is some csh code to process -Dvar=value command line arguments.

char **a = argv+1;
while (*a != NULL) {
    char *flag = *a;
    char *var;
    char *value;
    if (*flag++ != '-') break;
    a++;
    switch (*flag) {
      case 'D':      // -Dname=value 
	      flag++;
	      value = strchr(flag, '=');
	      if (value == NULL) {  signal an error; break; }
        *value++ = '\0'; // terminate flag, skip '='
        var = flag;
        process the definition of var as value  
	      break;
    }
}

The following code demonstrates one way to use a .ctbl file. The file initializes an array of rows. The array is then used as the payload of a strtbl. From there values are accessed via getEntryFromStrTbl. Note that making any insertions or deletions in a strtbl declared this way should fail since the contents are in static memory.

#include 

#include "strtbl.h"
struct row rows[] = {
#include "Pictools.ctbl"
};
struct strtbl table = {sizeof(rows)/sizeof(*rows), 
	sizeof(rows)/sizeof(*rows), FIRST, rows};

int main (int argc, char **argv) {	
  printf("thumbs.wholepage: \"%s\"\n", 
    getEntryFromStrTbl("thumbs.wholepage", &table)  );
}