rpnifs/python_rpnexpr.h

/*
 * Copyright (C) 2020 Weber Yann
 * 
 * This file is part of pyrpn.
 * 
 * pyrpn is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * any later version.
 * 
 * pyrpn is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with pyrpn.  If not, see <http://www.gnu.org/licenses/>.
 */
#ifndef _PYTHON_RPNEXPR_H__
#define _PYTHON_RPNEXPR_H__

#include "config.h"

#include <errno.h>
#include <float.h>

#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include "structmember.h"

#include "rpn_jit.h"
#include "python_rpntoken.h"
#include "python_const.h"

/**@file python_rpnexpr.h
 * @brief pyrpn.RPNExpr definition
 * @ingroup python_ext
 * @ingroup pymod_pyrpn_RPNExpr
 *
 * This file is the header of the RPNExpr Python class
 */

/**@defgroup pymod_pyrpn_RPNExpr pyrpn.RPNExpr
 * @brief Exposed Python class : RPNExpr
 * @ingroup pymod_pyrpn
 */


/**@brief RPNExpr Python class type definition
 * @ingroup pymod_pyrpn_RPNExpr */
extern PyTypeObject RPNExprType;

/**@brief Structure holding RPNExpr objects
 * @ingroup pymod_pyrpn_RPNExpr */
typedef struct
{
	/** Python's type definition */
	PyObject_VAR_HEAD;
	
	/**@brief Pointer on @ref rpn_expr_s */
	rpn_expr_t *rpn;

	/**@brief Array storing expression argument
	 * @note As attribute of rpn_expr allowing malloc & free only once */
	rpn_value_t *args;

	/**@brief If true, someone else will take care of freeing the
	 * rpn expression at deletion */
	short borrowed_expr;
} PyRPNExpr_t;

/**@brief Organize PyRPNExpr_t state data
 * @see rpnexpr_getstate
 * @see rpnexpr_setstate 
 * @ingroup pymod_pyrpn_RPNExpr */
typedef struct
{
	/**@brief The total size of the state */
	size_t total_sz;
	/**@brief Expression's argument count */
	size_t argc;
	/**@brief Expression's stack size */
	unsigned char stack_sz;
	/**@brief Number of tokens in expression */
	size_t token_sz;
} PyRPNExpr_state_t;

/**@brief Return a new instance of RPNExpr with a borrowed expression
 * @param borrowed An rpn expression to borrow
 * @note Borrowed expression means that the rpn_expr_t is handled by someone
 *       else and should not be freed when the instance is deleted
 * @return A new RPNExpr instance
 * @ingroup pymod_pyrpn_RPNExpr 
 */
PyObject* rpnexpr_init_borrowing(rpn_expr_t *borrowed);

/**@brief RpnExpr __new__ method
 * @param subtype Type of object being created (pyrpn.RPNExpr)
 * @param args positional arguments for subtype
 * @param kwds keyword argumenrs for subtype
 * @return The new Python RPNExpr object
 * @ingroup pymod_pyrpn_RPNExpr 
 */
PyObject* rpnexpr_new(PyTypeObject *subtype, PyObject *args, PyObject* kwds);

/**@brief RpnExpr constructor
 * @param self New RPNExpr instance
 * @param args Positional arguments list
 * @param kwds Keywords arguments dict
 * @return 0 if no error else -1
 * @ingroup pymod_pyrpn_RPNExpr
 */
int rpnexpr_init(PyObject *self, PyObject *args, PyObject *kwds);

/**@brief RPNExpr __del__ method 
 * @param self RPNExpr instance
 * @ingroup pymod_pyrpn_RPNExpr
 */
void rpnexpr_del(PyObject *self);

/**@brief Returns a byte representation of expression (like getstate but
 * without the stack informations
 * @param self RPNExpr instance
 * @param noargs Not an argument...
 * @return A bytes Python instance
 * @ingroup pymod_pyrpn_RPNExpr 
 */
PyObject* rpnexpr_getexprstate(PyObject *self, PyObject *noargs);

/**@brief RPNExpr __getstate__ method for pickling
 * @param self RPNExpr type object
 * @param noargs Not an argument...
 * @return A bytes Python instance suitable as argument for
 * @ref rpnexpr_setstate
 * @ingroup pymod_pyrpn_RPNExpr 
 */
PyObject* rpnexpr_getstate(PyObject *self, PyObject *noargs);

/**@brief RPNExpr __setstate__ method for pickling
 * @param cls RPNExpr type object
 * @param state Should by a bytes Python instance returned by @ref
 * rpnexpr_getstate
 * @return A bytes Python instance suitable as argument for
 * @ref rpnexpr_getstate
 * @ingroup pymod_pyrpn_RPNExpr 
 */
