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.

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'

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.

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 repository,

site.repository = '/path/to/project/repo'
environment.reference = '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 temporary working directory,

environment.directory #=> '/tmp/palimpsest_my_app_120140605-26021-d7vlnv'

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

An example palimpsest.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.

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 destination: '/path/to/out/dir'

To delete the working directory, use

environment.cleanup

Add this line to your application's Gemfile:

gem 'palimpsest'

And then execute:

$ bundle

Or install it yourself as:

$ gem install palimpsest

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. Also checkout Omniref's interactive documentation.

The Palimpsest source is hosted on GitHub. To clone the project run

$ git clone https://github.com/razor-x/palimpsest.git

Run rake -T to see all Rake tasks.

rake all                   # Run all tasks
rake build                 # Build palimpsest-0.2.0.gem into the pkg directory
rake bump:current[tag]     # Show current gem version
rake bump:major[tag]       # Bump major part of gem version
rake bump:minor[tag]       # Bump minor part of gem version
rake bump:patch[tag]       # Bump patch part of gem version
rake bump:pre[tag]         # Bump pre part of gem version
rake bump:set              # Sets the version number using the VERSION environment variable
rake install               # Build and install palimpsest-0.2.0.gem into system gems
rake install:local         # Build and install palimpsest-0.2.0.gem into system gems without network access
rake release               # Create tag v0.2.0 and build and push palimpsest-0.2.0.gem to Rubygems
rake rubocop               # Run RuboCop
rake rubocop:auto_correct  # Auto-correct RuboCop offenses
rake spec                  # Run RSpec code examples
rake yard                  # Generate YARD Documentation

Guard tasks have been separated into the following groups:

• doc
• lint
• unit

By default, Guard will generate documentation, lint, and run unit tests.

Please submit and comment on bug reports and feature requests.

To submit a patch:

1. Fork it (https://github.com/razor-x/palimpsest/fork).
2. Create your feature branch (git checkout -b my-new-feature).
3. Make changes. Write and run tests.
4. Commit your changes (git commit -am 'Add some feature').
5. Push to the branch (git push origin my-new-feature).
6. Create a new Pull Request.

Palimpsest is licensed under the MIT license.

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.