> pictools > doc > propcon
> pictools > doc > propcon
Pictools: MakeFile Internals
V3.3 (342)
propcon
/pictools/propcon
Converts Pictools.properties for inheritance and access by other languages
usage, in shell: propcon [-d directory] [-p prefix] [-r root] result.ext

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 and, if any are newer than the result file, regenerates directory/result.ext. The default dirctory is the current directory. The default prefix is result. For input, properties files are read from two override locations, the designated directory and its parents, and finally two defaults locatiions; see "Inheritance", below. The chain of parents stops at directory root; if unspecified, the scan stops at a directory containg robots.txt.

Currently implemented extension 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 '#'.

Inheritance

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.

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

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:
include "Pictools.h"
  ...
printf("color is %s\n", PAGE_BACKGROUND);
Code in a pictools Makefile
Makevars will have run "propcon Pictools.mkinc" and "include Pictools.mkinc". To export the vakue to recipes, export it:
export PAGE_BACKGROUND
.csh script
${PICTOOLS}/propcon Pictools.csh
source Pictools.csh
... $PAGE_BACKGROUND ...
in an Ant script for netbeans
(In .htaccess)
<exec executable=$_SERVER['PICTOOLS']."/propcon.exe">
    <arg value="-r"/>
    <arg value="${JAVAROOT}"/>
    <arg value="Pictools.ant"/>
</exec>

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)  );
}
 
Copyright © 2018 ZweiBieren, All rights reserved. Dec 20, 2018 12:18 GMT Page maintained by ZweiBieren