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.

Field Summary

Fields inherited from class org.jawk.ext.AbstractExtension

jrt, vm

Constructor Summary

CoreExtension()

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 org.jawk.ext.AbstractExtension

checkNumArgs, init, toAwkString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.jawk.ext.JawkExtension

init

Constructor Detail

CoreExtension

public CoreExtension()

Method Detail

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.