ReadMe for mc4hp

Table of Content

1. What is mc4hp?
2. Configuration file
  2.1 Syntax
  2.2.Values and defaults
  2.3. Example for a minimum configuration file
3. Macro syntax
  3.1. Basics
  3.2. Special cases
    3.2.1. Arguments
    3.2.2. Define
    3.2.3. If
    3.2.4. Self
    3.2.5. Parent
    3.2.6. Compiler
    3.2.7. File
4. Copyright & stuff

1. What is mc4hp?

It's a preprocessor which can be used for any kind of text files. It provides recursive evaluation/substitution and knows "if"s and "define"s. mc4hp stands for "macro compiler for homepages".
it will only process files that have different modification times and thus reducing the work :)

I tested it on Linux and Windows. mc4hp requires an installed JRE >= 1.4. (currently untested/unadjusted for gnu classpath)
Current version: v017

2. Configuration file

2.1. Syntax

The syntax is very simple (keep care, mc4hp is case-sensiv!):

key = data
# any line starting with "#", "//" or ";" will be ignored.
# leading or trailing white spaces will be ignored, too.
// any line starting with "[" will be ignored and
; are only for optical use to separted the settings eg.:
[general]

2.2. Values and defaults

start
marker that tells mc4hp where to start evaluating.
default: <!-- (< might be faster to type :)
end
marker that tells mc4hp where to stop evaluating.
default: --> (> might be faster to type :)
define
may contain several values separted by blanks. define is a very special values, see below for details.
default: (emtpy)
codepage
encoding used for the source files (see here for details).
default: ISO8859_1
force
if set to yes, mc4hp will compile all files.
default: no
update
if set to yes, mc4hp will update the timestamp of source and compiled (=dst) files (helpful in combination with force=yes).
default: no
threads
sets the number of worker-threads to use. if the values is larger than the total number of files, it will be reset to the number of files. minimum is 1.
default: 10
include
tells mc4hp which files should be processed as text files. binary files are simply copied.
default: htm html shtm shtml php php3 php4 asp js css
showfiles
if set to yes mc4hp will output the file names that are included. eg. <!-- start dir/file.htm --> ... <!-- end dir/file.htm -->
default: no
commentstart
for error messages produced by mc4hp and shownames.
default: start
commentend
for error messages produced by mc4hp and shownames.
default: end
src
sets the source directory - highly recommended to change the default!
default: .
cfg
sets the configuration directory (where mc4hp should search the included files) - highly recommende to change the default!
default: .
dst
sets the destionation directory (where to compile the files to) - highly recommende to change the default!
default: .
recursion
set to yes if you want to call a file itself again.
default: no (to avoid endless loops)
anythingelse
will be treatend as normal variable eg. os=linux (can be used for if).
default: (empty)

2.3. Example for a minimum configuration file

Very short :)
cfg=U:\my_homepage\cfg
dst=U:\my_homepage\dst
src=U:\my_homepage\src

3. Macro syntax

3.1. Basics

The evaluation is only done between the start- and end-marker (eg. <!-- and -->).
REMARK: The first charachter after the start-marker MUST be a $!
REMARK: Macros are processed from right to left!

<!--${os}-->
variable: will return "linux" if we have a line "os = linux" in the conf.
<!--$header-->
include file: will substitue it with the content of the file header which must be located in the cfg-directory.
<!--$(date.bat)-->
run program: will substitue it with the output of the script/program date.bat (must exist in the cfg-directory). - cfg will be set as working directory. Don't forget to set the file executable under Linux!
You may also pass on arguments:
<!--$header "title for this site"-->
arguments that have blanks can be set under quotes.
<!--$(md5sum.sh) program.tgz-->
eg. will calculate the md5sum of the given argument/file (if the script constists of "#!/bin/bash \ md5sum "$1"")
<!--$footer ${blahblahblah}-->
as mc4hp does recursive evaluation you can pass variables as arguments, too.
BTW, evaluation is done from right to left.

Example content of header

<html>
 <head>
  <title><!--${1}--></title>
 </head>

As you can see the first argument passed is called ${1}, the 2nd ${2} and so on... There is no actual limit for the numbers of arguments (except JAVA itself).

3.2. Special cases

3.2.1. Arguments

${1}, ${2}, ${3}, ...
${1} refers to 1st argument, ${2} to the 2nd etc...
${*}
refers to "${1} ${2} ... ${n}" (without quotes)
${@}
refers to ""${1}" "${2}" ... "${n}"" (with quotes!)
${#}
number of arguments

3.2.2. Define

Let's say we have "define=_en _de"

${define} returns "_en _de"
${define:c} returns the current define - in this case either "", "_en" or "_de".
${define:0} returns "_en"
${define:1} returns "_de"

There are special define-instructions. content of the example file "index.htm":

<!--$header "main site"-->
 <!--$define-->Jassu! (Greek for "Hi there!";)<!--$enddef-->
 <!--$define _en-->Hi there!
Here we have some more lines written in english.
<!--$enddef-->
 <!--$define _de-->Grüß dich!<!--$enddef-->
<!--$footer-->

The compiled file index.htm will result in 3 files in the dst-directory: index.htm, index_en.htm and index_de.htm.
index.htm contains "Jassu!"
index_en.htm contains "Hi there!"
index_de.htm contains "Grüß dich!"

REMARK: If you only have 2 lines ("$define _en" and "$define _de"), mc4hp will only create 2 files: index_en.htm and index_de.htm. - cool ey!? ;))

REMKARK: The $define-blocks must not overlap!

NEW: a few abbreviations:
long short
${define} ${def}
${define:c} ${def:c}
${define:0} ${def:0}
$define $def
$enddef $fed
$endif $fi

