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!

<!--$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