cgen 0.16.0 → 0.16.1

data/.gitignore

@@ -3,3 +3,6 @@ pkg/*
 doc/*
 junk/*
 tmp/*
+tmp
+*/tmp
+*/junk

data/README.txt

@@ -1,34 +1,75 @@
+= Overview
 
-high level overview
+Ruby has a C interface for defining extensions to the language. Using this interface, you define functions in C and add them as methods that are callable from ruby code. You may also define classes, modules, globals, and so on.
 
-purpose and history
+CGen is a library that makes it relatively easy to code, build, and load extensions from within a ruby program, rather than using a typical C development process. In this way, the construction of the extension is driven by the ruby program. The extension is also available for execution from the program. CGen is a kind of "inline" tool. 
 
-getting started
+The CShadow module is for the special case of T_DATA objects, particularly those whose data is defined by a C struct. A class of such objects can be defined only through the ruby C API. Unlike normal ruby objects such as arrays and strings, a T_DATA object contains a "blob" of data that can only be accessed through methods defined in a C extension.
 
-- will need compiler
+Including the CShadow module in a class lets you define the structure of the data blob by using simple attribute declarations (no C code needed). CShadow uses these declarations to generate the essential functions: accessors with type conversion and checking, mark/free, marshal, yaml, and initialization. Additional methods can be defined in ruby or using CGenerator. CShadow also manages inheritance of the structure from parent class to child class; the child class may define further attributes.
 
-advanced
+See the CGenerator, CShadow, and CShadow::Attribute pages for details.
 
-==Object attributes
+= Purpose and history
 
-===class CShadow::ObjectAttribute
+The intended use of cgen is managing a complex library that may change from one run of the program to the next. The reason for the change might be that the program is written in a DSL (domain-specific language), and that the library functions are generated based on the statements of the DSL.
 
