SCRIPTING

A Continuing Journey

Scripting Environment Provisions to the JavascriptCore Standard Global Environment

** FEATURES NOT LISTED HERE ARE NOT CONSIDERED STABLE **

Note: Within this documentation, Void, String, Number, Object, Any, Undefined, Boolean, and Function;
      are generic type terms, whenever such terms are mentioned within a: Constructor, Function,
      Property, Wanted or Prototype heading with an opening full-colon (:).

Note: This documentation is in beta-stage, so technical correctness is questionable. If in doubt,
      see the corresponding source code. Some changes will not be reflected in documentation, during
      development. See this documentation as a set of general guidelines in the now-time.

Function: echo(String, ...)

  Echo (0) through (N) strings separated by space on the standard output,
  and terminate the sequence with a new-line character.

Function: run.prototype run(String command, ...)

  Run the command given with the remaining parameters given, capturing standard io and status to
  a new prototype of the run function.

  Prototype: run.prototype

    stdout: The String output of the command.

    stderr: The String error of the command.

    status: The Number status of the command. (0) indicates success, and (1+) are error
            codes as defined by the command being called.

    valueOf: returns status

    toString: returns (stdout || stderr || status) in resolve order.

Function: String localPath(Void)

  Retrieve the current directory as a String.

Function: Boolean localPath(String path)

  Set the current directory to path. Throws ReferenceError if path is not a directory.
  Returns true if the operation is successful.

Property: Object Environment

  A JavaScript implementation of environment where Environment[K], represents the value
  of an environment key by the name K. Use standard JavaScript set/get/delete to manage
  environment. This environment object uses thread locks to ensure thread safety.

Function: String addPluginPath(String path)

  Adds the given path to the plugin search path. Throws an error if the path is not an existing
  directory. Returns path if successful.

Function: Any loadPlugin(String path)

  Loads the given plugin if it is found in the current directory, by the path given, or within the
  plugin search path (in that order). Throws an error if path is not found. Returns whatever the,
  plugin loader returns from the load call. The plugin will be supplied with the default global object.

Function: Any loadPlugin(String path, Object global)

  Loads the given plugin as in the path only form, and provides plugin with global for it's global-object
  (also-known-as: scope). The plugin may perform any validation required for its operation, and return
  any status or, throw exceptions.

Constructor: MachineType MachineType(Object representation)

  Creates and returns a MachineType.prototype with the representation given. This is an advanced function,
  which most users do not need to worry about. There are only a few MachineTypes. This constructor,
  provides each type with a unified prototype backing hosted by this constructor. The standard types are,
  predefined within the JavaScript Global Environment. This allows types to be used as parameters to,
  functions, and for values which are not MachineType natives to be marked for a specific conversion.

Prototype: MachineType.prototype

  Property: Boolean pointer

    The pointer property is true if this is a pointer to a type of this[width].

  Property: Boolean constant

    This property has no effect at this time.

  Property: Boolean signed

    True if this is a signed machine type of this[width].

  Property: Boolean unsigned (read-only)

    True if this[signed] is false.

  Property: Boolean floating

    True if this is a floating machine type of this[width].
  
  Property: Boolean vararg

    True if this type represents the C-ellipsis-function-parameter: '...'.

  Property: String name

    A string name which represents this type.

  Function: Number sizeOf(Number count)

    Returns the number of bytes required by this type, given N count members, multiplied by this[width].

  Function: Number unitsOf(Number bytes)

    Returns the maximum number of elements that will fit within bytes.

  Property: Number bits (read-only)

    Returns the number of bits occupied by a single unit of this type.

  Function: Number valueOf(Void)

    Returns the internal type code representation of this type.

  Function: String toString(Void)

    Returns the internal character code representation of this type.

  Function: MachineType toConst(Void)

    Returns a copy of this type with the constant flag active.

  Function: Number readAddress(Address address)

    Returns the value of this type at the given address.

  Function: Number readAddress(Address address, Number element)

    Returns the value of this type at the given address[element].

  Function: Undefined writeAddress(Address address, Number value)

    Writes the value to the given address.

  Function: Undefined writeAddress(Address address, Number element, Number value)

    Writes the value to the the given address[element].

  Function: Undefined bindAddress(Address address, Object object, Any propertyName)

    Creates a getter and setter for this type at the given address upon object specified, using the
    given property name for the accessor. If you bind an address, there is no guarantee on availability,
    of data if the data location is relocated during a resize. So when you bindAddress, make sure you
    stash your tree and keep it safe for as long as you want your slice. It is perfectly valid usage,
    to bind the entire tree space to several components, within a scope level only they can access.
    Memory will be freed when their scope can no longer be reached and garbage collection is performed.

  Function: Any value(Object object)

    Coerces object to a Number Object, and marks the new Number Object as a member of this type, returning
    the new Number Object. The type of the new Number Object can be accessed via the return[type] member.

