modalfields 1.1.1

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,15 @@
+source "http://rubygems.org"
+gem "activesupport", ">= 2.3.5"
+gem "activerecord", ">= 2.3.5"
+# gem "rails", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "rdoc", "~> 3.12"
+  gem "bundler", "~> 1"
+  gem "jeweler", "~> 1.8.3"
+  gem "sqlite3"
+  gem "pg"
+end

data/Gemfile.lock

@@ -0,0 +1,43 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activerecord (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      arel (~> 2.0.2)
+      tzinfo (~> 0.3.23)
+    activesupport (3.0.3)
+    arel (2.0.4)
+    builder (2.1.2)
+    git (1.2.5)
+    i18n (0.4.2)
+    jeweler (1.8.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.6.6)
+    pg (0.10.1)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    shoulda (2.10.3)
+    sqlite3 (1.3.3)
+    tzinfo (0.3.23)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (>= 2.3.5)
+  activesupport (>= 2.3.5)
+  bundler (~> 1)
+  jeweler (~> 1.8.3)
+  pg
+  rdoc (~> 3.12)
+  shoulda
+  sqlite3

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Javier Goizueta
+
+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.rdoc

@@ -0,0 +1,133 @@
+= ModalFields
+
+This is a Rails Plugin to maintain schema information in the models' definitions.
+It is a hybrid between HoboFields and model annotators.
+
+It works like other annotators, by adding documentation to the model classes
+from the DB schema. But the annotations are syntactic Ruby as in HoboFields rather than comments:
+
+  class User < ActiveRecord::Base
+    fields do
+      name :string
+      birthdate :date
+    end
+  end
+
+Apart from looking prettier to my eyes, this allows triggering special functionality
+from the field declarations (such as specifying validations).
+
+Fields that are foreign_keys of belongs_to associations are not annotated; it is assumed that
+belongs_to and other associations follow the fields block declaration, so the information
+is readily available.
+
+Primary keys named are also not annotated (unless the ModalFields.show_primary_keys property is changed)
+
+The annotations are kept up to date by the migration tasks (currently only if the plugin is installed under vendor)
+Comments and validation, etc. specifications modified manually are preserved, at least
+if the field block syntax is kept as generated (one line per field, one line for the
+block start and end...)
+
+Custom type fields and hooks can be define in files (e.g. fields.rb) in config/initializers/
+
+== Rake Tasks
+
+There's a couple of Rake tasks:
+* fields:update is what's called after a migration; it updates the fields blocks in the model class definitions.
+* fields:check shows the difference between the declared fields and the DB schema (what would be modified by fields:update)
+
+Under Rails 2, you need to add this to your Rakefile to make the tasks available:
+
+  require 'modalfields/tasks'
+
+== Some customization examples:
+
+  ModalFields.hook do
+
+    # Declare serialized fields as
+    #  field_name :serialized, :class=>Array
+    # another option would be: (using the generic hook)
+    #  field_name :text, :serialize=>Array
+    serialized do |model, declaration|
+      model.serialize declaration.name, declaration.attributes[:class].class || Object
+      declaration.replace!(:type=>:text).remove_attributes!(:class)
+    end
+
+    # Add specific support for date fields (_ui virtual attributes)
+    date do |model, declaration|
+      model.date_ui declaration.name
+    end
+
+    # Add specific support for date and datetime and detect fields with units
+    all_fields do |model, declaration|
+      date_ui name if [:date, :datetime].include?(declaration.type)
+      if ModalSupport::Units.valid_units?(units = declaration.name.to_s.split('_').last)
+        prec = {'m'=>1, 'mm'=>0, 'cm'=>0, 'km'=>3}[units] || 0
+        magnitude_ui name, prec, units
+      end
+    end
+
+  end
+
+  # Spatial Adapter columns: require specific column to declaration conversion and field types
+
+  ModalFields.column_to_field_declaration do |column|
+    type = column.type.to_sym
+    type = column.geometry_type if type==:geometry
+    attributes = {}
+    attrs = ModalFields.definitions[type]
+    attrs.keys.each do |attr|
+      v = column.send(attr)
+      attributes[attr] = v unless attrs[attr]==v
+    end
+    ModalFields::FieldDeclaration.new(column.name.to_sym, type, [], attributes)
+  end
+
+  ModalFields.define do
+    point               :srid=>nil, :with_z=>false, :with_m=>false, :sql_type=>'POINT'
+    line_string         :srid=>nil, :with_z=>false, :with_m=>false, :sql_type=>'LINESTRING'
+    polygon             :srid=>nil, :with_z=>false, :with_m=>false, :sql_type=>'POLYGON'
+    geometry_collection :srid=>nil, :with_z=>false, :with_m=>false, :sql_type=>'GEOMETRYCOLLECTION'
+    multi_point         :srid=>nil, :with_z=>false, :with_m=>false, :sql_type=>'MULTIPOINT'
+    multi_line_string   :srid=>nil, :with_z=>false, :with_m=>false, :sql_type=>'MULTILINESTRING'
+    multi_polygon       :srid=>nil, :with_z=>false, :with_m=>false, :sql_type=>'MULTIPOLYGON'
+    geometry            :srid=>nil, :with_z=>false, :with_m=>false, :sql_type=>nil
+  end
+
+  ModalFields.hook do
+    %w{point line_string polygon geometry_collection multi_point multi_line_string multi_polygon}.each do |spatial_type|
+      field_type spatial_type.to_sym do |model, declaration|
+        declaration.replace!(:type=>:geometry).add!(:sql_type=>spatial_type.upcase.tr('_',''))
+      end
+    end
+  end
+
+
+  # Enumerated field with symbolic constants associated (and translated literals) using the enum_id plugin
+  # Use:
+  #   enum :name, :values=>{id1=>:first_symbol, id2=>:second_symbol, ...}
+  # Or: (ids are sequential values starting in 1)
+  #  enum :name, :values=>[:first_symbol, :second_symbol, ...]
+  ModalFields.hook do
+    enum do |model, declaration|
+      values = declaration.attributes[:values]
+      if values.kind_of?(Array)
+        values = (1..values.size).map_hash{|i| values[i-1]}
+      end
+      model.enum_id declaration.name, values
+      declaration.replace! :type=>:integer, :name=>"#{declaration.name}_id"
+    end
+
+    class ModalFields::Declaration
+      def enum(*values)
+        values = values.first if values.size==1 && values.first.kind_of?(Hash)
+        {:values=>values}
+      end
+    end
+  end
+
+
+== Copyright
+
+Copyright (c) 2011 Javier Goizueta. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "modalfields"
+  gem.homepage = "http://github.com/jgoizueta/modalfields"
+  gem.license = "MIT"
+  gem.summary = %Q{Model annotator with Ruby (Hobo-like) syntax and hooks.}
+  gem.description = %Q{ModelFields is a Rails plugin that adds fields declarations to your models.}
+  gem.email = "jgoizueta@gmail.com"
+  gem.authors = ["Javier Goizueta"]
+  gem.add_runtime_dependency 'rails', '>= 2.3.0'
+
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "modalfields #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO

@@ -0,0 +1,33 @@
+type synonyms (timestamp, datetime)
+
+process specifiers (to add validations for required, etc.)(detect index modifications) decide what to do with multiple-column indices
+
+refactor into multiple files
+
+add extensible specifiers:
+  ModalFields.specify do
+    required do |model, column|
+       model.validates_presence_of column.name
+    end
+    unique do |model, column|
+      model.validates_uniqueness_of name, :allow_nil => !column.specifiers.include?(:required)
+    end
+  end
+
+rename hook to... filter? process? declared?  transformation?
+
+complete field declaration validation
+
+helper methods for field declaration: (can be used instead of the type and dispense with the need
+of extra attributes)
+  status enum_field(:draft, :approved, :published), :required
+instead of
+  status :enum_field, :required, :values=>[:draft, :approved, :published]
+
+Vendorized Installation:
+  Rails 2
+  script/plugin install git://github.com/jgoizueta/modalfields.git
+  Rails 3
+  rails plugin install git://github.com/jgoizueta/modalfields.git
+
+

data/VERSION

@@ -0,0 +1 @@
+1.1.1

data/lib/modalfields.rb

@@ -0,0 +1,13 @@
+require 'modalfields/modalfields'
+require 'modalfields/standardfields'
+
+if defined?(Rails)
+  if Rails.version.split('.').first.to_i > 2
+    class BackupTask < Rails::Railtie
+      rake_tasks do
+        Dir[File.join(File.dirname(__FILE__), 'tasks', '**/*.rake')].each { |f| load f }
+      end
+    end
+  end
+  ModalFields.enable if defined?(ActiveRecord::Base)
+end

data/lib/modalfields/modalfields.rb

@@ -0,0 +1,428 @@
+# This is a hybrid between HoboFields and model annotators.
+#
+# It works like other annotators, by updating the model annotations from the DB schema.
+# But the annotations are syntactic Ruby as in HoboFields rather than comments.
+#
+# Apart from looking better to my eyes, this allows triggering special functionality
+# from the field declations (such as specifying validations).
+#
+# The annotations are kept up to date by the migration tasks.
+# Comments and validation, etc. specifications modified manually are preserved, at least
+# if the field block syntax is kept as generated (one line per field, one line for the
+# block start and end...)
+#
+# Custom type fields and hooks can be define in files (e.g. fields.rb) in config/initializers/
+#
+module ModalFields
+
+  SPECIFIERS = [:indexed, :unique, :required]
+  COMMON_ATTRIBUTES = {:default=>nil, :null=>true}
+
+  class FieldDeclaration < Struct.new(:name, :type, :specifiers, :attributes)
+
+    def self.declare(name, type, *args)
+      attributes = args.extract_options!
+      new(name, type, args, attributes)
+    end
+
+    def replace!(replacements={})
+      replacements.each_pair do |key, value|
+        self[key] = value
+      end
+      self
+    end
+
+    def remove_attributes!(*attrs)
+      self.attributes = self.attributes.except(*attrs)
+      self
+    end
+
+    def add!(attrs)
+      self.attributes.merge! attrs
+      self
+    end
+
+    def to_s
+      code = "#{name} :#{type}"
+      code << ", "+specifiers.inspect[1...-1] unless specifiers.empty?
+      unless attributes.empty?
+        code << ", "+attributes.keys.sort_by{|attr| attr.to_s}.map{|attr|
+          v = attributes[attr]
+          v = v.kind_of?(BigDecimal) ? "BigDecimal('#{v.to_s}')" : v.inspect
+          ":#{attr}=>#{v}"
+        }*", "
+      end
+      code
+    end
+
+  end
+
+
+  class DefinitionsDsl
+    def field(name, attributes={})
+      ModalFields.definitions[name.to_sym] = COMMON_ATTRIBUTES.merge(attributes)
+    end
+    def method_missing(name, *args)
+      field(name, *args)
+    end
+  end
+
+  class HooksDsl
+    def field_type(type, &blk)
+      ModalFields.hooks[type.to_sym] = lambda{|model, column_declaration|
+        blk[model, column_declaration]
+      }
+    end
+    # geric filter applied to all the fields (after a specific filter for the type, if there is one)
+    def all_fields(&blk)
+      field_type :all_fields, &blk
+    end
+    def method_missing(name, *args, &blk)
+      field_type name, *args, &blk
+    end
+  end
+
+  class DeclarationsDsl
+    def initialize(model)
+      @model = model
+    end
+    def field(name, type, *args)
+      declaration = FieldDeclaration.declare(name, type, *args)
+      specific_hook = ModalFields.hooks[type.to_sym]
+      general_hook = ModalFields.hooks[:all_fields]
+      [specific_hook, general_hook].compact.each do |hook|
+        hook[@model, declaration] if hook
+      end
+      if ModalFields.validate(declaration)
+        @model.fields_info << declaration
+      end
+    end
+    def timestamps
+      field :created_at, :datetime
+      field :updated_at, :datetime
+    end
+    def method_missing(name, type, *args)
+      field(name, type, *args)
+    end
+  end
+
+  module FieldDeclarationClassMethods
+    def fields(&blk)
+      @fields_info ||= []
+      unless self.respond_to?(:fields_info)
+        self.instance_eval do
+          def fields_info
+            @fields_info
+          end
+        end
+      end
+      DeclarationsDsl.new(self).instance_eval(&blk)
+    end
+  end
+
+  @show_primary_keys = false
+  @hooks = {}
+  @definitions = {}
+  @column_to_field_declaration_hook = nil
+
+  class <<self
+    attr_reader :hooks, :definitions
+    # Define declaration of primary keys
+    #   ModalFields.show_primary_keys = false # the default: do not show primary keys
+    #   ModalFields.show_primary_keys = true  # always declare primary keys
+    #   ModalFields.show_primary_keys = :id   # only declare if named 'id' (otherwise the model will have a primary_key declaration)
+    #   ModalFields.show_primary_keys = :except_id   # only declare if named differently from 'id'
+    attr_accessor :show_primary_keys
+
+    # Run a definition block that executes field type definitions
+    def define(&blk)
+      DefinitionsDsl.new.instance_eval(&blk)
+    end
+
+    # Run a hooks block that defines field declaration processors
+    def hook(&blk)
+      HooksDsl.new.instance_eval(&blk)
+    end
+
+    # Define a custom column to field declaration conversion
+    def column_to_field_declaration(&blk)
+      @column_to_field_declaration_hook = blk
+    end
+
+    # Enable the ModalFields plugin (adds the fields declarator to model classes)
+    def enable
+      if defined?(::Rails)
+        # class ::ActiveRecord::Base
+        #   extend FieldDeclarationClassMethods
+        # end
+        ::ActiveRecord::Base.send :extend, FieldDeclarationClassMethods
+      end
+    end
+
+    # Update the field declarations of all the models.
+    # This modifies the source files of all the models (touches only the fields block or adds one if not present).
+    # It is recommended to run this on a clearn working directory (no uncommitted changes), so that the
+    # changes can be easily reviewed.
+    def update(modify=true)
+      dbmodels.each do |model, file|
+        new_fields, modified_fields, deleted_fields = diff(model)
+        unless new_fields.empty? && modified_fields.empty? && deleted_fields.empty?
+          pre, start_fields, fields, end_fields, post = split_model_file(file)
+          deleted_names = deleted_fields.map{|f| f.name.to_s}
+          fields = fields.reject{|line, name, comment| deleted_names.include?(name)}
+          fields = fields.map{|line, name, comment|
+            mod_field = modified_fields.detect{|f| f.name.to_s==name}
+            if mod_field
+              line = "    "+mod_field.to_s
+              line << " #{comment}" if comment
+              line << "\n"
+            end
+            [line, name, comment]
+          }
+          pk_names = Array(model.primary_key).map(&:to_s)
+          created_at = new_fields.detect{|f| f.name.to_s=='created_at'}
+          updated_at = new_fields.detect{|f| f.name.to_s=='updated_at'}
+          if created_at && updated_at && created_at.type.to_sym==:datetime && updated_at.type.to_sym==:datetime
+            with_timestamps = true
+            new_fields -= [created_at, updated_at]
+          end
+          fields += new_fields.map{|f|
+            comments = pk_names.include?(f.name.to_s) ? " \# PK" : ""
+            ["    #{f}#{comments}\n" ]
+          }
+          fields << ["    timestamps\n"] if with_timestamps
+          output_file = modify ? file : "#{file}_with_fields.rb"
+          join_model_file(output_file, pre, start_fields, fields, end_fields, post)
+        end
+      end
+    end
+
+    def check
+      dbmodels.each do |model, file|
+        new_fields, modified_fields, deleted_fields = diff(model)
+        unless new_fields.empty? && modified_fields.empty? && deleted_fields.empty?
+          rel_file = file.sub(/\A#{Rails.root}/,'')
+          puts "#{model} (#{rel_file}):"
+          [['+',new_fields],['*',modified_fields],['-',deleted_fields]].each do |prefix, fields|
+            puts fields.map{|field| "  #{prefix} #{field}"}*"\n" unless fields.empty?
+            # TODO: report index differences
+          end
+          puts ""
+        end
+      end
+    end
+
+    def validate(declaration)
+      definition = definitions[declaration.type.to_sym]
+      raise "Field type #{declaration.type} not defined" unless definition
+      # TODO: validate declaration.specifiers
+      # TODO: validate declaration.attributes with definition
+      true
+    end
+
+    private
+
+      # return ActiveRecord classes corresponding to tables, without STI derived classes, but including indirectly
+      # derived classes that do have their own tables (to achieve this we use the convention that in such cases
+      # the base class, directly derived from ActiveRecord::Base has a nil table_name)
+      def dbmodels
+        models = Dir.glob(File.join(Rails.root,"app/models/**/*.rb"))\
+                   .map{|f| [File.basename(f).chomp(".rb").camelize.constantize, f]}\
+                   .select{|c,f| has_table(c)}\
+                   .reject{|c,f| has_table(c.superclass)}
+        models.uniq
+      end
+
+      def has_table(cls)
+        (cls!=ActiveRecord::Base) && cls.respond_to?(:table_name) && !cls.table_name.blank?
+      end
+
+      def map_column_to_field_declaration(column)
+        if @column_to_field_declaration_hook
+          @column_to_field_declaration_hook[column]
+        else
+          type = column.type.to_sym
+          attributes = {}
+          attrs = definitions[type]
+          attrs.keys.each do |attr|
+            v = column.send(attr)
+            attributes[attr] = v unless attrs[attr]==v
+          end
+          FieldDeclaration.new(column.name.to_sym, type, [], attributes)
+        end
+      end
+
+      # Compare the declared fields of a model (in the fields block) to the actual model columns (in the schema).
+      # returns the difference as [new_fields, modified_fields, deleted_fields]
+      # where:
+      # * new_fields are field declarations not present in the model (corresponding to model columns not declared
+      #   in the fields declaration block).
+      # * modified_fields are field declarations corresponding to model columns that are different from their existing
+      #   declarations.
+      # * deleted_fields are fields declared in the fields block but not present in the current schema.
+      def diff(model)
+        # model.columns will fail if the table does not exist
+        existing_fields = model.columns rescue []
+        association_fields = model.reflect_on_all_associations(:belongs_to).map(&:primary_key_name).flatten.map(&:to_s)
+        pk_fields = Array(model.primary_key).map(&:to_s)
+        case show_primary_keys
+        when true
+          pk_fields = []
+        when :id
+          pk_fields = pk_fields.reject{|pk| pk=='id'}
+        when :except_id
+          pk_fields = pk_fields.select{|pk| pk=='id'}
+        end
+        if model.respond_to?(:fields_info)
+          declared_fields = model.fields_info
+          indices = model.connection.indexes(model.table_name) # name, columns, unique, spatial
+
+          existing_declared_fields = []
+          existing_undeclared_fields = []
+          existing_fields.each do |f|
+            name = f.name.to_s
+            if declared_fields.detect{|df| df.name.to_s==name} || association_fields.include?(name) || pk_fields.include?(name)
+              existing_declared_fields << f
+            else
+              existing_undeclared_fields << f
+            end
+          end
+          deleted_fields = declared_fields.reject{|f|
+            name = f.name.to_s
+            existing_declared_fields.detect{|df| df.name.to_s==name}
+          }
+          modified_fields = (declared_fields - deleted_fields).map{ |field_declaration|
+            column = existing_declared_fields.detect{|f| f.name.to_s == field_declaration.name.to_s}
+            identical = false
+            column = map_column_to_field_declaration(column)
+            if field_declaration.type.to_sym == column.type.to_sym
+              attrs = definitions[column.type.to_sym]
+              attr_keys = attrs.keys
+              decl_attrs = attr_keys.map{|a|
+                v = field_declaration.attributes[a]
+                v==attrs[a] ? nil : v
+              }
+              col_attrs = attr_keys.map{|a|
+                v = column.attributes[a]
+                v==attrs[a] ? nil : v
+              }
+              if decl_attrs == col_attrs
+                identical=true
+                # specifiers are defined only in declarations
+              end
+            end
+            column.specifiers = field_declaration.specifiers
+            identical ? nil : column
+          }.compact
+        else
+          modified_fields = deleted_fields = []
+          existing_undeclared_fields = existing_fields.reject{|f|
+            name = f.name.to_s
+            association_fields.include?(name) || pk_fields.include?(name)
+          }
+        end
+        new_fields = existing_undeclared_fields.map { |f|
+          attributes = {}
+          attrs = definitions[f.type.to_sym]
+          attrs.keys.each do |attr|
+            v = f.send(attr)
+            attributes[attr] = v unless attrs[attr]==v
+          end
+          FieldDeclaration.new(f.name.to_sym, f.type.to_sym, [], attributes)
+        }
+        [new_fields, modified_fields, deleted_fields]
+      end
+
+      # Break up the lines of a model definition file into sections delimited by the fields declaration.
+      # An empty fields declaration is added to the result if none is present in the file.
+      # The split result is an array with these elements:
+      # * pre: array of lines before the fields declaration
+      # * start_fields: line which opens the fields block
+      # * fields: array of triplets [line, name, comment] with the lines inside th fields block.
+      #   Name is the name of the field defined in the line, if any and comment is a comment including in the line;
+      #   both name and comment may be absent.
+      # * end_fields: line which closes the fields declaration
+      # * post: array of lines after the fields block
+      # All the lines include a trailing end-of-line separator.
+      def split_model_file(file)
+        code = File.read(file)
+        pre = []
+        start_fields = nil
+        fields = []
+        end_fields = nil
+        post = []
+        state = :pre
+        line_no = 0
+        field_block_end = nil
+        code.each_line do |line|
+          # line.chomp!
+          line_no += 1
+          case state
+          when :pre
+            if line =~ /^\s*fields\s+do(?:\s(.+))?$/
+              field_block_end = /^\s*end(?:\s(.+))?$/
+              start_fields = line
+              state = :fields
+            elsif line =~ /^\s*fields\s+\{(?:\s(.+))?$/
+              field_block_end = /^\s*\}(?:\s(.+))?$/
+              start_fields = line
+              state = :fields
+            else
+              pre << line
+            end
+          when :fields
+            if line =~ field_block_end
+              end_fields = line
+              state = :post
+            else
+              if line =~ /^\s*field\s+:(\w+).+?(#.+)?$/
+                name = $1
+                comment = $2
+              elsif line =~ /^\s*field\s+['"](.+?)['"].+?(#.+)?$/
+                name = $1
+                comment = $2
+              elsif line =~ /^\s*(\w+).+?(#.+)?$/
+                name = $1
+                comment = $2
+              else
+                name = comment = nil
+              end
+              fields << [line, name, comment]
+            end
+          when :post
+            post << line
+          end
+        end
+        if !start_fields
+          i = 0
+          (0...pre.size).each do |i|
+            break if pre[i] =~ /^\s*class\b/
+          end
+          raise "Model declaration not found in #{file}" unless i<pre.size
+          post = pre[i+1..-1]
+          pre = pre[0..i]
+          pre << "\n"
+          start_fields = "  fields do\n"
+          end_fields = "  end\n"
+          post.unshift "\n" unless post.first.strip.empty?
+          fields = []
+        end
+        [pre,start_fields,fields,end_fields,post]
+      end
+
+      # Write a model definition file from its broken up parts
+      def join_model_file(output_file, pre, start_fields, fields, end_fields, post)
+        File.open(output_file,"w"){ |output|
+          output.write pre*""
+          output.write start_fields
+          output.write fields.map{|f| f.first}*""
+          output.write end_fields
+          output.write post*""
+        }
+      end
+
+    end
+
+
+
+end