Palimpsest

by Evan Boyd Sosenko.

No web framework, no problem: Palimpsest gives any custom or legacy project a modern workflow and toolset.

Built flexible, simple, and customizable. Palimpsest runs on top of any project and acts as a post processor for your code. Features a Sprockets asset pipeline and easy integration with Kit.

Gem Version Dependency Status Build Status Coverage Status Code Climate githalytics.com alpha

Installation

Add this line to your application's Gemfile:

gem 'palimpsest'

And then execute:

$ bundle

Or install it yourself as:

$ gem install palimpsest

Documentation

The primary documentation for Palimpsest is this README and the YARD source documentation.

YARD documentation for all gem versions is hosted on the Palimpsest gem page. Documentation for the latest commits is hosted on the RubyDoc.info project page.

Usage

Palimpsest should not be considered stable until version 1.0.0 is released.

This README will focus on examples of how to get your project working with Palimpsest through Palimpsest::Environment.

Palimpsest's classes are independently useful outside of Palimpsest::Environment, and each is well documented for that purpose.

The first step is always

require 'palimpsest'

Additional requirements

Some optional Palimpsest features depend on gems not required by Palimpsest itself. Include these in your project's Gemfile if you plan to use them.

For example, to use the image_compression option, add to your Gemfile

gem 'sprockets-image_compressor'

and to your project

require 'sprockets-image_compressor'

or if you set js_compressor: uglifier you must add to your Gemfile

gem 'uglifier'

and to your project

require 'uglifier'

Similarly you must include gems for any sprockets engines you want to use.

Creating and populating an environment

Create an environment with

environment = Palimpsest::Environment.new

For most operations you will need to specify a site which can be any object which responds to the methods Palimpsest::Environment assumes exists in some of its own methods. A model class Palimpsest::Site is included which implements all possible expected methods. Finally, the examples below assume default options for each class, but these can be overridden with #options.

site = Palimpsest::Site.new
site.name = 'my_app'
environment.site = site

To populate the environment from a git repo,

site.repo = Grit::Repo.new '/path/to/project/repo'
environment.treeish = 'my_feature' # if you want something other then 'master'
environment.populate

or to populate from a directory,

site.source = '/path/to/project/source'
environment.populate from :source

Either way you will get a copy of your site in a new random working directory,

environment.directory #=> '/tmp/palimpsest_my_app_6025680'

Working with the environment

If you project contains a file palimpsest_config.yml, then its configuration is available with environment.config.

An example palimpsest_config.yml.

The configuration file tells Palimpsest how to behave when you ask it to manipulate the environment and acts as a shortcut to working with the other Palimpsest classes directly.

If you made it this far, you can make Palimpsest do all sorts of magic to your code in the working directory.

For example, to search through you code for tags referencing assets, process and save those assets with sprockets, and replace the tags with references to the processed assets,

environment.compile_assets

Check the Palimpsest::Environment documentation for all available magic, and freely extend the class to add new magic applicable to your project.

Finishing with the environment

You can copy the current state of the environment to another directory with Palimpsest::Environment#copy. By default, this will use site.path for the destination, or you can specify with

environment.copy dest: '/path/to/out/dir'

To delete the working directory, use

environment.cleanup

Development

Source Repository

The Palimpsest source is hosted at github. To clone the project run

$ git clone [email protected]:razor-x/palimpsest.git

License

Palimpsest is licensed under the MIT license.

Warranty

This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.