Class: Palimpsest::Environment

Inherits:
Object
  • Object
show all
Defined in:
lib/palimpsest/environment.rb

Overview

An environment is populated with the contents of a site's repository at a specified commit. Alternatively, a single directory can be used to populate the environment. The environment's files are rooted in a temporary #directory. An environment is the primary way to interact with a site's files.

An environment loads a #config file from the working #directory; by default, palimpsest_config.yml.

Paths are all relative to the working #directory.

# example of palimpsest_config.yml

# component settings
:components:
  # all component paths are relative to the base
  :base: _components

  # list of components
  :paths:
   #- [ components_path, install_path ]
    - [ my_app/templates, apps/my_app/templates ]
    - [ my_app/extra, apps/my_app ]

# externals settings
:externals:
  # server or local path that repos are under
  :server: "https://github.com/razor-x"

  # list of external repos
  :repos:
   #- [ name, install_path, branch, server (optional) ]
    - [ my_app, apps/my_app, master ]
    - [ sub_app, apps/my_app/sub_app, my_feature, "https://bitbucket.org/razorx" ]

# list of excludes
# matching paths are removed with {#remove_excludes}.
:excludes:
  - _assets
  - apps/*/.gitignore

# asset settings
:assets:
  # all options are passed to Assets#options
  # options will use defaults set in Palimpsest::Asset::DEFAULT_OPTIONS if unset here
  # unless otherwise mentioned, options can be set or overridden per asset type
  :options:
    # opening and closing brackets for asset source tags
    # global option only: cannot be overridden per asset type
    :src_pre: "[%"
    :src_post: "%]"

    # relative directory to save compiled assets
    :output: compiled

    # assume assets will be served under here
    :cdn: https://cdn.example.com/

    # compiled asset names include a uniqe hash by default
    # this can be toggled off
    :hash: false

  # directories to scan for files with asset tags
  :sources:
    # putting assets/stylesheets first would allow asset tags,
    # e.g. for images, to be used in your stylesheets
    - assets/stylesheets
    - public
    - app/src

  # all other keys are asset types
  :javascripts:
    :options:
      :js_compressor: :uglifier
    # these paths are loaded into the sprockets environment
    :paths:
      - assets/javascripts
      - other/javascripts

  # this is another asset type which will have it's own namespace
  :stylesheets:
    :options:
      :css_compressor: :sass

    :paths:
      - assets/stylesheets
  # images can be part of the asset pipeline
  :images:
    :options:
      # requires the sprockets-image_compressor gem
      :image_compression: true
      # options can be overridden per type
      :output: images
    :paths:
      - assets/images

Constant Summary collapse

DEFAULT_OPTIONS =

Default #options.

{
  # all environment's temporary directories will be rooted under here
  tmp_dir: '/tmp',

  # prepended to the name of the environment's working directory
  dir_prefix: 'palimpsest_',

  # name of config file to load, relative to environment's working directory
  config_file: 'palimpsest_config.yml'
}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(site: nil, treeish: 'master', options: {}) ⇒ Environment

Returns a new instance of Environment.



124
125
126
127
128
129
 
# File 'lib/palimpsest/environment.rb', line 124

def initialize site: nil, treeish: 'master', options: {}
  @populated = false
  self.options options
  self.site = site if site
  self.treeish = treeish
end

Instance Attribute Details

#populated ⇒ Object (readonly)

Returns the value of attribute populated.



122
 
# File 'lib/palimpsest/environment.rb', line 122

attr_reader :site, :treeish, :populated

#site ⇒ Object

Returns site to build the environment with.

Returns:

  • site to build the environment with



122
123
124
 
# File 'lib/palimpsest/environment.rb', line 122

def site
  @site
end

#treeish ⇒ String

Returns the reference used to pick the commit to build the environment with.

Returns:

  • (String) —

    the reference used to pick the commit to build the environment with



122
 
# File 'lib/palimpsest/environment.rb', line 122

attr_reader :site, :treeish, :populated

Instance Method Details

#assets ⇒ Array<Assets>

Returns assets with settings and paths loaded from config.

Returns:

  • (Array<Assets>) —

    assets with settings and paths loaded from config



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/palimpsest/environment.rb', line 277

def assets
  return @assets if @assets

  @assets = []

  config[:assets].each do |type, opt|
    next if [:sources].include? type
    next if opt[:paths].nil?

    assets = Assets.new directory: directory, paths: opt[:paths]
    assets.options config[:assets][:options] unless config[:assets][:options].nil?
    assets.options opt[:options] unless opt[:options].nil?
    assets.type = type
    @assets << assets
  end unless config[:assets].nil?

  @assets
end

#cleanup ⇒ Environment

Removes the environment's working directory.

Returns:



173
174
175
176
177
178
179
180
181
 
# File 'lib/palimpsest/environment.rb', line 173

def cleanup
  FileUtils.remove_entry_secure directory if @directory
  @config = nil
  @directory = nil
  @assets = []
  @components = []
  @populated = false
  self
end

#compile_assets ⇒ Environment

Finds all assets in #sources_with_assets and generates the assets and updates the sources.

Returns:



318
319
320
321
322
323
324
325
 
# File 'lib/palimpsest/environment.rb', line 318

def compile_assets
  sources_with_assets.each do |file|
    source = File.read file
    assets.each { |a| a.update_source! source }
    Utility.write source, file, preserve: true
  end
  self
end

#components ⇒ Array<Component>

Returns components with paths loaded from config.

Returns:

  • (Array<Component>) —

    components with paths loaded from config



221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/palimpsest/environment.rb', line 221

def components
  return @components if @components
  return [] if config[:components].nil?
  return [] if config[:components][:paths].nil?

  @components = []

  base = directory
  base += config[:components][:base].nil? ? '' : '/' + config[:components][:base]

  config[:components][:paths].each do |paths|
   @components << Component.new(source_path: "#{base}/#{paths[0]}", install_path: "#{directory}/#{paths[1]}")
  end

  @components
end

#config(settings = {}) ⇒ Hash

Returns configuration loaded from #options[:config_file] under #directory.

Parameters:

  • settings (Hash) (defaults to: {}) —

    merged with current config

Returns:



210
211
212
213
214
215
216
217
218
 
# File 'lib/palimpsest/environment.rb', line 210

def config settings = {}
  if @config.nil?
    populate unless populated
    @config = YAML.load_file "#{directory}/#{options[:config_file]}"
    validate_config if @config
  end

  @config.merge! settings
end

#copy(dest: site.path) ⇒ Environment

Copy the contents of the working directory.

Parameters:

  • dest (String) (defaults to: site.path) —

    path to copy environment's files to

Returns:



165
166
167
168
169
 
# File 'lib/palimpsest/environment.rb', line 165

def copy dest: site.path
  FileUtils.mkdir_p dest
  FileUtils.cp_r Dir["#{directory}/*"], dest, preserve: true
  self
end

#directory ⇒ String

Returns the environment's working directory.

Returns:

  • (String) —

    the environment's working directory



153
154
155
156
157
158
159
160
 
# File 'lib/palimpsest/environment.rb', line 153

def directory
  if @directory.nil?
    name = site.nil? ? '' : site.name
    @directory = Utility.make_random_directory options[:tmp_dir], "#{options[:dir_prefix]}#{name}_"
  else
    @directory
  end
end

#externals ⇒ Array<External>

Returns externals loaded from config.

Returns:

  • (Array<External>) —

    externals loaded from config



246
247
248
249
250
251
252
253
254
255
256
257
258
259
 
# File 'lib/palimpsest/environment.rb', line 246

def externals
  return @externals if @externals
  return [] if config[:externals].nil?
  return [] if config[:externals][:repos].nil?

  @externals = []

  config[:externals][:repos].each do |repo|
    source = repo[3].nil? ? config[:externals][:server] : repo[3]
    @externals << External.new(name: repo[0], source: source, branch: repo[2], install_path: "#{directory}/#{repo[1]}" )
  end

  @externals
end

#install_components ⇒ Environment

Install all components.

Returns:



240
241
242
243
 
# File 'lib/palimpsest/environment.rb', line 240

def install_components
  components.each { |c| c.install }
  self
end

#install_externals ⇒ Environment

Install all externals.

Returns:



263
264
265
266
 
# File 'lib/palimpsest/environment.rb', line 263

def install_externals
  externals.each { |e| e.install.cleanup }
  self
end

#options(options = {}) ⇒ Hash

Uses DEFAULT_OPTIONS as initial value.

Parameters:

  • options (Hash) (defaults to: {}) —

    merged with current options

Returns:

  • (Hash) —

    current options



134
135
136
137
 
# File 'lib/palimpsest/environment.rb', line 134

def options options={}
  @options ||= DEFAULT_OPTIONS
  @options = @options.merge options
end

#populate(from: :auto) ⇒ Environment

Extracts the site's files from repository to the working directory.

Returns:



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/palimpsest/environment.rb', line 185

def populate from: :auto
  cleanup if populated
  fail RuntimeError, "Cannot populate without 'site'" if site.nil?

  case from
  when :auto
    if site.respond_to?(:repo) ? site.repo : nil
      populate from: :repo
    else
      populate from: :source
    end
  when :repo
    fail RuntimeError, "Cannot populate without 'treeish'" if treeish.empty?
    Utility.extract_repo site.repo, treeish, directory
    @populated = true
  when :source
    Kernel.system 'rsync', '-rt', %q{--exclude='.git/'}, "#{site.source}/", directory
    @populated = true
  end

  self
end

#remove_excludes ⇒ Environment

Remove all excludes defined by config[:excludes].

Returns:



270
271
272
273
274
 
# File 'lib/palimpsest/environment.rb', line 270

def remove_excludes
  return self if config[:excludes].nil?
  config[:excludes].map{ |e| Dir["#{directory}/#{e}"] }.flatten.each { |e| FileUtils.remove_entry_secure e }
  self
end

#sources_with_assets ⇒ Array

Returns all source files with asset tags.

Returns:

  • (Array) —

    all source files with asset tags



297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/palimpsest/environment.rb', line 297

def sources_with_assets
  return [] if config[:assets].nil?
  return [] if config[:assets][:sources].nil?

  @sources_with_assets = []

  opts = {}
  [:src_pre, :src_post].each do |opt|
    opts[opt] = config[:assets][:options][opt] unless config[:assets][:options][opt].nil?
  end unless config[:assets][:options].nil?

  config[:assets][:sources].each do |path|
    @sources_with_assets << Assets.find_tags("#{directory}/#{path}", nil, opts)
  end

  @sources_with_assets.flatten
end

#validate_asset_options(opts) ⇒ Object

Checks the option in the asset key.



336
337
338
339
340
341
 
# File 'lib/palimpsest/environment.rb', line 336

def validate_asset_options opts
  opts.each do |k,v|
    fail RuntimeError, 'bad option in config' if k == :sprockets_options
    fail RuntimeError, message if k == :output && ! Utility.safe_path?(v)
  end
end