-===class CShadow::ShadowObjectAttribute
+In fact, the original use of cgen was to support a DSL for designing and simulating dynamic networks of hybrid automata.[RedShift, formerly hosted at redshift.sourceforge.net, now at http://rubyforge.org/projects/redshift]
 
+Cgen was introduced in 2001 with this post:
 
-examples
+http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/24443
 
-more docs
+= Getting started
 
+== Installing
 
-==web site
+Cgen is available from http://rubyforge.org/projects/cgen.
 
-==license
+Install either as gem:
 
-==author
-Copyright 2001-2009
-Joel VanderWerf,
-mailto:vjoel@users.sourceforge.net
+  gem install cgen
 
-http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/24443
+or from tarball, by unpacking and then:
+
+  ruby install.rb config
+  ruby install.rb setup
+  ruby install.rb install
+
+=== System Requirements
+
+Cgen is pure ruby, so you don't need a compiler to install it. However, you do need a C compiler to do anything useful with it.
+
+On Unix and GNU/Linux, the gcc compiler works fine. The Sun C compiler has also been tested.
+
+On Windows, you should use a compiler that is compatible with your ruby interpreter. The following compilers have been tested:
+
+* MSVC 6.0 (with the traditional one-click ruby installer--the OCI)
+* MSVC 2003
+* Mingw32 (gcc; the foundation of the new OCI by Luis Lavena)
+
+= Examples
+
+The cgen package comes with a substantial examples directory, but it is not yet very well organized. Here are the best ones to start with:
+
+sample.rb::
+  introduction to CGenerator
+
+complex.rb::
+  introduction to CShadow
+
+matrix.rb::
+  second example of CShadow
+
+= Web site
+
+http://rubyforge.org/projects/cgen
+http://cgen.rubyforge.org/
+
+= License
+
+Ruby license.
+
+= Author
 
+Copyright 2001-2009, Joel VanderWerf, mailto:vjoel@users.sourceforge.net.

data/examples/complex.rb

@@ -1,5 +1,3 @@
-#!/usr/bin/env ruby
-
 require 'cgen/cshadow'
 
 class MyComplex < Numeric

data/examples/complex2.rb

@@ -1,5 +1,3 @@
-#!/usr/bin/env ruby
-
 require 'cgen/cshadow'
 
 class MyComplex2 < Numeric

data/examples/matrix.rb

@@ -1,5 +1,3 @@
-#!/usr/bin/env ruby
-
 require 'cgen/cshadow'
 
 class MyMatrix

data/examples/sample.rb

@@ -1,27 +1,3 @@
-#!/usr/bin/env ruby
-
-=begin
-
-Sample for CGenerator.
-
-==version
-
-CGenerator 0.14
-
-The current version of this software can be found at 
-((<"http://redshift.sourceforge.net/cgen
-"|URL:http://redshift.sourceforge.net/cgen>)).
-
-==license
-This software is distributed under the Ruby license.
-See ((<"http://www.ruby-lang.org"|URL:http://www.ruby-lang.org>)).
-
-==author
-Joel VanderWerf,
-((<vjoel@users.sourceforge.net|URL:mailto:vjoel@users.sourceforge.net>))
-
-=end
-
 require 'cgen/cgen'
 require 'fileutils'
 

data/lib/cgen/attribute.rb

@@ -27,7 +27,7 @@ module CShadow
   #
   # The subclass hierarchy has two branches: ObjectAttribute and
   # CNativeAttribute. The former is a reference to a Ruby object (in other
-  # words, a struct member of type +VALUE+. The latter has subclasses for
+  # words, a struct member of type +VALUE+). The latter has subclasses for
   # various C data types, such as +double+ and <tt>char *</tt>.
   #
   # ==Adding new attribute classes

data/lib/cgen/cgen.rb

@@ -178,366 +178,6 @@ require 'cgen/inherit'
 # It is useful to keep a reference to +lib+ around to send define and declare
 # messages to.
 #
-# ===Templates
-#
-# All templates respond to #library and #file methods, which return the library
-# or file object which contains the template. (The library itself does not
-# respond to #file.) They also respond to #name and #parent.
-#
-# ===Library
-#
-# ---Library#use_work_dir dir_name
-#
-# Changes into +dir_name+, creating it first if necessary. Does nothing if
-# alread in a diredctory of that name. Often used with +"tmp"+.
-#
-# ---Library#commit
-#
-# Writes the files to disk, and makes and loads the library.
-#
-# Note that #commit must be called after all C code definitions for the library,
-# but before instantiation of any objects that use those definitions. If a
-# definition occurs after commit, or if instantiation occurs before commit, then
-# a CGenerator::Library::CommitError is raised, with an appropriate message.
-# Sometimes, this forces you to use many small libraries, each committed just in
-# time for use. See examples/fixed-array.rb.
-#
-# ---Library#committed?
-#
-# True if the library has been committed.
-#
-# ---Library#before_commit(&block)
-# ---Library#after_commit(&block)
-#
-# Schedules block to run before or after Library#commit. The before blocks are
-# run in the same order in which they were scheduled; the after blocks run in
-# the reverse order (analogously with +BEGIN+/+END+). Each block is evaluated in
-# the context in which it was created (instance_eval is *not* used), and it is
-# passed the library as an argument.
-#
-# ---Library#empty?
-#
-# True if no content has been added to the library.
-#
-# ---Library#add_file name
-#
-# Creates templates for two files, a source (.c) file and an include (.h) file
-# that will be generated in the same dir as the library. The base file name is
-# taken from the argument. Returns an array containing the include file template
-# and the source file template, in that order.
-#
-# Functions can be added to the source file by calling #define_method and
-# similar methods on the source file template. Their +rb_init+ calls are done in
-# #init_library_function in the main library source file. The new source file
-# automatically #includes the library's main header file, as well as its own
-# header file, and the library's main source file also #includes the new header
-# file. Declarations can be added to the header file by calling #declare on it,
-# but in many cases this is taken care of automatically.
-#
-# ---Library#extconf
-#
-# Override #extconf if you want to do more than just #create_makefile. Note that
-# #create_makefile recognizes all .c files in the library directory, and
-# generates a makefile that compiles them and links them into the dynamic
-# library.
-#
-# ---Library#write
-# ---Library#makedepend
-# ---Library#mkmf
-# ---Library#make arg = nil
-#
-# Internal methods called, in sequence, by #commit:
-#
-#   * #write       dumps each file template to disk, if needed
-#   * #makedepend  executes +makedepend+
-#   * #mkmf        calls Library#extconf
-#   * #make        executes the system's +make+ program.
-#
-# These methods can be overridden, but are more typically called directly. The
-# argument to #make is interpolated into the system call as a command line
-# argument to the +make+ program. If the argument is 'clean' or 'distclean' then
-# the make log is deleted; if the argument is 'distclean' then all .c and .h
-# files generated by #write are deleted (additional user-supplied .c and .h
-# files in the library dir are not affected).
-#
-# ---Library#update_file f, template
-#
-# Called by write on each .c and .h file to actually write +template+ to the
-# open file +f+. The default behavior is to compare the existing data with the
-# generated data, and leave the file untouched if nothing changed. Subclasses
-# may have more efficient ways of doing this. (For instance, check a version
-# indicator in the file on disk, perhaps stored using the file's preamble
-# accumulator. It is even possible to defer some entries in the template until
-# after this check has been made: code that only needs to be regenerated if some
-# specification has changed)
-#
-# ---Library#purge_source_dir
-# ---Library#purge_source_dir= flag
-#
-# Access the #purge_source_dir attribute of a library, which controls what
-# happens to .c, .h, and .o files in the source dir of the library that are not
-# among those generated as part of the library. If this is set to +:delete+,
-# then those files are deleted. Other true values cause the .c, .h, and .o files
-# to be renamed with the .hide extension. (Note that this makes it difficult to
-# keep manually written C files in the same dir.) False +flag+ values (the
-# default) cause CGen to leave the files untouched.
-#
-# Note that, regardless of this setting, #mkmf will construct a Makefile which
-# lists all .c files that are in the source dir. If you do not delete obsolete
-# files, they will be compiled into your library!
-#
-# ---Library#init_library_function
-#
-# Returns a Function template object; see below. This function is called when
-# the library is loaded. Method definitions put stuff here to register methods
-# with Ruby. Usually, there is no need to bother this guy directly. Use
-# Library#setup instead.
-#
-# ---Library#setup key => "statements", ...
-#
-# Inserts code in the #init_library_function, which is called when the library
-# is loaded. The +key+ is used for redundancy checking, as in the #declare
-# accumulators. Note that hashes are unordered, so constructs like
-#
-#    setup :x => "...", :y => "..."
-#
-# can result in unpredictable order. To avoid this, use several #setup calls.
-#
-# ---Library#source_file ---Library#include_file
-#
-# Returns the template for the main source or include file of the library.
-# Usually, there is no need to access these directly.
-#
-# ---Library#define_c_function name, type
-#
-# Defines a plain ol' C function. Returns a Function template (see below), or a
-# template of the specified +type+, if given.
-#
-# ---Library#define_c_method mod, name, subclass
-# ---Library#define_c_module_function mod, name, subclass
-# ---Library#define_c_global_function name, subclass
-# ---Library#define_c_singleton_method mod, name, subclass
-# ---Library#define_c_class_method mod, name, subclass
-#
-# Defines a function of the specified name and type in the given class/module
-# (or in the global scope), and returns the function template (often used with
-# #instance_eval to add arguments, code, etc.). The +subclass+ argument is
-# optional and allows the template to belong to a subclass of the function
-# template it would normally belong to.
-#
-# For example,
-#
-#   define_c_method String, "reverse"
-#
-# The arguments accepted by the method automatically include +self+. By default,
-# arguments are passed as individual C arguments, but the can be passed in a
-# Ruby or C array. The latter has the advantage of argument parsing (based on
-# rb_scan_args), defaults, and typechecking. See Method#c_array_args.
-# #define_c_class_method is just an alias for #define_c_singleton_method.
-#
-# ---Library#include "file1.h", "<file2.h>", ...
-#
-# Insert the include statement(s) at the top of the library's main .c file. For
-# convenience, <ruby.h> is included automatically, as is the header file of the
-# library itself.
-#
-# ---Library#declare :x => "int x", ... ---Library#declare_extern :x => "int x",
-# ...
-#
-# Puts the string in the declaration area of the .c or .h file, respectively.
-# The declaration area is before the function definitions, and after the
-# structure declarations.
-#
-# ---Library#declare_struct name, attributes=nil
-# ---Library#declare_extern_struct name, attributes=nil
-#
-# Returns a Structure template, which generates to a typedefed C struct in the
-# .c or .h file. The #declare method of this template is used to add members.
-#
-# ---Library#declare_class cl ---Library#declare_module mod
-# ---Library#declare_symbol sym
-#
-# Define a C variable which will be initialized to refer to the class, module,
-# or symbol. These accumulators return the name of the C variable which will be
-# generated and initialized to the ID of the symbol, and this return value can
-# be interpolated into C calls to the Ruby API. (The arguments are the actual
-# Ruby objects.) This is very useful in #rb_ivar_get/#rb_ivar_set calls, and it
-# avoids doing the lookup more than once:
-#
-#   ...
-#   declare :my_ivar => "VALUE my_ivar"
-#   body %{
-#     my_ivar = rb_ivar_get(shadow->self, #{declare_symbol :@my_ivar});
-#     rb_ivar_set(shadow->self, #{declare_symbol :@my_ivar}, Qnil);
-#   }
-#
-# The second declaration notices that the library already has a variable that
-# will be initialized to the ID of the symbol, and uses it.
-#
-# ---Library#literal_symbol sym
-#
-# Like Library#declare_symbol, but converts the ID to a VALUE at library
-# initialization time. Useful for looking up hash values keyed by symbol
-# objects, for example. +sym+ is a string or symbol.
-#
-# ---Library#show_times message
-#
-# If the attribute #show_times_flag is set to true, print the user and system
-# times (and child user and child system on some platforms) and real time for
-# each major step of the commit process. Display +message+.
-#
-# ===File
-#
-# File templates are managed by the Library, and most users do not need to
-# interact with them directly. They are structured into four sections: includes,
-# structure declarations, variable and function declarations, and function
-# definitions. Each source file automatically includes its corresponding header
-# file and the main header file for the library (which includes ruby.h). The
-# main source file for the library includes each additional header file.
-#
-# ---File#define_c_method
-# ---File#define_c_module_function
-# ---File#define_c_global_function
-# ---File#define_c_singleton_method
-#
-# As for the Library, but can be used on any source file within the library.
-# Used to break large projects up into many files.
-#
-# ---File#preamble
-#
-# An accumulator that wraps its input in C comments and places it at the head of
-# the source file.
-#
-# ===Function
-#
-# ---Funtion#scope :static ---Funtion#scope :extern ---Funtion#arguments 'int
-# x', 'double y', 'VALUE obj', ... ---Funtion#return_type 'void'
-#
-# These accumulators affect the prototype of the function, which will be placed
-# in the declaration section of either the .h or the .c file, depending on the
-# scope setting. The default scope is static. The default return type is 'void'.
-#
-# For the Method subclasses of Function, argument and return types can be
-# omitted, in which case they default to 'VALUE'.
-#
-# ---Funtion#declare :x => "static double x", ... ---Funtion#init "x = 0", ...
-# ---Funtion#setup 'x' => "x += 1", ... ---Funtion#body 'y = sin(x);
-# printf("%d\n", y)', ...
-#
-# These four accumulators determine the contents of the function between the
-# opening and closing braces. The #init code is executed once when the function
-# first runs; it's useful for initializing static data. The #setup code runs
-# each time the function is called, as does the #body. Distinguishing #setup
-# from #body is useful for two reasons: first, #setup is guaranteed to execute
-# before #body, and, second, one can avoid setting up the same variable twice,
-# because of the key.
-#
-# ---Funtion#returns "2*x"
-#
-# Specifies the string used in the final return statement of the function.
-# Subsequent uses of this method clobber the previous value. Alternately, one
-# can simply insert a "return" manually in the body.
-#
-# ===Method ===ModuleFunction ===GlobalFunction ===SingletonMethod
-#
-# These subclasses of the Function template are designed for coding Ruby
-# methods. The necessary registration (+rb_define_method+, etc.) is handled
-# automatically. Defaults are different from Function: +'VALUE self'+ is
-# automatically an argument, and argument and return types are assumed to be
-# +'VALUE'+ and can be omitted by the caller. The return value is +nil+ by
-# default.
-#
-# ---Method#arguments :arg1, :arg2, ...
-#
-# The default way of specifying arguments. Allows a fixed number of VALUE
-# arguments.
-#
-# ---Method#c_array_args argc_name = 'argc', argv_name = 'argv', &block
-# ---Method#rb_array_args args_name = 'args'
-#
-# Specifies that arguments are to be collected and passed in a C or Ruby array,
-# instead of individually (which is the default). In each case, the array of
-# actual arguments will be bound to a C parameter with the name specified. See
-# the Ruby API documentation for details.
-#
-# If a block is given to Method#c_array_args, it will be used to specify a call
-# to the API function +rb_scan_args+ and to declare the associated variables.
-# For example:
-#
-#   c_array_args('argc', 'argv') {
-#     required :arg0, :arg1
-#     optional :arg2, :arg3, :arg4
-#     rest     :rest
-#     block    :block
-#   }
-#
-# declares all the listed symbols as variables of type +VALUE+ in function
-# scope, and arranges for the following to be called in the #setup clause (i.e.,
-# before the #body):
-#
-#     rb_scan_args(argc, argv, "23*&", &arg0, &arg1, &arg2, &arg3, &arg4, &rest, &block);
-#
-# The <tt>'argc', 'argv'</tt> are the default values and are usually omitted.
-#
-# The lines in the block can occur in any order, and any line can be omitted.
-# However, only one line of each kind should be used. In addition, each optional
-# argument can be associated with a fragment of C code that will be executed to
-# assign it a default value, if needed. For example, one can add the following
-# lines to the above block:
-#
-#     default   :arg3 => "INT2NUM(7)",
-#               :arg4 => "INT2NUM(NUM2INT(arg2) + NUM2INT(arg3))"
-#
-# Otherwise, optional arguments are assigned nil.
-#
-# In this case, if +arg4+ is not provided by +argv+, then it is initialized
-# using the code given. If, in addition, +arg3+ is not provided, then it too is
-# initialized. These initializations happen in the #setup clause of the Function
-# template and are executed in the same order as the arguments are given in the
-# +optional+ line.
-#
-# Finally, argument types can be checked automatically:
-#
-#     typecheck :arg2 => Numeric, :arg3 => Numeric
-#
-# The value passed to the function must either be +nil+ or match the type. Note
-# that type checking happens *before* default assignment, so that default
-# calculation code can assume types are correct. No typechecking code is
-# generated if the type is Object.
-#
-# ===Structure
-#
-# ---Structure#declare :x => "int x"
-#
-# Adds the specified string to define a structure member.
-#
-# ===Utility functions
-#
-# ---CGenerator.make_c_name s
-#
-# Geenrates a unique C itentifier from the given Ruby identifier, which may
-# include +/[@$?!]/+, +'::'+, and even +'.'+. (Some special globals are not yet
-# supported: +$:+ and +$-I+, for example.)
-#
-# It is unique in the sense that distinct Ruby identifiers map to distinct C
-# identifiers. (Not completely checked. Might fail for some really obscure
-# cases.)
-#
-# ---String.tab n
-#
-# Tabs left or right by n chars, using spaces.
-#
-# ---String.tabto n
-#
-# The first non-empty line is adjusted to have n spaces before the first
-# nonspace. Additional lines are changed to preserve relative tabbing.
-#
-# ---String.taballto n
-#
-# Aligns each line to have n spaces before the first non-space.
-#
-# (These routines probably don't work well, if at all, with "hard" tabs.)
-#
 # ==Example
 #
 #   require 'cgen'
@@ -778,7 +418,7 @@ require 'cgen/inherit'
 # way that makes clear that the problem is really with commit.
 module CGenerator
 
-VERSION = '0.16.0'
+VERSION = '0.16.1'
 
 class Accumulator ## should be a mixin? "Cumulative"?
 
@@ -889,6 +529,9 @@ module KeyAccumulator
   end
 end
 
+# All templates respond to #library and #file methods, which return the library
+# or file object which contains the template. (The library itself does not
+# respond to #file.) They also respond to #name and #parent.
 class Template < Accumulator
 
   def initialize name = "", parent = nil, &block
@@ -926,9 +569,35 @@ class Library < Template
   
   class CommitError < RuntimeError; end
   
-  attr_reader :init_library_function, :include_file, :source_file
-  attr_accessor :purge_source_dir, :show_times_flag
+  # Returns a Function template object. This function is called when the library
+  # is loaded. Method definitions put stuff here to register methods with Ruby.
+  # Usually, there is no need to bother this guy directly. Use Library#setup
+  # instead.
+  attr_reader :init_library_function
   
+  # Returns the template for the main include file of the library.
+  # Usually, there is no need to access this directly.
+  attr_reader :include_file
+  
+  # Returns the template for the main source file of the library.
+  # Usually, there is no need to access this directly.
+  attr_reader :source_file
+  
+  attr_accessor :show_times_flag
+  
+  # The #purge_source_dir attribute controls what happens to .c, .h, and .o
+  # files in the source dir of the library that are not among those generated as
+  # part of the library. If this is set to +:delete+, then those files are
+  # deleted. Other true values cause the .c, .h, and .o files to be renamed with
+  # the .hide extension. (Note that this makes it difficult to keep manually
+  # written C files in the same dir.) False +flag+ values (the default) cause
+  # CGen to leave the files untouched.
+  #
+  # Note that, regardless of this setting, #mkmf will construct a Makefile which
+  # lists all .c files that are in the source dir. If you do not delete obsolete
+  # files, they will be compiled into your library!
+  attr_accessor :purge_source_dir
+
   def initialize name
     super name
     
@@ -960,6 +629,8 @@ class Library < Template
       ## a template which is not the parent
   end
   
+  # Changes into +dir_name+, creating it first if necessary. Does nothing if
+  # already in a directory of that name. Often used with +"tmp"+.
   def use_work_dir dir_name
     if File.basename(Dir.pwd) == dir_name
       yield
@@ -972,6 +643,19 @@ class Library < Template
     end
   end
 
+  # Creates templates for two files, a source (.c) file and an include (.h) file
+  # that will be generated in the same dir as the library. The base file name is
+  # taken from the argument. Returns an array containing the include file
+  # template and the source file template, in that order.
+  #
+  # Functions can be added to the source file by calling #define_method and
+  # similar methods on the source file template. Their +rb_init+ calls are done
+  # in
+  # #init_library_function in the main library source file. The new source file
+  # automatically #includes the library's main header file, as well as its own
+  # header file, and the library's main source file also #includes the new
+  # header file. Declarations can be added to the header file by calling
+  # #declare on it, but in many cases this is taken care of automatically.
   def add_file name, opts = {}
     pair = @pile.detect {|p| p[0].name == name + ".h"}
 
@@ -998,22 +682,42 @@ class Library < Template
     end
   end
   
+  # True if the library has been committed.
   def committed?
     @committed
   end
   
+  # True if no content has been added to the library.
   def empty?
     @init_library_function.empty?  ## is this enough?
   end
   
+  # Schedules block to run before Library#commit. The before blocks are run in
+  # the same order in which they were scheduled; the after blocks run in the
+  # reverse order (analogously with +BEGIN+/+END+). Each block is evaluated in
+  # the context in which it was created (instance_eval is *not* used), and it is
+  # passed the library as an argument.
   def before_commit(&block)
     (@before_commit ||= []) << block
   end
   
+  # Schedules block to run after Library#commit. The before blocks are run in
+  # the same order in which they were scheduled; the after blocks run in the
+  # reverse order (analogously with +BEGIN+/+END+). Each block is evaluated in
+  # the context in which it was created (instance_eval is *not* used), and it is
+  # passed the library as an argument.
   def after_commit(&block)
     (@after_commit ||= []) << block
   end
   
+  # Writes the files to disk, and makes and loads the library.
+  #
+  # Note that #commit must be called after all C code definitions for the
+  # library, but before instantiation of any objects that use those definitions.
+  # If a definition occurs after commit, or if instantiation occurs before
+  # commit, then a CGenerator::Library::CommitError is raised, with an
+  # appropriate message. Sometimes, this forces you to use many small libraries,
+  # each committed just in time for use. See examples/fixed-array.rb.
   def commit(build = true)
     assert_uncommitted
     
@@ -1042,10 +746,34 @@ class Library < Template
     end
   end
   
+  #----------------
+  # :section: Build methods
+  #
+  # Methods used during commit to control the build chain.
+  # In sequence, #commit calls these methods:
+  #
+  #   * #write       dumps each file template to disk, if needed
+  #   * #makedepend  executes +makedepend+
+  #   * #mkmf        calls Library#extconf
+  #   * #make        executes the system's +make+ program
+  #   * #loadlib     load the library that has been built
+  #
+  # These methods can be overridden, but are more typically called via commit or
+  # sometimes directly. The argument to #make is interpolated into the system
+  # call as a command line argument to the +make+ program. If the argument is
+  # 'clean' or 'distclean' then the make log is deleted; if the argument is
+  # 'distclean' then all .c and .h files generated by #write are deleted
+  # (additional user-supplied .c and .h files in the library dir are not
+  # affected).
+  #----------------
+  
   def process_times
     RUBY_VERSION.to_f >= 1.7 ? Process.times : Time.times
   end
 
+  # If the attribute #show_times_flag is set to true, print the user and system
+  # times (and child user and child system on some platforms) and real time for
+  # each major step of the commit process. Display +message+.
   def show_times message
     yield if block_given?
     if @show_times_flag
@@ -1094,6 +822,14 @@ class Library < Template
     end
   end
   
+  # Called by write on each .c and .h file to actually write +template+ to the
+  # open file +f+. The default behavior is to compare the existing data with the
+  # generated data, and leave the file untouched if nothing changed. Subclasses
+  # may have more efficient ways of doing this. (For instance, check a version
+  # indicator in the file on disk, perhaps stored using the file's preamble
+  # accumulator. It is even possible to defer some entries in the template until
+  # after this check has been made: code that only needs to be regenerated if
+  # some specification has changed)
   def update_file f, template
     template_str = template.to_s
     file_data = f.gets(nil) ## sysread is faster?
@@ -1256,6 +992,11 @@ class Library < Template
       ### this is fragile--should record abs path when Lib is created
   end
   
+  # Override #extconf if you want to do more than just #create_makefile. Note
+  # that #create_makefile recognizes all .c files in the library directory, and
+  # generates a makefile that compiles them and links them into the dynamic
+  # library.
+  #
   # Yields the array of lines being constructed so that additional configuration
   # can be added. See the ruby documentation on mkmf.
   def extconf # :yields: lines_array
@@ -1332,27 +1073,67 @@ class Library < Template
               :rb_define_global_function,
               :rb_define_singleton_method) {RbDefineAccumulator}
   
+  # call-seq:
+  #   define_c_method mod, name, subclass
+  #   define_c_module_function mod, name, subclass
+  #   define_c_global_function name, subclass
+  #   define_c_singleton_method mod, name, subclass
+  #   define_c_class_method mod, name, subclass
+  #
+  # Defines a function of the specified name and type in the given class/module
+  # (or in the global scope), and returns the function template (often used with
+  # #instance_eval to add arguments, code, etc.). The +subclass+ argument is
+  # optional and allows the template to belong to a subclass of the function
+  # template it would normally belong to.
+  #
+  # For example,
+  #
+  #   define_c_method String, "reverse"
+  #
+  # The arguments accepted by the method automatically include +self+. By
+  # default, arguments are passed as individual C arguments, but the can be
+  # passed in a Ruby or C array. The latter has the advantage of argument
+  # parsing (based on rb_scan_args), defaults, and typechecking. See
+  # Method#c_array_args. #define_c_class_method is just an alias for
+  # #define_c_singleton_method.
+  #
   def define_c_method(*args)
     @source_file.define_c_method(*args)
   end
   
+  # See #define_c_method.
   def define_c_module_function(*args)
     @source_file.define_c_module_function(*args)
   end
   
+  # See #define_c_method.
   def define_c_global_function(*args)
     @source_file.define_c_global_function(*args)
   end
   
+  # See #define_c_method.
   def define_c_singleton_method(*args)
     @source_file.define_c_singleton_method(*args)
   end
   alias define_c_class_method define_c_singleton_method
   
+  # call-seq:
+  #   include "file1.h", "<file2.h>", ...
+  #
+  # Insert the include statement(s) at the top of the library's main .c file.
+  # For convenience, <ruby.h> is included automatically, as is the header file
+  # of the library itself.
   def include(*args)
     @source_file.include(*args)
   end
   
+  # call-seq:
+  #   declare :x => "int x", ...
+  #   declare_extern :x => "int x", ...
+  #
+  # Puts the string in the declaration area of the .c or .h file, respectively.
+  # The declaration area is before the function definitions, and after the
+  # structure declarations.
   def declare(*args)
     @source_file.declare(*args)
   end
@@ -1362,20 +1143,53 @@ class Library < Template
     @include_file.declare(*args)
   end
   
+  # call-seq:
+  #   declare_struct name, attributes=nil
+  #   declare_extern_struct name, attributes=nil
+  #
+  # Returns a Structure template, which generates to a typedefed C struct in the
+  # .c or .h file. The #declare method of this template is used to add members.
   def declare_struct struct_name, *rest
     @source_file.declare_struct struct_name, *rest
   end
   alias declare_static_struct declare_struct
   
+  # See #declare_struct.
   def declare_extern_struct struct_name, *rest
     @include_file.declare_struct struct_name, *rest
   end
   
+  # call-seq:
+  #   define_c_function  
+  #
+  # Defines a plain ol' C function. Returns a Function template (see below), or
+  # a template of the specified +type+, if given.
   def define(*args)
     @source_file.define(*args)
   end
   alias define_c_function define
   
+  # call-seq:
+  #   declare_class cl
+  #   declare_module mod
+  #   declare_symbol sym
+  #
+  # Define a C variable which will be initialized to refer to the class, module,
+  # or symbol. These accumulators return the name of the C variable which will
+  # be generated and initialized to the ID of the symbol, and this return value
+  # can be interpolated into C calls to the Ruby API. (The arguments are the
+  # actual Ruby objects.) This is very useful in #rb_ivar_get/#rb_ivar_set
+  # calls, and it avoids doing the lookup more than once:
+  #
+  #   ...
+  #   declare :my_ivar => "VALUE my_ivar"
+  #   body %{
+  #     my_ivar = rb_ivar_get(shadow->self, #{declare_symbol :@my_ivar});
+  #     rb_ivar_set(shadow->self, #{declare_symbol :@my_ivar}, Qnil);
+  #   }
+  #
+  # The second declaration notices that the library already has a variable that
+  # will be initialized to the ID of the symbol, and uses it.
   def declare_module mod
     c_name = "module_#{CGenerator::make_c_name mod.to_s}"
     declare mod => "VALUE #{c_name}"
@@ -1385,6 +1199,7 @@ class Library < Template
   end
   alias declare_class declare_module
   
+  # See #declare_module.
   def declare_symbol sym
     c_name = "ID_#{CGenerator::make_c_name sym}"
     declare sym => "ID #{c_name}"
@@ -1393,6 +1208,9 @@ class Library < Template
     c_name.intern
   end
   
+  # Like Library#declare_symbol, but converts the ID to a VALUE at library
+  # initialization time. Useful for looking up hash values keyed by symbol
+  # objects, for example. +sym+ is a string or symbol.
   def literal_symbol sym
     c_name = "SYM_#{CGenerator::make_c_name sym}"
     declare sym => "VALUE #{c_name}"
@@ -1401,6 +1219,16 @@ class Library < Template
     c_name.intern
   end
   
+  # call-seq:
+  #   setup key => "statements", ...
+  #
+  # Inserts code in the #init_library_function, which is called when the library
+  # is loaded. The +key+ is used for redundancy checking, as in the #declare
+  # accumulators. Note that hashes are unordered, so constructs like
+  #
+  #    setup :x => "...", :y => "..."
+  #
+  # can result in unpredictable order. To avoid this, use several #setup calls.
   def setup(*args)
     @init_library_function.setup(*args)
   end
@@ -1472,6 +1300,15 @@ class CFragment < Template
 end # class CFragment
 
 
+# File templates are managed by the Library, and most users do not need to
+# interact with them directly. They are structured into four sections: includes,
+# structure declarations, variable and function declarations, and function
+# definitions. Each source file automatically includes its corresponding header
+# file and the main header file for the library (which includes ruby.h). The
+# main source file for the library includes each additional header file.
+#
+# The File#preamble accumulator wraps its input in C comments and places it at
+# the head of the source file.
 class CFile < CFragment
   
   attr_reader :include_file
@@ -1552,10 +1389,14 @@ class CFile < CFragment
   accumulator(:declare)        {StatementKeyAccumulator}
   accumulator(:define)         {FunctionAccumulator}
   
+  # As for the Library, but can be used on any source file within the library.
+  # Used to break large projects up into many files.
   def define_c_function c_name, subclass = Function
     define c_name, subclass
   end
   
+  # As for the Library, but can be used on any source file within the library.
+  # Used to break large projects up into many files.
   def define_c_method mod, name, subclass = Method
     unless subclass <= Method ## should use assert
       raise "#{subclass.name} is not <= Method"
@@ -1564,18 +1405,24 @@ class CFile < CFragment
     define c_name, subclass
   end
   
+  # As for the Library, but can be used on any source file within the library.
+  # Used to break large projects up into many files.
   def define_c_module_function mod, name, subclass = ModuleFunction
     raise unless subclass <= ModuleFunction
     c_name = library.rb_define_module_function :mod => mod, :rb_name => name
     define c_name, subclass
   end
   
+  # As for the Library, but can be used on any source file within the library.
+  # Used to break large projects up into many files.
   def define_c_global_function name, subclass = GlobalFunction
     raise unless subclass <= GlobalFunction
     c_name = library.rb_define_global_function :rb_name => name
     define c_name, subclass
   end
   
+  # As for the Library, but can be used on any source file within the library.
+  # Used to break large projects up into many files.
   def define_c_singleton_method mod, name, subclass = SingletonMethod
     raise unless subclass <= SingletonMethod
     c_name = library.rb_define_singleton_method :mod => mod, :rb_name => name
@@ -1583,7 +1430,6 @@ class CFile < CFragment
   end
   alias define_c_class_method define_c_singleton_method
   
-  # For ruby 1.7/1.8 after 20Dec2002
   def define_alloc_func klass
     klass_c_name = declare_class klass
     c_name = "alloc_func_#{klass_c_name}"
@@ -1657,6 +1503,121 @@ class Prototype < CFragment
   
 end # class Prototype
 
+# The Function class manages all kinds of functions and methods.
+#
+# === Function Prototype
+#
+#   scope :static
+#   scope :extern
+#   arguments 'int x', 'double y', 'VALUE obj', ... 
+#   return_type 'void'
+#
+# These accumulators affect the prototype of the function, which will be placed
+# in the declaration section of either the .h or the .c file, depending on the
+# scope setting. The default scope is static. The default return type is 'void'.
+#
+# For the Method subclasses of Function, argument and return types can be
+# omitted, in which case they default to 'VALUE'.
+#
+# === Function Body
+#
+#   declare :x => "static double x", ...
+#   init "x = 0", ...
+#   setup 'x' => "x += 1", ...
+#   body 'y = sin(x); printf("%d\n", y)', ...
+#
+# These four accumulators determine the contents of the function between the
+# opening and closing braces. The #init code is executed once when the function
+# first runs; it's useful for initializing static data. The #setup code runs
+# each time the function is called, as does the #body. Distinguishing #setup
+# from #body is useful for two reasons: first, #setup is guaranteed to execute
+# before #body, and, second, one can avoid setting up the same variable twice,
+# because of the key.
+#
+#   returns "2*x"
+#
+# Specifies the string used in the final return statement of the function.
+# Subsequent uses of this method clobber the previous value. Alternately, one
+# can simply insert a "return" manually in the body.
+#
+# === Method Classes
+#
+#   Method
+#   ModuleFunction
+#   GlobalFunction
+#   SingletonMethod
+#
+# These subclasses of the Function template are designed for coding
+# Ruby-callable methods in C. The necessary registration (+rb_define_method+,
+# etc.) is handled automatically. Defaults are different from Function: +'VALUE
+# self'+ is automatically an argument, and argument and return types are assumed
+# to be +'VALUE'+ and can be omitted by the caller. The return value is +nil+ by
+# default.
+#
+# === Method Arguments
+#
+# There are three ways to declare arguments, corresponding to the three ways
+# provided by the Ruby interpreter's C API.
+#
+#   arguments :arg1, :arg2, ...
+#
+# The default way of specifying arguments. Allows a fixed number of VALUE
+# arguments.
+#
+#   c_array_args argc_name = 'argc', argv_name = 'argv', &block
+#
+#   rb_array_args args_name = 'args'
+#
+# Specifies that arguments are to be collected and passed in a C or Ruby array,
+# instead of individually (which is the default). In each case, the array of
+# actual arguments will be bound to a C parameter with the name specified. See
+# the Ruby API documentation for details.
+#
+# If a block is given to Method#c_array_args, it will be used to specify a call
+# to the API function +rb_scan_args+ and to declare the associated variables.
+# For example:
+#
+#   c_array_args('argc', 'argv') {
+#     required :arg0, :arg1
+#     optional :arg2, :arg3, :arg4
+#     rest     :rest
+#     block    :block
+#   }
+#
+# declares all the listed symbols as variables of type +VALUE+ in function
+# scope, and arranges for the following to be called in the #setup clause (i.e.,
+# before the #body):
+#
+#   rb_scan_args(argc, argv, "23*&", &arg0, &arg1, &arg2,
+#                &arg3, &arg4, &rest, &block);
+#
+# The <tt>'argc', 'argv'</tt> are the default values and are usually omitted.
+#
+# The lines in the block can occur in any order, and any line can be omitted.
+# However, only one line of each kind should be used. In addition, each optional
+# argument can be associated with a fragment of C code that will be executed to
+# assign it a default value, if needed. For example, one can add the following
+# lines to the above block:
+#
+#     default   :arg3 => "INT2NUM(7)",
+#               :arg4 => "INT2NUM(NUM2INT(arg2) + NUM2INT(arg3))"
+#
+# Otherwise, optional arguments are assigned nil.
+#
+# In this case, if +arg4+ is not provided by +argv+, then it is initialized
+# using the code given. If, in addition, +arg3+ is not provided, then it too is
+# initialized. These initializations happen in the #setup clause of the Function
+# template and are executed in the same order as the arguments are given in the
+# +optional+ line.
+#
+# Finally, argument types can be checked automatically:
+#
+#     typecheck :arg2 => Numeric, :arg3 => Numeric
+#
+# The value passed to the function must either be +nil+ or match the type. Note
+# that type checking happens *before* default assignment, so that default
+# calculation code can assume types are correct. No typechecking code is
+# generated if the type is Object.
 class Function < CFragment
 
   def initialize name, parent
@@ -1932,7 +1893,11 @@ class SingletonMethod < RubyFunction
   end
 end
 
-
+# A Structure instance keeps track of data members added to a struct.
+#
+#   declare :x => "int x"
+#
+# Adds the specified string to define a structure member.
 class Structure < CFragment
 
   class InheritAccumulator < Accumulator; include SetAccumulator; end
@@ -1964,6 +1929,13 @@ OpName= {
   '=='  => :op_eqeq
 }
 
+# Generates a unique C itentifier from the given Ruby identifier, which may
+# include +/[@$?!]/+, +'::'+, and even +'.'+. (Some special globals are not yet
+# supported: +$:+ and +$-I+, for example.)
+#
+# It is unique in the sense that distinct Ruby identifiers map to distinct C
+# identifiers. (Not completely checked. Might fail for some really obscure
+# cases.)
 def CGenerator.make_c_name s
   s = s.to_s
   OpName[s] || translate_ruby_identifier(s)
@@ -2014,7 +1986,7 @@ end # module CGenerator
 
 class String
 
-  # tabs left or right by n chars, using spaces
+  # Tabs left or right by n chars, using spaces.
   def tab n
     if n >= 0
       gsub(/^/, ' ' * n)
@@ -2023,8 +1995,8 @@ class String
     end
   end
   
-  # preserves relative tabbing
-  # the first non-empty line ends up with n spaces before nonspace
+  # The first non-empty line is adjusted to have n spaces before the first
+  # nonspace. Additional lines are changed to preserve relative tabbing.
   def tabto n
     if self =~ /^( *)\S/
       tab(n - $1.length)
@@ -2033,7 +2005,7 @@ class String
     end
   end
   
-  # aligns each line
+  # Aligns each line to have n spaces before the first non-space.
   def taballto n
     gsub(/^ */, ' ' * n)
   end

data/lib/cgen/cshadow.rb

@@ -712,7 +712,6 @@ module CShadow
 
   private
   
-    # :stopdoc:
     def check_overwrite_shadow_attrs(*symbols)
       for attr in shadow_attrs
         for sym in symbols
@@ -737,20 +736,19 @@ module CShadow
       check_overwrite_shadow_attrs(*args)
       super
     end
-    # :startdoc:
 
     # Same as #shadow_attr with the +:reader+ and +:writer+ options.
-    def shadow_attr_accessor(*args)
+    def shadow_attr_accessor(*args) # :doc:
       shadow_attr :reader, :writer, *args
     end
 
     # Same as #shadow_attr with the +:reader+ option.
-    def shadow_attr_reader(*args)
+    def shadow_attr_reader(*args) # :doc:
       shadow_attr :reader, *args
     end
 
     # Same as #shadow_attr with the +:writer+ option.
-    def shadow_attr_writer(*args)
+    def shadow_attr_writer(*args) # :doc:
       shadow_attr :writer, *args
     end
 
@@ -783,7 +781,7 @@ module CShadow
     #
     # Typically, #shadow_attr_accessor and so on are called instead.
     #
-    def shadow_attr(*args)
+    def shadow_attr(*args) # :doc:
       attr_persists = true
       for arg in args
         case arg

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: cgen
 version: !ruby/object:Gem::Version 
-  version: 0.16.0
+  version: 0.16.1
 platform: ruby
 authors: 
 - Joel VanderWerf