nanoc 2.0 → 2.1

data/lib/nanoc/base/site.rb

@@ -1,143 +1,272 @@
 module Nanoc
+
+  # A Nanoc::Site is the in-memory representation of a nanoc site. It holds
+  # references to the following site data:
+  #
+  # * +pages+ is a list of Nanoc::Page instances representing pages
+  # * +assets+ is a list of Nanoc::Asset instances representing assets
+  # * +page_defaults+ is a Nanoc::PageDefaults instance representing page
+  #   defaults
+  # * +asset_defaults+ is a Nanoc::AssetDefaults instance representing asset
+  #   defaults
+  # * +layouts+ is a list of Nanoc::Layout instances representing layouts
+  # * +templates+ is a list of Nanoc::Template representing templates
+  # * +code+ is a Nanoc::Code instance representing custom site code
+  #
+  # In addition, each site has a +config+ hash which stores the site
+  # configuration. This configuration hash can have the following keys:
+  #
+  # +output_dir+:: The directory to which compiled pages and assets will be
+  #                written. This path is relative to the current working
+  #                directory, but can also be an absolute path.
+  #
+  # +data_source+:: The identifier of the data source that will be used for
+  #                 loading site data.
+  #
+  # +router+:: The identifier of the router that will be used for determining
+  #            page and asset representation paths.
+  #
+  # +index_filenames+:: A list of filenames that will be stripped off full
+  #                     page and asset paths to create cleaner URLs (for
+  #                     example, '/about/' will be used instead of
+  #                     '/about/index.html'). The default value should be okay
+  #                     in most cases.
+  #
+  # A site also has several helper classes:
+  #
+  # * +router+ is a Nanoc::Router subclass instance used for determining page
+  #   and asset paths.
+  # * +data_source+ is a Nanoc::DataSource subclass instance used for managing
+  #   site data.
+  # * +compiler+ is a Nanoc::Compiler instance that compiles page and asset
+  #   representations.
+  #
+  # The physical representation of a Nanoc::Site is usually a directory that
+  # contains a configuration file, site data, and some rake tasks. However,
+  # different frontends may store data differently. For example, a web-based
+  # frontend would probably store the configuration and the site content in a
+  # database, and would not have rake tasks at all.
   class Site
 
+    # The default configuration for a site. A site's configuration overrides
+    # these options: when a Nanoc::Site is created with a configuration that
+    # lacks some options, the default value will be taken from
+    # +DEFAULT_CONFIG+.
     DEFAULT_CONFIG = {
-      :output_dir   => 'output',
-      :eruby_engine => 'erb',
-      :data_source  => 'filesystem'
+      :output_dir       => 'output',
+      :data_source      => 'filesystem',
+      :router           => 'default',
+      :index_filenames  => [ 'index.html' ]
     }
 
     attr_reader :config
-    attr_reader :compiler, :data_source
-    attr_reader :code, :pages, :page_defaults, :layouts, :templates
-
-    # Creating a Site object
-
-    def self.from_cwd
-      File.file?('config.yaml') ? new : nil
-    end
-
-    def initialize
+    attr_reader :compiler, :data_source, :router
+    attr_reader :page_defaults, :asset_defaults
+    attr_reader :pages, :assets, :layouts, :templates, :code
+
+    # Returns a Nanoc::Site object for the site specified by the given
+    # configuration hash +config+.
+    #
+    # +config+:: A hash containing the site configuration.
+    def initialize(config)
       # Load configuration
-      @config = DEFAULT_CONFIG.merge((YAML.load_file('config.yaml') || {}).clean)
+      @config = DEFAULT_CONFIG.merge(config.clean)
 
       # Create data source
-      @data_source_class = PluginManager.data_source_named(@config[:data_source])
-      error "Unrecognised data source: #{@config[:data_source]}" if @data_source_class.nil?
+      @data_source_class = Nanoc::DataSource.named(@config[:data_source])
+      raise Nanoc::Errors::UnknownDataSourceError.new(@config[:data_source]) if @data_source_class.nil?
       @data_source = @data_source_class.new(self)
 
       # Create compiler
