environment-macros 1.2

Summary

JPlate environment macros

Import Summary

Import Definitions
File	Description	Comment
${jplate.LOCALE_HOME}/environment-macros-messages.xml	Import local specific messages.	Import locale specific messages.
common.xml	Contains all JPlate common work.	Import our macros...
utility-macros.xml	Contains all JPlate utility macros.	Import our macros...

Macro Definition Summary

Macro Definitions
Name	Description	URI
assert-dir-exists	Determines if `@{dir}` exists and if not, fails with `@{error-msg}`.	http://jplate.sourceforge.net/environment
assert-file-exists	Determines if `@{file}` exists and if not, fails with `@{error-msg}`.	http://jplate.sourceforge.net/environment
auto-property	Define setting properties using either environment variables or default values. The property entitled `@{property}` will not be re-set if it is currently defined (set).	http://jplate.sourceforge.net/environment
basename	Same as Ant's stock basename task - however, this allows the property to be reset.	http://jplate.sourceforge.net/environment
compute-branch	Compute the branch based upon a root dir, `@{root}`, and full path, `@{full-path}`. The branch represents the full path minus the root dir. Please note: if `@{root}` does not exist in `@{full-path}`, `@{property}` will be set with an empty value.	http://jplate.sourceforge.net/environment
conditional-set-property	This will conditionally set a property whether. If `@{property}` is set it will use `@{set}` otherwise `@{unset}`.	http://jplate.sourceforge.net/environment
console-input	Will prompt for input if property not set (or if the `@{always}` attribute is true). If `@{always}` is true and `@{property}` is set and `@{default}` is empty, the value of `@{property}` becomes the `@{default}` value. If the attribute `@{required}` is true and no value is set for `@{property}`, this macro will cause a fail to be invoked. Please note that if `@{default}` is set and input is prompted but the user does not enter anything, the value of `@{default}` will be used to set the property!	http://jplate.sourceforge.net/environment
copy	This will copy from `@{src}` to `@{dest-dir}`.	http://jplate.sourceforge.net/environment
copy-dir	This will copy the contents of a directory from `@{src-dir}` to `@{dest-dir}`. Please note: if `@{dest-dir}` does not exist, it will be created.	http://jplate.sourceforge.net/environment
copy-ref-id	This will copy from `@{src-ref-id}` to `@{dest-dir}`. Please note: if `@{dest-dir}` does not exist, it will be created.	http://jplate.sourceforge.net/environment
dirname	Same as Ant's stock dirname task - however, this allows the property to be reset.	http://jplate.sourceforge.net/environment
equality-set-property	This will set the value of the property entitled `@{name}` based upon a comparison to the value contained by the property ${property}. If `@{property}` equals `@{value}`, `@{name}` will be set to `@{equal}`, otherwise it will be set to `@{unequal}`.	http://jplate.sourceforge.net/environment
execute-java-app	Execute a java class whose class name is `@{class-property}`. If this property is not set, the user will be prompted for the class name.	http://jplate.sourceforge.net/environment
for	This implements a for loop with starting and ending values for the loop.	http://jplate.sourceforge.net/environment
if-dir-exists	Determines if `@{dir}` exists and will act accordingly.	http://jplate.sourceforge.net/environment
if-file-exists	Determines if `@{file}` exists and will act accordingly.	http://jplate.sourceforge.net/environment
load-file	This will load a file into a property. If `@{property}` was already set, it will be overridden.	http://jplate.sourceforge.net/environment
print-ref-id	Print the contents of `@{ref-id}` to the console.	http://jplate.sourceforge.net/environment
set-property	This will set a property whether its set or not.	http://jplate.sourceforge.net/environment

Details

Macro Definition Details

assert-dir-exists

Determines if @{dir} exists and if not, fails with @{error-msg}.

Attribute Definitions
Name	Description	Default
dir	The name of the directory that should exist.	Not Defined
error-msg	The message to display if `@{dir}` does not exist.	${jplate-environment.assert-dir-exists.error-msg}
description	Information about this macro call.	Not Defined

@{dir}

@{error-msg}

Attributes
@{dir} = the name of the directory that should exist.
@{error-msg} = the message to display if @{dir} does not exist.
@{description} = information about calling this macro.

assert-file-exists

Determines if @{file} exists and if not, fails with @{error-msg}.

Attribute Definitions
Name	Description	Default
file	The name of the file that should exist.	Not Defined
error-msg	The message to display if `@{file}` does not exist.	${jplate-environment.assert-file-exists.error-msg}
description	Information about this macro call.	Not Defined