PyObject* rpnexpr_setstate(PyObject *cls, PyObject *state);

/**@brief RPNExpr __copy__ method for cloning
 * @param cls RPNExpr class
 * @param noargs Not an argument...
 * @return A new cloned instance
 * @ref rpnexpr_setstate
 * @ingroup pymod_pyrpn_RPNExpr 
 */
PyObject* rpnexpr_copy(PyObject *cls, PyObject *noargs);

/**@brief RPNExpr.__len__() method
 * @param self RPNExpr instance
 * @return A integer with the number of tokens in expression
 * @ingroup pymod_pyrpn_RPNExpr 
 */
Py_ssize_t rpnexpr_len(PyObject *self);

/**@brief Sequence method for __getitem__ token getter
 * @param self RPNExpr instance
 * @param idx The item index (can be negative)
 * @return A @ref RPNTokenType subclass instance
 * @ingroup pymod_pyrpn_RPNExpr 
 */
PyObject* rpnexpr_token_item(PyObject *self, Py_ssize_t idx);

/**@brief Sequence method for __setitem__ token setter
 * @param self RPNExpr instance
 * @param idx The item index
 * @param elt An RPNTokenType subclass token to set
 * @return 0 or -1 on error and raise IndexError
 * @ingroup pymod_pyrpn_RPNExpr 
 */
int rpnexpr_token_ass_item(PyObject *self, Py_ssize_t idx, PyObject* elt);

/**@brief Eval an RPN expression given arguments and return the
 * value
 * @param self RPNExpr instance
 * @param argv Array of PyObject* arguments
 * @param argc Number of arguments
 * @return The value resulting of evaluation
 * @ingroup pymod_pyrpn_RPNExpr
 */
PyObject* rpnexpr_eval(PyObject* self, PyObject** argv, Py_ssize_t argc);

/**@brief Mutate an RPN expression given arguments and return the value
 * @param self RPNExpr instance
 * @param args Positionnal arguments
 * @param kwds Keyword arguments
 * @return Py_None
 * @ingroup pymod_pyrpn_RPNExpr 
 */
PyObject* rpnexpr_mutate(PyObject* self, PyObject *args, PyObject *kwds);

/**@brief Set all stack item to zero
 * @param self RPNExpr instance
 * @param noargs Dummy argument for METH_NOARG
 * @return None
 * @ingroup pymod_pyrpn_RPNExpr
 */
PyObject* rpnexpr_reset_stack(PyObject *self, PyObject *noargs);

/**@brief RPNExpr.__repr__()
 * @param self RPNExpr instance
 * @return An str instance representing the exppression
 * @ingroup pymod_pyrpn_RPNExpr
 */
PyObject* rpnexpr_repr(PyObject *self);

/**@brief RPNExpr.__str__()
 * @param self RPNExpr instance
 * @return An str instance representing the exppression
 * @ingroup pymod_pyrpn_RPNExpr
 */
PyObject* rpnexpr_str(PyObject *self);

/**@brief RPNExpr PEP-207 richcompare method
 * @param _self RPNExpr instance
 * @param other RPNExpr instance to compare to
 * @param op The comparison to be done
 * @return Py_True or Py_False
 * @ingroup pymod_pyrpn_RPNExpr 
 */
PyObject* rpnexpr_richcompare(PyObject *_self, PyObject *other, int op);

/**@brief Return a new Python str with a random RPN expression
 * @param cls pyrpn module object
 * @param args Position arguments in Python list
 * @param kwds Keywords arguments in Python dict
 * @return A str instance
 * @ingroup pymod_pyrpn
 */
PyObject* rpnexpr_random(PyObject *cls, PyObject *args, PyObject *kwds);

/**@brief Return a new named tuple containing default mutation parameters
 * @param cls The class (class method)
 * @param argv The arguments (FASTCALL)
 * @param argc The number of arguments
 * @return The named tuple
 * @ingroup pymod_pyrpn_RPNExpr 
 */
PyObject* rpnexpr_default_mutation_params(PyObject *cls, PyObject **argv, Py_ssize_t argc);

/**@brief Try to convert a python object into a rpn_mutation_params_t
 * @param py_params The python object
 * @param params A pointer on the parameters to initialize
 * @return -1 on failure and raise an exception
 * @ingroup pymod_pyrpn_RPNExpr 
 */
int rpnexpr_pyobj_to_mutation_params(PyObject* py_params, rpn_mutation_params_t *params);

#endif