-      @compiler     = Compiler.new(self)
-      @autocompiler = AutoCompiler.new(self)
-
-      # Set not loaded
-      @data_loaded = false
+      @compiler = Compiler.new(self)
+
+      # Load code (necessary for custom routers)
+      load_code
+
+      # Create router
+      @router_class = Nanoc::Router.named(@config[:router])
+      raise Nanoc::Errors::UnknownRouterError.new(@config[:router]) if @router_class.nil?
+      @router = @router_class.new(self)
+
+      # Initialize data
+      @page_defaults        = PageDefaults.new({})
+      @page_defaults.site   = self
+      @asset_defaults       = AssetDefaults.new({})
+      @asset_defaults.site  = self
+      @pages                = []
+      @assets               = []
+      @layouts              = []
+      @templates            = []
     end
 
+    # Loads the site data. This will query the Nanoc::DataSource associated
+    # with the site and fetch all site data. The site data is cached, so
+    # calling this method will not have any effect the second time, unless
+    # +force+ is true.
+    #
+    # +force+:: If true, will force load the site data even if it has been
+    #           loaded before, to circumvent caching issues.
     def load_data(force=false)
+      # Don't load data twice
+      @data_loaded ||= false
       return if @data_loaded and !force
 
-      # Load data
+      # Load all data
       @data_source.loading do
-        @code           = @data_source.code
-        @pages          = @data_source.pages.map { |p| Page.new(p, self) }
-        @page_defaults  = @data_source.page_defaults
-        @layouts        = @data_source.layouts
-        @templates      = @data_source.templates
+        load_code(force)
+        load_page_defaults
+        load_pages
+        load_asset_defaults
+        load_assets
+        load_layouts
+        load_templates
       end
 
+      # Set loaded
+      @data_loaded = true
+    end
+
+  private
+
+    # Loads this site's code and executes it.
+    def load_code(force=false)
+      # Don't load code twice
+      @code_loaded ||= false
+      return if @code_loaded and !force
+
+      # Get code
+      @code = @data_source.code
+
+      # Fix code if outdated
+      if @code.is_a? String
+        warn_data_source('Code', 'code', false)
+        @code = Code.new(code)
+      end
+
+      # Set site
+      @code.site = self
+
+      # Execute code
+      # FIXME This could be dangerous when using nanoc as a framework
+      # (a separate ruby process should probably be forked, and the code
+      # should only be loaded in this forked process)
+      @code.load
+
+      # Set loaded
+      @code_loaded = true
+    end
+
+    # Loads this site's page defaults.
+    def load_page_defaults
+      # Get page defaults
+      @page_defaults = @data_source.page_defaults
+
+      # Fix page defaults if outdated
+      if @page_defaults.is_a? Hash
+        warn_data_source('PageDefaults', 'page_defaults', false)
+        @page_defaults = PageDefaults.new(@page_defaults)
+      end
+
+      # Set site
+      @page_defaults.site = self
+    end
+
+    # Loads this site's pages, sets up page child-parent relationships and
+    # builds each page's list of page representations.
+    def load_pages
+      # Get pages
+      @pages = @data_source.pages
+
+      # Fix pages if outdated
+      if @pages.any? { |p| p.is_a? Hash }
+        warn_data_source('Page', 'pages', true)
+        @pages.map! { |p| Page.new(p[:uncompiled_content], p, p[:path]) }
+      end
+
+      # Set site
+      @pages.each { |p| p.site = self }
+
       # Setup child-parent links
       @pages.each do |page|
-        # Skip pages without parent
-        next if page.path == '/'
-
         # Get parent
         parent_path = page.path.sub(/[^\/]+\/$/, '')
         parent = @pages.find { |p| p.path == parent_path }
+        next if parent.nil? or page.path == '/'
 
         # Link
         page.parent = parent
         parent.children << page
       end
 
-      # Set loaded
-      @data_loaded = true
-    end
-
-    # Creating a new site on disk
-
-    def self.create(sitename)
-      # Check whether site exists
-      error "A site named '#{sitename}' already exists." if File.exist?(sitename)
-
-      FileUtils.mkdir_p sitename
-      in_dir([sitename]) do
-        # Create output
-        FileManager.create_dir 'output'
-
-        # Create config
-        FileManager.create_file 'config.yaml' do
-          "output_dir:  \"output\"\n" +
-          "data_source: \"filesystem\"\n"
-        end
-
-        # Create rakefile
-        FileManager.create_file 'Rakefile' do
-          "Dir['tasks/**/*.rake'].sort.each { |rakefile| load rakefile }\n" +
-          "\n" +
-          "task :default do\n" +
-          "  puts 'This is an example rake task.'\n" +
-          "end\n"
-        end
-
-        # Create tasks
-        FileManager.create_file 'tasks/default.rake' do
-          "task :example do\n" +
-          "  puts 'This is an example rake task in tasks/default.rake.'\n" +
-          "end\n"
-        end
-
-        # Setup site
-        Site.from_cwd.setup
-      end
+      # Build page representations
+      @pages.each { |p| p.build_reps }
     end
 