@{file}

@{error-msg}

Attributes
@{file} = the file that should exist.
@{error-msg} = if @{dir} does not exist, the message to display.
@{description} = information about calling this macro.

Attributes
@{property} = the name of the property to set.
@{default} = default value to use if the property named @{property} is not set.
@{description} = information about calling this macro.

basename

Same as Ant's stock basename task - however, this allows the property to be reset.

Attribute Definitions
Name	Description	Default
file	The path to take the basename of.	Not Defined
property	The name of the property to set.	Not Defined
suffix	The suffix to remove from the resulting basename (specified either with or without the .).	Not Defined
prepend	Information to prepend to property's value.	Not Defined
append	Information to append to property's value.	Not Defined
description	Information about this macro call.	Not Defined

Attributes
@{file} = the path to take the basename of.
@{property} = the name of the property to set.
@{suffix} = the suffix to remove from the resulting basename (specified either with or without the ".").
@{prepend} = information to prepend to property's value.
@{append} = information to append to property's value.
@{description} = information about calling this macro.

compute-branch

Compute the branch based upon a root dir, @{root}, and full path, @{full-path}. The branch represents the full path minus the root dir. Please note: if @{root} does not exist in @{full-path}, @{property} will be set with an empty value.

Attribute Definitions
Name	Description	Default
root	The root of the path defined in `@{full-path}`.	Not Defined
full-path	The absolute path for which `@{root}` is the root of the path and the branch computed is this path minus the root.	Not Defined
property	The property to set with the branch.	Not Defined
description	Information about this macro call.	Not Defined

@{root}

@{full-path}

Please note:

@{root}

@{full-path}

@{property}

Attributes
@{root} = the root of the path defined in @{full-path}.
@{full-path} = the absolute path for which @{root} is the root of the path and the branch computed is this path minus the root.
@{property} = the property to set with the branch.
@{description} = information about calling this macro.

Example
@{root} = /foo/bar/alpha
@{full-path} = /foo/bar/alpha/beta/theta/zeta

Result
@{property} = beta/theta/zeta.

Example
@{root} = /hello/world
@{full-path} = /foo/bar/alpha/beta/theta/zeta

Result
@{property} =

conditional-set-property

This will conditionally set a property whether. If @{property} is set it will use @{set} otherwise @{unset}.

Attribute Definitions
Name	Description	Default
name	The name of the property to set.	Not Defined
property	The name of the property to examine to see if set.	Not Defined
set	The value to use if `@{property}` is set.	Not Defined
unset	The value to use if `@{property}` is not set.	Not Defined
is-warnable	A flag, if true states a warning should be displayed - anything else no warning is outputted.	true
warning-msg	if set to anything and the property named, name, is set, will echo the value of this param. Please note, the property will still be set.	${jplate-environment.conditional-set-property.warning-msg}
description	Information about this macro call.	Not Defined

@{name}

@{property}

@{set}

@{unset}

Attributes
@{name} = the name of the property to set.
@{property} = the name of the property to examine to see if set.
@{set} = the value to use if @{property} is set.
@{unset} = the value to use if @{property} is not set.
@{is-warnable} = a flag, if true implies a warning should be displayed (if @{property} is currently set), or false no warning message.
@{warning-msg} = if set to anything and the property named, name, is set, will echo the value of this param. Please note, the property will still be set.
@{description} = information about calling this macro.

console-input

Will prompt for input if property not set (or if the @{always} attribute is true). If @{always} is true and @{property} is set and @{default} is empty, the value of @{property} becomes the @{default} value. If the attribute @{required} is true and no value is set for @{property}, this macro will cause a fail to be invoked. Please note that if @{default} is set and input is prompted but the user does not enter anything, the value of @{default} will be used to set the property!

Attribute Definitions
Name	Description	Default
prompt	When requesting input, the message to display.	Not Defined
property	The property to set.	Not Defined
default	The default value to use if upon input, nothing entered.	Not Defined
always	If true will prompt for input regardless if property has been set.	false
required	If true, after input the property must be set or failure will occur.	true
error-msg	If `@{property}` is required and no value set, the error message to display.	${jplate-environment.console-input.error-msg}
description	Information about this macro call.	Not Defined

@{always}

@{property}

@{default}

@{property}

@{default}

@{required}

@{property}

@{default}

Attributes
@{prompt} = when requesting input, the message to display.
@{property} = the property to set.
@{default} = the default value to use if upon input, nothing entered.
@{always} = if true will prompt for input regardless if property has been set.
@{required} = if true, after input the property must be set or failure will occur.
@{error-msg} = if @{property} is required and no value set, the error message to display.
@{description} = information about calling this macro.

