API Documentation¶
-
class
csnake.
CodeWriter
(lf=None, indent=4)[source]¶ Bases:
csnake.codewriterlite.CodeWriterLite
Container class for C code, with methods to add C constructs.
CodeWriter
(abbreviated CW or cw) is a code container that allows you to add code (both manually written and generated), access it as astr
, iterate over the lines of code and output the code to a file.It also helps you to indent and dedent code, open or close code blocks consistently.
CodeWriter
is iterable (iterates over lines of code), and also has methods like__contains__()
and__len__()
.Here’s an overview of abc’s
CodeWriter
is a virtual subclass of:>>> from csnake import CodeWriter >>> from collections.abc import Container, Iterable, Sized, Collection >>> cwr = CodeWriter() >>> assert isinstance(cwr, Container) >>> assert isinstance(cwr, Iterable) >>> assert isinstance(cwr, Sized) >>> assert isinstance(cwr, Collection)
Parameters: - lf (
Optional
[str
]) – linefeed character used to separate lines of code when rendering code withstr()
orcode
. - indent (
Union
[int
,str
]) – indentation unit string orint
number of spaces, used to indent code.
-
lf
¶ linefeed character used to separate lines of code when rendering code with
str()
orcode
.Type: str
-
lines
¶ lines of code.
Type: list(str)
-
__contains__
(item)¶ Return whether a
str
is a substring of the codewriter.Parameters: item (str) – a potential substring of the codewriter. Return type: bool
Returns: Whether or not item is a substring of the str()
representation of the codewriter.
-
__getitem__
(key)¶ Return the nth line of code.
Return type: str
-
__iter__
()¶ Return an iterator that iterates over the lines in the codewriter.
Return type: Iterable
[str
]
-
__len__
()¶ Return the number of lines in the codewriter.
-
add
(text)¶ Append text to the end of last line.
Parameters: text ( str
) –str
to append to the last line.Raises: ValueError
– iftext
is not astr
.Return type: None
-
add_autogen_comment
(source_file_name=None)[source]¶ Add a comment denoting the code was autogenerated by a script.
File name of the script the file is generated from is optional.
Parameters: source_file_name ( Optional
[str
]) – name of the script the code was generated fromExamples
Without a script file name:
>>> from csnake import CodeWriter >>> cwr1 = CodeWriter() >>> cwr1.add_autogen_comment() >>> print(cwr1) /* * This file was automatically generated using csnake v0.2.0. * * This file should not be edited directly, any changes will be * overwritten next time the script is run. * * Source code for csnake is available at: * https://gitlab.com/andrejr/csnake */
With a script name:
>>> from csnake import CodeWriter >>> cwr2 = CodeWriter() >>> cwr2.add_autogen_comment('test.py') >>> print(cwr2) /* * This file was automatically generated using csnake v0.2.0. * * This file should not be edited directly, any changes will be * overwritten next time the script is run. * Make any changes to the file 'test.py', not this file. * * Source code for csnake is available at: * https://gitlab.com/andrejr/csnake */
Return type: None
-
add_define
(name, value=None, comment=None)[source]¶ Add a define directive for macros.
Macros may or may not have a value.
Parameters: - name (
str
) – macro name - value (
Union
[CExtendedLiteral
,VariableValue
,None
]) – literal or variable assigned to the macro (optional) - comment (
Optional
[str
]) – comment accompanying macro definition
Examples
>>> from csnake import CodeWriter, Variable, Subscript >>> cwr = CodeWriter() >>> cwr.add_define('PI', 3.14) >>> cwr.add_define('LOG') >>> somearr = Variable('some_array', 'int', value=range(0, 5)) >>> cwr.add_define('DEST', Subscript(somearr, 2)) >>> print(cwr) #define PI 3.14 #define LOG #define DEST some_array[2]
Return type: None
- name (
-
add_enum
(enum)[source]¶ Add an enumeration definition.
Parameters: enum ( Enum
) – enum in questionSee also
Enum
for details on the enum classExamples
>>> from csnake import ( ... CodeWriter, Enum, Variable, Dereference, AddressOf ... ) >>> cw = CodeWriter() >>> name = "somename" >>> pfx = "pfx" >>> typedef = False >>> enum = Enum(name, prefix=pfx, typedef=typedef) >>> cval1 = Variable("varname", "int") >>> enum.add_value("val1", 1) >>> enum.add_value("val2", Dereference(1000)) >>> enum.add_value("val3", cval1) >>> enum.add_value("val4", AddressOf(cval1), "some comment") >>> cw.add_enum(enum) >>> print(cw) enum somename { pfxval1 = 1, pfxval2 = *1000, pfxval3 = varname, pfxval4 = &varname /* some comment */ };
Return type: None
-
add_function_call
(func, *arg)[source]¶ Add a call to a function with listed arguments.
Parameters: - func (
Function
) – function in question - *arg – (rest of the args) function’s args in sequence
See also
Function
for details on the Function classExamples
>>> from csnake import CodeWriter, Variable, Function >>> cw = CodeWriter() >>> arg1 = Variable("arg1", "int") >>> arg2 = Variable("arg2", "int", value=range(10)) >>> arg3 = ("arg3", "int") >>> arg4 = {"name": "arg4", "primitive": "int"} >>> fun = Function( ... "testfunct", "void", arguments=(arg1, arg2, arg3, arg4) ... ) >>> fun.add_code(("code;", "more_code;")) >>> cw.add_function_call(fun, 1, 2, 3, 4) >>> print(cw) testfunct(1, 2, 3, 4);
Return type: None
- func (
-
add_function_definition
(func)[source]¶ Add a functions’s definition / implementation.
Parameters: func ( Function
) – function in questionSee also
Function
for details on the Function classExamples
>>> from csnake import CodeWriter, Variable, Function >>> cw = CodeWriter() >>> arg1 = Variable("arg1", "int") >>> arg2 = Variable("arg2", "int", value=range(10)) >>> arg3 = ("arg3", "int") >>> arg4 = {"name": "arg4", "primitive": "int"} >>> fun = Function( ... "testfunct", "void", arguments=(arg1, arg2, arg3, arg4) ... ) >>> fun.add_code(("code;", "more_code;")) >>> cw.add_function_definition(fun) >>> print(cw) void testfunct(int arg1, int arg2[10], int arg3, int arg4) { code; more_code; }
Return type: None
-
add_function_prototype
(func, extern=False, comment=None)[source]¶ Add a functions’s prototype.
Parameters: - func (
Function
) – function in question - extern (
bool
) – wheter to add theextern
qualifier to the - prototype (True) or not (False, default) –
- comment (
Optional
[str
]) – accompanying inline comment
See also
Function
for details on the Function classExamples
>>> from csnake import CodeWriter, Variable, Function >>> cw = CodeWriter() >>> arg1 = Variable("arg1", "int") >>> arg2 = Variable("arg2", "int", value=range(10)) >>> arg3 = ("arg3", "int") >>> arg4 = {"name": "arg4", "primitive": "int"} >>> fun = Function( ... "testfunct", "void", arguments=(arg1, arg2, arg3, arg4) ... ) >>> fun.add_code(("code;", "more_code;")) >>> cw.add_function_prototype(fun) >>> print(cw) void testfunct(int arg1, int arg2[10], int arg3, int arg4);
Return type: None
- func (
-
add_license_comment
(license_, authors=None, intro=None, year=None)[source]¶ Add a comment with the license and authors.
The comment also adds the year to the copyright.
Parameters: - license_ –
str
containing the text of the license - authors (
Optional
[Iterable
[Mapping
[str
,str
]]]) – optional iterable containing mappings (dict-likes, one per author) with key-value pairs for keys ‘name’ (author’s name) and email (author’s email, optional) - intro (
Optional
[str
]) – introductory text added before the author list, optional - year (
Optional
[int
]) – year of the copyright (optional). If it is left out, current year is assumed.
Raises: ValueError
– if any of the arguments is of wrong typeExamples
Just license:
>>> from csnake import CodeWriter >>> license_text = 'license\ntext\nlines' >>> cw1 = CodeWriter() >>> cw1.add_license_comment(license_text) >>> print(cw1) /* * license * text * lines */
With introduction:
>>> intro_text = 'intro\ntext' >>> cw2 = CodeWriter() >>> cw2.add_license_comment(license_text, intro=intro_text) >>> print(cw2) /* * intro * text * * license * text * lines */
With authors:
>>> authors = [ ... {'name': 'Author Surname'}, ... {'name': 'Other Surname', 'email': 'test@email'}, ... ] >>> cw3 = CodeWriter() >>> cw3.add_license_comment( ... license_text, authors=authors, intro=intro_text ... ) >>> print(cw3) /* * intro * text * * Copyright © 2018 Author Surname * Copyright © 2018 Other Surname <test@email> * * license * text * lines */
Return type: None
- license_ –
-
add_line
(text=None, comment=None, ignore_indent=False)¶ Add a line of text to the container after the last line.
Parameters: - text (
Optional
[str
]) –str
to add - comment (
Optional
[str
]) – optional comment - ignore_indent (
bool
) – switch to ignore indentation and insert the code with indentation 0
Raises: ValueError
– if text or comment isn’t astr
Return type: None
- text (
-
add_lines
(lines, ignore_indent=False)¶ Append code lines from an iterable or a multi-line str.
If lines is an iterable iterating over
str
objects, adds the lines to the codewriter in order.If lines is a multi-line string, adds its lines to the codewriter.
Parameters: - lines (
Union
[Iterable
[str
],str
]) – anIterable
ofstr
or a multi-line str to add to codewriter. - ignore_indent (
bool
) – whether to ignore the current indentation level or not. If ignore_indent is true, the lines will be appended without indentation.
Raises: ValueError
– if one of the arguments is of the wrong typeExamples
Adding a list of lines:
>>> from csnake import CodeWriter >>> cwr = CodeWriter() >>> lol = ['list', 'of', 'lines'] >>> cwr.add_lines(lol) >>> print(cwr) list of lines
Return type: None
- lines (
-
add_struct
(struct)[source]¶ Add a struct declaration.
Parameters: struct ( Struct
) – struct in questionSee also
Struct
for details on the Struct class.Example
>>> from csnake import CodeWriter, Variable, Struct >>> cw = CodeWriter() >>> strct = Struct("strname", typedef=False) >>> var1 = Variable("var1", "int") >>> var2 = Variable("var2", "int", value=range(10)) >>> strct.add_variable(var1) >>> strct.add_variable(var2) >>> strct.add_variable(("var3", "int")) >>> strct.add_variable({"name": "var4", "primitive": "int"}) >>> cw.add_struct(strct) >>> print(cw) struct strname { int var1; int var2[10]; int var3; int var4; };
Return type: None
-
add_switch_break
()[source]¶ Break a switch case.
Used with
start_switch()
,end_switch()
,add_switch_case()
,add_switch_default()
,add_switch_return()
, to form C switch statements.Examples
See
start_switch()
.Return type: None
-
add_switch_case
(case=typing.Union[csnake.cconstructs.CExtendedLiteral, csnake.cconstructs.VariableValue], comment=None)[source]¶ Add a switch case statement.
Used with
start_switch()
,end_switch()
,add_switch_default()
,add_switch_break()
,add_switch_return()
, to form C switch statements.Parameters: - case – literal or variable representing the current case’s value
- comment (
Optional
[str
]) – accompanying inline comment
Examples
See
start_switch()
.Return type: None
-
add_switch_default
(comment=None)[source]¶ Add a switch default statement.
Used with
start_switch()
,end_switch()
,add_switch_case()
,add_switch_break()
,add_switch_return()
, to form C switch statements.Switch statements can be nested, so
end_switch()
closes the innermost switch.Examples
See
start_switch()
.Return type: None
-
add_switch_return
(value=None)[source]¶ Return inside of a switch statement
Used with
start_switch()
,end_switch()
,add_switch_case()
,add_switch_default()
,add_switch_break()
, to form C switch statements.Parameters: value ( Union
[CExtendedLiteral
,VariableValue
,None
]) – literal or variable representing the value to returnExamples
See
start_switch()
.Return type: None
-
add_variable_declaration
(variable, extern=False)[source]¶ Add a variable’s declaration.
Parameters: - variable (
Variable
) – variable in question - extern (
bool
) – wheter to add theextern
qualifier to the - declaration (True) or not (False, default) –
See also
Variable
for details on the Variable classExamples
>>> import numpy as np >>> from csnake import CodeWriter, Variable >>> cw = CodeWriter() >>> var = Variable( ... "test", ... primitive="int", ... value=np.arange(24).reshape((2, 3, 4)) ... ) >>> cw.add_variable_declaration(var) >>> print(cw) int test[2][3][4];
Return type: None
- variable (
-
add_variable_initialization
(variable)[source]¶ Add a variable’s initialization.
Parameters: variable ( Variable
) – variable in questionSee also
Variable
for details on the Variable classExample
>>> import numpy as np >>> from csnake import CodeWriter, Variable >>> cw = CodeWriter() >>> var = Variable( ... "test", ... primitive="int", ... value=np.arange(24).reshape((2, 3, 4)) ... ) >>> cw.add_variable_initialization(var) >>> print(cw) int test[2][3][4] = { { {0, 1, 2, 3}, {4, 5, 6, 7}, {8, 9, 10, 11} }, { {12, 13, 14, 15}, {16, 17, 18, 19}, {20, 21, 22, 23} } };
Return type: None
-
close_brace
()¶ Add a closed brace and decrease indentation for subsequent lines.
See
dedent()
for more information on how dedentation is done.Examples
See
open_brace()
.Return type: None
-
code
¶ The contents of the codewriter rendered to a str, using
lf
as the linebreak.Type: str Return type: str
-
cpp_entry
()[source]¶ Start a conditional
extern “C”
for use CPP compilers.Examples
cpp_entry()
andcpp_exit()
in action:>>> from csnake import CodeWriter >>> cwr = CodeWriter() >>> cwr.cpp_entry() >>> cwr.add_line('some_code();') >>> cwr.cpp_exit() >>> print(cwr) #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ some_code(); #ifdef __cplusplus } #endif /* __cplusplus */
Return type: None
-
cpp_exit
()[source]¶ End a conditional
extern “C”
for use CPP compilers.Examples
See
cpp_entry()
.Return type: None
-
end_comment
(ignore_indent=False)¶ End a comment block.
A comment block previously started by
start_comment()
is ended. The following code is not inside a block comment.Raises: NoCommentStartError
– if you attempt to end a comment block when a comment block hasn’t been started.Examples
See
start_comment()
.Return type: None
-
end_if_def
(ignore_ifdef_stack=False)[source]¶ Insert an
#endif
to end a#ifdef
(preprocessor) block.#ifdef
(or#ifndef
) blocks can be nested.#endif
always ends the innermost block.endif
statements are added byend_if_def()
.Parameters: ignore_ifdef_stack (
bool
) – (optional) don’t throw an exception#endif
if is unmatched.Raises: ValueError
– if one of the arguments is of the wrong type.DefStackEmptyError
– if there isn’t a matching#ifdef
andignore_ifdef_stack
isn’t set.
Examples
See
start_if_def()
.Return type: None
-
end_switch
(ignore_switch_stack=False)[source]¶ End a switch statement.
Used with
start_switch()
,add_switch_case()
,add_switch_default()
,add_switch_break()
,add_switch_return()
, to form C switch statements.Switch statements can be nested, so
end_switch()
closes the innermost switch.Parameters: ignore_switch_stack (
bool
) – don’t throw an exception if a switch start is missingRaises: SwitchStackEmptyError
– ifend_switch()
is called outside of a- switch statement, and
ignore_switch_stack
isFalse
.
Examples
See
start_switch()
.Return type: None
-
include
(name, comment=None)[source]¶ Add an
#include
directive.System headers should be surrounded with brackets (<>), while local headers may or may not be surrounded with quotation marks (“”) (the resulting code will have quotation marks surrounding the header’s name)
Parameters: - name (
str
) – name of header to include, with or without brackets/quotes. If no brackets/quotes surround the name, quotes are used by default. - comment (
Optional
[str
]) – accompanying inline comment
Examples
All types of includes.
>>> from csnake import CodeWriter >>> cw = CodeWriter() >>> cw.include('"some_local_header.h"') >>> cw.include('other_local_header.h') >>> cw.include("<string.h>") >>> print(cw) #include "some_local_header.h" #include "other_local_header.h" #include <string.h>
Return type: None
- name (
-
indent
()¶ Increase the indentation level by 1 unit.
Examples
indent()
anddedent()
in action:>>> from csnake import CodeWriter >>> cwr = CodeWriter() >>> cwr.add_line('line_1;') >>> cwr.indent() >>> cwr.add_line('line_2;') >>> cwr.add_line('line_3;') >>> cwr.dedent() >>> cwr.add_line('line_4;') >>> print(cwr) line_1; line_2; line_3; line_4;
Return type: None
-
open_brace
()¶ Add an open brace and increase indentation for subsequent lines.
See
indent()
for more information on how indentation is done.Examples
Using
open_brace()
andclose_brace()
.>>> from csnake import CodeWriter >>> cwr = CodeWriter() >>> cwr.add_line('line_1;') >>> cwr.open_brace() >>> cwr.add_line('line_2;') >>> cwr.add_line('line_3;') >>> cwr.close_brace() >>> cwr.add_line('line_4;') >>> print(cwr) line_1; { line_2; line_3; } line_4;
Return type: None
-
start_comment
(ignore_indent=False)¶ Start a comment block.
All of the lines added after this are in a block comment, until the block is finished by
end_comment()
.Parameters: ignore_indent ( bool
) – whether to ignore the indentation and just start the comment from the beginning of the next line.Raises: NestedCommentError
– if you attempt to start a comment block when a comment block has already been started.Examples
Starting and ending a comment block with
start_comment()
andend_comment()
:>>> from csnake import CodeWriter >>> cwr = CodeWriter() >>> cwr.add_line('line_1;') >>> cwr.start_comment() >>> cwr.add_line('line_2;') >>> cwr.add_line('line_3;') >>> cwr.end_comment() >>> cwr.add_line('line_4;') >>> print(cwr) line_1; /* * line_2; * line_3; */ line_4;
Return type: None
-
start_if_def
(define, invert=False, comment=None)[source]¶ Start an
#ifdef
or#ifndef
(preprocessor) block.#ifdef
(or#ifndef
) blocks can be nested.#endif
always ends the innermost block.endif
statements are added byend_if_def()
.Parameters: - define (
str
) – name of the macro whose existence we’re checking. - invert (
bool
) – (optional) whether this block is an#ifndef
(True
) or#ifdef
(False
, default). - comment (
Optional
[str
]) – (optional) comment accompanying the statement.
Raises: ValueError
– if one of the arguments is of the wrong type.Examples
start_if_def()
andend_if_def()
in action, including nested ifdefs:>>> from csnake import CodeWriter >>> cwr = CodeWriter() >>> cwr.start_if_def('DEBUG') >>> cwr.start_if_def('ARM', invert=True) >>> cwr.add_define('LOG') >>> cwr.end_if_def() >>> cwr.end_if_def() >>> print(cwr) #ifdef DEBUG #ifndef ARM #define LOG #endif /* ARM */ #endif /* DEBUG */
Return type: None
- define (
-
start_switch
(switch)[source]¶ Start a switch statement.
Used with
end_switch()
,add_switch_case()
,add_switch_default()
,add_switch_break()
,add_switch_return()
, to form C switch statements.Switch statements can be nested, so
end_switch()
closes the innermost switch.Parameters: switch ( Union
[CExtendedLiteral
,VariableValue
]) – literal or variable the choice depends on.Examples
Demonstration of switch-related methods:
>>> from csnake import CodeWriter, Variable >>> cw = CodeWriter() >>> var = Variable("somevar", "int") >>> case_var = Variable("case_var", "int") >>> cw.start_switch(var) >>> cw.add_switch_case(2) >>> cw.add_line('do_something();') >>> cw.add_switch_break() >>> cw.add_switch_case(case_var) >>> cw.add_switch_return(5) >>> cw.add_switch_default() >>> cw.add_switch_return(8) >>> cw.end_switch() >>> print(cw) switch (somevar) { case 2: do_something(); break; case case_var: return 5; default: return 8; } /* ~switch (somevar) */
Return type: None
-
write_to_file
(filename)[source]¶ Write code to filename.
Parameters: filename ( str
) – name of the file to write code intoReturn type: None
-
zero_indent
()¶ Set indentation level to zero.
Return type: None
- lf (
-
class
csnake.
Enum
(name, prefix=None, typedef=False)[source]¶ Bases:
object
Class describing C
enum
construct.Parameters: - name (
str
) – name of the enum - prefix (
Optional
[str
]) – prefix to add to every enumeration’s name - typedef (
bool
) – whether or not the enum istypedef
’d
-
name
¶ name of the enum
-
typedef
¶ whether or not the enum is
typedef
’d
-
prefix
¶ prefix to add to every enumeration’s name
-
values
¶ list of
Enum.EnumValue
-
class
EnumValue
(name, value=None, comment=None)[source]¶ Bases:
object
Singular value of an C-style enumeration.
-
add_value
(name, value=None, comment=None)[source]¶ Add a single
name = value
pair (or justname
).Return type: None
-
add_values
(values)[source]¶ Add multiple
name = value
pairs (or justname
s).Values can be one of:
- a
dict
with name : value entries - a collection of:
str
s denoting names (no value)dict
s with keys [name, value, comment], and optional- keys [value, comment]
- collections (
list
-like) of length 1-3 denoting [name, - value, comment] respectively
- collections (
Return type: None
- a
-
declaration
¶ The declaration
str
(with indentation of 4 spaces).See also
generate_declaration()
for the underlying method.Return type: str
-
generate_declaration
(indent=4)[source]¶ Generate enum declaration code.
Generate a
CodeWriterLite
instance containing the initialization code for thisEnum
.Parameters: indent ( Union
[int
,str
]) – indentstr
orint
denoting the number of spaces for indentationExamples
>>> from csnake import ( ... Enum, Variable, Dereference, AddressOf ... ) >>> name = "somename" >>> pfx = "pfx" >>> typedef = False >>> enum = Enum(name, prefix=pfx, typedef=typedef) >>> cval1 = Variable("varname", "int") >>> enum.add_value("val1", 1) >>> enum.add_value("val2", Dereference(1000)) >>> enum.add_value("val3", cval1) >>> enum.add_value("val4", AddressOf(cval1), "some comment") >>> print(enum.generate_declaration()) enum somename { pfxval1 = 1, pfxval2 = *1000, pfxval3 = varname, pfxval4 = &varname /* some comment */ };
Return type: CodeWriterLite
- name (
-
class
csnake.
Struct
(name, typedef=False)[source]¶ Bases:
object
Class describing C
struct
construct.Parameters: - name (
str
) – name of struct - typedef (
bool
) – whether or not the struct istypedef
’d
-
name
¶ name of struct
-
typedef
¶ whether or not the struct is
typedef
’d
-
variables
¶ list
ofstruct
’s variables
-
add_variable
(variable)[source]¶ Add a variable to struct.
Variables inside of a
Struct
are ordered (added sequentially).Parameters: variable ( Union
[Variable
,Collection
[+T_co],Mapping
[~KT, +VT_co]]) –variable to add. It can be defined in multiple ways.
variable can be:
- a
Variable
- a
Collection
(tuple
/list
-like) of 2 str
s (name, primitive)
- a
- a
Mapping
(dict
-like) with keys [‘name’, - ’primitive’]
- a
- a
-
declaration
¶ CodeWriterLite
instance containing the declaration code for thisStruct
.See also
generate_declaration()
for the underlying method.
-
generate_declaration
(indent=4)[source]¶ Generate a
CodeWriterLite
instance containing the initialization code for thisStruct
.Parameters: indent ( Union
[int
,str
]) – indentstr
orint
denoting the number of spaces for indentationExample
>>> from csnake import Variable, Struct >>> strct = Struct("strname", typedef=False) >>> var1 = Variable("var1", "int") >>> var2 = Variable("var2", "int", value=range(10)) >>> strct.add_variable(var1) >>> strct.add_variable(var2) >>> strct.add_variable(("var3", "int")) >>> strct.add_variable({"name": "var4", "primitive": "int"}) >>> print(strct.generate_declaration()) struct strname { int var1; int var2[10]; int var3; int var4; };
Return type: CodeWriterLite
- name (
-
class
csnake.
Function
(name, return_type='void', qualifiers=None, arguments=None)[source]¶ Bases:
object
Class describing C function.
You can generate a function prototype (declaration), a definition or a call. A function’s body is a
CodeWriterLite
, so You can add lines of code to it (or a whole newCodeWriter
instance).Parameters: - name (
str
) – name of the function - return_type (
str
) –str
containing function’s return type - qualifiers (
Union
[str
,Iterable
[str
],None
]) –str
orSequence
ofstr
listing the function’s qualifiers (const
,volatile
, …) - arguments (
Optional
[Iterable
[+T_co]]) –an iterable which yields one the following types:
- a
Variable
- a
Collection
(tuple
/list
-like) of 2 strings - (name, primitive)
- a
- a
Mapping
(dict
-like) with keys (name, - primitive)
- a
- a
-
name
¶ name of the function
-
return_type
¶ str
containing function’s return type
-
qualifiers
¶ str
orSequence
ofstr
listing the function’s qualifiers (const
,volatile
, …)
-
arguments
¶ an iterable which yields one the following types:
- a
Variable
- a
Collection
(tuple
/list
-like) of 2 strings - (name, primitive)
- a
- a
Mapping
(dict
-like) with keys (name, - primitive)
- a
- a
-
codewriter
¶ internal instance of
CodeWriterLite
that contains
-
the funtion's body code.
-
add_argument
(arg)[source]¶ Add an argument to function.
Arguments are added sequentially.
arg: an one the following types:
- a
Variable
- a
Collection
(tuple
/list
-like) of 2 strings - (name, primitive)
- a
- a
Mapping
(dict
-like) with keys (name, - primitive)
- a
Return type: None
- a
-
add_arguments
(args)[source]¶ Add multiple arguments to function.
Arguments are added sequentially.
args: an iterable which yields one the following types:
- a
Variable
- a
Collection
(tuple
/list
-like) of 2 strings - (name, primitive)
- a
- a
Mapping
(dict
-like) with keys (name, - primitive)
- a
Return type: None
- a
-
add_code
(code)[source]¶ Add a
str
orIterable
ofstr
s to function’s bodyIf code is an iterable, it should be one string - one line. Since a
CodeWriter
is an iterable ofstr
s , you can simply add its contents to the function.Parameters: code ( Union
[str
,Iterable
[str
]]) –str
orIterable
ofstr
s to be addedReturn type: None
-
definition
¶ Function definition
str
.See also
generate_definition()
for the underlying method.Return type: str
-
generate_call
(*arg)[source]¶ Return function calling code for specific arguments.
Parameters: *arg – argument values for call, in order of appearance. Doesn’t end with a semicolon (;).
Examples
>>> from csnake import Variable, Function >>> arg1 = Variable("arg1", "int") >>> arg2 = Variable("arg2", "int", value=range(10)) >>> arg3 = ("arg3", "int") >>> arg4 = {"name": "arg4", "primitive": "int"} >>> fun = Function( ... "testfunct", "void", arguments=(arg1, arg2, arg3, arg4) ... ) >>> fun.add_code(("code;", "more_code;")) >>> print(fun.generate_call(1, 2, 3, 4)) testfunct(1, 2, 3, 4)
Return type: str
-
generate_definition
(indent=' ')[source]¶ Return a
CodeWriterLite
instance containing the definition code for thisFunction
.Parameters: indent ( Union
[int
,str
]) – indentstr
orint
denoting the number of spaces for indentationExamples
>>> from csnake import Variable, Function >>> arg1 = Variable("arg1", "int") >>> arg2 = Variable("arg2", "int", value=range(10)) >>> arg3 = ("arg3", "int") >>> arg4 = {"name": "arg4", "primitive": "int"} >>> fun = Function( ... "testfunct", "void", arguments=(arg1, arg2, arg3, arg4) ... ) >>> fun.add_code(("code;", "more_code;")) >>> print(fun.generate_definition()) void testfunct(int arg1, int arg2[10], int arg3, int arg4) { code; more_code; }
Return type: CodeWriterLite
-
generate_prototype
(extern=False)[source]¶ Generate function prototype code.
Parameters: extern ( bool
) – whether or not the function is to be declared asextern
Doesn’t end with a semicolon (;).
Examples
>>> from csnake import Variable, Function >>> arg1 = Variable("arg1", "int") >>> arg2 = Variable("arg2", "int", value=range(10)) >>> arg3 = ("arg3", "int") >>> arg4 = {"name": "arg4", "primitive": "int"} >>> fun = Function( ... "testfunct", "void", arguments=(arg1, arg2, arg3, arg4) ... ) >>> fun.add_code(("code;", "more_code;")) >>> print(fun.generate_prototype()) void testfunct(int arg1, int arg2[10], int arg3, int arg4)
Return type: str
-
init_target_code
(formatters=None)[source]¶ Return code used for variable initialization, formatted with the supplied formatters.
Parameters: formatters ( Optional
[LiteralFormatters
]) – collection of formatters used for formatting the initializationstr
Return type: str
-
prototype
¶ Function prototype (declaration)
str
.Ends with a semicolon (;).
See also
generate_prototype()
for the underlying method.Return type: str
- name (
-
class
csnake.
Variable
(name, primitive, qualifiers=None, array=None, comment=None, value=None)[source]¶ Bases:
object
Class describing C variable contruct.
You can generate declarations and initializations for variables, and variables can be initialized to very complex values (you can init an array variable to an array of
struct
containing arrays that containstructs
, …).The formatting of initialization
str
s can be altered by encasing some level of the initialization with aFormattedLiteral
.As for function values, the following (Python input → C code) translations are assumed (numpy and scipy ints and floats are considered ints and floats):
dict
→struct
literallist
or tuple → array literalint
→int
literal orint
literalfloat
→float
literal ordouble
literalbool
→bool
literal orint
literalVariable
→ name of the variable
There is no type checking for initializations. That’s what your compiler is for, no sense in replicating such functionality here.
Parameters: - name (
str
) – name of the variable - primitive (
Union
[str
,FuncPtr
]) –str
name orFuncPtr
defining the variable’s type - qualifiers (
Union
[str
,Iterable
[str
],None
]) –str
orSequence
ofstr
listing the variable’s qualifiers (const
,volatile
, …) - array (
Optional
[Iterable
[+T_co]]) –Sequence
ofint
defining the dimensions of a (possibly multidimensional) array. If it’s left out, it’s inferred from value. - comment (
Optional
[str
]) – accompanying comment - value (
Optional
[CLiteral
]) – variable’s value, used for initialization. Explained in detail above
-
__str__
()[source]¶ Initialization
str
.Ends with a semicolon (;).
See also
generate_initialization()
for the underlying method.
-
declaration
¶ Declaration string.
Ends with a semicolon (;).
See also
generate_declaration()
for the underlying method.Return type: str
-
generate_declaration
(extern=False)[source]¶ Return a declaration
str
.Doesn’t end with a semicolon (;).
Parameters: extern ( bool
) – whether or not the value is to be declared asextern
Examples
>>> import numpy as np >>> from csnake import Variable >>> var = Variable( ... "test", ... primitive="int", ... value=np.arange(24).reshape((2, 3, 4)) ... ) >>> print(var.generate_declaration()) int test[2][3][4]
Return type: str
-
generate_initialization
(indent=4)[source]¶ Return a
CodeWriterLite
instance containing the initialization code for thisVariable
.Ends with a semicolon (;).
Parameters: indent ( Union
[int
,str
]) – indentstr
orint
denoting the number of spaces for indentationExample
>>> import numpy as np >>> from csnake import Variable >>> var = Variable( ... "test", ... primitive="int", ... value=np.arange(24).reshape((2, 3, 4)) ... ) >>> print(var.generate_initialization()) int test[2][3][4] = { { {0, 1, 2, 3}, {4, 5, 6, 7}, {8, 9, 10, 11} }, { {12, 13, 14, 15}, {16, 17, 18, 19}, {20, 21, 22, 23} } };
Return type: CodeWriterLite
-
init_target_code
(formatters=None)[source]¶ Return a
str
used for initialization of otherVariable
sReturn type: str
-
initialization
¶ Initialization
str
.Ends with a semicolon (;).
See also
generate_initialization()
for the underlying method.Return type: str
-
class
csnake.
FuncPtr
(return_type, arguments=None, comment=None)[source]¶ Bases:
object
Class describing function pointer args and return type.
This class made for declaring function pointer type specifics for use with
Variable
s as their type argument.Parameters: - return_type (
str
) –str
containing the return type - arguments (
Optional
[Iterable
[+T_co]]) –an iterable which yields one the following types:
- a
Variable
- a
Collection
(tuple
/list
-like) of 2 strings - (name, primitive)
- a
- a
Mapping
(dict
-like) with keys (name, - primitive)
- a
- a
-
get_declaration
(name, qualifiers=None, array=None)[source]¶ Generate the whole declaration
str
according to parameters.This method is meant to be called from
Variable.generate_declaration()
andVariable.generate_initialization()
function and is probably useless to You elsewhere.Return type: str
- return_type (
-
class
csnake.
FormattedLiteral
(value, *args, **kwargs)[source]¶ Bases:
object
A C literal with its formatter collection altered.
The accompanying literal formatter collection will be used when generating the initialization
str
.Parameters: **kwargs – keyword arguments for each of the formatters in [‘int_formatter’, ‘float_formatter’, ‘bool_formatter’, ‘string_formatter’] we want to change for this literal. Every missing formatter is inherited from the literal (or default).
-
class
csnake.
VariableValue
[source]¶ Bases:
object
Abstract base class for any initializer value based on a variable.
Sometimes we want to initialize a value to another variable, but in some more complicated manner: using the address-of operator, dereference operator, subscripting, typecasting… This is an ABC for those modifiers.
-
class
csnake.
AddressOf
(variable)[source]¶ Bases:
csnake.cconstructs.VariableValue
Address of (&) VariableValue for variable initialization.
Subclass of
VariableValue
that returns an initialization string containing the & (address of) used on a value.Parameters: variable ( VariableValue
) – variable to return the address of.-
variable
¶ variable to return the address of.
Examples
>>> from csnake import Variable, AddressOf >>> var1 = Variable("var1", "int") >>> addrof_var1 = AddressOf(var1) >>> var2 = Variable("var2", "int", value=addrof_var1) >>> print(var2) int var2 = &var1;
-
-
class
csnake.
Arrow
(variable, item)[source]¶ Bases:
csnake.cconstructs.VariableValue
Arrow (->) VariableValue for variable initialization.
Subclass of
VariableValue
that returns an initialization string for accessing a specific member of a struct indirectly (through a pointer).Parameters: - variable (
Union
[CLiteral
,VariableValue
]) – variable whose member we’re accessing - member – name of member we’re accessing
-
variable
¶ variable whose member we’re accessing
-
member
¶ name of member we’re accessing
Examples
>>> from csnake import Variable, Arrow >>> var1 = Variable("var1", "struct somestr") >>> arrvar = Arrow(var1, 'some_member') >>> var2 = Variable("var2", "int", value=arrvar) >>> print(var2) int var2 = var1->some_member;
- variable (
-
class
csnake.
Dereference
(value)[source]¶ Bases:
csnake.cconstructs.VariableValue
Dereference (*) modifier for variable initialization.
Subclass of
VariableValue
that returns an initialization string containing the * (dereference) used on a value.Parameters: value ( Union
[CExtendedLiteral
,VariableValue
]) – value to dereference.-
value
¶ value to dereference.
Examples
>>> from csnake import Variable, Dereference >>> var1 = Variable("var1", "int") >>> derefd_var1 = Dereference(var1) >>> var2 = Variable("var2", "int", value=derefd_var1) >>> print(var2) int var2 = *var1; >>> derefd_number = Dereference(16) >>> var3 = Variable("var3", "int", value=derefd_number) >>> print(var3) int var3 = *16;
-
-
class
csnake.
Dot
(variable, member)[source]¶ Bases:
csnake.cconstructs.VariableValue
Dot (.) VariableValue for variable initialization.
Subclass of
VariableValue
that returns an initialization string for accessing a specific member of a struct.Parameters: - variable (
Union
[CLiteral
,VariableValue
]) – variable whose member we’re accessing - member (
str
) – name of member we’re accessing
-
variable
¶ variable whose member we’re accessing
-
member
¶ name of member we’re accessing
Examples
>>> from csnake import Variable, Dot >>> var1 = Variable("var1", "struct somestr") >>> dotvar = Dot(var1, 'some_member') >>> var2 = Variable("var2", "int", value=dotvar) >>> print(var2) int var2 = var1.some_member;
- variable (
-
class
csnake.
GenericModifier
(value, function)[source]¶ Bases:
csnake.cconstructs.VariableValue
VariableValue generated by applying a function to a value.
A value’s initializer string is passed through the supplied function, which should return a
str
.Parameters: - value (
Union
[CExtendedLiteral
,VariableValue
]) – value whose initializer we’re passing through a function - format_function – function used for modifying a value’s initializer
-
value
¶ value whose initializer we’re passing through a function
-
format_function
¶ function used for modifying a value’s initializer
Examples
>>> from csnake import Variable, GenericModifier >>> var1 = Variable("var1", "int") >>> genmod_var1 = GenericModifier(var1, lambda l: f'TRANSLATE({l})') >>> var2 = Variable("var2", "int", value=genmod_var1) >>> print(var2) int var2 = TRANSLATE(var1); >>> genmod_var2 = GenericModifier('test', lambda l: f'do_whatever({l})') >>> var3 = Variable("var3", "int", value=genmod_var2) >>> print(var3) int var3 = do_whatever("test");
- value (
-
class
csnake.
OffsetOf
(struct, member)[source]¶ Bases:
csnake.cconstructs.VariableValue
offsetof VariableValue modifier for initializing to offsets of struct members.
Subclass of
VariableValue
that returns an initialization string containing the offset of a specific member of a struct.Parameters: - struct (
Union
[Struct
,str
]) – struct whose member’s offset we’re using - member (
Union
[VariableValue
,str
]) – struct member whose offset we’re using
-
struct
¶ struct whose member’s offset we’re using
-
member
¶ struct member whose offset we’re using
Examples
>>> from csnake import Variable, OffsetOf, Struct >>> offs_val1 = OffsetOf('struct some', 'some_member') >>> var2 = Variable("var2", "int", value=offs_val1 ) >>> print(var2) int var2 = offsetof(struct some, some_member); >>> test_struct = Struct('other') >>> offs_val2 = OffsetOf(test_struct, 'other_member') >>> var3 = Variable("var3", "int", value=offs_val2 ) >>> print(var3) int var3 = offsetof(struct other, other_member);
- struct (
-
class
csnake.
Subscript
(variable, subscript)[source]¶ Bases:
csnake.cconstructs.VariableValue
Subscript ([]) modifier for variable initialization.
Subclass of
VariableValue
that returns an initialization string with a subscripted value.Parameters: - variable (
Union
[CLiteral
,VariableValue
]) – variable to be typecast - subscript (
Iterable
[+T_co]) – aVariableValue
orint
orlist
or tuple of them representing the subscript[s].
-
variable
¶ variable to be typecast
-
subscript
¶ a
VariableValue
orint
orlist
or tuple of them representing the subscript[s].
Examples
>>> from csnake import Variable, Subscript >>> var1 = Variable("var1", "int") >>> subscr1_var1 = Subscript(var1, 3) >>> var2 = Variable("var2", "int", value=subscr1_var1) >>> print(var2) int var2 = var1[3]; >>> subscr2_var1 = Subscript(var1, (3, 2)) >>> var3 = Variable("var3", "int", value=subscr2_var1) >>> print(var3) int var3 = var1[3][2]; >>> subscr2_var1 = Subscript(var1, (var3, 2)) >>> var4 = Variable("var4", "int", value=subscr2_var1) >>> print(var4) int var4 = var1[var3][2];
- variable (
-
class
csnake.
TextModifier
(text)[source]¶ Bases:
csnake.cconstructs.VariableValue
Generic textual VariableValue for initializing to an arbitrary
str
.The
str
supplied as the argument is output verbatim as the Initialization string.Parameters: text ( str
) – initialization string-
text
¶ initialization string
Examples
>>> from csnake import Variable, TextModifier >>> textmod1 = TextModifier('whatever + you + want') >>> var2 = Variable("var2", "int", value=textmod1) >>> print(var2) int var2 = whatever + you + want; >>> textmod2 = TextModifier(f'you_can_do_this_too + {var2.name}') >>> var3 = Variable("var3", "int", value=textmod2) >>> print(var3) int var3 = you_can_do_this_too + var2;
-
-
class
csnake.
Typecast
(value, cast)[source]¶ Bases:
csnake.cconstructs.VariableValue
Typecast modifier for variable initialization.
Subclass of
VariableValue
that returns an initialization string containing the typecast to type used on a value.Parameters: - value (
Union
[CExtendedLiteral
,VariableValue
]) – value to be typecast - cast (
str
) – type to cast to
-
value
¶ value to be typecast
-
cast
¶ type to cast to
Examples
>>> from csnake import Variable, Typecast >>> var1 = Variable("var1", "int") >>> cast_var1 = Typecast(var1, 'long') >>> var2 = Variable("var2", "int", value=cast_var1) >>> print(var2) int var2 = (long) var1; >>> cast_number = Typecast(16, 'long') >>> var3 = Variable("var3", "int", value=cast_number) >>> print(var3) int var3 = (long) 16;
- value (