3.2.3. If

$if is very similar to $define. currently supported operators are
== (equal, string comparison)
!= (not equal, string comparison)
< (less than, number comparison)
> (greater than, number comparison)
<= (less or equal, number comparison)
>= (greator or equal, number comparison)
another example header:

<html>
 <head>
  <title><!--${2}--></title>
 </head>
 <body>
  <!--$if ${1} == downloadmenu-->  <!--$submenu--> <!--$endif-->
  <!--$if ${1} != downloadmenu--> Here should be a quote of the day, but only if arugment 1 is not "downloadmenu" <!--$endif-->
  <!--$if "${1}" == "othermenu"--> As you see it doesn't matter if you put the arguments under quotes or not. <!--$othermenu-->
  <!--$endif-->

REMKARK: The $if-blocks must not overlap!

Examples how to use this header:

<!--$header downloadmenu "download section"-->
<!--$header othermenu "some other fancy menu"-->
<!--$header "" "arg 1 is empty!"-->
<!--$header "xy" "this will work but won't insert the download or other menu"-->

Another example: date

<!--$if "${os}" == "linux"--> <!--$(date.sh)--> <!--$endif-->
<!--$if "${os}" == "win"--> <!--$(date.bat)--> <!--$endif-->

Content of date.sh
#!/bin/bash
date

Content of date.bat
@echo off
echo.|date

3.2.4. Self

${0} refers to the current file itself. eg. current file u:\my_homepage\src\download\index.htm

${0} returns relative file/path: download/file.htm [sic! this is a slash and NO backslash!]
${0:a} returns the absolute path: u:\my_homepage\src\download\index.htm
${0:d} returns the relative directory: download/
${0:e} returns the file extention: .htm (empty if no extention)
${0:f} returns the base file name: index

${0:df} returns the relative directory and file name: download/index
${0:fe} returns the base file name and extention: index.htm
${0:D} returns the full file name with define: download/index_en.htm
${0:E} returns the full file name with leading define eg. en/download/index.htm
${0:F} returns the full file name: download/index.htm

${0:m} returns the modification date/time (format yyyy-mm-dd hh:nn:ss) - handy for the footer eg. "last changed 2005-01-29"
${0:md} returns the modification date (format yyyy-mm-dd)
${0:mt} returns the modification time (format hh:nn:ss)
${0:ms} returns the modification date/time in seconds since 1970 (you know "unix time")
${0:mi} returns an ISO8601 date/time (format yyy-mm-ddThh:nn:ss+TZ:TZ)

${0:mY} returns the modification year (format YYYY)
${0:mM} returns the modification month (format MM)
${0:mD} returns the modification day (format DD)
${0:mH} returns the modification hour (format HH)
${0:mN} returns the modification minutes (format NN)
${0:mS} returns the modification seconds (format SS)

${0:sb} returns size in bytes (format #)
${0:sB} returns size in bytes (format #,###)
${0:sk} returns size in kb (1024; format #)
${0:sK} returns size in kb (1024; format #,##0.00)
${0:sm} returns size in mb (1024; format #))
${0:sM} returns size in mb (1024; format #,##0.00)
${0:sg} returns size in gb (1024; format #)
${0:sG} returns size in gb (1024; format #,##0.00)

3.2.5. Parent

As ${0} refers to the current file, you don't know the parent file ("root file" might be a better name). It's nearly the same as ${0} but it's called ${p} (So there is also ${p:a}, ${p:m} etc...)
eg.:

index.html (has a reference to header; ${p} contains "index.html")
  header (has a reference to banner; ${p} contains "index.html")
    banner (${p} contains "index.html"!)

3.2.6. Compiler

${c:v} returns version number of mc4hp
${c} returns "mc4hp" (well, obligatorial :)
${c:u} returns user name (taken from System.getProperty())
${c:os} returns the operating system (eg. "Windows 2000")
${c:oa} returns the os' architecture (eg. "x86")
${c:ov} returns the os' version (eg. "5.0")

${c:m} returns the compile date/time (format yyyy-mm-dd hh:nn:ss) - handy for the footer eg. "last changed 2005-01-29"
${c:md} returns the compile date (format yyyy-mm-dd)
${c:mt} returns the compile time (format hh:nn:ss)
${c:ms} returns the compile date/time in seconds since 1970 (you know "unix time")
${c:mi} returns an ISO8601 date/time (format yyy-mm-ddThh:nn:ss+TZ:TZ)

${c:mY} returns the compile year (format YYYY)
${c:mM} returns the compile month (format MM)
${c:mD} returns the compile day (format DD)
${c:mH} returns the compile hour (format HH)
${c:mN} returns the compile minutes (format NN)
${c:mS} returns the compile seconds (format SS)

3.2.7. File

The same as "Parent" and "Self", but this File refers to a file you define!

<!--$file "c:\windows\notepad.exe"-->
tells to mc4hp to retrieve file information for "c:\windows\notepad.exe".
<!--${f:a}-->
returns "c:\windows\notepad.exe"
<!--$file header-->
tells to mc4hp to retrieve file information for "header" - the search path is file, ${src}\file, ${cfg}\file, ${dst}\file!
<!--${f:a}-->
returns "c:\mc4hp\cfg\header"
<!--$file "${src}\header"-->
see above
<!--${f:a}-->
see above

4. Copyright & stuff

(c) 2005-2007 by The Condor - www.niksoft.at
This program is free for personal use; if you want the crapy source mail me; donations are welcome (see "license.txt" for details) - I may convert to GPL.
Please donate! http://www.niksoft.at/donate.php

Last edited: 2007-02-20