yannweb/rpnifs
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Comment & doxygen documentation enhancement

Browse source
This commit is contained in:
Yann Weber 2023-08-09 14:36:11 +02:00
commit 077821fc3f
19 changed files with 667 additions and 160 deletions
Download patch file Download diff file Expand all files Collapse all files

20
Doxyfile.mk
View file

@ -46,13 +46,13 @@ INLINE_GROUPED_CLASSES = NO
INLINE_SIMPLE_STRUCTS = NO
TYPEDEF_HIDES_STRUCT = NO
LOOKUP_CACHE_SIZE = 0
EXTRACT_ALL = YES
EXTRACT_PRIVATE = NO
EXTRACT_PACKAGE = NO
EXTRACT_STATIC = NO
EXTRACT_ALL = NO
EXTRACT_PRIVATE = YES
EXTRACT_PACKAGE = YES
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_LOCAL_METHODS = NO
EXTRACT_ANON_NSPACES = NO
EXTRACT_LOCAL_METHODS = YES
EXTRACT_ANON_NSPACES = YES
HIDE_UNDOC_MEMBERS = NO
HIDE_UNDOC_CLASSES = NO
HIDE_FRIEND_COMPOUNDS = NO
@ -83,7 +83,7 @@ QUIET = NO
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = NO
WARN_NO_PARAMDOC = YES
WARN_AS_ERROR = NO
WARN_FORMAT = "$file:$line: $text"
INPUT = ./
@ -151,7 +151,6 @@ USE_HTAGS = NO
VERBATIM_HEADERS = YES
CLANG_ASSISTED_PARSING = NO
ALPHABETICAL_INDEX = YES
COLS_IN_ALPHA_INDEX = 5
GENERATE_HTML = YES
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html
@ -199,14 +198,12 @@ PDF_HYPERLINKS = YES
USE_PDFLATEX = YES
LATEX_BATCHMODE = NO
LATEX_HIDE_INDICES = NO
LATEX_SOURCE_CODE = NO
LATEX_BIB_STYLE = plain
LATEX_TIMESTAMP = NO
GENERATE_RTF = NO
RTF_OUTPUT = rtf
COMPACT_RTF = NO
RTF_HYPERLINKS = NO
RTF_SOURCE_CODE = NO
GENERATE_MAN = YES
MAN_OUTPUT = man
MAN_EXTENSION = .3
@ -216,7 +213,6 @@ XML_OUTPUT = xml
XML_PROGRAMLISTING = YES
GENERATE_DOCBOOK = NO
DOCBOOK_OUTPUT = docbook
DOCBOOK_PROGRAMLISTING = NO
GENERATE_AUTOGEN_DEF = NO
GENERATE_PERLMOD = NO
PERLMOD_LATEX = NO
@ -229,8 +225,6 @@ SKIP_FUNCTION_MACROS = YES
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
EXTERNAL_PAGES = YES
PERL_PATH = /usr/bin/perl
CLASS_DIAGRAMS = YES
HIDE_UNDOC_RELATIONS = YES
HAVE_DOT = YES
DOT_NUM_THREADS = 0

17
config.h
View file

@ -19,12 +19,21 @@
#ifndef __RPN_CONFIG__
#define __RPN_CONFIG__
/**@file config.h
* @brief Global definition for all C files
*/
/**@brief The programms is under GPL */
#define _GNU_SOURCE
#define PYRPN_doc_meth(NAME, header, docstring) PyDoc_STRVAR(NAME ## _doc,\
header "\n--\n\n" docstring);
/**@brief Allow fancy method declaration by indicating arguments list
* explicitly
* @param name char* The method name
* @param callback The C function to call
* @param flags int Python flags for method call options
* @param header char* List of arguments
* @param docstring char* The method documentation
*/
#define PYRPN_method(name, callback, flags, header, docstring) \
{name, (PyCFunction)callback, flags, \
PyDoc_STR(name "("header ")\n--\n\n" docstring)}

23
python_const.c
View file

