Functions
=========

| Some functions are builtin
| Some functions are defined in the Psiexp library (#include "psiexp.psi")
| You can define your own functions in your .psi program file(s) 
| Defined functions are associative arrays

.. function:: copyArray(destArr, srcArr, isDeep)

.. function:: system(args)

   execute a shell command and return the exit status

.. function:: systemString(command)

   Execute Unix *command*, return the entire output as a single string

.. function:: systemArray(variable, command)

   Execute Unix *command*, and break its output into lines.
   *variable* will contain this array of the resulting strings.

.. data:: process 

   A **process** is an object
      | in: 
      | out: 
      | pid:
      | cmd:
      | you can write to stdin of process with fprintf
      | when process writes it generates an event

.. function:: killPipe(theProcess)

   *thePipe* 

.. function:: readWritePipe(cmd)

   | *theProcess* = readWritePipe(*cmd*);
   | Execute *cmd* in a new process.  Return a **process** object
   | Generate event for each line of output from *theProces*.
   | Generate event when process terminates?
   | fprintf(*theProcess*) sends results to standard input of *theProcess*
   | fclose(*theProcess*) closes the standard input of *theProcess*
   | kill(*theProcess*) kills *theProcess*


Return a proc object.  Fields:
      * pid: process id of new process

	

.. function:: readPipe(cmd)

   Executes Unix command *cmd* and generates an event for each line from the command's standard output.
   When the command terminates, sends an event with type "eof".

.. function:: metro(name [, args...])

   args: repeat, single(default)

.. function:: float(arg)

   convert *arg* to float if possible, otherwise 0.0

.. function:: int(arg)

   convert *arg* to int if possible (*arg* is float or string), otherwise 0.

.. function:: string(arg)

   return a string representation of *arg*

.. function:: csvRead(args)

.. function:: csvWrite(args)

.. function:: readFile(path, lines)

   Read text file *path*, breaking it into an array of strings (using line breaks as seperator)
   and assign this array to the variable *lines*.

.. function:: writeFile(path, lines)

   Write text file *path*.  *lines* is the array of strings to be written.
   Each element in *lines* will be followed by a newline.

.. function:: readSoundFile(path, channelArray)

   Read sound file *path* and store it in an array of channels.
   Assign this array to the variable *channelArray*.
   Each channel is a floating point array of samples between 0 and 1.
   len(*channelArray*) will be the number of channels
   and if len(*channelArray*) is nonzero len(*channelArray[0]*) will be the number of samples.


.. function:: nameFromOpenPanel([title[, text]])

   Opens a macOS file browser window with title *title* and additional message *text*
   and returns the path of the chosen file,
   or the empty string if user cancels the dialog.


.. function:: assocKeyAtIndex(assocArray, index)

   Returns the key at index *index* of *assocArray* 

.. function:: assocElemAtIndex(assocArray, index)

   Returns the value at index *index* of *assocArray*.

.. function:: assocSummary(assocArray)

   Returns a string with a summary of the contents of *assocArray*

.. function:: len(arg)

   If *arg* is a string, return the number of characters.  If *arg* is an array, return the number of elements.  Otherwise return 0.

.. function:: sizeof(arg)

   *Deprecated*.
   Use :func:`len` instead.

.. function:: typeof(arg)

   Returns a string describing the type of *arg*, one of "int", "float", "string", "array", "assoc", "NULL", "OP", "LEX", "BIN", "IARR", "FARR", "SARR", "SYM"

.. function:: getField(arg, "description")

   Returns the description field of atom *arg*, if there is one

.. function:: addUie(container, uie);

   Adds *uie* to *container*

.. function:: unlinkUie(container, uie);

   Unlinks UIE and subviews from NS view hierarchy

.. function:: setFrame1

   set the frame of a UIE

.. function:: refresh

   force user interface to update itself

.. function:: redraw

   force immediate redrawing of a UIE (CURRENTLY A NO-OP)






.. function:: findstrindex(theString, lookingFor)

   Return the index of the first occurrence of string *lookingFor* in *theString*, otherwise -1.

.. function:: floatingButton(container [, text])

   Create a floating button labelled *text*, constrained in *container*.
     | floating attributes:
     | x.moveFloatingUie = { x, y }
     | x.dragStyle
     | 0: black square in upper left
     | 1: whole button
     | 5: drag disabled
     | x.dragColor = color,  color of draggable part of button
     | x.dragEnable integer, nonzero enables drag
     |
     | x.floatWidth  must be set explicitly in .psi program
     | x.floatHeight must be set explicitly in .psi program
     | x.floatX  x position of floating thing
     | x.floatY  y position of floating thing


.. function:: util("currentFullScreenWindow")

   If any windows are in full screen mode, return the first one found,
   otherwise return NULL.

.. function:: util("trace", remark)

   Prints a call trace with *remark* (default: "trace").  Used when debugging
   to trace calls to one of your routines

.. function:: util("set", "arg", value)
.. function:: util("get", "arg")

   Set or get internal values.  Mostly for debugging.  Values for *arg*:
     | hideFloating
     | warnDeprecated
     | warnIgnoredUieMsg
     | traceUieWarnings
     | legacy
     | flipped
     | warnUpperCaseUieAttributes

.. function:: util(command, thing, options)

   Commands

   * dumpExecImage
   * dumpExecModule
   * dumpBinStack
   * dumpDataStack
   * dumpAll
   * dumpParseSymTab
   * hideConsole
   * trace
   * atomNumber

   Options

   * verbose
   * noeval
   * descrBeforeEval
   * descrAfterEval

.. function:: description(id[, modifier])

   Return a text description of *id*.
   Values for *modifier*:

   * raw
   * deref
   * eval
   * evalowner
   * verbose

The following link: :ref:`my-reference-label` is a link to another page