class YARD::Serializers::FileSystemSerializer

Implements a serializer that reads from and writes to the filesystem.

Attributes

basepath[R]

The base path to write data to. @return [String] a base path

extension[R]

The extension of the filename (defaults to html)

@return [String] the extension of the file. Empty string for no extension.

Public Class Methods

new(opts = {}) click to toggle source

Creates a new FileSystemSerializer with options

@option opts [String] :basepath ('doc') the base path to write data to @option opts [String] :extension ('html') the extension of the serialized

path filename. If this is set to the empty string, no extension is used.
Calls superclass method YARD::Serializers::Base::new
# File lib/yard/serializers/file_system_serializer.rb, line 28
def initialize(opts = {})
  super
  @name_map = nil
  @basepath = (options[:basepath] || 'doc').to_s
  @extension = (options.key?(:extension) ? options[:extension] : 'html').to_s
end

Public Instance Methods

basepath=(value) click to toggle source
# File lib/yard/serializers/file_system_serializer.rb, line 10
def basepath=(value)
  @basepath = options[:basepath] = value
end
exists?(object) click to toggle source

Checks the disk for an object and returns whether it was serialized.

@param [CodeObjects::Base] object the object to check @return [Boolean] whether an object has been serialized to disk

# File lib/yard/serializers/file_system_serializer.rb, line 71
def exists?(object)
  File.exist?(File.join(basepath, serialized_path(object)))
end
extension=(value) click to toggle source
# File lib/yard/serializers/file_system_serializer.rb, line 19
def extension=(value)
  @extension = options[:extension] = value
end
serialize(object, data) click to toggle source

Serializes object with data to its serialized path (prefixed by the #basepath).

@return [String] the written data (for chaining)

# File lib/yard/serializers/file_system_serializer.rb, line 38
def serialize(object, data)
  path = File.join(basepath, serialized_path(object))
  log.debug "Serializing to #{path}"
  File.open!(path, "wb") {|f| f.write data }
end
serialized_path(object) click to toggle source

Implements the serialized path of a code object.

@param [CodeObjects::Base, CodeObjects::ExtraFileObject, String] object

the object to get a path for. The path of a string is the string itself.

@return [String] if object is a String, returns

object, otherwise the path on disk (without the basepath).
# File lib/yard/serializers/file_system_serializer.rb, line 50
def serialized_path(object)
  return object if object.is_a?(String)

  if object.is_a?(CodeObjects::ExtraFileObject)
    fspath = ['file.' + object.name + (extension.empty? ? '' : ".#{extension}")]
  else
    objname = object != YARD::Registry.root ? mapped_name(object) : "top-level-namespace"
    objname += '_' + object.scope.to_s[0, 1] if object.is_a?(CodeObjects::MethodObject)
    fspath = [objname + (extension.empty? ? '' : ".#{extension}")]
    if object.namespace && object.namespace.path != ""
      fspath.unshift(*object.namespace.path.split(CodeObjects::NSEP))
    end
  end

  File.join(encode_path_components(*fspath))
end

Private Instance Methods

build_filename_map() click to toggle source

Builds a filename mapping from object paths to filesystem path names. Needed to handle case sensitive YARD objects mapped into a case insensitive filesystem. Uses with {#mapped_name} to determine the mapping name for a given object.

@note In order to use filesystem name mapping, you must initialize

the serializer object after preparing the {YARD::Registry}.
# File lib/yard/serializers/file_system_serializer.rb, line 84
def build_filename_map
  @name_map = {}
  YARD::Registry.all.each do |object|
    lpath = nil
    if object.parent && object.parent.type != :root
      lpath = object.parent.path + "::" + object.name.to_s.downcase
    else
      lpath = object.path.downcase
    end

    @name_map[lpath] ||= {}
    size = @name_map[lpath].size
    name = "#{object.name}#{size > 0 ? "_" * size : ""}"
    @name_map[lpath][object.name] = name
  end
end
encode_path_components(*components) click to toggle source

Remove special chars from filenames. Windows disallows \ / : * ? “ < > | but we will just remove any non alphanumeric (plus period, underscore and dash).

# File lib/yard/serializers/file_system_serializer.rb, line 111
def encode_path_components(*components)
  components.map! do |p|
    p.gsub(/[^\w\.-]/) do |x|
      encoded = String.new('_')

      x.each_byte {|b| encoded << ("%X" % b) }
      encoded
    end
  end
end
mapped_name(object) click to toggle source

@return [String] the filesystem mapped name of a given object.

# File lib/yard/serializers/file_system_serializer.rb, line 102
def mapped_name(object)
  build_filename_map unless @name_map
  map = @name_map[object.path.downcase]
  map && map[object.name] ? map[object.name] : object.name.to_s
end