copy

This will copy from @{src} to @{dest-dir}.

Attribute Definitions
Name	Description	Default
src	The source to copy from - be it a file, dir or ref id.	Not Defined
dest-dir	The directory to copy to.	Not Defined
error-msg	Error message to display if `@{src}` does not exist or is not a file, dir or ref id.	${jplate-environment.copy.error-msg}
description	Information about this macro call.	Not Defined

@{src}

@{dest-dir}

@{src}

a file, the file will be copied.
a directory, the directory's contents will be copied.
a path ref, the contents of each element will be copied (meaning a file will copy the file, a directory will copy the contents of the directory, etc).

Please note:

@{dest-dir}

Attributes
@{src} = the source to copy from - be it a file dir or ref id.
@{dest-dir} = the directory to copy files to.
@{error-msg} = the error message to display if @{src} does not exist or is not a file, dir or ref id.
@{description} = information about calling this macro.

copy-dir

This will copy the contents of a directory from @{src-dir} to @{dest-dir}. Please note: if @{dest-dir} does not exist, it will be created.

Attribute Definitions
Name	Description	Default
src-dir	The source dir copy from.	Not Defined
dest-dir	The directory to copy to.	Not Defined
error-msg	Error message to display if `@{src-dir}` does not exist.	${jplate-environment.copy-dir-set-property.error-msg}
description	Information about this macro call.	Not Defined

@{src-dir}

@{dest-dir}

Please note:

@{dest-dir}

Attributes
@{src-dir} = the source to copy from.
@{dest-dir} = the directory to copy files to.
@{error-msg} = the error message to display if @{src-dir} does not exist.
@{description} = information about calling this macro.

copy-ref-id

This will copy from @{src-ref-id} to @{dest-dir}. Please note: if @{dest-dir} does not exist, it will be created.

Attribute Definitions
Name	Description	Default
src-ref-id	The source to copy from - be it a file, dir or ref id.	Not Defined
dest-dir	The directory to copy to.	Not Defined
error-msg	Error message to display if `@{src-ref-id}` is not a ref id.	${jplate-environment.copy-ref-id.error-msg}
description	Information about this macro call.	Not Defined

@{src-ref-id}

@{dest-dir}

Please note:

@{dest-dir}

Attributes
@{src-ref-id} = the source ref id to copy from.
@{dest-dir} = the directory to copy files to.
@{error-msg} = the error message to display if @{src-ref-id} is not a ref-id.
@{description} = information about calling this macro.

dirname

Same as Ant's stock dirname task - however, this allows the property to be reset.

Attribute Definitions
Name	Description	Default
file	The path to take the basename of.	Not Defined
property	The name of the property to set.	Not Defined
prepend	Information to prepend to property's value.	Not Defined
append	Information to append to property's value.	Not Defined
description	Information about this macro call.	Not Defined

Attributes
@{file} = the path to take the dirname of.
@{property} = the name of the property to set.
@{prepend} = information to prepend to property's value.
@{append} = information to append to property's value.
@{description} = information about calling this macro.

equality-set-property

This will set the value of the property entitled @{name} based upon a comparison to the value contained by the property ${property}. If @{property} equals @{value}, @{name} will be set to @{equal}, otherwise it will be set to @{unequal}.

Attribute Definitions
Name	Description	Default
name	The name of the property to set.	Not Defined
property	The name of the property to examine for equality/inequality.	Not Defined
value	The value to compare against `@{property}`.	Not Defined
equal	the value to use if `@{property}` equals `@{value}`.	Not Defined
unequal	The value to use if `@{property}` not equal to `@{value}`.	Not Defined
is-warnable	A flag, if true states a warning should be displayed - anything else no warning is outputted.	true
warning-msg	The message to emit if `@{name}` is currently set.	${jplate-environment.equality-set-property.warning-msg}
description	Information about this macro call.	Not Defined

@{name}

@{property}

@{value}

@{name}

@{equal}

@{unequal}

Attributes
@{name} = the name of the property to set.
@{property} = the name of the property to examine to see if set.
@{value} = the value to compare @{property} to.
@{equal} = the value to use if @{property} equals @{value}.
@{unequal} = the value to use if @{property} is not equal to @{value}.
@{is-warnable} = a flag, if true states a warning should be displayed - anything else no warning is outputted.
@{warning-msg} = The message to emit if @{name} is currently set.
@{description} = information about calling this macro.

