org.jawk.ext
Class CoreExtension
java.lang.Object
org.jawk.ext.AbstractExtension
org.jawk.ext.CoreExtension
- All Implemented Interfaces:
- JawkExtension
public class CoreExtension
- extends AbstractExtension
- implements JawkExtension
Extensions which make developing in Jawk and
interfacing other extensions with Jawk
much easier.
The extension functions which are available are as follows:
- Array -
Array(array,1,3,5,7,9)
Inserts elements into an associative array whose keys
are ordered non-negative integers, and the values
are the arguments themselves. The first argument is
the assocative array itself.
- Map/HashMap/TreeMap/LinkedMap -
Map(map,k1,v1,k2,v2,...,kN,vN)
,
or Map(k1,v1,k2,v2,...,kN,vN)
.
Build an associative array with its keys/values as
parameters. The odd parameter count version takes
the map name as the first parameter, while the even
parameter count version returns an anonymous associative
array for the purposes of providing a map by function
call parameter.
Map/HashMap configures the assocative array as a
hash map, TreeMap as an ordered map, and LinkedMap
as a map which traverses the key set in order of
insertion.
- MapUnion -
MapUnion(map,k1,v1,k2,v2,...,kN,vN)
Similar to Map, except that map is not cleared prior
to populating it with key/value pairs from the
parameter list.
- MapCopy -
cnt = MapCopy(aa_target, aa_source)
Clears the target associative array and copies the
contents of the source associative array to the
target associative array.
- TypeOf -
typestring = TypeOf(item)
Returns one of the following depending on the argument:
- "String"
- "Integer"
- "AssocArray"
- "Reference" (see below)
- String -
str = String(3)
Converts its argument to a String.
Similar to the _STRING extension, but provided
for completeness/normalization.
- Double -
dbl = Double(3)
Converts its argument ot a Double.
Similar to the _DOUBLE extension, but provided
for completeness/normalization.
- Halt -
Halt()
Similar to exit(), except that END blocks are
not executed if Halt() called before END
block processing.
- Timeout -
r = Timeout(300)
A blocking function which waits N milliseconds
before unblocking (continuing). This is useful in scripts which
employ blocking, but occasionally needs to break out
of the block to perform some calculation, polling, etc.
- Throw -
Throw("this is an awkruntimeexception")
Throws an AwkRuntimeException from within the script.
- Version -
print Version(aa)
Prints the version of the Java class which represents the parameter.
- Date -
str = Date()
Similar to the Java equivalent : str = new Date().toString();
- FileExists -
b = FileExists("/a/b/c")
Returns 0 if the file doesn't exist, 1 otherwise.
- NewRef[erence]/Dereference/DeRef/Unreference/UnRef/etc. -
Reference Management Functions.
These are described in detail below.
Reference Management
AWK's memory model provides only 4 types of variables
for use within AWK scripts:
- Integer
- Double
- String
- Associative Array
Variables can hold any of these types. However, unlike
for scalar types (integer/double/string), AWK applies
the following restrictions with regard to associative
arrays:
- Associative array assignments (i.e., assocarray1 = associarray2)
are prohibited.
- Functions cannot return associative arrays.
These restrictions, while sufficient for AWK, are detrimental
to extensions because associative arrays are excellent vehicles
for configuration and return values for user extensions.
Plus, associative arrays can be subclassed, which can be used
to enforce type safety within user extensions. Unfortunately, the
memory model restrictions make using associative arrays in this
capacity very difficult.
We attempt to alleviate these difficulties by adding references
to Jawk via the CoreExtension module.
References convert associative arrays into
unique strings called reference handles.
Since reference handles are strings, they can be
assigned and returned via AWK functions without restriction.
And, reference handles are then used by other reference extension
functions to perform common associative array operations, such as
associative array cell lookup and assignment, key existence
check, and key iteration.
The reference model functions are explained below:
- NewRef / NewReference -
handle = NewRef(assocarray)
Store map into reference cache. Return the unique string handle
for this associative array.
- DeRef / Dereference -
val = DeRef(handle, key)
Return the cell value of the associative array referenced by the key.
In other words:
return assocarray[key]
- UnRef / Unreference -
UnRef(handle)
Eliminate the reference occupied by the reference cache.
- InRef -
while(key = InRef(handle)) ...
Iterate through the keyset of the associative array
referred to by handle in the reference cache.
This is similar to:
for (key in assocarray)
...
where assocarray is the associative array referred to by
handle in the reference cache.
Warning: unlike the IN keyword, InRef
will maintain state regardless of scope. That is,
if one were to break; out of the while loop above,
the next call to InRef() will be the next anticipated
element of the assoc array.
- IsInRef -
b = IsInRef(handle, key)
Checks whether the associative array in the reference cache
contains the key. This is similar to:
if (key in assocarray)
...
where assocarray is the associative array referred to by
handle in the reference cache.
- DumpRefs -
DumpRefs()
Dumps the reference cache to stdout.
Method Summary |
java.lang.String[] |
extensionKeywords()
All the extended keywords supported
by this extension. |
int[] |
getAssocArrayParameterPositions(java.lang.String extension_keyword,
int num_args)
Assume no guarantee of any extension parameter being an
associative array. |
java.lang.String |
getExtensionName()
The name of the extension package. |
java.lang.Object |
invoke(java.lang.String keyword,
java.lang.Object[] args)
Invoke extension as a method. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
CoreExtension
public CoreExtension()
getExtensionName
public java.lang.String getExtensionName()
- Description copied from interface:
JawkExtension
- The name of the extension package.
- Specified by:
getExtensionName
in interface JawkExtension
extensionKeywords
public java.lang.String[] extensionKeywords()
- Description copied from interface:
JawkExtension
- All the extended keywords supported
by this extension.
Note: Jawk will
throw a runtime exception if the
keyword collides with any other keyword
in the system, extension or otherwise.
- Specified by:
extensionKeywords
in interface JawkExtension
getAssocArrayParameterPositions
public int[] getAssocArrayParameterPositions(java.lang.String extension_keyword,
int num_args)
- Description copied from class:
AbstractExtension
- Assume no guarantee of any extension parameter being an
associative array.
- Specified by:
getAssocArrayParameterPositions
in interface JawkExtension
- Overrides:
getAssocArrayParameterPositions
in class AbstractExtension
- Parameters:
extension_keyword
- The extension keyword to check.num_args
- The number of actual parameters used in this
extension invocation.
- Returns:
- An array of parameter indexes containing associative arrays.
Note: non-inclusion of a parameter index
into this array makes no implication as to whether the
parameter is a scalar or an associative array. It means
that its type is not guaranteed to be an associative array.
invoke
public java.lang.Object invoke(java.lang.String keyword,
java.lang.Object[] args)
- Description copied from interface:
JawkExtension
- Invoke extension as a method.
- Specified by:
invoke
in interface JawkExtension
- Parameters:
keyword
- The extension keyword.args
- Arguments to the extension.
- Returns:
- The return value (result) of the extension.