com.ccg.macros.at.Base
com.ccg.macros.at.Core
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
public class Core
Set of core macros which provide some standard basic features.
class Example {
public void main(String[] args) {
com.ccg.macros.at.Core o = new com.ccg.macros.at.Core();
System.out.println(o);
}
}
| Constructor Summary | |
|---|---|
Core()
Constructs the object and readies it for installation. |
|
| Method Summary | |
|---|---|
void |
debug(Output out,
Vector args)
@debug(LEVEL,TEXT) macro - debug output. |
void |
decrement(Output out,
Vector args)
@decrement(NAME) decrements value of integer macro by 1. |
void |
define(Output out,
Vector args)
@define(NAME,VAL[,OPT]) macro - define a new macro. |
void |
definition(Output out,
Vector args)
@definition(NAME) macro - fetch definition of a macro. |
void |
dumpDefinitions(Output out,
Vector args)
@dumpDefinitions() macro - dump definition of all macros. |
void |
fnb(Output out,
Vector args)
@fnb(V0[,V1[,V2[,...]) macro - find first "non-blank" value. |
void |
formatMillis(Output out,
Vector args)
@formatMillis([MILLIS][,DATE_FMT[,TIME_FMT]],[TZ]) macro - format a Java millisecond count. |
String |
getLineSeparator()
Get the string used to separate lines on the current platform |
void |
ifDefined(Output out,
Vector args)
@ifDefined(MACRO,YES,NO) macro - branch if macro is defined. |
void |
ifEqual(Output out,
Vector args)
@ifEqual(V1,V2,E,NE) macro - branching macro. |
void |
include(Output out,
Vector args)
@include(SOURCE,[IGNERR],[NOOUT]) insert and process other file(s). |
void |
increment(Output out,
Vector args)
@increment(NAME) increments value of integer macro by 1. |
void |
param(Output out,
Vector args)
@param(N[,t|f]) macro - get parameter value This macro is typically used in the definition of run time macros (in the VAL parameter of "@define(NAME,VAL)". |
void |
quote(Output out,
Vector args)
@quote(TEXT) macro - output text verbatim This macro is invoked in the form "@quote(TEXT)". |
void |
setDocumentInfo(Output out,
Vector args)
@setDocumentInfo(TYPE,INFO,yyyy-MM-dd) set information about the document. |
void |
setLineSeparator(String val)
Set the string used to separate lines on the current platform |
void |
systemProperty(Output out,
Vector args)
@systemProperty(NAME[,DEF]) macro - fetch a specific system property. |
| Methods inherited from class com.ccg.macros.at.Base |
|---|
getAtMacros, getDoubleParameter, getIntParameter, getLongParameter, getStringParameter, install |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
|---|
public Core()
installation.
Base.install(com.ccg.macros.AtMacros)| Method Detail |
|---|
public void setLineSeparator(String val)
val - New String value to assign - note, if you pass null, we will
attempt to reset it based on the "line.separator" system
property.getLineSeparator()public String getLineSeparator()
setLineSeparator(java.lang.String)
public void ifEqual(Output out,
Vector args)
throws IOException,
InterpretException
This macro is used to compare two values (V1 and V2). If the evaluation of the two values results in identical values, then the equal statement (E) is evaluated, else the false statement "NE" is evaluated.
@define(name,fred)@ifEqual("@name","barney","betty","wilma")
The above should result in the output of "wilma".
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void increment(Output out,
Vector args)
throws IOException,
InterpretException
This macro is used to increment the value of the macro "NAME" by 1. If the macro does not exist or has a non numeric value, it is created and initialized with a value of '1'.
@increment(cnt)@cnt,@increment(cnt)@cnt
The above should result in the output of "1,2".
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void decrement(Output out,
Vector args)
throws IOException,
InterpretException
This macro is used to decrement the value of the macro "NAME" by 1. If the macro does not exist or has a non numeric value, it is created and initialized with a value of '1'.
@define(cnt,4)@decrement(cnt)@cnt,@decrement(cnt)@cnt
The above should result in the output of "3,2".
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void ifDefined(Output out,
Vector args)
throws IOException,
InterpretException
This macro is evaluates the MACRO name passed. If the evaluated value of the MACRO is a defined macro, then the YES clause is evaluated. Otherwise the NO clause is evaluated.
The following determines if the @name() macro is defined. If not, it defines it to "fred".
@ifDefined("name",,"@define("name","fred")")
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void fnb(Output out,
Vector args)
throws IOException,
InterpretException
This macro returns the first parameter that evaluates to something other than white space (or no space). It is particularily useful when defining macros where you want to provide a default value if the user omits one. Here's an example that defines "pkb" to print "Paul Blankenbaker (574-7964)" unless a alternate phone number is passed:
@define("pkb","Paul Blankenbaker (@fnb("@param(0)","574-7964"))")
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void param(Output out,
Vector args)
throws IOException,
InterpretException
@define(email,"<a href=\"mailto:@param(0)\">@param(0)</a>")
@email("paul@mekwin.com")
The above defines a new run time macro "@email", the new "@email" macro allows the user to pass an argument which is subsitutes in two places. This provides a means to make some pretty powerful run time macros.
Note, the second parameter indicates whether you want the value of the parameter to be interpretted or not. You can get the exact value passed (instead of the default interrpretted results), by passing "f".
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void quote(Output out,
Vector args)
throws IOException,
InterpretException
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void setDocumentInfo(Output out,
Vector args)
throws IOException,
InterpretException
Often it is desirable to have a consistent set of macros to retrieve information about the document being processed (such as its last revision date, copyright, etc). This macro is used to generate these values.
You typically use this macro at the start of your document in the following form:
@setDocumentInfo("cvsId","$Id: Core.java,v 1.1.1.1 2004/01/26 20:46:18 pkb Exp $","2001-12-25")
The following parameters are recognized:
This takes the information passed to it and then defines the following macros:
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void formatMillis(Output out,
Vector args)
throws IOException,
InterpretException
This macro is invoked in the form "@millis(MILLIS)". This
macro accepts up to four arguments (how to format the date/time
and the time zone). Refer to the SimpleDateFormat class
if you want to specify your own custom format (like:
"yyyy-MM-dd").
The four optional parameters to this macro accepts include:
SimpleDateFormat
class (like "yyyy-MMM-dd hh:mm:ss").TimeZone.getTimeZone(String). For example: "UTC",
"America/Los_Angeles", or "GMT+10". If you pass a unrecognized
timezone, we will ignore your request (we will log a debug
message) and use the default time zone for the JVM.If you want to use one of the built in local formats, pass use one of the following keywords for the DATE_FMT and/or TIME_FMT parameters:
DateFormat.SHORT format for
this portion.
DateFormat.MEDIUM format for
this portion.
DateFormat.LONG format for
this portion.
DateFormat.FULL format for
this portion.
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void debug(Output out,
Vector args)
throws IOException,
InterpretException
debug level is enabled for
the LEVEL specified, the text is interpretted and debug output is
generated. This can be VERY useful when tracking down problems in
your source file.
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void define(Output out,
Vector args)
throws IOException,
InterpretException
@define(pkb_email,"@quote(paul@mekwin.com)")
After interpretting the above, one could then use "@pkb_email()" in the document and have "paul@mekwin.com" appear. It should be noted, that the "VAL" area can contain references to other macros. For example:
@define(pkb,"Paul Blankenbaker (@pkb_email)")
There are two important concepts to understand with the above. One is that the @pkb macro just defined contains a reference to another macro. This is handled properly and the contained @pkb_email reference will be expanded each time the @pkb macro is used. The second concept is that the expansion occurs at the time the @pkb macro is used, not at the time it is defined. In other words, if someone changed the definition of the @pkb_email macro, then it would affect subsequent invocations of the @pkb macro.
The third parameter to this macro is optional, and can be extremely useful in some circumstances. The third parameter can be one of the following:
To get an idea of how these behave, try running the the following through to see what comes out:
@define("name","Joe Schmoe")
@define("phone","333-333-3333")
@define("pname","@name @phone")
@define("nname","@name @phone","now")
@define("phone","444-444-4444")
@define("phone","555-555-5555","ifnew")
@quote("@pname=")@pname
@quote("@nname=")@nname
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void definition(Output out,
Vector args)
throws IOException,
InterpretException
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void systemProperty(Output out,
Vector args)
throws IOException,
InterpretException
Here are some sample (and useful definitions) out of "Core.At" which area available and make use of this:
@define("userName","@systemProperty("user.name","unknown")","now")
@define("userHome","@systemProperty("user.home",".")","now")
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void dumpDefinitions(Output out,
Vector args)
throws IOException,
InterpretException
This macro is mainly used for debugging purposes. It dumps the definition of ALL defined macros.
NOTE: You may optionally pass a single argument to this method. If passed, the argument will be expanded for each definition in our macro dictionary. The following macros will be available:
Here is an example which produces the same results as the default output:
@dumpDefinitions("@dumpDefName()=@dumpDefValue()
")
Here's an example which provides a little fancier output in HTML:
@dumpDefinitions("<h2>@quote(@)@dumpDefName()</h2>
<pre>
@htmlEscape("@dumpDefValue()")
</pre>
")
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
public void include(Output out,
Vector args)
throws IOException,
InterpretException
This macro is used to load and process the contents of another file. Currently the full or relative path to the source must be specified (in the future, path searching may be added).
It should be noted however, that the CLASSPATH and/or JAR files are searched. For example, the file "/com/ccg/macros/at/Jnlp.At" would be found as its included with the distribution. Check the "/com/ccg/macros/at" directory for "*.At" files which are available.
For example, to include the file "/opt/include/atmacros/companies.atmacros", one could use the following command:
@include("/etc/hosts")
The second parameter IGNERR is optional. It may be set to either "true" or "false" (only first letter is checked). If omitted, it defaults to a value of "false". When set to "true", then no error will be thrown if the file is not found. If set to "false" (or omitted), then an error will be thrown if the desired SOURCE could not be found.
The third parameter DISOUT is optional. It may be set to either "true", "false", "cdata" or "definitions" (only first letter is checked). If omitted, it defaults to a value of "false". When set to "true", then no output will be produced while interpretting the file included (this allows one to load definition files). When set to "false" (or omitted), any output produced as a result of interpretting the file will be written to the current output device. When set to "definition" (or "d"), no output will be generated, AND the file will only be included if it has not be included in the past (this is useful when you don't want to bother processing macro definition files more than once).
When the third parameter is set to "cdata" (or "c"), the contents of the file are treated as character data (similar to XML) and placed in the output verbatim.
When using this directive to include definition files, it is often handy to set the DISOUT value to "definition" (or "d") to disable any output as a result of interpretting the definition file (this allows one to enter comments in their definition files). It also prevents the same definitions from being loaded more than once during a run.
out - The output device to write the results of
processing the argument to.args - A vector of arguments which were passed to the macro.
IOException - If there is a problem writing to the output device
InterpretException - If a problem is encountered interpretting the arguments passed.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||