class YARD::Serializers::FileSystemSerializer
Implements a serializer that reads from and writes to the filesystem.
Attributes
The base path to write data to. @return [String] a base path
The extension of the filename (defaults to html
)
@return [String] the extension of the file. Empty string for no extension.
Public Class Methods
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.
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
# File lib/yard/serializers/file_system_serializer.rb, line 10 def basepath=(value) @basepath = options[:basepath] = value end
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
# File lib/yard/serializers/file_system_serializer.rb, line 19 def extension=(value) @extension = options[:extension] = value end
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
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
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
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
@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