-    # Compiling
+    # Loads this site's asset defaults.
+    def load_asset_defaults
+      # Get page defaults
+      @asset_defaults = @data_source.asset_defaults
 
-    def compile
-      @compiler.run
+      # Set site
+      @asset_defaults.site = self
+    rescue NotImplementedError
+      @asset_defaults = AssetDefaults.new({})
+      @asset_defaults.site = self
     end
 
-    def autocompile(port)
-      @autocompiler.start(port)
-    end
+    # Loads this site's assets and builds each asset's list of asset
+    # representations.
+    def load_assets
+      # Get assets
+      @assets = @data_source.assets
 
-    # Creating
+      # Set site
+      @assets.each { |a| a.site = self }
 
-    def setup
-      @data_source.loading { @data_source.setup }
+      # Build asset representations
+      @assets.each { |p| p.build_reps }
+    rescue NotImplementedError
+      @assets = []
     end
 
-    def create_page(name, template_name='default')
-      load_data
+    # Loads this site's layouts.
+    def load_layouts
+      # Get layouts
+      @layouts = @data_source.layouts
 
-      template = @templates.find { |t| t[:name] == template_name }
-      error "A template named '#{template_name}' was not found; aborting." if template.nil?
+      # Fix layouts if outdated
+      if @layouts.any? { |l| l.is_a? Hash }
+        warn_data_source('Layout', 'layouts', true)
+        @layouts.map! { |l| Layout.new(l[:content], l, l[:path] || l[:name]) }
+      end
 
-      @data_source.loading { @data_source.create_page(name, template) }
+      # Set site
+      @layouts.each { |l| l.site = self }
     end
 
-    def create_template(name)
-      load_data
+    # Loads this site's templates.
+    def load_templates
+      # Get templates
+      @templates = @data_source.templates
 
-      @data_source.loading {@data_source.create_template(name) }
-    end
+      # Fix templates if outdated
+      if @templates.any? { |t| t.is_a? Hash }
+        warn_data_source('Template', 'templates', true)
+        @templates.map! { |t| Template.new(t[:content], t[:meta].is_a?(String) ? YAML.load(t[:meta]) : t[:meta], t[:name]) }
+      end
 
-    def create_layout(name)
-      load_data
+      # Set site
+      @templates.each { |t| t.site = self }
+    end
 
-      @data_source.loading { @data_source.create_layout(name) }
+    # Raises a warning about an outdated data source method.
+    def warn_data_source(class_name, method_name, is_array)
+      warn(
+        "In nanoc 2.1, DataSource##{method_name} should return #{is_array ? 'an array of' : 'a' } Nanoc::#{class_name} object#{is_array ? 's' : ''}. Future versions will not support these outdated data sources.",
+        'DEPRECATION WARNING'
+      )
     end
 
   end
+
 end

data/lib/nanoc/base/template.rb

@@ -0,0 +1,64 @@
+module Nanoc
+
+  # A Nanoc::Template represents a template, which can be used for creating
+  # new pages. Pages don't necessary have to be created using templates, but
+  # they can be useful for generating pages where you only have to "fill in
+  # the blanks".
+  class Template
+
+    # The Nanoc::Site this template belongs to.
+    attr_accessor :site
+
+    # The name of this template.
+    attr_reader :name
+
+    # The raw content a page created using this template will have.
+    attr_reader :page_content
+
+    # A hash containing the attributes a page created using this template will
+    # have.
+    attr_reader :page_attributes
+
+    # Creates a new template.
+    #
+    # +name+:: The name of this template.
+    #
+    # +page_content+:: The raw content a page created using this template will
+    #                  have.
+    #
+    # +page_attributes+:: A hash containing the attributes a page created
+    #                     using this template will have.
+    def initialize(page_content, page_attributes, name)
+      @page_content     = page_content
+      @page_attributes  = page_attributes.clean
+      @name             = name
+    end
+
+    # Saves the template in the database, creating it if it doesn't exist yet
+    # or updating it if it already exists. Tells the site's data source to
+    # save the template.
+    def save
+      @site.data_source.loading do
+        @site.data_source.save_template(self)
+      end
+    end
+
+    # Renames the template. Tells the site's data source to rename the
+    # template.
+    def move_to(new_name)
+      @site.data_source.loading do
+        @site.data_source.move_template(self, new_name)
+      end
+    end
+
+    # Deletes the template. Tells the site's data source to delete the
+    # template.
+    def delete
+      @site.data_source.loading do
+        @site.data_source.delete_template(self)
+      end
+    end
+
+  end
+
+end

