exegesis 0.0.2

data/.gitignore

@@ -0,0 +1,5 @@
+pkg
+.rbx
+.yardoc
+doc/
+Gemfile.lock

data/.rvmrc

@@ -0,0 +1,2 @@
+RVM_STRING="rvm use rbx-head@exegesis --create --verbose"
+[ -e './.rvmrc_local' ] && source './.rvmrc_local' || $RVM_STRING

data/.yardopts

@@ -0,0 +1,5 @@
+--no-private
+--embed-mixins
+-
+README.md
+LICENSE

data/CHANGELOG

@@ -0,0 +1,10 @@
+
+* 0.0.2
+	Large amount of functionality in place, including BaseDirectories,
+	Directories, SourceFiles, and Visitors. Internal Architectural stuff also
+	working (objects are stored in flyweights so there are no duplicates and
+	everything stays synced.
+
+* 0.0.1
+
+	Initial Release

data/Gemfile

@@ -0,0 +1,20 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in exegesis.gemspec
+gemspec
+
+group :documentation do
+  gem 'rdoc'
+  gem 'yard'
+  gem 'kramdown'
+end
+
+group :development do
+  gem 'pry'
+end
+
+group :test do
+  gem 'rspec'
+  gem 'rspec-spies', '2.1.0'
+  gem 'bahia'
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Joe Fredette
+
+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/NOTES.md

@@ -0,0 +1,214 @@
+# Basic structure
+
+## Implementation
+
+* SourceFiles and Directories should be members of a Flyweight, and creation
+  should try to do a lookup first. Perhaps Celluloid can be used to do this,
+  with directories potentially acting as supervisors.
+
+## Architecture
+
+A suite of raketasks (potentially hidden behind a 'exegesis' script. Adhereing
+to the following model:
+
+    class Project
+      HAS_MANY BaseDirectories #as a series of methods in a subclass
+      HAS_MANY SourceFiles
+
+    Responsibilities:
+      this represents the root directory of a project. It will be subclassed
+      into project-style specific class. Eg, a RailsProject IS_A Project, it's
+      BaseDirectories are, perhaps, `spec`, `app`, `lib`, and `config`. A
+      GemProject might have `lib`, `spec`, and `bin`, a C project might have
+      `test`, `src`, `vendor`, `obj`, etc.
+
+      It also provides methods like `#build_skeleton!(dir)` which take a
+      location in the filesystem and build the structure specified by the
+      project.
+
+      It also serves as a point from which we may start a `#visit` to all of
+      it's subdirs and files.
+
+    NB:
+      It might be interesting to have Projects be able to embed other projects.
+      This could be useful for representing, eg, tests in a C project as a
+      subproject with it's own file-structure and stuff. So that a CProject is
+      now a pair of two underlying `CSourceProject`, each of which has a `src`,
+      `obj`, and `vendor`, which in the one project represents the testing
+      setup, and the other represents the application setup. Possible problem
+      might be trying to get dependencies to work across projects.
+
+    ----------------------------------------------------------------------------
+
+    class BaseDirectory IS_A Directory
+      HAS_A Root
+      HAS_MANY Directories
+      HAS_MANY SourceFiles
+
+    Responsibilities:
+      Expose properties of the root directory, Spawn the initial set of
+      directories which will recursively find all the files in the project
+
+      The class will also wrap some of the SourceFile classmacros, like #join and
+      #expand_path and stuff. Think along the lines of Rails.root and the like.
+
+    Collaborators:
+      Directory
+      SourceFile
+
+    ----------------------------------------------------------------------------
+
+    class Directory
+      HAS_MANY SourceFiles
+      HAS_MANY Directories (Children)
+      HAS_A Directory (Parent)
+
+    Responsibilities:
+      Finds all the files and directories at a given level of the project
+      structure, allows for recursive informing of children -- ideally in
+      parallel. 
+
+    Collaborators: 
+      SourceFile
+      Directory
+
+    ----------------------------------------------------------------------------
+
+    class SourceFile
+      HAS_A Extension
+      HAS_A Path
+      HAS_A Base Name
+      HAS_MANY SourceFiles (Dependencies)
+
+    Responsibilities:
+      Represents a sourcefile on disk, providing access to it's file-system
+      related information as well as internal information based on the language.
+
+    Notes:
+      This will likely work w/ an inheritance heirarchy for each programming
+      language. Mostly it will be one-level deep, but in the case where a
+      subsequent language forms a superset/subset, deeper inheritance may occur
+      (similarly we might have a module for shared subsets, etc).
+
+    Collaborators:
+      SourceFile
+      SourceFileFactory       -- to build the appropriate subclass based on file extenstion
+
+    ----------------------------------------------------------------------------
+
+    class SourceFileFactory
+      #snip
+
+    Responsibilities:
+      Provide an extensible way to build SourceFile instances appropriate to the
+      language the source of a given file is in.
+
+    Collaborators:
+      LanguageIdentifier
+      SourceFile
+
+    ----------------------------------------------------------------------------
+
+    class LanguageIdentifier
+      #snip
+
+    Responsibilities:
+      A command object to identify the language of a given sourcefile
+
+    Collaborators:
+      SourceFileFactory
+
+    ----------------------------------------------------------------------------
+
+    class FileSearcher
+
+    Responsibilities:
+      Encapsulates an API for looking through a single directory of files,
+      sorting them into directories/files/whatever, and providing those path
+      lists on demand
+
+    NB:
+      The aim is to isolate the minimum API with this class, so that alternative
+      source backends could potentially be written, eg -- a backend for
+      distributed sourcetrees, or w/ files in Riak or S3 or whereever
+
+    Collaborators:
+      Used By:
+        Project, Directory
+      Uses:
+        Some system-level class like Dir, FileList, or Find
+
+
+# Tools
+
+Would be nice to model these guys as actors, especially so that we and make use
+of that nice async stuff for a little map-reduce-y action. Celluloid? (DCell? :])
+
+# #visit
+
+This is an interface which would take some kind of Visitor class, which defines
+up to `n` methods (on for each model type). This method would iterate over all
+of it's contents (directories/files/whatever) and apply to each the appropriate
+method from the visitor, with the instance as an argument. The visitor can
+potentially recursively call #visit on directories, which should also support
+this interface
+
+# DSL
+
+w/ the restructure to use the `Project->[BaseDirs]` change, it would be useful to
+have a DSL to specify a project in a simpler way than manually defining a new
+subclass of `Project`. To wit, I rather like:
+
+    project 'rails' do
+      src_dir 'app'
+      src_dir 'lib'
+      src_dir 'db'
+
+      test_dir 'spec'
+      test_dir 'features'
+
+      config_dir 'config'
+
+      file 'Gemfile'
+      file 'Rakefile'
+
+      #etc
+    end
+
+This would define an appropriate `Project` subclass, called 'RailsProject', with methods pointing to
+the various subdirs.
+
+# Features
+
+## Core Features (Must Haves)
+
+* Automatic Building w/ dependency discovery
+  - manual configuration of dependencies also allowed
+  - parallel builds by default
+* Automatic Test Suite w/ boilerplate autogenerated
+  - Integrates with specific tools to do this, eg, Check or CUnit, etc.
+* Handles at least C, C++, and maybe Go and Rust
+
+## Added Features (Should Haves)
+
+* Automatic, file-system-event based recompiles.
+* Integration with other Unit testing systems
+
+## Neat Features (Could Haves)
+
+* Statistics on code base (LOC, Complexity metrics, etc)
+* Plugin API
+
+## Far out Features (Want-to Haves)
+
+* Language-aware search indexing (with ElasticSearch backend?)
+
+## Random features
+
+* Automatically generate git helper stuff
+  - spawn a repo
+  - build the project skeleton
+  - set up gitignore
+  - set up hooks (run tests, etc)
+  - Set up standard docs (README, AUTHORS, LICENSE, etc)
+

data/README.md

@@ -0,0 +1,44 @@
+** Exegesis is a pre-alpha tool. It is not recommended for public consumption **
+
+It'll be 0.1 or better when it's ready.
+
+# Exegesis
+
+Exegesis is a tool for automating many parts of the development of C projects.
+Following a convention-over-configuration model.
+
+It provides tools to:
+
+  * Create skeleton projects
+  * Build
+  * Testing
+  * Packaging
+
+Though C is presently the only supported language, it is the aim of Exegesis to
+support tooling for other compiled languages.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'exegesis'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install exegesis
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+desc 'run specs'
+RSpec::Core::RakeTask.new do |task|
+  task.rspec_opts = ["-c", "-f progress"]
+end
+
+task :default => :spec

data/TODO.md

@@ -0,0 +1,63 @@
+1. Projects
+  1.1. Composite projects
+
+2. Dependency Heirarchy (#visit should respect it)
+  2.1. Explicit-ordering
+      That is, an explicit sort based on a list of key/list pairs, the key being
+      the object that depends on the others being processed. We should have a
+      generic visitor class that can consume such a list and respect that
+      dependency structure when doing it's visitation.
+
+  2.2. Driven by a real example
+      Write a nontrivial (but simple) app in C/Go/Typescript/whatever, try to
+      use Exegesis to do dependency discovery, set up rake-tasks for
+      compilation, etc.
+
+3. FileUtil methods
+  3.1 Directories should respond to stuff like `#mkdir`, `#ls`, etc. we should
+  have `#cd` return a BaseDirectory for the given path, perhaps. SourceFiles
+  should respond to `#stat`, etc. Basically load up the filesystem as methods.
+
+4. Break up FileSystemEntity into several modules
+  it's a bit of a hodge-podge at the moment
+
+5. Search
+  Need to be able to search for files in-project and on-path (the latter being
+  for referencing system-librarys). Exegesis, in the long run, is going to
+  calculate at least the following tasks:
+
+    * <rake task> ~ <equivalent make-related task>
+
+    * configure   ~ ./configure
+    * default     ~ make
+    * all         ~ make all
+    * install     ~ make install
+    * clean       ~ make clean
+    * distclean   ~ make distclean
+
+  In particular, configure needs to be able to calculate external dependencies
+  and use pkg-config to check for them (in the cases where pkg-config makes
+  sense). Ideally with minimal effort it could automatially scour something like
+  CPAN for C projects (CCAN?) or w/e and find where you have to go to install
+  those dependencies.
+
+  In any case, we need the ability to reference files in-context, so that an
+  `#include 'foo/bar'` in the src directory knows to reference `src/foo/bar`
+  and not `obj/foo/bar` in it's dependency setup. It would be good to also
+  implement `find` in terms of exegesis.
+
+6. Celluloid
+  It would be very powerful to be able to have each file act independently,
+  especially in the case of `#visit`, because we can asynchronously spawn
+  visitors to do their work, and as long as the visitor can manage concurrent
+  access, the directories/files it visits have no shared state with anything,
+  and thus should be pretty easy to fit into a multi-threaded, link-free
+  framework like exegesis.
+
+------ Things worth doing later ------
+
+1. Model symlinks
+2. build a visitor that outputs a `dot` graph of the folder heirarchy. bonus
+   points for outputting a DAG when symlinks are built
+3. Performance testing.
+

data/bin/exegesis

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require 'rake'
+require 'exegesis'
+
+Rake.application.init('exegesis')
+
+task :version do
+  puts "Exegesis, version #{Exegesis::VERSION}"
+end
+
+Rake.application.top_level
+
+
+

data/exegesis.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/exegesis/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Joe Fredette"]
+  gem.email         = ["jfredett@gmail.com"]
+  gem.description   = %q{A tool for automatically compiling C projects}
+  gem.summary       = %q{Exegesis is a tool for automating many parts of the development of C projects.
+                         Following a convention-over-configuration model, it provides tools to create 
+                         skeleton projects, as well as providing tools to automate building, testing, and
+                         packaging.}
+  gem.homepage      = ""
+
+  gem.add_dependency "rake"
+  gem.add_dependency "celluloid"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "exegesis"
+  gem.require_paths = ["lib"]
+  gem.version       = Exegesis::VERSION
+end

data/lib/exegesis/base_directory.rb

@@ -0,0 +1,29 @@
+# class BaseDirectory IS_A Directory
+#  HAS_A Root
+#  HAS_MANY Directories
+#  HAS_MANY SourceFiles (files)
+#
+# Responsibilities:
+#  Expose properties of the root directory, Spawn the initial set of
+#  directories which will recursively find all the files in the project
+#
+#  The class will also wrap some of the SourceFile macros, like #join and
+#  #expand_path and stuff. Think along the lines of Rails.root and the like.
+#
+# Collaborators:
+#  [Directory]
+#  [SourceFile]
+class BaseDirectory < Directory
+  # @param root [String] the root path of the project
+  # @param searcher [FileSearcher] an object used to search for files in a given
+  #    directory
+  def initialize(root, searcher = FileSearcher)
+    super(nil, root, searcher)
+  end
+
+  # The path to the root of the project
+  def path
+    name
+  end
+  alias root path
+end

data/lib/exegesis/directory.rb

@@ -0,0 +1,33 @@
+# class Directory
+#   HAS_MANY SourceFiles
+#   HAS_MANY Directories (Children)
+#   HAS_A Directory (Parent)
+#
+# Responsibilities:
+#   Finds all the files and directories at a given level of the project
+#   structure, allows for recursive informing of children -- ideally in
+#   parallel.
+#
+# Collaborators:
+#   SourceFile
+#   Directory
+class Directory
+  include FileSystemEntity
+
+  delegate [:directories, :files] => :searcher
+  alias children directories
+
+  private
+
+  attr_reader :searcher
+
+  # @param parent [Directory] the root directory or project of the project
+  # @param name [String] the name of the directory
+  # @param searcher [FileSearcher] an object used to search for files in a given
+  #    directory
+  def initialize(parent, name, searcher = FileSearcher)
+    @parent = parent
+    @name = name
+    @searcher = searcher.new(self)
+  end
+end

data/lib/exegesis/file_searcher.rb

@@ -0,0 +1,48 @@
+# class FileSearcher
+#
+# Responsibilities:
+#   Encapsulates an API for looking through a single directory of files,
+#   sorting them into directories/files/whatever, and providing those path
+#   lists on demand
+#
+# NB:
+#   The aim is to isolate the minimum API with this class, so that alternative
+#   source backends could potentially be written, eg -- a backend for
+#   distributed sourcetrees, or w/ files in Riak or S3 or whereever
+#
+# Collaborators:
+#   Used By:
+#     Project, Directory
+#   Uses:
+#     Some system-level class like Dir, FileList, or Find
+class FileSearcher
+  # Create a new FileSearcher on the given path
+  #
+  # @param parent [Directory] the parent directory to search downward from
+  def initialize(parent)
+    @parent = parent
+  end
+
+  #All of the directories in the given path
+  def directories
+    content.select { |s| File.directory?(s) }.map { |s| Directory.create(parent, File.basename(s)) }
+  end
+
+  #All of the files in the given path
+  def files
+    content.select { |s| File.file?(s) }.map { |s| SourceFile.create(parent, File.basename(s)) }
+  end
+
+  #All of the content from the given path
+  def content
+    Dir[File.join(parent.path, '*')]
+  end
+
+  def inspect
+    "FileSearcher(#{parent.path.inspect})"
+  end
+
+  private
+
+  attr_reader :parent
+end

data/lib/exegesis/file_system_entity.rb

@@ -0,0 +1,52 @@
+# A collection of shared methods for Directories and SourceFiles
+module FileSystemEntity
+  def self.included(base)
+    base.send(:include , Registerable)
+    base.send(:extend  , Forwardable)
+    base.send(:include , Methods)
+  end
+
+  module Methods
+    def path
+      File.join(parent.path, name)
+    end
+
+    def inspect
+      "#{self.class.inspect}(#{path.inspect})"
+    end
+
+    attr_reader :parent, :name
+    alias container parent
+
+    def basename
+      File.basename(name, ext)
+    end
+
+    def ext
+      @ext || ""
+    end
+    alias extension ext
+
+
+    def visit(visitor)
+      visitor.on_enter if visitor.respond_to? :on_enter
+
+      visitor.call(self.class, self)
+
+      if respond_to?(:directories)
+        directories.each do |dir|
+          dir.visit(visitor)
+        end
+      end
+
+      if respond_to?(:files)
+        files.each do |file|
+          file.visit(visitor)
+        end
+      end
+
+      visitor.on_exit if visitor.respond_to? :on_exit
+    end
+  end
+end
+