cauterize 0.0.1.pre1

data/.gitignore

@@ -0,0 +1,24 @@
+# Object files
+*.o
+
+# Libraries
+*.lib
+*.a
+
+# Shared objects (inc. Windows DLLs)
+*.dll
+*.so
+*.so.*
+*.dylib
+
+# Executables
+*.exe
+*.out
+*.app
+
+# Bundler
+Gemfile.lock
+pkg
+
+# Examples
+example/cauterize_output

data/.rspec

@@ -0,0 +1 @@
+-r spec_helper --color

data/.travisci.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - "1.9.3"
+script: bundle exec rake

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in cauterize.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 John Van Enk
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# *THIS PROJECT IS EXPERIMENTAL. IT MAY BREAK AND RUIN EVERYTHING YOU KNOW AND LOVE.*
+
+# cauterize
+
+A Ruby DSL for generating marshalable structured data easily compatable with
+statically allocated C systems. Currently, it prefers simplicity and
+predictability over speed.
+
+# Why?
+
+Basically, `malloc` is a huge pain when you only have 16K of RAM.
+
+# Examples
+
+There's currently a (single) example in this project. To run it, do this:
+
+```
+git clone git://github.com/sw17ch/cauterize.git
+cd cauterize
+bundle install
+cd example
+sh build.sh
+```
+
+If this completes without error, then you should find a bunch of generated code
+in cauterize_output. Look at the structures and enumerations defined in the
+`example_project.h` file. Also look at how the `Pack_*` and `Unpack_*`
+functions are organized and named.
+
+Once you've looked at this, take a look at `example_project.c`. This will show
+you the exact mechanism used to package and unpackage different structures.
+
+`cauterize.h` and `cauterize.c` are used as iterators over C buffers. They are
+used to abstract the process of packaging and unpackaging different elements.
+
+# Different Types
+
+There are 6 fundamental classes of types in Cauterize. These types have several characteristics:
+
+* They can be copied with `memcpy`.
+* They do not attempt to cover the concept of indirection or pointers.
+* They are simple.
+* They cannot be defined recursively.
+
+## Scalars
+
+Scalars are any type that corresponds to a C scalar value. That is, something
+that can be defined with the native types (`int`, `long`, `short`, etc). It is
+highly recommended that these ONLY ever use values from `stdint.h`. This
+ensures that the sizes of these scalars will be consistent across platforms.
+
+Scalars can be defined simply by giving them a name that corresponds to a type
+from `stdint.h`.
+
+```ruby
+scalar(:uint8_t)
+scalar(:uint32_t)
+```
+
+## Enumerations
+
+Enumerations correspond almost exactly to C enumerations. They are a list of
+names. When appropriate, a specific scalar value may also be specified. If no
+scalar is specified, enumerations will be represented in order from 0.
+
+```ruby
+enumeration(:color) do |e|
+  e.value :red
+  e.value :blue
+  e.value :green
+end
+
+enumeration(:days_of_week) do |e|
+  e.value :sunday, 100
+  e.value :monday, 101
+  e.value :tuesday, 102
+  e.value :wednesday, 103
+  e.value :thursday, 104
+  e.value :friday, 105
+  e.value :saturday, 106
+end
+```
+
+## Fixed Arrays
+
+Fixed arrays are arrays that only ever make sense when they are full. An
+example of an array with this property is a MAC Address. MAC addresses are
+always 6 bytes. Never more. Never less.
+
+```ruby
+fixed_array(:mac_address) do |a|
+ a.array_type :uint8_t # the type held by the array
+ a.array_size 6 # the number of elements in the array
+end
+```
+
+## Variable Arrays
+
+Variable Arrays are arrays that have a maximum length, but may not be entirely
+utilized.
+
+```ruby
+# a way to represent some number of dates/times as 32-bit values
+variable_array(:datetimes) do |a|
+  a.size_type  :uint8_t # WILL BE DEPRECATED
+  a.array_type :int32_t
+  a.array_size 128
+end
+
+# a string, represented as `int_8`'s, with a maximum length of 32 bytes
+variable_array(:string_32) do |a|
+  a.size_type  :uint8_t # WILL BE DEPRECATED
+  a.array_type :int8_t
+  a.array_size 32
+end
+```
+
+## Composites
+
+Composites are very similar to C structures. They are collections of other
+types. Each field has a name and may correspond to any other defined type.
+
+```ruby
+composite(:person) do |c|
+  c.field :name, :string_32
+  c.field :age, :uint8_t
+  c.field :date_of_birth, :uint32_t
+end
+```
+
+## Groups
+
+Groups are similar to C unions with one major difference. Each group is
+comprised of a type tag and a union of the types the union is capable of
+representing. This is known as a tagged union.
+
+The tag is used to inform the user application what type the union is currently
+representing. The tag is a special enumeration that is automatically defined.
+
+```ruby
+group(:requests) do |g|
+  c.field :add_user, :add_user_request
+  c.field :get_user, :get_user_request
+  c.field :delete_user, :delete_user_request
+end
+
+group(:responses) do |g|
+  c.field :add_user, :add_user_response
+  c.field :get_user, :get_user_response
+  c.field :delete_user, :delete_user_response
+end
+```

