Language Guide
==============

This reference guide describes how to use the rpcc language to structure your remote procedure's data.


.. _language_data_types:

Data types
----------

A :code:`rpcc` message field can have on of the following types:

.. list-table::
   :widths: 20 40 40
   :header-rows: 1

   * - .rpcc type
     - Mercury type
     - C++ type
   * - bool
     - hg_bool_t
     - bool
   * - int8
     - hg_int8_t
     - int8_t
   * - int16
     - hg_int16_t
     - int16_t
   * - int32
     - hg_int32_t
     - int32_t
   * - int64
     - hg_int64_t
     - int64_t
   * - uint8
     - hg_uint8_t
     - uint8_t
   * - uint16
     - hg_uint16_t
     - uint16_t
   * - uint32
     - hg_uint32_t
     - uint32_t
   * - uint64
     - hg_uint64_t
     - uint64_t
   * - csize
     - hg_size_t
     - size_t
   * - float
     - float
     - float
   * - double
     - double
     - double
   * - string
     - hg_const_string_t
     - std::string
   * - exposed_buffer
     - hg_bulk_t
     - hermes::exposed_buffer

.. _language_rpc_options:

RPC options
-----------

Individual rpc declarations in a :code:`.rpcc` file can be annotated with several *options* that control how the
resulting code should be generated. The following options can be provided:

- :code:`id`: The identifier associated to this remote procedure. The value provided must be unique, otherwise
  compilation will fail. If unspecified, :code:`rpcc` will internally generate a unique identifier for the rpc.

  .. code-block:: rpcc

    rpc foo {
        id: 42;
        arguments {
            int32 bar;
        };

        return_values {
            bool success;
        };
    };

- :code:`include_if`: This option allows developers to conditionally include rpc definitions in the generated code. Any
  such rpc will be enclosed between appropriate C/C++ *preprocessor tags* so that the build system can control
  whether a rpc definition should be made available to user code.

  .. code-block:: rpcc

    rpc foo {
        # the classes for this RPC will be enclosed between #ifdef and #endif clauses
        # in the generated code
        include_if: compiler_defines(HAS_FOO);
        arguments {
            int32 bar;
        };

        return_values {
            bool success;
        };
    };

    rpc bar {
        # the classes for this RPC will be enclosed between #ifndef and #endif clauses
        # in the generated code
        include_if: compiler_not_defines(HAS_BAR);
        arguments {
            int32 baz;
        };

        return_values {
            bool success;
        };
    };