Constructor: SharedLibrary SharedLibrary(String path)

  Loads the named shared library by path, or by the defined system library paths. This process will throw
  a ReferenceError if the library is not found. 
  
  Symbols within the SharedLibrary may be accessed via normal JavaScript property lookup. All symbols are
  pointers, to the specified type within the library. So library[errno], would typically be a pointer to an
  int. You would then use the Address constructor, or a MachineType.bindAddress call to read or write the
  data. For procedure calls, use the SharedFunction constructor to construct call frames automatically.

  Caveat: SharedLibrary has an internal property named path, which is a reference to the path specified,
          for lookup. if you need to access a symbol named path, you will have to call an external library,
          procedure to locate it. A SharedLibrary will convert to its loaded address, so any library, which,
          can process the machine pointer can be used to find the symbol.

Constructor: SharedLibrary SharedLibrary()

  Returns the jse binary as a SharedLibrary; providing access to all exported symbols.

Constructor: SharedFunction SharedFunction(SharedLibrary library, MachineType returnType, String symbolName, ...)

  Locates symbolName within library, and creates a type definition for the library-procedure, using the
  given return type and remaining MachineType parameters (...) as the procedure execution protocol; and
  returns the protype of that procedure as the new (callable) SharedFunction.
  
  No pointer types will be automatically coerced from a return call, however all types returned from a call
  are marked. Automatic pseudo MachineType coercion has not yet found a standard free of gotchas, and all
  current auto-type-conversions are experimental. Numbers convert safely to their defined MachineTypes, where
  the function specifies, and if not specified on the number or by the function, the default size is int.

  If you want a VarArg call use the VarArg type as the last parameter of the specification, which will
  activate, parameter parsing. Within a vararg call, parameters will be parsed according to
  their type member specification, however Strings are auto converted to zero terminated Int8 buffer, if no
  type is defined upon the string. Calling toString on an Int8 buffer/Address creates a native JavaScript
  string value. Future direction is to have an explicit utf flag for this behavior.

  ** IF YOU FIND AN ERROR IN A FLOATING OR SIGNEDNESS CONVERSION, PLEASE FILE AN ISSUE **

Constructor: Address Address(MachineType type, Number length) 

  Creates an accessible address of type with the specified length. The memory will be allocated and freed
  as needed, or by property setting. To free by setting the pointer property, set pointer to 0; to free by
  length property set length to zero. The Address must have been allocated by this constructor, to free it,
  manually, or automatically. To check if an Address is allocated, get its allocated property. If an address,
  is not allocated and it is zero, it can be reallocated for continuing use at any time. The length of the
  content can be resized using the length property, if the address was created by this constructor.

  If you set the readOnly property, no property set access will (actually) succeed, but no errors will be
  thrown. No errors will be thrown for buffer over/underflow. Negative addressing calculations may be performed
  on indices, however no calculation below zero or above allocation will be accessed for read or write.

  The type of the address may be changed. For information on working with addresses see your core.js

  It is not generally recommended to use Addresses unless you are certain on what you are doing. Crashing,
  your engine is the most likely outcome of incorrect addressing and or calling. MachineType interfacing,
  must be tested and sanely error checked according to specification of API. So it is best to create
  scripts in the form of libraries and or shell scripts which perform certain complex tasks very well,
  and as simply as possible.

  Caveat: An address can be read if it is readOnly, and a reference to it may be obtained as write,
          even if it is an error. The script engine is designed to: "Do what the fuck you said",
          IN THEORY.

Constructor: Address Address(MachineType type, Number length, Number pointer)

  Creates a new address with the given type, length and pointer. No allocation is performed.