com.ccg.util.Convert
com.ccg.util.TagLookup
com.ccg.util.CommandLineUtility
com.ccg.macros.At
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
public class At
A command line implementation of "@macros".
This is a full working "filter" type of program which is capable of processing macros. It comes with a built in set of macros (see the method defintions for the built in macros.
This program works as a standard Unix filter. It reads in a ASCII text file, interprets (processes) any contained macros and outputs the resulting text file. As an example, try feeding in the following contents to a invocation of "java com.ccg.macros.At":
@define(pkb_email,"@quote(paul@mekwin.com)") @define(pkb,"Paul Blankenbaker (@pkb_email)") Hello @pkb, looks like your email is "@pkb_email". Today is @now. @define(pkb_email,"@quote(paul_blankenbaker@yahoo.com)") Did the email address in the @quote(@pkb) macro change? @quote(@pkb)=@pkb Currently, the @quote(@pkb) macro is defined as "@definition(pkb)". The built-in @quote(@now) macro is defined as a Java method invocation which looks like: "@definition(now)". Here is a list of ALL available definitions. @dumpDefinitions
You can use many of the standard command line options which the
CommandLineUtility class recognizes. In
addtion, the following command line options are recognized:
run()| Constructor Summary | |
|---|---|
At(String[] args)
Initializes object with an array of command line arguments. |
|
| Method Summary | |
|---|---|
void |
atCopyToDir(Output out,
Vector args)
@atCopyToDir(MATCH0,MATCH1,&02e;&02e;&02e;,DIR) copy AND interpret one or more files to directory. |
void |
copyToDir(Output out,
Vector args)
@copyToDir(MATCH0,MATCH1,&02e;&02e;&02e;,DIR) copy one or more files to directory. |
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. |
AtMacros |
getAtMacros()
Get the "@macro" interpreter to use. |
String |
getLineSeparator()
Get the string used to separate lines on the current platform. |
void |
htmlEscape(Output out,
Vector args)
@htmlEscape(TEXT) - escape special HTML characters '<', '>' and '&'. |
void |
include(Output out,
Vector args)
@include(SOURCE,[IGNERR],[NOOUT]) insert and process other file(s). |
void |
loadDefaultDefinitions()
Process a set of well known user files. |
void |
loadTSV(Output out,
Vector args)
@loadTSV(NAME,SOURCE) load a tab separated table. |
void |
now(Output out,
Vector args)
@now() macro - dumps current time. |
void |
param(Output out,
Vector args)
@param(N) macro - get parameter value. |
void |
quote(Output out,
Vector args)
@quote(TEXT) macro - output text verbatim. |
void |
run()
Runs the interpreter reading from the input source and writing the output. |
void |
setAtMacros(AtMacros val)
Set the "@macro" interpreter to use. |
void |
setLineSeparator(String val)
Set the string used to separate lines on the current platform. |
| Methods inherited from class com.ccg.util.CommandLineUtility |
|---|
getFiles, getInputStream, getLineNumberReader, getOutputStream, getPrintWriter, getStrings, setInputStream, setOutputStream |
| Methods inherited from class com.ccg.util.TagLookup |
|---|
get, getBoolean, getChoice, getColor, getDate, getDate, getFont, getIndexedList, getInputStream, getLocale, getLookup, getNumber, getNumber, getOutputStream, getString, getString, getStrings, getTag, getTimeSpan, getTimeSpan, setLookup, setTag |
| Methods inherited from class com.ccg.util.Convert |
|---|
choiceValue, getDateFormat, getNumberFormat, setDateFormat, setNumberFormat, toBoolean, toColor, toDate, toFont, toInputStream, toLocale, toNumber, toOutputStream, toString, toTimeSpan |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
|---|
public At(String[] args)
This constructor initializes the object with an array of
command line arguments. Once constructed one, can use the run() method to cause the interpreter to run.
args - Array of command line arguments (typically the what the #main method would be passed at startup).run()| 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 loadDefaultDefinitions()
This method will attempt to load definitions from file(s) in some well known (or expected locations). All files are optional (if not found nothing is done). Also, no output is produced while interpretting these files (they are purely for the purpose of adding standard definitions).
Refer to the ConfigSource class and in particular the
ConfigSource.getFile() method to see how the path to the
default file is determined.
public void setAtMacros(AtMacros val)
val - New AtMacros value to assign.getAtMacros()public AtMacros getAtMacros()
setAtMacros(com.ccg.macros.AtMacros)public void run()
parent class.
run in interface Runnablerun in class CommandLineUtility
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.
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 now(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 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 htmlEscape(Output out,
Vector args)
throws IOException,
InterpretException
This should probably be relocated to a special HTML version of
the At class. However, I needed something that would
translate '<' into "<", '>' into ">" and '&' into "&"
so that HTML examples would appear as the expected when viewed by
a browser.
This macro simply replaces HTML special characters, with the HTML escape codes.
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 loadTSV(Output out,
Vector args)
throws IOException,
InterpretException
This macro is used to load the definition of a tab separated table. It doesn't actually read the contents of the database immediately, instead it defines a new macro named "NAME" and associates a SOURCE (typically a file or URL) where we should fetch the data from.
When you want to insert the data of the table into your output, you then use the "@NAME(FORMAT)" macro to read each line from the table and FORMAT the output of the table.
For example, if one created a table named phone.tsv like the following:
Last First Phone Blankenbaker Paul 555-555-5555 Brown Megan 555-555-5555
And you used the following macros:
@loadTSV("phoneTable","phone.tsv")
@phoneTable("@param(1),@param(0),@param(2)\n")
This will result in the output of one blank line followed by a comma seaparated list of just the data fields. This is shown below:
Paul,Blankenbaker,555-555-5555 Megan,Brown,555-555-5555
If you are producing HTML, you can use the table formatting tags to nicely format your table data.
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).
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" or "false" (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 using this directive to include definition files, it is often handy to set the DISOUT value to "true" to disable any output as a result of interpretting the definition file (this allows one to enter comments in their definition files).
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 copyToDir(Output out,
Vector args)
throws IOException,
InterpretException
This macro is used to copy 0 or more existing files to a output directory. If the directory doesn't exist, it will be created. You may use the "*" as a wildcard in each of the file name strings to match more than one file.
For example, to copy the ".at" and "*.properties" files from the "/etc/macros" directory to the "/home/user/etc/macros" directory, one could use the following:
@defnow("sdir","/etc/macros")
@copyToDir("@sdir()/*.at","@sdir()/*.properties","/home/user/etc/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 atCopyToDir(Output out,
Vector args)
throws IOException,
InterpretException
This macro is used to copy 0 or more existing files to a output directory. If the directory doesn't exist, it will be created. You may use the "*" as a wildcard in each of the file name strings to match more than one file.
There is a HUGE difference between this command and the "@copyToDir". This command interprets each file that it copies and evaluates any "@macros" which it contains. This can be a VERY useful way to install HTML documents to their final location and do some subsitutions during the installation process.
It should be noted that any definitions (or redefinitions) made by the files processed WILL AFFECT all subsequent files processed (I may add a version of this macro which saves/restores the macros for each file processed).
To see the power of this function, take a look at the atcopy.atmacros "script". It does the following:
If you have the source code installed such that the "ccg" top level directory can be found under the "$COMHOME" environment variable, you should be able to try this out via:
java com.ccg.macros.At -Dcomhome=$COMHOME -Dhtmlroot=$HOME/public_html \
-in $COMHOME/ccg/macros/doc-files/atcopy.atmacros
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 | |||||||||