data/Rakefile

@@ -0,0 +1,38 @@
+require 'tmpdir'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+task :default => :greatest
+
+desc "Run C tests"
+task :greatest do
+  Dir.mktmpdir do |d|
+    test_suite_path = File.join(d, "test_suite.c")
+    mk_test_suite_file(test_suite_path)
+
+    args = "-Wall -Wextra -Werror -Ic/test -Ic/src -I#{d}"
+    srcs = "c/src/cauterize.c c/test/test.c"
+    bin = File.join(d, "test.bin")
+    sh "gcc #{args} #{srcs} -o #{bin}"
+    sh bin
+  end
+end
+
+# Support Methods
+
+SUITE_ENTRY_TEMPLATE = "  RUN_TEST(%s);"
+
+def mk_test_suite_file(path)
+  test_files = Dir["c/test/*.c"]
+  suite_text = test_files.map do |test_file|
+    File.read(test_file).lines.map do |l|
+      m = l.match(/^TEST (?<sym>[^\(]+)\(\)/)
+      m ? m[:sym] : nil
+    end.compact
+  end.flatten.map {|t| SUITE_ENTRY_TEMPLATE % t}.join("\n") + "\n"
+
+  File.open(path, "wb") {|fh| fh.write(suite_text)}
+end

data/bin/cauterize

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+
+LIB_PATH = File.dirname(__FILE__) + "/../lib"
+C_PATH = File.dirname(__FILE__) + "/../c/src"
+
+$LOAD_PATH.unshift LIB_PATH
+
+require 'thor'
+require 'cauterize/cauterize'
+
+class CmdLineException < Exception; end
+
+class CauterizeCmdline < Thor
+  desc "generate [language] [target_dir] [[description file]]",
+       "Generate sources for [language] in [target_dir]."
+  method_option :omit_support, :type => :boolean,
+                               :desc => "Omit the support files needed by Cauterize",
+                               :default => false
+  method_option :force, :type => :boolean,
+                        :desc => "Bravely overwrite files in non-empty directories",
+                        :default => false
+  def generate(language, target_dir, desc_file = nil)
+    raise CmdLineException.new("Language '#{language}' is not supported.") unless language == 'c'
+
+    if not options[:force] and Dir.exist?(target_dir) and Dir[target_dir + "/*"].size > 0
+      raise CmdLineException.new("Directory '#{target_dir}' isn't empty. Cowardly quitting.")
+    end
+
+    desc_file ||= "Cauterize"
+
+    if not File.exist? desc_file
+      raise CmdLineException.new("The description file #{desc_file} does not exist.")
+    end
+
+    # Generate the C files.
+    Cauterize.generate_c(target_dir, desc_file)
+
+    # Copy the cauterize support files.
+    unless options[:omit_support]
+      Dir[C_PATH + "/*"].each do |path|
+        FileUtils.cp(path, target_dir)
+      end
+    end
+  end
+end
+
+begin
+  CauterizeCmdline.start
+rescue CmdLineException => ex
+  puts ex.message
+end
+
+# vim: set syntax=ruby ts=2 sw=2 et ai

data/c/src/cauterize.c

@@ -0,0 +1,74 @@
+#define CAUTERIZE_C
+
+#include "cauterize.h"
+#include "cauterize_debug.h"
+
+#include <string.h>
+
+#define S CAUTERIZE_STATUS_T
+#define T struct Cauterize
+
+S CauterizeInitAppend( struct Cauterize * m, uint8_t * buffer, size_t length)
+{
+  CA_ASSERT(NULL != m);
+  CA_ASSERT(NULL != buffer);
+
+  m->size = length;
+  m->used = 0;
+  m->pos = 0;
+  m->buffer = buffer;
+
+  return CA_OK;
+}
+
+S CauterizeInitRead( struct Cauterize * m, uint8_t * buffer, size_t used)
+{
+  CA_ASSERT(NULL != m);
+  CA_ASSERT(NULL != buffer);
+
+  m->size = used;
+  m->used = used;
+  m->pos = 0;
+  m->buffer = buffer;
+
+  return CA_OK;
+}
+
+S CauterizeAppend(T * m, uint8_t * src, size_t length)
+{
+  CA_ASSERT(NULL != m);
+  CA_ASSERT(NULL != src);
+
+  size_t needed = m->used + length;
+
+  if (needed > m->size)
+    return CA_ERR_NOT_ENOUGH_SPACE;
+
+  uint8_t * dest = &m->buffer[m->used];
+  memcpy(dest, src, length);
+  m->used += length;
+
+  return CA_OK;
+}
+
+S CauterizeRead(T * m, uint8_t * dst, size_t length)
+{
+  CA_ASSERT(NULL != m);
+  CA_ASSERT(NULL != dst);
+  CA_ASSERT(m->used >= m->pos);
+
+  size_t available = m->used - m->pos;
+
+  if (length > available)
+    return CA_ERR_NOT_ENOUGH_DATA;
+
+  uint8_t * src = &m->buffer[m->pos];
+  memcpy(dst, src, length);
+  m->pos += length;
+
+  return CA_OK;
+}
+
+#undef S
+#undef T
+#undef CAUTERIZE_C

data/c/src/cauterize.h

@@ -0,0 +1,46 @@
+#ifndef CAUTERIZE_H
+#define CAUTERIZE_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+typedef uint32_t CAUTERIZE_STATUS_T;
+
+#define CA_OK                    (0)
+#define CA_ERR_ASSERT            (1)
+#define CA_ERR_NOT_ENOUGH_SPACE  (2)
+#define CA_ERR_NOT_ENOUGH_DATA   (3)
+#define CA_ERR_INVALID_LENGTH    (4)
+#define CA_ERR_INVALUD_TYPE_TAG  (5)
+#define CA_ERR_GENERAL           (UINT32_MAX)
+
+struct Cauterize {
+  size_t size; // Size of the buffer in bytes
+  size_t used; // Number of used bytes in the buffer
+  size_t pos; // The next byte to be read
+  uint8_t * buffer; // Buffer to hold data
+};
+
+CAUTERIZE_STATUS_T CauterizeInitAppend(
+    struct Cauterize * m,
+    uint8_t * buffer,
+    size_t length);
+
+CAUTERIZE_STATUS_T CauterizeInitRead(
+    struct Cauterize * m,
+    uint8_t * buffer,
+    size_t used);
+
+CAUTERIZE_STATUS_T CauterizeAppend(
+    struct Cauterize * m,
+    uint8_t * src,
+    size_t length);
+
+CAUTERIZE_STATUS_T CauterizeRead(
+    struct Cauterize * m,
+    uint8_t * dst,
+    size_t length);
+
+#define CA_MAX(a,b) ((a) > (b) ? (a) : (b))
+
+#endif /* CAUTERIZE_H */

data/c/src/cauterize_debug.h

@@ -0,0 +1,29 @@
+#ifndef CAUTERIZE_DEBUG_H
+#define CAUTERIZE_DEBUG_H
+
+#ifndef CAUTERIZE_C
+  #error "You should not include cauterize_debug.h."
+#endif
+
+#ifndef NDEBUG
+
+#include <stdio.h>
+#define CA_ASSERT_PRINT(msg) \
+  fprintf(stderr, "ASSERT: %s (%s:%d)\n", msg, __FILE__, __LINE__);
+
+#define CA_ASSERT(cond) CA_ASSERTm(#cond, cond)
+#define CA_ASSERTm(msg, cond) \
+  do { \
+    if(!(cond)) { \
+      CA_ASSERT_PRINT(msg); \
+      return CA_ERR_ASSERT; \
+    } \
+  } while(0)
+
+#else
+
+#define CA_ASSERT(cond)
+
+#endif
+
+#endif /* CAUTERIZE_DEBUG_H */