123456789_123456789_123456789_123456789_123456789_

Class: YARD::Serializers::FileSystemSerializer

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
YardocSerializer, YARD::Server::DocServerSerializer
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Base
Instance Chain:
self, Base
Inherits: YARD::Serializers::Base
Defined in: lib/yard/serializers/file_system_serializer.rb

Overview

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

Class Method Summary

Base - Inherited

.new

Creates a new serializer with options.

Instance Attribute Summary

Base - Inherited

#options

All serializer options are saved so they can be passed to other serializers.

Instance Method Summary

Base - Inherited

#after_serialize

Called after serialization.
#before_serialize

Called before serialization.
#exists?

Returns whether an object has been serialized.
#serialize

Serializes an object.
#serialized_path

The serialized path of an object.

Constructor Details

.new(opts = {}) ⇒ FileSystemSerializer

Creates a new FileSystemSerializer with options

Parameters:

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

    a customizable set of options

Options Hash (opts):

  • :basepath (String) — default: 'doc' —

    the base path to write data to

  • :extension (String) — default: 'html' —

    the extension of the serialized path filename. If this is set to the empty string, no extension is used.

[ GitHub ] 

  


# 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


  







Instance Attribute Details



  

    #basepath  ⇒ String  (rw)
  



  

    
The base path to write data to.


  





  
Returns:





  [ GitHub ]


  

  


# File 'lib/yard/serializers/file_system_serializer.rb', line 8



attr_reader :basepath


  








  

    #basepath=(value)   (rw)
  

  [ GitHub ]


  

  


# File 'lib/yard/serializers/file_system_serializer.rb', line 10



def basepath=(value)
  @basepath = options[:basepath] = value
end


  








  

    #extension  ⇒ String  (rw)
  



  

    
The extension of the filename (defaults to html)


  





  
Returns:


    
  
  • 
    (String)
—    
    the extension of the file. Empty string for no extension.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/serializers/file_system_serializer.rb', line 17



attr_reader :extension


  








  

    #extension=(value)   (rw)
  

  [ GitHub ]


  

  


# File 'lib/yard/serializers/file_system_serializer.rb', line 19



def extension=(value)
  @extension = options[:extension] = value
end


  







Instance Method Details



  

    #build_filename_map   (private)
  



  

    
  

    Note:
    
In order to use filesystem name mapping, you must initialize
the serializer object after preparing the ::YARD::Registry.



  



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.


  



  [ GitHub ]


  

  


# 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)   (private)
  



  

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


  



  [ GitHub ]


  

  


# 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


  








  

    #exists?(object)  ⇒ Boolean 
  



  

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


  





  
Parameters:



Returns:


    
  
  • 
    (Boolean)
—    
    whether an object has been serialized to disk
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/serializers/file_system_serializer.rb', line 71



def exists?(object)
  File.exist?(File.join(basepath, serialized_path(object)))
end


  








  

    #mapped_name(object)  ⇒ String  (private)
  



  

    
  





  
Returns:


    
  
  • 
    (String)
—    
    the filesystem mapped name of a given object.
    

    
  
    • 





  [ GitHub ]


  

  


# 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


  








  

    #serialize(object, data)  ⇒ String 
  



  

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


  





  
Returns:


    
  
  • 
    (String)
—    
    the written data (for chaining)
    

    
  
    • 





  [ GitHub ]


  

  


# 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)  ⇒ String 
  



  

    
Implements the serialized path of a code object.


  





  
Parameters:



Returns:


    
  
  • 
    (String)
—    
    if object is a ::String, returns
object, otherwise the path on disk (without the basepath).
    

    
  
    • 





  [ GitHub ]


  

  


# 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