data/lib/nanoc/binary_filters/image_science_thumbnail.rb

@@ -0,0 +1,28 @@
+module Nanoc::BinaryFilters
+
+  class ImageScienceThumbnail < Nanoc::BinaryFilter
+
+    identifier :image_science_thumbnail
+
+    def run(file)
+      require 'image_science'
+
+      # Get temporary file path
+      tmp_file = Tempfile.new('filter')
+      tmp_path = tmp_file.path
+      tmp_file.close
+
+      # Create thumbnail
+      ImageScience.with_image(file.path) do |img|
+        img.thumbnail(@asset_rep.thumbnail_size || 150) do |thumbnail|
+          thumbnail.save(tmp_path)
+        end
+      end
+
+      # Return thumbnail file
+      File.open(tmp_path)
+    end
+
+  end
+
+end

data/lib/nanoc/cli/base.rb

@@ -0,0 +1,219 @@
+module Nanoc::CLI
+
+  # Nanoc::CLI::Base is the central class representing a commandline nanoc
+  # tool. It has a list of commands, and is linked to a specific nanoc site.
+  class Base
+
+    attr_reader :commands, :site
+
+    # Creates a new instance of the commandline nanoc tool.
+    def initialize
+      create_commands
+    end
+
+    # Parses the given commandline arguments and executes the requested
+    # command.
+    def run(args)
+      # Check arguments
+      if args.length == 0
+        @help_command.run([], [])
+        exit 1
+      end
+
+      # Find version or help options
+      if args.length == 1
+        # Parse arguments
+        begin
+          parsed_arguments = Nanoc::CLI::OptionParser.parse(args[0..1], global_option_definitions)
+        rescue Nanoc::CLI::OptionParser::IllegalOptionError => e
+          $stderr.puts "illegal option -- #{e}"
+          exit 1
+        end
+
+        # Handle version option
+        if parsed_arguments[:options].has_key?(:version)
+          puts "nanoc #{Nanoc::VERSION} (c) 2007-2008 Denis Defreyne."
+          exit 1
+        # Handle help option
+        elsif parsed_arguments[:options].has_key?(:help)
+          show_help
+          exit 1
+        end
+      end
+
+      # Find command
+      command = command_named(args[0])
+
+      # Get extended option definitions (with help)
+      extended_option_definitions = command.option_definitions + [
+        # --help
+        {
+          :long => 'help', :short => 'h', :argument => :forbidden,
+          :desc => 'show this help message and quit'
+        },
+        # --verbose
+        {
+          :long => 'verbose', :short => 'V', :argument => :forbidden,
+          :desc => 'enable more detailed output'
+        }
+      ]
+
+      # Parse arguments
+      begin
+        parsed_arguments = Nanoc::CLI::OptionParser.parse(args[1..-1], extended_option_definitions)
+      rescue Nanoc::CLI::OptionParser::IllegalOptionError => e
+        $stderr.puts "illegal option -- #{e}"
+        exit 1
+      rescue Nanoc::CLI::OptionParser::OptionRequiresAnArgumentError => e
+        $stderr.puts "option requires an argument -- #{e}"
+        exit 1
+      end
+
+      # Check help option
+      if parsed_arguments[:options].has_key?(:help)
+        show_help(command)
+        exit 1
+      end
+
+      # Check verbose option
+      if parsed_arguments[:options].has_key?(:verbose)
+        Nanoc::CLI::Logger.instance.level = :low
+      end
+
+      # Find and run command
+      command.run(parsed_arguments[:options], parsed_arguments[:arguments])
+    end
+
+    # Returns the command with the given name.
+    def command_named(name)
+      # Find by exact name or alias
+      command = @commands.find { |c| c.name == name or c.aliases.include?(name) }
+      return command unless command.nil?
+
+      # Find by approximation
+      commands = @commands.select { |c| c.name[0, name.length] == name }
+      if commands.length > 1
+        $stderr.puts "nanoc: '#{name}' is ambiguous:"
+        $stderr.puts "  #{commands.map { |c| c.name }.join(' ') }"
+        exit 1
+      elsif commands.length == 0
+        $stderr.puts "nanoc: unknown command '#{name}'\n"
+        show_help
+        exit 1
+      else
+        return commands[0]
+      end
+    end
+
+    # Shows the help text for the given command, or shows the general help
+    # text if no command is given.
+    def show_help(command=nil)
+      if command.nil?
+        @help_command.run([], [])
+      else
+        @help_command.run([], [ command.name ])
+      end
+    end
+
+    # Helper function which can be called when a command is executed that
+    # requires a site, such as the compile command.
+    def require_site
+      if site.nil?
+        $stderr.puts 'The current working directory does not seem to be a ' +
+                     'valid/complete nanoc site directory; aborting.'
+        exit 1
+      end
+    end
+
+    # Gets the site (Nanoc::Site) in the current directory and loads its data.
+    def site
+      # Load site if possible
+      if File.file?('config.yaml') and @site.nil?
+        begin
+          @site = Nanoc::Site.new(YAML.load_file('config.yaml'))
+          @site.load_data
+        rescue Nanoc::Errors::UnknownDataSourceError => e
+          $stderr.puts "Unknown data source: #{e}"
+          exit 1
+        rescue Nanoc::Errors::UnknownRouterError => e
+          $stderr.puts "Unknown router: #{e}"
+          exit 1
+        rescue Exception => e
+          $stderr.puts "ERROR: An exception occured while loading this site."
+          $stderr.puts
+          $stderr.puts "If you think this is a bug in nanoc, please do report it at " +
+                       "<http://nanoc.stoneship.org/trac/newticket> -- thanks!"
+          $stderr.puts
+          $stderr.puts 'Message:'
+          $stderr.puts '  ' + e.message
+          $stderr.puts
+          $stderr.puts 'Backtrace:'
+          $stderr.puts e.backtrace.map { |t| '  - ' + t }.join("\n")
+          exit 1
+        end
+      end
+
+      @site
+    end
+
+    # Sets the data source's VCS to the VCS with the given name. Does nothing
+    # when the site's data source does not support VCSes (i.e. does not
+    # implement #vcs=).
+    def set_vcs(vcs_name)
+      # Skip if not possible
+      return if vcs_name.nil?
+      return if site.nil? or !site.data_source.respond_to?(:vcs=)
+
+      # Find VCS
+      vcs_class = Nanoc::Extra::VCS.named(vcs_name.to_sym)
+      if vcs_class.nil?
+        $stderr.puts "A VCS named #{vcs_name} was not found; aborting."
+        exit 1
+      end
+
+      # Set VCS
+      site.data_source.vcs = vcs_class.new
+    end
+
+    # Returns the list of global option definitionss.
+    def global_option_definitions
+      [
+        {
+          :long => 'help', :short => 'h', :argument => :forbidden,
+          :desc => 'show this help message and quit'
+        },
+        {
+          :long => 'version', :short => 'v', :argument => :forbidden,
+          :desc => 'show version information and quit'
+        }
+      ]
+    end
+
+  protected
+
+    def create_commands
+      @commands = []
+
+      # Find all command classes
+      command_classes = []
+      ObjectSpace.each_object(Class) do |klass|
+        command_classes << klass if klass < Nanoc::CLI::Command
+      end
+
+      # Create commands
+      command_classes.each do |klass|
+        if klass.to_s == 'Nanoc::CLI::HelpCommand'
+          @help_command = HelpCommand.new
+          @commands << @help_command
+        else
+          @commands << klass.new
+        end
+      end
+
+      # Set base
+      @commands.each { |c| c.base = self }
+    end
+
+  end
+
+end

data/lib/nanoc/cli/cli.rb

@@ -0,0 +1,16 @@
+module Nanoc::CLI # :nodoc:
+end
+
+# Load extensions
+Nanoc.load('cli', 'ext.rb')
+Nanoc.load('cli', 'option_parser.rb')
+
+# Load logger
+Nanoc.load('cli', 'logger.rb')
+
+# Load commands
+Nanoc.load('cli', 'command.rb')
+Nanoc.load('cli', 'commands', '*.rb')
+
+# Load base
+Nanoc.load('cli', 'base.rb')