Package org.sentrysoftware.jawk.ext

Class CoreExtension

java.lang.Object
org.sentrysoftware.jawk.ext.AbstractExtension
org.sentrysoftware.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 associative 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 associative 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(aaTarget, aaSource)
    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 to 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 overriden, 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 key-set 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.
Author:
Danny Daglas

  • Constructor Details

    • CoreExtension

      public CoreExtension()

      Constructor for CoreExtension.

  • Method Details

    • getExtensionName

      public String getExtensionName()

      getExtensionName.

      Specified by:
      getExtensionName in interface JawkExtension
      Returns:
      name of the extension package.

    • extensionKeywords

      public String[] extensionKeywords()
      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
      Returns:
      the list of keywords the extension provides support for

    • getAssocArrayParameterPositions

      public int[] getAssocArrayParameterPositions(String extensionKeyword, int numArgs)
      Define the parameters which are expected to be associative arrays. This is used by the semantic analyzer to enforce type checking and correct Jawk variable allocation (which is done at the beginning of script execution). Assume no guarantee of any extension parameter being an associative array.
      Specified by:
      getAssocArrayParameterPositions in interface JawkExtension
      Overrides:
      getAssocArrayParameterPositions in class AbstractExtension
      Parameters:
      extensionKeyword - The extension keyword to check.
      numArgs - How many actual parameters are used in the call.
      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 Object invoke(String keyword, Object[] args)
      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.