rpnifs/python_pyrpn.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_PYRPN_H__
#define _PYTHON_PYRPN_H__

#include "config.h"

#include <errno.h>

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

#include "rpn_jit.h"
#include "python_rpnexpr.h"

/**@defgroup python_ext Python API
 * @brief Python API definitions
 *
 * @ref python_pyrpn.c and @ref python_rpnexpr.c should be compiled in a .so file
 * in order to expose a pyrpn Python module.
 *
 * This module contains functions :
 * - pyrpn.get_ops() returning a dict with long & short operations
 * - pyrpn.random_expr(args_count, token_count=10) generating a random expression
 *
 * And it contains the pyrpn.RPNExpr class with following methods :
 * - pyrpn.RPNExpr.__init__(self, expression, args_count, stack_size=16)
 * - pyrpn.RPNExpr.eval(self, ...) expression evaluation
 * - pyrpn.RPNExpr.reset_stack(self) to set all stack items to 0
 */

/**@defgroup python_module pyrpn Python module
 * @brief Exposed Python module : pyrpn
 * @ingroup python_ext
 */

/**@file python_pyrpn.h
 * @brief Python module & type headers
 * @ingroup python_module
 *
 * This file is the header of the pyrpn Python module definition
 */

extern PyTypeObject RPNExprType;

/**@brief Python module initialization function
 * @ingroup python_module */
PyMODINIT_FUNC PyInit_pyrpn(void);
/**@brief pyrpn module methods list
 * @ingroup python_module */
extern PyMethodDef rpnmodule_methods[];
/**@brief Python module specs
 * @ingroup python_module */
extern PyModuleDef rpnmodule;

/**@brief Return a dict with valid operations (short keys and long values)
 * @param mod pyrpn module object
 * @param noargs Dummy argument for METH_NOARG
 * @return The a new dict
 * @ingroup python_module
 */
PyObject* pyrpn_ops(PyObject* mod, PyObject* noargs);

/**@brief Return a new Python str with a random RPN expression
 * @param mod pyrpn module object
 * @param args Position arguments in Python list
 * @param kwds Keywords arguments in Python dict
 * @ingroup python_module
 */
PyObject* pyrpn_random(PyObject *mod, PyObject *args, PyObject *kwds);

/**@mainpage
 * Documentation entrypoints :
 * - @ref python_ext
 * - @ref rpn_lang
 * - @ref rpn
 */

#endif