csnake 0.4.0
C code generation helper package.
License: MIT
Requires Python: <4.0,>=3.9
Keywords: codegen, c, embedded

######
csnake
######

.. image:: https://gitlab.com/andrejr/csnake/badges/master/pipeline.svg
   :alt: pipeline status
   :target: https://gitlab.com/andrejr/csnake/pipelines
.. image:: https://gitlab.com/andrejr/csnake/badges/master/coverage.svg
   :alt: coverage report
   :target: https://andrejr.gitlab.io/csnake/coverage/index.html

Csnake is a Python 3 package that helps you generate C code from Python.

Csnake provides you with a consistent and opinionated API that helps you
structure your C-generating Python code.
It does so by providing classes and functions for generating every C language
construct.

Probably the most important feature is the ability to initialize a value to
``struct`` and *array* initializers from Python *dicts* and *lists* (actually,
``Map``\s and ``Collection``\s), nested arbitrarily.

Here's a taste:

.. code-block:: python

   from csnake import CodeWriter, Variable, FormattedLiteral
   import numpy as np

   var = Variable(
       "test",
       primitive="struct whatever",
       value={
           "field1": [{"x": num, "y": 10 - num} for num in range(2)],
           "field2": {"test": range(3), "field": np.arange(6).reshape(2, 3)},
           "field3": FormattedLiteral([30, 31, 32], int_formatter=hex),
           "field4": 8,
       },
   )
   cw = CodeWriter()
   cw.add_variable_initialization(var)
   print(cw)


This yields:

.. code-block:: c

    struct whatever test = {
        .field1 = {
            {
                .x = 0,
                .y = 10
            },{
                .x = 1,
                .y = 9
            }
        },
        .field2 = {
            .test = {0, 1, 2},
            .field = {
                {0, 1, 2},
                {3, 4, 5}
            }

        },
        .field3 = {0x1e, 0x1f, 0x20},
        .field4 = 8
    };

As shown, ``numpy`` arrays are supported as values (so are ``sympy`` arrays),
and values can be formatted by arbitrary functions (here we're using ``hex`` to
output ints as hex literals for member `field3`).

Motivation
==========

Csnake's varable generation was motivated by a common embedded development
task: inputting data into C code.

Csnake should be of help when generating C code for representing data like
bitmaps, fonts, statemachines, lookup tables - as arrays and structs.
It can also be used for loop unrolling, templating, ...

Csnake  can be easily incorporated into a build system (Make, CMake,
Scons,...), and also goes along great with Jinja2 and
`Ned Batchelder's cog <https://nedbatchelder.com/code/cog/>`_.

Documentation
=============

Documentation (Sphinx) can be viewed on
`GitLab pages for this package <https://andrejr.gitlab.io/csnake/>`_.

Examples
========

Csnake is used on several of my yet-to-be-released open source embedded
projects. I'll be adding those (and other) examples along the way.

Credits
=======

Csnake is a major re-implementation (and improvement) of
`C-Snake <https://github.com/SchrodingersGat/C-Snake>`_
by
`Oliver <https://github.com/SchrodingersGat>`_
(original idea) and Andrej (variable initialization idea and implementation,
author of this package).

It's provided under the MIT license.

Changelog
=========

The changelog can be found within the documentation, 
`here <https://andrejr.gitlab.io/csnake/changes.html>`_.