execute-java-app

Execute a java class whose class name is @{class-property}. If this property is not set, the user will be prompted for the class name.

Attribute Definitions
Name	Description	Default
class-property	The name of the property who has the fully qualified class name to execute.	Not Defined
class-path-ref	The class path for executing the java app.	Not Defined
args-property	The name of the property who has the arguments to pass to the class.	Not Defined
class-prompt-msg	The message to use if the property defined by class-property name has not been set.	${jplate-environment.execute-java-app.class-prompt-msg}
args-prompt-msg	The message to use if the property defined by args-property name has not been set.	${jplate-environment.execute-java-app.args-prompt-msg}
description	Information about this macro call.	Not Defined

@{class-property}

Attributes
class-property = the name of the property who has the fully qualified class name to execute.
class-path-ref = the class path for executing the java app.
args-property = the name of the property who has the arguments to pass to the class.
class-prompt-msg = the message to use if the property defined by class-property name has not been set.
args-prompt-msg = the message to use if the property defined by args-property name has not been set.
@{description} = information about calling this macro.

for

This implements a for loop with starting and ending values for the loop.

Attribute Definitions
Name	Description	Default
property	The name of the property that will contain the current value of the loop.	Not Defined
start	The start value of the loop.	1
end	The end value of the loop	Not Defined
inc	The value to increment (or decrement) when looping.	1
description	Information about this macro call.	Not Defined

Attributes
@{property} = the name of the property that will contain the current value of the loop.
@{start} = the start value of the loop.
@{end} = the end value of the loop.
@{inc} = value to increment (or decrement) while looping.
@{description} = information about calling this macro.

Elements
@{loop} = the children will be executed for each iteration of the loop.

if-dir-exists

Determines if @{dir} exists and will act accordingly.

Attribute Definitions
Name	Description	Default
dir	The name of the directory to check for existance.	Not Defined
description	Information about this macro call.	Not Defined

Attributes
@{dir} = the to directory examine for its existance.
@{description} = information about calling this macro.

Elements
@{then} = the block of code to execute if @{dir} exists.
@{else} = the block of code to execute if @{dir} does not exist.

if-file-exists

Determines if @{file} exists and will act accordingly.

Attribute Definitions
Name	Description	Default
file	The name of the file that should exist.	Not Defined
description	Information about this macro call.	Not Defined

Attributes
@{file} = the to file examine for its existance.
@{description} = information about calling this macro.

Elements
@{then} = the block of code to execute if @{file} exists.
@{else} = the block of code to execute if @{file} does not exist.

load-file

This will load a file into a property. If @{property} was already set, it will be overridden.

Attribute Definitions
Name	Description	Default
src-file	The location of the file to load and store in `@{property}`.	Not Defined
property	The property to hold `@{src-file}`.	Not Defined
description	Information about this macro call.	Not Defined

@{property}

Attributes
@{src-file} = the location of the file to load and store in @{property}.
@{property} = the property to hold @{src-file}.
@{description} = information about calling this macro.

print-ref-id

Print the contents of @{ref-id} to the console.

Attribute Definitions
Name	Description	Default
ref-id	The name of the ref id to display.	Not Defined
indent	String to use for indenting the contents of refid.	Not Defined
error-msg	When printing `@{ref-id}`, if a directory does not exist and ant raises an error, this value will be displayed instead.	${jplate-environment.print-ref-id.error-msg}
description	Information about this macro call.	Not Defined

@{ref-id}

Attributes
@{refid} = the name of the ref id to display.
@{indent} = string to use for indenting the contents of refid.
@{error-msg} = when printing @{ref-id}, if a directory does not exist, an error is raised by Ant. Instead of that error being displayed, the value of @{error-msg} is displayed instead.
@{description} = information about calling this macro.

set-property

This will set a property whether its set or not.

Attribute Definitions
Name	Description	Default
property	The name of the property to set.	Not Defined
value	The value to set the property to set.	Not Defined
is-warnable	A flag, if true states a warning should be displayed - anything else no warning is outputted.	true
warning-msg	if set to anything and the property named, property, is set, will echo the value of this param. Please note, the property will still be set.	${jplate-environment.set-property.warning-msg}
description	Information about this macro call.	Not Defined

Attributes
@{property} = the name of the property to set.
@{value} = the value to set the property to set.
@{is-warnable} = a flag, if true states a warning should be displayed - anything else no warning is outputted.
@{warning-msg} = if set to anything and the property named, property, is set, will echo the value of this param. Please note, the property will still be set.
@{description} = information about calling this macro.