# Pathena file-type class definition

from file_type_attribs import *

# ============== Do not change anything above this line ==============

# This template is used to add Pathena handlers for "special" files,
# i.e., files whose types cannot be recognized simply by their extensions,
# as can files of type "ps" or "pdf".  Special files are associated with
# an application or class of applications.  They are usually localized to
# one or several directory subtrees, and might require nontrivial conversion
# to extract a usable text form.  E-mail files in "maildir" format are
# an example of special files.

# To add a new special type "abc/xyz", copy this template to file
# "abc_xyz.py" in the "types" subdirectory, then edit the indicated
# variables.

# NOTE: This file is processed as a Python source module.  You will
# need some familiarity with Python programming to create the necessary
# class definition.  Examples are provided to guide you.


# Additional module imports:

# import email_utils


# Provide the file species name as a string.  The genus name will
# come from the parent class.

species_name = ''

# Example:
# species_name = 'maildir'

# NOTE: If more than one variant of a special file type is to be indexed,
# each should be given its own species, e.g., "message" and "folder".


# Replace <Genus_Class> by an actual class from the file
# lib/file_type_attribs.py.  Example: Email_Genus.

class Special_Type(<Genus_Class>):

    def __init__(self, name):
        <Genus_Class>.__init__(self, name)

    phylum = 'special'

#    font_class = 'sans'    # or 'serif', 'fixed'
    
#    external_viewers = None
#    external_editors = None

    # List of OS/shell commands needed by file conversion methods.

#    commands_needed = ()

    # This is the primary method for retrieving a file's contents and
    # converting to text, with possible variation for different uses.
    # Usage key:  0 = display, 1 = indexing, 2 = headline generation,
    #             3 = cached conversion

#    def convert_file(self, path, usage=0):
#        return file_converter(path)

    # If a meaningful title or displayable metadata can be derived for
    # a file, override these methods.  Optional arg orig_path is used
    # when path refers to a temporary file.

#    def extract_title(self, path, orig_path=None):
#        return os.path.basename(path)
    
#    def extract_metadata(self, path, orig_path=None):
#	 return ''

    # Following used for special files only.  It should return a pair
    # of booleans (use_path, include_content), where include_content 
    # indicates if a file is to be indexed as part of the special class.
    # use_path indicates whether to use or suppress path name indexing.

#    def recognize_file(self, path, file_name):
#        return (None, None)

    # Choose what portions of a path to include for indexing.
    
#    def path_excerpt(self, path):
#        return path


#----------- Notes ------------

# external_viewers:
#
# Provide a list or tuple of shell/OS commands suitable for invoking an
# external viewer on files of the indicated type.  Each command should
# accept a file name argument for reading its input and should launch
# a window-based viewer to display the file.
# The tuple should have this form:   ((<display_name>, <command>),...)
#
# Example:
#    external_viewers = (('xpdf', 'xpdf %s'),
#                        ('gv',   'gv %s'))

# external_editors:
#
# This is an attribute similar to external_viewers except the commands
# will invoke a suitable editing tool.

# convert_file method:
#
# Provide a method that accepts a path name and converts a file of
# the given type to plain text form.  The converter may translate
# textual content from an encoded form, create a directory listing,
# extract excerpts, or merely pull out a few items of metadata.  
# With argument 'usage' you can vary the output based on time of
# invocation (display, indexing or headline generation).
#
# Example:
#    shell_command = make_shell_command('pdftotext %s')
#    def convert_file(self, path, usage=0):
#        return self.shell_command(path)

# extract_title:
#
# This method is similar to convert_file except that only a document
# title is returned where available.

# extract_metadata:
#
# This method is similar to extract_title except that a text string of
# suitable metadata is returned where appropriate.

# recognize_file method:
#
# Special files are recognized by this predicate, which decides whether
# to include a file based on its path name or file name.  Result is a
# pair of booleans (use_path, include_content), which allows indexing of
# generated file names to be suppressed.
#
# Example:
#    def recognize_file(self, path, file_name):
#        include = os.path.isfile(path) and \
#                  not file_name.startswith('.') and \
#                  os.path.split(os.path.dirname(path))[1] == 'cur'
#        return (1, include)

# path_excerpt method:
#
# Path names submitted for indexing are preprocessed by this method,
# allowing less meaningful portions of a path to be suppressed.
#
# Example:    
#    def path_excerpt(self, path):
#        return os.path.split(os.path.split(path)[0])[0]


# ============== Do not change anything below this line ==============

register_type_class(Special_Type(species_name))
