.. default-domain:: chpl

.. module:: Message

Message
=======
**Usage**

.. code-block:: chapel

   use Message;


or

.. code-block:: chapel

   import Message;

.. enum:: enum MsgType { NORMAL, WARNING, ERROR }

   .. enumconstant:: enum constant NORMAL

   .. enumconstant:: enum constant WARNING

   .. enumconstant:: enum constant ERROR

.. enum:: enum MsgFormat { STRING, BINARY }

   .. enumconstant:: enum constant STRING

   .. enumconstant:: enum constant BINARY

.. enum:: enum ObjectType { PDARRAY, SEGSTRING, LIST, DICT, VALUE, DATETIME, TIMEDELTA }

   .. enumconstant:: enum constant PDARRAY

   .. enumconstant:: enum constant SEGSTRING

   .. enumconstant:: enum constant LIST

   .. enumconstant:: enum constant DICT

   .. enumconstant:: enum constant VALUE

   .. enumconstant:: enum constant DATETIME

   .. enumconstant:: enum constant TIMEDELTA

.. record:: MsgTuple

   
   * Encapsulates the message string and message type.
   

   .. attribute:: var msg: string

   .. attribute:: var msgType: MsgType

.. class:: ReplyMsg

   
   * Encapsulates state corresponding to a reply message sent back to 
   * the Arkouda client.
   

   .. attribute:: var msg: string

   .. attribute:: var msgType: MsgType

   .. attribute:: var msgFormat: MsgFormat

   .. attribute:: var user: string

.. record:: RequestMsg

   
   * Encapsulates state corresponding to a client request sent to the Arkouda server.
   

   .. attribute:: var user: string

   .. attribute:: var token: string

   .. attribute:: var cmd: string

   .. attribute:: var format: string

   .. attribute:: var args: string

   .. attribute:: var size: int

.. record:: ParameterObj

   
   * Encapsulate parameter for a request sent to the Arkouda server
   * Note - Only used when args is in JSON format. 
   * Note - during the transition from space delimited string to JSON formated string, this object is not part of RequestMsg,
   *   but will be once all messages are transitioned to JSON arguments.
   

   .. attribute:: var key: string

   .. attribute:: var val: string

   .. attribute:: var objType: ObjectType

   .. attribute:: var dtype: string

   .. method:: proc init()

   .. method:: proc init(key: string, val: string, objType: ObjectType, dtype: string)

   .. method:: proc asMap() throws

   .. method:: proc getJSON() throws

   .. method:: proc ref setKey(value: string)

   .. method:: proc ref setVal(value: string)

   .. method:: proc ref setObjType(value: ObjectType)

   .. method:: proc ref setDType(value: string)

   .. method:: proc getObjType()

      
      * Return the objType value
      * Returns str
      

   .. method:: proc getDType()

      
      * Return the Dtype value as NumpyDtype
      * Returns Dtype
      

   .. method:: proc getValue()

      
      * Return the raw string value
      * Returns string
      

   .. method:: proc getScalarValue(type t): t throws

      
      * Attempt to cast the value to the provided type
      * Throw and error if the cast isn't possible
      

   .. method:: proc getIntValue(): int throws

      
      * Return the value as int64
      * Returns int
      

   .. method:: proc getPositiveIntValue(max: int): int throws

      
      * Return the value as a positive int64
      * If the value is negative, return 'value + max + 1', otherwise return the value
      * This is useful for implementing Python's negative indexing rules
      *
      * Returns int
      

   .. method:: proc getUIntValue(): uint throws

      
      * Return the value as uint64
      * Returns uint
      

   .. method:: proc getUInt8Value(): uint(8) throws

   .. method:: proc getRealValue(): real throws

      
      * Return the value as float64
      * Returns real
      

   .. method:: proc getBoolValue(): bool throws

      
      * Return the value as bool
      * Returns bool
      

   .. method:: proc getBigIntValue(): bigint throws

   .. method:: proc getValueAsType(type t = string): t throws

      
      * Return the value as the provided type
      

   .. method:: proc getList(size: int) throws

      
      Parse value as a list of strings.
      :size: int: number of values in the list
      Note - not yet able to handle list of pdarray or SegString names
      

   .. method:: proc getListAs(type t, size: int) throws

   .. method:: proc getTuple(param size: int): size*int throws

      
      Parse value as a tuple of integers with the given size
      

   .. method:: proc getJSON(size: int) throws

.. class:: MessageArgs

   
   Container class for the message arguments formatted as json
   :param_list:  array of ParameterObj
   :size: int - number of parameters contained in list
   

   .. attribute:: var param_list: list(ParameterObj)

   .. attribute:: var size: int

   .. method:: proc init()

   .. method:: proc init(param_list: list(ParameterObj))

   .. method:: proc init(param_list: list(ParameterObj, parSafe = true))

   .. method:: proc getJSON(keys: list(string) = list(string)): string throws

   .. method:: proc get(key: string) throws

      
      * Identify the parameter with the provided key and return it
      * Returns ParameterObj with the provided key
      * Throws KeyNotFound error if the provide key does not exist.
      

   .. method:: proc getValueOf(key: string) throws

   .. method:: proc items()

      
      Return "iterable" of ParameterObj
      

   .. method:: proc keys()

      
      Return a list of all keys
      

   .. method:: proc vals()

      
      Return a list of all values
      

   .. method:: proc contains(key: string): bool

      
      Return bool if param_list contains given key name
      

.. function:: proc parseParameter(payload: string) throws

   
   Parse and individual parameter components into a ParameterObj
   

.. function:: proc parseMessageArgs(json_str: string, size: int) throws

   
   Parse arguments formatted as json string into objects
   

.. function:: proc deserialize(ref msg: RequestMsg, request: string) throws

   
   * Deserializes a JSON-formatted string to a RequestMsg object, where the
   * JSON format is as follows (size is only set for json args. Otherwise, -1):
   *
   * {"user": "user", "token": "token", "cmd": "cmd", "format": "STRING", "args": "arg1 arg2", "size": "-1"}
   *
   

.. function:: proc serialize(msg: string, msgType: MsgType, msgFormat: MsgFormat, user: string): string throws

   
   * Generates a ReplyMsg object and serializes it into a JSON-formatted reply message
   

.. function:: proc jsonToPdArray(json: string, size: int) throws

   
   * Converts the JSON array to a pdarray
   

.. function:: proc parseJsonTuple(json: string, param size: int): size*int throws

   
   Helper function to parse a JSON string as a tuple of integers