@ -1,4 +1,11 @@
#include "python_const.h"
/**@file python_const.c
* @brief pyrpn.const code
* @ingroup python_ext
* @ingroup pymod_pyrpn_RPNIterParams
* @ingroup pymod_pyrpn_RPNTokenTypes
* @ingroup pymod_pyrpn_RPNMutationParams
*/
/** @todo implement GC with m_clear */
PyModuleDef rpnconstmodule = {
@ -13,6 +20,8 @@ PyModuleDef rpnconstmodule = {
};
/* Various named tuple definition, instanciated in python_rpnexpr module init */
/**@brief @ref pymod_pyrpn_RPNIterParams fields definition
* @ingroup pymod_pyrpn_RPNIterParams */
static PyStructSequence_Field params_fields[] = {
{
.name = "argc",
@ -43,6 +52,8 @@ PyStructSequence_Desc rpnif_params_desc = {
};
PyTypeObject rpnif_params_SeqDesc;
/**@brief @ref pymod_pyrpn_RPNTokenTypes field definition
* @ingroup pymod_pyrpn_RPNTokenTypes */
static PyStructSequence_Field token_types_fields[] = {
{ .name = "op",
.doc = "Operation",
@ -62,6 +73,8 @@ PyStructSequence_Desc rpn_token_types_desc = {
};
PyTypeObject rpn_token_types_SeqDesc;
/**@brief @ref pymod_pyrpn_RPNMutationParams field definition
* @ingroup pymod_pyrpn_RPNMutationParams */
static PyStructSequence_Field mutation_params_fields[] = {
{ .name = "minimum_length",
.doc = "Expression minimum length",
@ -106,6 +119,12 @@ rpn_mutation_params_t rpn_mutation_params_default = {
.w_mut_elt = {1.0,1.0,1.0},
};
/**@brief Adds a constant to @ref pymod_pyrpn_const module
* @param mod The @ref pymod_pyrpn_const module
* @param name The constant's name
* @param value The constant's value
* @return 0 or -1 on error
*/
int Py_rpnconst_add(PyObject* mod, const char* name, int value)
{
PyObject *val;
@ -119,7 +138,9 @@ int Py_rpnconst_add(PyObject* mod, const char* name, int value)
return 0;
}
/** @todo rename this function ! (bad prefix) */
/**@todo rename this function ! (bad prefix)
* @brief Module initialisation function
* @return The initialized module */
PyObject *Py_rpnconst_init(void)
{
PyObject *mod;

38
python_const.h
View file

@ -30,24 +30,56 @@
#include "rpn_mutate.h"
#include "rpn_if_default.h"
/**@file python_const.h
* @brief Python pyrpn.const module headers
* @ingroup python_ext
* @ingroup pymod_pyrpn_const
*/
/**@defgroup pymod_pyrpn_const module pyrpn.const
* @brief A module containing constant values
*
* Constants values are @ref ifs_if_default_posflag
* and @ref ifs_if_default_resflag
* @ingroup pymod_pyrpn
*/
/**@brief pyrpn.const module specs
* @ingroup python_module */
* @ingroup pymod_pyrpn */
extern PyModuleDef rpnconstmodule;
/**@brief A single instance of this object is used for parameters representation */
/**@defgroup pymod_pyrpn_RPNIterParams pyrpn.RPNIterParams
* @brief namedtuple representing @ref pymod_pyrpn_RPNExprIter parameters
* @ingroup pymod_pyrpn */
/**@brief RPNIterParams named tuple for RPNIterExpr parameters
* @ingroup pymod_pyrpn_RPNIterParams */
extern PyTypeObject rpnif_params_SeqDesc;
/**@brief @ref rpnif_params_SeqDesc named tuple description
* @ingroup pymod_pyrpn_RPNIterParams */
extern PyStructSequence_Desc rpnif_params_desc;
/**@defgroup pymod_pyrpn_RPNTokenTypes pyrpn.RPNTokenTypes
* @brief namedtuple with @ref pymod_pyrpn_token_Token subclass
* @ingroup pymod_pyrpn */
/**@brief RPNTokenTypes named tuple with token types */
extern PyTypeObject rpn_token_types_SeqDesc;
/**@brief @ref rpn_token_types_SeqDesc named tuple description */
extern PyStructSequence_Desc rpn_token_types_desc;
/**@defgroup pymod_pyrpn_RPNMutationParams pyrpn.RPNMutationParams
* @brief namedtuple storing mutation parameters
* @ingroup pymod_pyrpn */
/**@brief RPNMutationParams named tuple with mutation parameters */
extern PyTypeObject rpn_mutation_params_SeqDesc;
/**@brief @ref rpn_mutation_params_SeqDesc named tuple description */
extern PyStructSequence_Desc rpn_mutation_params_desc;
/**@brief Default values for mutations parameters */
extern rpn_mutation_params_t rpn_mutation_params_default;
/**@brief pyrpn.const module initialisation function
* @ingroup python_module */
* @return The initialized module
* @ingroup pymod_pyrpn */
PyObject *Py_rpnconst_init(void);
#endif

34
python_if.c
View file

@ -1,5 +1,12 @@
#include "python_if.h"
/**@file python_if.c
* @brief Python RPNIterExpr type definition
* @ingroup python_ext
* @ingroup pymod_pyrpn_RPNExprIter
*/
/**@brief @ref pymod_pyrpn_RPNExprIter methods definition
* @ingroup pymod_pyrpn_RPNExprIter */
static PyMethodDef RPNIterExpr_methods[] = {
PYRPN_method("get_params", rpnif_get_params,
METH_NOARGS,
@ -33,29 +40,38 @@ static PyMethodDef RPNIterExpr_methods[] = {
{NULL} //Sentinel
};
/**@brief @ref pymod_pyrpn_RPNExprIter members definition
* @ingroup pymod_pyrpn_RPNExprIter */
static PyMemberDef RPNIterExpr_members[] = {
{"expressions", T_OBJECT, offsetof(PyRPNIterExpr_t, expr), READONLY,
"The tuple of expressions"},
{NULL}
};
/**@brief @ref pymod_pyrpn_RPNExprIter sequence methods definition
* @ingroup pymod_pyrpn_RPNExprIter */
static PySequenceMethods RPNIterExpr_seq_methods = {
.sq_length = rpnif_len,
.sq_item = rpnif_expr_item,
.sq_ass_item = rpnif_expr_ass_item,
};
/**@brief @ref pymod_pyrpn_RPNExprIter mapping methods definition
* @ingroup pymod_pyrpn_RPNExprIter */
static PyMappingMethods RPNIterExpr_mapping_methods = {
.mp_length = rpnif_len,
.mp_subscript = rpnif_subscript,
.mp_ass_subscript = rpnif_ass_subscript,
};
/**@brief @ref pymod_pyrpn_RPNExprIter attributes definition
* @ingroup pymod_pyrpn_RPNExprIter */
static PyGetSetDef RPNIterExpr_getset[] = {
{NULL}
};
// Allows manipulation from numpy
/**@brief @ref pymod_pyrpn_RPNExprIter buffer methods definition
* @ingroup pymod_pyrpn_RPNExprIter */
static PyBufferProcs RPNIterExpr_as_buffer = {
(getbufferproc)rpnif_getbuffer,
(releasebufferproc)rpnif_releasebuffer,
@ -570,6 +586,11 @@ int rpnif_expr_ass_item(PyObject *self, Py_ssize_t idx, PyObject* elt)
return 0;
}
/** Convert key to integer index
* @param self @ref PyRPNIterExpr_t instance
* @param _key An expression name (str)
* @return The expression index or -1 on error (raise python exception)
*/
static Py_ssize_t _rpnif_subscript_idx(PyObject *self, PyObject *_key)
{
if(!PyUnicode_Check(_key))
@ -822,7 +843,9 @@ PyObject* rpnif_str(PyObject *self)
return buf;
}
/** Return a string representation of expressions dict
* @param self @ref PyRPNIterExpr_t instance
* @return a str instance */
static PyObject* _rpnif_expr_repr(PyObject *self)
{
PyRPNIterExpr_t *expr_self = (PyRPNIterExpr_t*)self;
@ -986,3 +1009,10 @@ PyObject* rpnif_setstate(PyObject *self, PyObject *state_bytes)
Py_RETURN_NONE;
}
/**@def _ret_append(key)
* @hiderefs
* local macro */
/**@def _const_res_key()
* @hiderefs
* local macro*/

125
python_if.h
View file

@ -32,8 +32,16 @@
#include "python_rpnexpr.h"
#include "python_const.h"
/**@defgroup python_if RPN Iterated Function Python class
* @ingroup python_module
/**@file python_if.h
* @brief Python RPNIterExpr type headers
* @ingroup python_ext
* @ingroup pymod_pyrpn_RPNExprIter
*
* This file is the header of the RPNIterExpr Python class
*/
/**@defgroup pymod_pyrpn_RPNExprIter class pyrpn.RPNExprIter
* @ingroup pymod_pyrpn
* @brief Exposed Python class : RPNIterExpr
*
* Iterated expression are composed of RPN expressions, they are able to
@ -43,21 +51,15 @@
* @see ifs_if
*/
/**@file python_if.h
* @brief Python RPNIterExpr type headers
* @ingroup python_if
*
* This file is the header of the RPNIterExpr Python class
*/
/**@brief RPNIterExpr Python class type definition
* @ingroup python_if */
* @ingroup pymod_pyrpn_RPNExprIter */
extern PyTypeObject RPNIterExprType;
/**@brief Structure holding RPNIterExpr objects
* @ingroup python_if */
* @ingroup pymod_pyrpn_RPNExprIter */
typedef struct
{
/** Python's type definition */
PyObject_VAR_HEAD;
/** @brief Number of dimention in map */
@ -74,8 +76,9 @@ typedef struct
/**@brief RpnIterExpr __new__ method
* @param subtype Type of object being created (pyrpn.RPNIterExpr)
* @param args positional arguments for subtype
* @param kwargs keyword argumenrs for subtype
* @param kwds keyword argumenrs for subtype
* @return The new Python RPNIterExpr object
* @ingroup pymod_pyrpn_RPNExprIter
*/
PyObject* rpnif_new(PyTypeObject *subtype, PyObject* args, PyObject* kwds);
@ -84,35 +87,57 @@ PyObject* rpnif_new(PyTypeObject *subtype, PyObject* args, PyObject* kwds);
* @param args Positional arguments list
* @param kwds Keywords arguments dict
* @return 0 if no error else -1
* @ingroup python_if
* @ingroup pymod_pyrpn_RPNExprIter
*/
int rpnif_init(PyObject *self, PyObject *args, PyObject *kwds);
/**@brief RPNIterExpr __del__ method
* @param self RPNExpr instance
* @ingroup python_type
* @ingroup pymod_pyrpn_RPNExprIter
*/
void rpnif_del(PyObject *self);
/**@brief Buffer protocol request handler method */
/**@brief Buffer protocol request handler method
* @param self RPNIterExpr instance
* @param view A memoryview to fill depending on flags
* @param flags Indicates the request type
* @return -1 on error
* See python documentation at
* https://docs.python.org/3/c-api/buffer.html#buffer-request-types
* @ingroup pymod_pyrpn_RPNExprIter
*/
int rpnif_getbuffer(PyObject *self, Py_buffer *view, int flags);
/**@brief Buffer protocol request release method */
/**@brief Buffer protocol request release method
* @param self RPNIterExppr instance
* @param view The memoryview to release (free what we filled)
* See python documentation at
* https://docs.python.org/3/c-api/buffer.html#buffer-request-types
* @ingroup pymod_pyrpn_RPNExprIter
*/
void rpnif_releasebuffer(PyObject *self, Py_buffer *view);
/**@brief Return a named tuple of custom rif data */
/**@brief Return a named tuple of custom rif data
* @param self RPNIterExpr instance
* @return A RPNIterParams named tuple
* @ingroup pymod_pyrpn_RPNExprIter
*/
PyObject *rpnif_get_params(PyObject *self);
/**@brief Runs an if on given */
/**@brief Runs an IF on given position
* @param self RPNInterExpr instance
* @param pos The start position
* @return A new position
* @ingroup pymod_pyrpn_RPNExprIter
*/
PyObject *rpnif_step(PyObject *self, PyObject* pos);
/**@brief Return the list of expressions */
PyObject *rpnif_get_expr(PyObject *self);
/**@brief RPNIterExpr __getstate__ method for pickling
* @param cls RPNIterExpr type object
* @param noargs Not an argument...
* @return A bytes Python instance suitable as argument for
* @ref rpnexpr_setstate
* @ingroup pymod_pyrpn_RPNExprIter
*/
PyObject* rpnif_getstate(PyObject *cls, PyObject *noargs);
@ -122,35 +147,85 @@ PyObject* rpnif_getstate(PyObject *cls, PyObject *noargs);
* rpnexpr_getstate
* @return A bytes Python instance suitable as argument for
* @ref rpnexpr_setstate
* @ingroup pymod_pyrpn_RPNExprIter
*/
PyObject* rpnif_setstate(PyObject *cls, PyObject *state);
/**@brief RPNIterExpr.__repr__()
* @param self RPNIterExpr instance
* @ingroup python_type
* @return A string representation of the instance
* @ingroup pymod_pyrpn_RPNExprIter
*/
PyObject* rpnif_repr(PyObject *self);
/**@brief RPNIterExpr.__str__()
* @param self RPNIterExpr instance
* @ingroup python_type
* @return A string representation of the instance
* @ingroup pymod_pyrpn_RPNExprIter
*/
PyObject* rpnif_str(PyObject *self);
/**@brief RPNExpr.__len__() method
* @param self RPNIterExpr instance
* @return A integer with the number of tokens in expression
* @ingroup pymod_pyrpn_RPNExprIter
*/
Py_ssize_t rpnif_len(PyObject *self);
PyObject* rpnif_expr_item(PyObject *self, Py_ssize_t);
/**@brief Sequence method for __getitem__ method
*
* Allow expressions access with integer indexes
* @param self RPNIterExpr instance
* @param idx Item index
* @return Corresponding RPNExpr or raise IndexError
* @ingroup pymod_pyrpn_RPNExprIter
*/
PyObject* rpnif_expr_item(PyObject *self, Py_ssize_t idx);
/**@brief Sequence method for __setitem__ method
*
* Allow to recompile an expressions using a str with integer indexes
* @param self RPNIterExpr instance
* @param idx Item index
* @param elt The code (str) to compile in indicated expression
* @return 0 if no error else -1
* @ingroup pymod_pyrpn_RPNExprIter
*/
int rpnif_expr_ass_item(PyObject *self, Py_ssize_t idx, PyObject* elt);
/**@brief Mapping method to access expressions by name
* @param self RPNIterExpr instance
* @param key An expression name (depending on parameters)
* @return The corresponding RPNExpr of raise KeyError
* @ingroup pymod_pyrpn_RPNExprIter
*/
PyObject* rpnif_subscript(PyObject *self, PyObject *key);
/**@brief Mapping method to recompile an expression by name
* @param self RPNIterExpr instance
* @param key An expression name (depending on parameters)
* @param elt The code (str) to compile in indicated expression
* @return 0 if no error else -1
* @ingroup pymod_pyrpn_RPNExprIter
*/
int rpnif_ass_subscript(PyObject *self, PyObject *key, PyObject *elt);
/**@brief Mimics dict.keys() method
* @param self RPNIterExpr instance
* @return A tuple with expressions name
* @ingroup pymod_pyrpn_RPNExprIter */
PyObject *rpnif_keys(PyObject *self);
/**@brief Mimics dict.values() method
* @param self RPNIterExpr instance
* @return A tuple with RPNExpr instances
* @ingroup pymod_pyrpn_RPNExprIter */
PyObject *rpnif_values(PyObject *self);
/**@brief Mimics dict.items() method
* @param self RPNIterExpr instance
* @return A tuple with tuples(key, value)
* @ingroup pymod_pyrpn_RPNExprIter */
PyObject *rpnif_items(PyObject *self);

2
python_pyrpn.c
View file

@ -21,10 +21,12 @@
/**@file python_pyrpn.c
* @brief Python module & type definition
* @ingroup python_ext
* @ingroup python_pyrpn
*
* This file contains pyrpn Python module definition
*/
/**@brief pyrpn module's method definition */
static PyMethodDef rpnmodule_methods[] = {
PYRPN_method("get_ops", pyrpn_ops,
METH_NOARGS,

37
python_pyrpn.h
View file

@ -33,8 +33,19 @@
#include "python_const.h"
#include "python_rpntoken.h"
/**@defgroup python_ext Python API
* @brief Python API definitions
/**@file python_pyrpn.h
* @brief Python module & type headers
* @ingroup python_ext
* @ingroup pymod_pyrpn
*
* This file is the header of the pyrpn Python module definition
*/
/**@defgroup python_ext Python extension
* @brief RPNIFS python extension
*
* RPNIFS comes with a python extension module allowing to use the RPN
* expressions in python.
*
* @ref python_pyrpn.c and @ref python_rpnexpr.c should be compiled in a .so file
* in order to expose a pyrpn Python module.
@ -49,33 +60,28 @@
* - pyrpn.RPNExpr.reset_stack(self) to set all stack items to 0
*/
/**@defgroup python_module pyrpn Python module
* @brief Exposed Python module : pyrpn
/**@defgroup pymod_pyrpn pyrpn Python module
* @brief Python extension main entry-point
* @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
*/
/**@brief RPNExpr Python class type definition */
extern PyTypeObject RPNExprType;
/**@brief Python module initialization function
* @ingroup python_module */
* @return The initialized module
* @ingroup pymod_pyrpn */
PyMODINIT_FUNC PyInit_pyrpn(void);
/**@brief Python module specs
* @ingroup python_module */
* @ingroup pymod_pyrpn */
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
* @ingroup pymod_pyrpn
*/
PyObject* pyrpn_ops(PyObject* mod, PyObject* noargs);
@ -83,7 +89,8 @@ PyObject* pyrpn_ops(PyObject* mod, PyObject* noargs);
* @param mod pyrpn module object
* @param args Position arguments in Python list
* @param kwds Keywords arguments in Python dict
* @ingroup python_module
* @return A str instance
* @ingroup pymod_pyrpn
*/
PyObject* pyrpn_random(PyObject *mod, PyObject *args, PyObject *kwds);

24
python_rpnexpr.c
View file

@ -18,6 +18,14 @@
*/
#include "python_rpnexpr.h"
/**@file python_rpnexpr.c
* @brief Python module & type definition
* @ingroup python_ext
* @ingroup python_pyrpn_RPNExpr
*/
/**@brief @ref pymod_pyrpn_RPNExpr methods definition
* @ingroup python_pyrpn_RPNExpr */
static PyMethodDef RPNExpr_methods[] = {
PYRPN_method("random", rpnexpr_random,
METH_CLASS | METH_VARARGS | METH_KEYWORDS,
@ -58,11 +66,15 @@ static PyMethodDef RPNExpr_methods[] = {
{NULL} //Sentinel
};
/**@brief @ref pymod_pyrpn_RPNExpr members definition
* @ingroup python_pyrpn_RPNExpr */
static PyMemberDef RPNExpr_members[] = {
{NULL}
};
/**@todo Continue sequence implementation with contains, concat, repeat etc. */
/**@brief @ref pymod_pyrpn_RPNExpr methods definition
* @todo Continue sequence implementation with contains, concat, repeat etc.
* @ingroup python_pyrpn_RPNExpr */
static PySequenceMethods RPNExpr_seq_methods = {
.sq_length = rpnexpr_len,
.sq_item = rpnexpr_token_item,
@ -888,6 +900,11 @@ PyObject* rpnexpr_default_mutation_params(PyObject *cls, PyObject **argv, Py_ssi
}
/**@brief Parse given object to float
* @param obj The python object to parse
* @param res Points on result
* @note Raise python exception on error
*/
static inline void _parse_float(PyObject *obj, float *res)
{
double tmp = PyFloat_AsDouble(obj);
@ -900,6 +917,11 @@ static inline void _parse_float(PyObject *obj, float *res)
return;
}
/** Parse weights python parameter
* @param obj The python object
* @param w Points on the 3 weights to parse
* @note Raise python exception on error
*/
static inline void _parse_type_weights(PyObject *obj, float w[3])
{
PyObject *fast = PySequence_Fast(obj, "Not a RPNTokenTypeTuple nor with a length of 3");

105
python_rpnexpr.h
View file

@ -32,27 +32,29 @@
#include "python_rpntoken.h"
#include "python_const.h"
/**@defgroup python_type RPNExpr Python class
* @brief Exposed Python class : RPNExpr
* @ingroup python_module
*/
/**@file python_rpnexpr.h
* @brief Python RPNExpr type headers
* @ingroup python_type
* @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 python_type */
* @ingroup pymod_pyrpn_RPNExpr */
extern PyTypeObject RPNExprType;
/**@brief Structure holding RPNExpr objects
* @ingroup python_type */
* @ingroup pymod_pyrpn_RPNExpr */
typedef struct
{
/** Python's type definition */
PyObject_VAR_HEAD;
/**@brief Pointer on @ref rpn_expr_s */
@ -69,26 +71,35 @@ typedef struct
/**@brief Organize PyRPNExpr_t state data
* @see rpnexpr_getstate
* @see rpnexpr_setstate */
* @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 kwargs keyword argumenrs 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);
@ -97,13 +108,13 @@ PyObject* rpnexpr_new(PyTypeObject *subtype, PyObject *args, PyObject* kwds);
* @param args Positional arguments list
* @param kwds Keywords arguments dict
* @return 0 if no error else -1
* @ingroup python_type
* @ingroup pymod_pyrpn_RPNExpr
*/
int rpnexpr_init(PyObject *self, PyObject *args, PyObject *kwds);
/**@brief RPNExpr __del__ method
* @param self RPNExpr instance
* @ingroup python_type
* @ingroup pymod_pyrpn_RPNExpr
*/
void rpnexpr_del(PyObject *self);
@ -112,6 +123,7 @@ void rpnexpr_del(PyObject *self);
* @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);
@ -120,6 +132,7 @@ PyObject* rpnexpr_getexprstate(PyObject *self, PyObject *noargs);
* @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);
@ -129,23 +142,41 @@ PyObject* rpnexpr_getstate(PyObject *self, PyObject *noargs);
* 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 self RPNExpr instance
* @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);
PyObject* rpnexpr_token_item(PyObject *self, Py_ssize_t);
/**@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
@ -154,14 +185,16 @@ int rpnexpr_token_ass_item(PyObject *self, Py_ssize_t idx, PyObject* elt);
* @param argv Array of PyObject* arguments
* @param argc Number of arguments
* @return The value resulting of evaluation
* @ingroup python_type
* @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 PyObject* RPNExpr instance
* @param PyObject* Positionnal arguments
* @param PyObject* Keyword arguments
* @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);
@ -169,44 +202,56 @@ PyObject* rpnexpr_mutate(PyObject* self, PyObject *args, PyObject *kwds);
* @param self RPNExpr instance
* @param noargs Dummy argument for METH_NOARG
* @return None
* @ingroup python_type
* @ingroup pymod_pyrpn_RPNExpr
*/
PyObject* rpnexpr_reset_stack(PyObject *self, PyObject *noargs);
/**@brief RPNExpr.__repr__()
* @param self RPNExpr instance
* @ingroup python_type
* @return An str instance representing the exppression
* @ingroup pymod_pyrpn_RPNExpr
*/
PyObject* rpnexpr_repr(PyObject *self);
/**@brief RPNExpr.__str__()
* @param self RPNExpr instance
* @ingroup python_type
* @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 mod pyrpn module object
* @param cls pyrpn module object
* @param args Position arguments in Python list
* @param kwds Keywords arguments in Python dict
* @ingroup python_module
* @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 PyObject* The class (class method)
* @param PyObject** The arguments (FASTCALL)
* @param Py_ssize_t The number of arguments
* @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 PyObject* The python object
* @param rpn_mutation_params_t A pointer on the parameters to initialize
* @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);

19
python_rpntoken.c
View file

@ -1,5 +1,16 @@
#include "python_rpntoken.h"
/**@file python_rpntoken.c
* @brief Python module & type definition
* @ingroup python_ext
* @ingroup python_pyrpn_token
* @ingroup python_pyrpn_token_Token
* @ingroup python_pyrpn_token_TokenOp
* @ingroup python_pyrpn_token_TokenVal
* @ingroup python_pyrpn_token_TokenArg
*/
/**@brief @ref pymod_pyrpn_token_Token method definition
* @ingroup python_pyrpn_token_Token */
static PyMethodDef RPNToken_methods[] = {
PYRPN_method("from_str", rpntoken_from_str, METH_CLASS | METH_O,
"cls, token_str, /",
@ -22,6 +33,8 @@ PyTypeObject RPNTokenType = {
.tp_methods = RPNToken_methods,
};
/**@brief @ref pymod_pyrpn_token_TokenOp method definition
* @ingroup python_pyrpn_token_TokenOp */
static PyMethodDef RPNTokenOp_methods[] = {
PYRPN_method("opcode_max", rpntokenop_opcode_max,
METH_STATIC | METH_NOARGS,
@ -36,6 +49,8 @@ static PyMethodDef RPNTokenOp_methods[] = {
{NULL} //
};
/**@brief @ref pymod_pyrpn_token_TokenOp members definition
* @ingroup python_pyrpn_token_TokenOp */
static PyMemberDef RPNTokenOp_members[] = {
{"opcode", T_BYTE, offsetof(RPNTokenOp_t, super.value.op_n), READONLY,
"The number representing the operand"},
@ -61,6 +76,8 @@ PyTypeObject RPNTokenOpType = {
.tp_methods = RPNTokenOp_methods,
};
/**@brief @ref pymod_pyrpn_token_TokenArg members definition
* @ingroup python_pyrpn_token_TokenArg */
static PyMemberDef RPNTokenArg_members[] = {
{"argno", T_ULONG, offsetof(RPNTokenOp_t, super.value.arg_n), READONLY,
"The argument number"},
@ -79,6 +96,8 @@ PyTypeObject RPNTokenArgType = {
.tp_members = RPNTokenArg_members,
};
/**@brief @ref pymod_pyrpn_token_TokenVal members definition
* @ingroup python_pyrpn_token_TokenVal */
static PyMemberDef RPNTokenVal_members[] = {
{"value", T_ULONG, offsetof(RPNTokenOp_t, super.value.value), READONLY,
"The immediate value"},

162
python_rpntoken.h
View file

@ -26,56 +26,186 @@
#include <Python.h>
#include "structmember.h"
/**@file python_rpnexpr.h
/**@file python_rpntoken.h
* @brief Python RPNToken type headers
* @ingroup python_type
* @ingroup python_ext
* @ingroup pymod_pyrpn_token
*
* This file is the header of the RPNToken classes and subclasses
*
*/
extern PyTypeObject RPNTokenType;
extern PyTypeObject RPNTokenOpType;
extern PyTypeObject RPNTokenValType;
extern PyTypeObject RPNTokenArgType;
/**@defgroup pymod_pyrpn_token module pyrpn.token
* @brief Python module representing RPNExpr tokens
* @ingroup pymod_pyrpn
*/
/**@brief pyrpn.token module */
extern PyModuleDef rpntokens_module;
/**@defgroup pymod_pyrpn_token_Token pyrpn.token.Token
* @brief Abstract class representing an @ref pymod_pyrpn_RPNExpr token
* @ingroup pymod_pyrpn_token */
/**@brief pyrpn.token.Token generic type
* @ingroup pymod_pyrpn_token_Token */
extern PyTypeObject RPNTokenType;
/**@defgroup pymod_pyrpn_token_TokenOp pyrpn.token.TokenOp
* @brief Python class representing an @ref pymod_pyrpn_RPNExpr operation token
*
* Extends @ref pymod_pyrpn_token_Token
* @ingroup pymod_pyrpn_token */
/**@brief pyrpn.token.TokenOp type
* @ingroup pymod_pyrpn_token_TokenOp */
extern PyTypeObject RPNTokenOpType;
/**@defgroup pymod_pyrpn_token_TokenVal pyrpn.token.TokenVal
* @brief Python class representing an @ref pymod_pyrpn_RPNExpr value token
*
* Extends @ref pymod_pyrpn_token_Token
* @ingroup pymod_pyrpn_token */
/**@brief pyrpn.token.TokenVal type
* @ingroup pymod_pyrpn_token_TokenVal */
extern PyTypeObject RPNTokenValType;
/**@defgroup pymod_pyrpn_token_TokenArg pyrpn.token.TokenArg
* @brief Python class representing an @ref pymod_pyrpn_RPNExpr argument token
*
* Extends @ref pymod_pyrpn_token_Token
* @ingroup pymod_pyrpn_token */
/**@brief pyrpn.token.TokenArg type
* @ingroup pymod_pyrpn_token_TokenArg */
extern PyTypeObject RPNTokenArgType;
/**@brief C representation of @ref RPNTokenType generic class
* @ingroup pymod_pyrpn_token_Token */
typedef struct
{
/** Python's type definition */
PyObject_HEAD;
/** @brief The token value (will be set by subtypes) */
rpn_token_t value;
} RPNToken_t;
/**@brief C representation of all @ref RPNTokenType subclasses
* @ingroup pymod_pyrpn_token_tokenOp
* @ingroup pymod_pyrpn_token_tokenVal
* @ingroup pymod_pyrpn_token_tokenArg
*/
typedef struct {
/** @brief Pointer on super type */
RPNToken_t super;
} RPNTokenOp_t;
} RPNTokenSubClass_t;
typedef struct {
RPNToken_t super;
} RPNTokenVal_t;
/**@brief C representation of @ref RPNTokenOpType
* @ingroup pymod_pyrpn_token_TokenOp */
typedef RPNTokenSubClass_t RPNTokenOp_t;
/**@brief C representation of @ref RPNTokenValType
* @ingroup pymod_pyrpn_token_TokenVal */
typedef RPNTokenSubClass_t RPNTokenVal_t;
/**@brief C representation of @ref RPNTokenArgType
* @ingroup pymod_pyrpn_token_TokenArg */
typedef RPNTokenSubClass_t RPNTokenArg_t;
typedef struct {
RPNToken_t super;
} RPNTokenArg_t;
/**@brief Module initialisation function
* @return initialized module
* @ingroup pymod_pyrpn_token */
PyObject* rpntokens_module_init(void);
PyObject* rpntoken_from_str(PyObject *_self, PyObject *arg);
/** Instanciate a new RPNToken subclass given a token */
/**@brief Class method returning a token instance from a string representation
* @param cls @ref RPNTokenType class or any subclass
* @param arg A str representing a token
* @return A new @ref RPNTokenType subclass instance or NULL on error
* @ingroup pymod_pyrpn_token_Token
*/
PyObject* rpntoken_from_str(PyObject *cls, PyObject *arg);
/**@brief Instanciate a new RPNToken subclass given a C token
* @param token An expression token
* @return A new @ref RPNTokenType subclass instance
* @ingroup pymod_pyrpn_token_Token
*/
PyObject* rpntoken_from_token(const rpn_token_t *token);
/**@brief @ref RPNTokenType __init__ method
* @param _self @ref RPNTokenType subclass instance
* @param args Positional arguments
* @param kwds Keyword arguments
* @return 0 or -1 on error
* @ingroup pymod_pyrpn_token_Token
*/
int rpntoken_init(PyObject *_self, PyObject *args, PyObject *kwds);
/**@brief PEP-207 comparison method
* @param _self An @ref RPNTokenType subclass instance
* @param other The @ref RPNTokenType subclass instance to compare to
* @param op The comparison
* @return Py_True or Py_False
* @ingroup pymod_pyrpn_token_Token
*/
PyObject* rpntoken_richcompare(PyObject *_self, PyObject *other, int op);
/**@brief __str__ method
* @param _self An @ref RPNTokenType subclass instance
* @return A str representing the token
* @ingroup pymod_pyrpn_token_Token */
PyObject* rpntoken_str(PyObject *_self);
/**@brief __repr__ method
* @param _self An @ref RPNTokenType subclass instance
* @return A str representing the token
* @ingroup pymod_pyrpn_token_Token */
PyObject* rpntoken_repr(PyObject *_self);
/**@brief @ref RPNTokenOpType __init__ method
* @param _self RPNTokenOpType being initialized
* @param args Positional arguments
* @param kwds Keyword arguments
* @return 0 or -1 on error
* @ingroup pymod_pyrpn_token_TokenOp */
int rpntokenop_init(PyObject *_self, PyObject *args, PyObject *kwds);
/**@brief @ref RPNTokenOpType opcode_max method
* @param Py_UNUSED unused argument for static method
* @return The maximum valid opcode
* @ingroup pymod_pyrpn_token_TokenOp */
PyObject *rpntokenop_opcode_max(PyObject *Py_UNUSED(_static));
/**@brief @ref RPNTokenOpType chr method
* @param _self @ref RPNTokenOpType instance
* @param Py_UNUSED unused argument
* @return A string with a single chr representing the operation
* @ingroup pymod_pyrpn_token_TokenOp */
PyObject *rpntokenop_opchr(PyObject *_self, PyObject* Py_UNUSED(_null));
/**@brief @ref RPNTokenOpType str method
* @param _self @ref RPNTokenOpType instance
* @param Py_UNUSED unused argument
* @return A string representing the operation on multiple chr
* @ingroup pymod_pyrpn_token_TokenOp */
PyObject *rpntokenop_opstr(PyObject *_self, PyObject* Py_UNUSED(_null));
/**@brief @ref RPNTokenValType __init__ method
* @param _self RPNTokenValType being initialized
* @param args Positional arguments
* @param kwds Keyword arguments
* @return 0 or -1 on error
* @ingroup pymod_pyrpn_token_TokenVal */
int rpntokenval_init(PyObject *_self, PyObject *args, PyObject *kwds);
/**@brief @ref RPNTokenArgType __init__ method
* @param _self RPNTokenArgType being initialized
* @param args Positional arguments
* @param kwds Keyword arguments
* @return 0 or -1 on error
* @ingroup pymod_pyrpn_token_TokenArg */
int rpntokenarg_init(PyObject *_self, PyObject *args, PyObject *kwds);
#endif

27
rpn_if.h
View file

@ -34,12 +34,29 @@
* @ingroup ifs
* @brief Iterated RPN expression
*
* A single Iterated Function implemented using an RPN expression.
* @note For more details about Iterated function see dedicated
* section : @ref doc_ifs_if
*
* @note The goal is to optimize iteration writing the code in C and providing
* an high level Python API.
* Iterated function are function that can be iterated on successive position
* in a memory map. The function takes its arguments from a position in the
* memory map and output its results at a resulting position in the memory map.
*
* For more details about IF see dedicated page : @ref doc_ifs_if
* The iterated function can be seen as a function taking a position as argument
* and outputing another position with borders effects from data stored at given
* positions.
*
* The implementation try to be as generic as possible, allowing to implement
* the transformation using a @ref rpn_expr_t system. The iterated function
* has 2 functions as parameters :
* - The first one @ref rpn_if_param_s.getarg_f transform a position
* to argument(s) and fetch the other arguments from the memory map
* - The second @ref rpn_if_param_s.setres_f takes the results from the
* @ref rpn_expr_t system, transform it in position and results and set
* the memory map at resulting position with results.
*
* Based on this generic implementation @ref ifs_if_default are implemented for
* various common cases : mutli-dimentionnal positions and constants, boolean,
* colors as results.
*/
/**@brief Shortcut for struct @ref rpn_if_s */
@ -100,7 +117,6 @@ struct rpn_if_s
/**@brief Alloc a new @ref rpn_if_s using given parameters
* @param params IF parameters
* @param rpn list of RPN expresions of params->rpn_sz size
* @param memmap A suitable memory map. If NULL given, a new mmap is used
* @return A pointer on an allocated @ref rpn_if_s
*/
@ -121,6 +137,7 @@ size_t rpn_if_step(rpn_if_t *rif, size_t pos);
/**@brief Returns the list of RPN expression : allowing to recompile them
* @param rif Pointer on IF
* @return A list of RPN expressions
* @note The memory area returned must not be freed !
*/

73
rpn_if_default.h
View file

@ -18,6 +18,8 @@
*/
#ifndef __rpn_if_default__h__
#define __rpn_if_default__h__
#include "config.h"
#include "rpn_if.h"
/**@file rpn_if_default.h Defines default IF
* @ingroup ifs_if_default
@ -25,17 +27,19 @@
* @brief Default IF definitions
*/
/**@defgroup ifs_if_default Default functions
/**@defgroup ifs_if_default Default iterated functions
* @ingroup ifs_if
* @brief Simple iterated functions functions
* @brief Iterated function default implementation
*
* Defines default @ref rpn_if_param_s.res_f and @ref rpn_if_param_s.arg_f
* functions.
* Defines default @ref rpn_if_param_s.setres_f and @ref rpn_if_param_s.getarg_f
* functions and flags to select them (see @ref ifs_if_default_posflag and
* @ref ifs_if_default_resflag ).
*
* The @ref rpn_if_default_params function constructs suitable
* @ref rpn_if_param_t to instanciate an @ref rpn_if_t with
* @ref rpn_if_new function.
*/
#include "config.h"
#include "rpn_if.h"
/**@weakgroup ifs_if_default_posflag Default IF position flags
* @ingroup ifs_if_default
* @{ */
@ -65,6 +69,7 @@ typedef struct rpn_if_default_data_s rpn_if_default_data_t;
/**@brief Stores default IF data
*
* Stores flags and size limit
* @ingroup ifs_if_default
*/
struct rpn_if_default_data_s
{
@ -77,7 +82,8 @@ struct rpn_if_default_data_s
* @note If NULL no limit
* - For @ref RPN_IF_POSITION_LINEAR size_lim is a single size_t
* - For @ref RPN_IF_POSITION_XY size_lim is two size_t (height and width)
* - For @ref RPN_IF_POSITION_XDIM *size_lim is the size of size_lim
* - For @ref RPN_IF_POSITION_XDIM the first element (*size_lim) is the
* size of the size_lim array
*/
size_t *size_lim;
@ -101,10 +107,11 @@ struct rpn_if_default_data_s
* (@ref ifs_if_default_resflag )
* @param lim Depends on pos_flag parameter (
* see @ref rpn_if_default_data_s::size_lim )
* @param val Depends on res_flag parameter (
* @param res_const Depends on res_flag parameter (
* see @ref rpn_if_default_data_s::const_val )
* @param rpn_stack_sz The size of the stack for expressions
* @returns A new @ref rpn_if_param_t or NULL on error
* @todo Implementation/testing
* @ingroup ifs_if_default
*/
rpn_if_param_t* rpn_if_default_params(short pos_flag, short res_flag,
const size_t *lim, const rpn_value_t *res_const,
@ -113,7 +120,7 @@ rpn_if_param_t* rpn_if_default_params(short pos_flag, short res_flag,
/** Fetch size limit and const values array sizes given flag values
* @param pos_flag (@ref ifs_if_default_posflag)
* @param res_flag (@ref ifs_if_default_resflag)
* @param short[2] size limit array size and constant values array size
* @param sizes size limit array size and constant values array size
* @return 0 or -1 if a flag is not valid
* @warning returns 1 for size limit when XDIM position, but actually the
* limit is given by the 1st number in the limit (example : [2,640,480],
@ -122,16 +129,37 @@ rpn_if_param_t* rpn_if_default_params(short pos_flag, short res_flag,
*/
int rpn_if_sizes_from_flag(short pos_flag, short res_flag, short sizes[2]);
/**@brief Default argf function ( see @ref rpn_if_param_s.arg_f ) */
/**@brief Default argf function ( see @ref rpn_if_param_s.getarg_f )
*
* This function handle internal rif modification to set next arguments.
* It will call specialized function depending on
* @ref rpn_if_default_data_s.pos_flag and @ref rpn_if_default_data_s.res_flag
* @note The position is the first set of arguments and can be use to
* look for the other one
*
* @param rif Pointer on expressions
* @param pos The position
* @return 0 or -1 on error
*/
int rpn_if_getarg_default(rpn_if_t *rif, size_t pos);
/**@brief Default result function ( see @ref rpn_if_param_s.res_f ) */
/**@brief Default result function ( see @ref rpn_if_param_s.setres_f )
*
* This function will store the result at given position and
* It will call specialized function depending on
* @ref rpn_if_default_data_s.pos_flag and @ref rpn_if_default_data_s.res_flag
* @param rif Pointer on expressions
* @param pos Will be set to the resulting position
* @return 0 or -1 on error
*/
int rpn_if_setres_default(rpn_if_t *rif, size_t *pos);
/**@brief Set the first expression argument from position
/**@brief Set the first expression argument from linear position
* @param rif Expressions
* @param pos Memory map offset
* @param args pointer on expressions arguments
* @note Other arguments are set using the generic @ref rpn_if_argf_default
* @return 0 or -1 on error
* @note Other arguments are set using the generic @ref rpn_if_getarg_default
* function
*/
int rpn_if_argf_linear(rpn_if_t *rif, size_t pos, rpn_value_t *args);
@ -139,7 +167,8 @@ int rpn_if_argf_linear(rpn_if_t *rif, size_t pos, rpn_value_t *args);
* @param rif Expressions
* @param pos Pointer on resulting position in memory map
* @param data Pointer on resulting data
* @note Data from position fecth is done by generic @ref rpn_if_resf_default
* @return 0 or -1 on error
* @note Data from position fecth is done by generic @ref rpn_if_setres_default
* function
*/
int rpn_if_resf_linear(rpn_if_t *rif, size_t *pos, rpn_value_t *data);
@ -148,7 +177,8 @@ int rpn_if_resf_linear(rpn_if_t *rif, size_t *pos, rpn_value_t *data);
* @param rif Expressions
* @param pos Memory map offset
* @param args pointer on expression arguments
* @note Other arguments are set using the generic @ref rpn_if_argf_default
* @return 0 or -1 on error
* @note Other arguments are set using the generic @ref rpn_if_getarg_default
* function
*/
int rpn_if_argf_xy(rpn_if_t *rif, size_t pos, rpn_value_t *args);
@ -156,7 +186,8 @@ int rpn_if_argf_xy(rpn_if_t *rif, size_t pos, rpn_value_t *args);
* @param rif Expressions
* @param pos Memory map offset pointer
* @param data Pointer on resulting data
* @note Data from position fetch is done by generic @ref rpn_if_resf_default
* @return 0 or -1 on error
* @note Data from position fetch is done by generic @ref rpn_if_setres_default
* function
*/
int rpn_if_resf_xy(rpn_if_t *rif, size_t *pos, rpn_value_t *data);
@ -165,7 +196,8 @@ int rpn_if_resf_xy(rpn_if_t *rif, size_t *pos, rpn_value_t *data);
* @param rif Expressions
* @param pos Memory map offset
* @param args Pointer on expression arguments
* @note Other arguments are set using the generic @ref rpn_if_argf_default
* @return 0 or -1 on error
* @note Other arguments are set using the generic @ref rpn_if_getarg_default
* function
*/
int rpn_if_argf_xdim(rpn_if_t *rif, size_t pos, rpn_value_t *args);
@ -173,7 +205,8 @@ int rpn_if_argf_xdim(rpn_if_t *rif, size_t pos, rpn_value_t *args);
* @param rif Expressions
* @param pos Memory map offset pointer
* @param data Pointer on resulting data
* @note Data from position fetch is done by generic @ref rpn_if_resf_default
* @return 0 or -1 on error
* @note Data from position fetch is done by generic @ref rpn_if_setres_default
* function
*/
int rpn_if_resf_xdim(rpn_if_t *rif, size_t *pos, rpn_value_t *data);

6
rpn_ifs.h
View file

@ -26,6 +26,11 @@
#include "rpn_jit.h"
#include "rpn_if.h"
/**@file rpn_ifs.h
* @brief IFS header
* @ingroup ifs
*/
/**@defgroup ifs Iterated function system
* @brief IFS implementation with RPN expressions
*
@ -130,6 +135,7 @@ int rpn_ifs_weight_update(rpn_ifs_t *rifs);
rpn_expr_t **rpn_ifs_flat_rpn(rpn_ifs_t *rifs);
/**@brief Randomly choose an IF and make a step updating ifs current posisition
* @param rifs The IF system
* @return -1 on error else 0
*/
int rpn_ifs_step(rpn_ifs_t *rifs);

17
rpn_jit.h
View file

@ -148,19 +148,20 @@ int rpn_expr_init(rpn_expr_t* expr, const unsigned char stack_sz,
/**@brief Reinit an existing @ref rpn_expr_s avoiding mmap and malloc
* for executable memory map and for stack
* @param expr
* @param expr Pointer on the expression
* @return 0 or -1 on error
*/
int rpn_expr_reinit(rpn_expr_t* expr);
/**@brief Recompile an existing, allready initialized, expression
* @param rpn_expr_t* The expression
* @param const char * The code to compile
* @param expr The expression
* @param code The code to compile
* @return 0 if no error else -1
*/
int rpn_expr_recompile(rpn_expr_t *expr, const char *code);
/**@brief Takes into account modifications in token representation
* @param rpn_expr_t*
* @param expr The expression with updated tokens
* @return 0 if no error else -1
*/
int rpn_expr_tokens_updated(rpn_expr_t* expr);
@ -179,10 +180,11 @@ int rpn_expr_compile(rpn_expr_t *expr, const char *code);
* @param tokens Tokenized form
* @param long_op If true long operation are used, else 1 chr op are used
* @return 0 if no error else -1 and @ref rpn_expr_s::err_reason is set
* @note The @ref rpn_tokenized_s::tokens attribute is "captured" by the
*
* @note The @ref rpn_tokenized_s.tokens attribute is "captured" by the
* @ref rpn_expr_s structure and will be deallocated when @ref rpn_expr_close
* is called. It is not encouraged to keep a reference on this attribute after
* @ref rpn_expr_start_untokenize call (but pointed @ref rpn_tokenized_t
* @ref rpn_expr_untokenize call (but pointed @ref rpn_tokenized_t
* can be reused)
* @ingroup rpn
*/
@ -221,7 +223,6 @@ unsigned long rpn_expr_eval(rpn_expr_t *expr, unsigned long *args);
/**@brief Free ressources handled by given @ref rpn_expr_s
* @param expr Pointer on rpn_expr_t
* @param expr Pointer on @ref rpn_expr_s
* @ingroup rpn
*/
void rpn_expr_close(rpn_expr_t* expr);
@ -269,7 +270,7 @@ int _rpn_expr_init_map(rpn_expr_t* expr);
int _rpn_expr_end_map(rpn_expr_t *expr);
/**@brief Reset the memory map, filling it with zeroes and reseting permissions
* @param rpn_expr_t*
* @param expr Pointer on rpn_expr_t
* @return 0 if no error else -1
*/
int _rpn_expr_reset_map(rpn_expr_t *expr);

6
rpn_lib.h
View file

@ -50,7 +50,9 @@
#define CODE_SZ(NAME) NAME ## _sz
/**@brief macro to declare a code part and associated size */
#define CODE_PART(NAME) const extern void* NAME; extern const unsigned long NAME ## _sz
#define CODE_PART(NAME) const extern void* NAME; \
/**@brief Cord part size */\
extern const unsigned long NAME ## _sz
/**@brief Define the type of value manipulated by RPN expressions
*
@ -58,7 +60,9 @@
* @todo use it */
typedef unsigned long int rpn_value_t;
/**@brief Small alias for PyLong_FromUnsignedLong */
#define PyLong_FromRpnValue_t PyLong_FromUnsignedLong
/**@brief Small alias for PyLong_AsUnsignedLong */
#define PyLong_AsRpnValue_t PyLong_AsUnsignedLong
/**@brief Function heading code

76
rpn_mutate.h
View file

@ -27,10 +27,16 @@
#include "rpn_parse.h"
/**@file rpn_mutate.h
* @brief Expression mutation headers
*/
/**@brief Mutation parameters */
typedef struct rpn_mutation_params_s rpn_mutation_params_t;
/**@brief Type of random values used by mutations */
typedef uint16_t rnd_t;
/** @brief Mutation parameters */
struct rpn_mutation_params_s
{
/**@brief Minimum expression length */
@ -50,12 +56,15 @@ struct rpn_mutation_params_s
* mutating a token*/
float w_mut_elt[3];
/**@brief For internal use, set by @ref rpn_mutation_init_params
/**@brief For internal use, set by rpn_mutation_init_params
*
* weight reported by groups on rnd_t integers
* - [0..3] -> weights mutation
* - [4..6] -> w_add_elt
* - [7..9] -> w_mut_elt
*
* @note Weights are stored a way allowing fast random choice.
* They are kind of ascending threshold until @ref rnd_t max value.
*/
rnd_t _weights[10];
};
@ -63,42 +72,85 @@ struct rpn_mutation_params_s
/**@brief Initialize mutation parameters
*
* pre-process integers threshold by group
* @param rpn_mutation_params_t*
* @param params
* @return 0 if no error else -1 and set ERRNO (EINVAL)
*/
int rpn_mutation_init_params(rpn_mutation_params_t *params);
/**@brief Mutate a tokenized rpn expression */
/**@brief Mutate a tokenized rpn expression
* @param toks The tokenized expression
* @param params The mutation parameters
* @return 0 or -1 on error */
int rpn_mutation(rpn_tokenized_t *toks, rpn_mutation_params_t *params);
/**@brief Mutate an expression by adding a token
* @param toks The tokenized expression
* @param params The mutation parameters
* @return 0 or -1 on error */
int rpn_mutation_add(rpn_tokenized_t *toks, rpn_mutation_params_t *params);
/**@brief Mutate an expression by removing a token
* @param toks The tokenized expression
* @param params The mutation parameters
* @return 0 or -1 on error */
int rpn_mutation_del(rpn_tokenized_t *toks, rpn_mutation_params_t *params);
/**@brief Mutate an expression by changing a token
* @param toks The tokenized expression
* @param params The mutation parameters
* @return 0 or -1 on error */
int rpn_mutation_mut(rpn_tokenized_t *toks, rpn_mutation_params_t *params);
/**@brief Mutate an expression by changing a token value (not type)
* @param toks The tokenized expression
* @param params The mutation parameters
* @return 0 or -1 on error */
int rpn_mutation_mut_soft(rpn_tokenized_t *toks, rpn_mutation_params_t *params);
/**@brief Change the "value" of a token randomly not it's type */
/**@brief Change the "value" of a token randomly not it's type
* @param tok Point on the token to mutate
* @param toks The tokenized expression the token tok belongs to
* @param params The mutation parameters
* @return 0 or -1 on error */
int rpn_mutation_random_token(rpn_token_t *tok,
rpn_tokenized_t *toks, rpn_mutation_params_t *params);
/**@breif Choose a random token type
* @return -1 on error
/**@brief Choose a random token type
* @param type Point on result
* @param weights The weight of each types for the choice
* @note Weights comes from @ref rpn_mutation_params_s._weights and are
* processed in a form allowing a fast random choice.
* @return 0 or -1 on error
*/
int rpn_random_token_type(rpn_token_type_t *type, rnd_t *weights);
/**@param rnd_t* Is set to a random value
/**@brief Generate a random value
* @param rand Point on result
* @return -1 on error else 0 */
int rpn_getrandom(rnd_t *rand);
/**@param size_t Maximum value
* @param size_t* Will be set to a value between [..max[
/**@brief Generate a random number between 0 and max (max excluded)
* @param max Maximum value
* @param res Will be set to a value between [..max[
* @return -1 on error else 0 */
int rpn_rand_limit(size_t max, size_t *res);
/**@briref Given a size return an element with regards to given weights */
/**@brief Given a size return an random element with regards to given weights
* @param sz The given size
* @param weights Weights coming from @ref rpn_mutation_params_s._weights
* @param res Points on result
* @return 0 or -1 on error */
int _rpn_random_choice(size_t sz, rnd_t *weights, size_t *res);
/**@brief Given a size and a (random) value, returns an element with regards
* to given weights
* @param sz The given size
* @param weights Weights coming from @ref rpn_mutation_params_s._weights
* @param rand A (random) value
* @param res Points on result */
void __rpn_random_choice(size_t sz, rnd_t *weights, rnd_t rand, size_t *res);
// Debugging function
/**@brief Debugging function that dump mutation params in a human readable format
* @param fd The file descriptor on wich we should print parameters
* @param params The mutation parameters to dump */
void _print_params(int fd, rpn_mutation_params_t *params);
#endif

16
rpn_parse.h
View file

@ -37,7 +37,7 @@
* @brief Parsing an expression into a @ref rpn_tokenized_t
*
* The tokenized form ( see @ref rpn_tokenized_t ) of an expression is usefull
* for @ref mutation.
* for mutations (see @ref rpn_mutate.h ).
*
* The tokenizing process is done in a way allowing compilation process to
* fetch tokens while parsing the expression (see @ref rpn_tok).
@ -164,6 +164,8 @@ struct rpn_tokenizer_s
* Stores operation identification informations
* @ingroup rpn_tokenize */
extern const rpn_op_t rpn_ops[];
/**@brief The count of operand (the size of @ref rpn_ops array) */
extern const size_t RPN_OP_SZ;
@ -223,7 +225,7 @@ char* rpn_tokenized_expr(rpn_tokenized_t *tokens, char long_op);
const rpn_op_t* rpn_match_token(const char* token);
/**@brief Returns NULL or pointer on corresponding operation infos
* @param unsigned char opcode (index in @ref rpn_ops )
* @param opcode (index in @ref rpn_ops )
* @return NULL or operation informations
*/
const rpn_op_t* rpn_op_from_opcode(unsigned char opcode);
@ -244,13 +246,19 @@ int rpn_match_token_i(const char* token);
*/
int rpn_match_number(const char* token, unsigned long *result);
/**@todo doc */
/**@brief Stores a token string representation in given buffer
* @param token The token to represent
* @param dst The destination buffer for the string
* @param sz The biffer size
* @return Same as snprintf (the number of chr stored or negative value on error
*/
int rpn_token_snprintf(rpn_token_t *token, char *dst, size_t sz);
/**@brief Get operations list size
* @return number of operations in @ref rpn_ops
*/
size_t rpn_op_sz();
/**@brief Macro version of @ref rpn_op_sz() */
#define RPN_OPS_SZ (sizeof(rpn_ops)/sizeof(rpn_op_t))
/**@page rpn_lang RPN expression syntax
@ -287,7 +295,7 @@ size_t rpn_op_sz();
* Each valid operations are declared in @ref rpn_ops variable (see
* @ref rpn_parse.c for details).
*
* The @ref python_module expose a function pyrpn.get_ops() ( @see pyrpn_ops )
* The @ref pymod_pyrpn expose a function pyrpn.get_ops() ( @see pyrpn_ops )
* returning a dict with long operations as key and short as value.
* \subsubsection rpn_lan_op_internal Internal mechanism
* Operations are done using a loopstack : operands are poped from stack, and