Package org.metricshub.jawk.ext

Class CoreExtension

java.lang.Object
org.metricshub.jawk.ext.AbstractExtension
org.metricshub.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 for completeness/normalization.
  • Double - dbl = Double(3)
    Converts its argument to a Double 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

  • Field Details

  • Constructor Details

    • CoreExtension

      public CoreExtension()

      Constructor for CoreExtension.

  • Method Details

    • getExtensionName

      public String getExtensionName()
      Description copied from class: AbstractExtension

      getExtensionName.

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

    • mapFunction

      public Object mapFunction(Object... args)

    • hashMapFunction

      public Object hashMapFunction(Object... args)

    • linkedMapFunction

      public Object linkedMapFunction(Object... args)

    • treeMapFunction

      public Object treeMapFunction(Object... args)

    • mapUnionFunction

      public Object mapUnionFunction(Object... args)

    • mapCopyFunction

      public int mapCopyFunction(AssocArray target, AssocArray source)

    • arrayFunction

      public int arrayFunction(AssocArray target, Object... values)

    • typeOfFunction

      public String typeOfFunction(Object value)

    • stringFunction

      public String stringFunction(Object value)

    • doubleFunction

      public Object doubleFunction(Object value)

    • haltFunction

      public Object haltFunction(Object... args)

    • newReferenceFunction

      public Object newReferenceFunction(Object... args)

    • newRefFunction

      public Object newRefFunction(Object... args)

    • dereferenceFunction

      public Object dereferenceFunction(Object... args)

    • deRefFunction

      public Object deRefFunction(Object... args)

    • unreferenceFunction

      public int unreferenceFunction(Object handle)

    • unRefFunction

      public int unRefFunction(Object handle)

    • inRefFunction

      public Object inRefFunction(Object handle)

    • isInRefFunction

      public int isInRefFunction(Object handle, Object key)

    • dumpRefsFunction

      public void dumpRefsFunction()

    • timeoutFunction

      public Object timeoutFunction(Object millis)

    • throwFunction

      public Object throwFunction(Object... args)

    • versionFunction

      public String versionFunction(Object value)

    • dateFunction

      public String dateFunction(Object... args)

    • fileExistsFunction

      public int fileExistsFunction(Object path)