Perl extension for generating Doxygen documentation. More...

Inheritance diagram for Doxygen::Source:

Public Member Functions
	new (%flags)
	Constructor for Doxygen::Source objects.
	DESTROY ()
	parse ($path)
	Parse the specified source file.
	spawn ($doctype, $path)
	Spawn a sub-process via `system()` to execute a program to handle the current path.
	massage ()
	Massage items in file after parsing and before generating.
	generate (%flags)
	Generates output understandable by doxygen to standard output.
	entity ()
	Return the top node from the entity stack.
	entityPop ($entity)
	Pop the top entity from the entity stack.
	entityPush ($entity)
	Push a new current entity on the stack.
	flag ($name, $docType)
	Return value of named flag in source context.
	focus ()
	Return the current focus for adding comment lines.
	getFile ($path)
	Get file object for this filter object, creating object if necessary.
	log ($code,@@stuff)
	Formatted logging function.
	popLog ()
	Pop the last indentation level from the logging stream.
	pushLog ($spaces)
	Indent the logging functionality accessible via log().
	_warning_ ($stuff)
	Special logging call used for trapping warnings.
	_commentPattern_ ($string)
	Convert a string into a pattern for recognizing a comment.
	_filterPattern_ ($string)
	Convert a string into a pattern for recognizing a comment.
	_flagValue_ ($string)
	Evaluate a string (or pattern) representing a flag value.
	_suffixPattern_ ($string)
	Convert a string into a pattern for recognizing a suffix.

Detailed Description

Perl extension for generating Doxygen documentation.

SYNOPSIS

  my  $source = new Doxygen::Source($path);
  
  $source->generate;

ABSTRACT

Represents a single source file to be filtered for Doxygen.

A newly created instance requires a pathname, from which text is read. Zero or more parsers will be passed against the source text, storing interim state (Doxygen::Item objects) on the Source object.

When the parsing is complete, use the object to generate Doxygen-enabled output.

DESCRIPTION

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Version:: '0.01'

Author:: Marc M. Adkins, mailTo:Perl@Doorways.org

Definition at line 53 of file Source.pm.

Member Function Documentation

Doxygen::Source::_commentPattern_ ( $ string )

Convert a string into a pattern for recognizing a comment.

Todo:: handle qr()im flags

Doxygen::Source::_filterPattern_ ( $ string )

Convert a string into a pattern for recognizing a comment.

Todo:: handle qr()im flags

Doxygen::Source::_flagValue_ ( $ string )

Evaluate a string (or pattern) representing a flag value.

Todo:: handle qr()im flags

Doxygen::Source::_suffixPattern_ ( $ string )

Convert a string into a pattern for recognizing a suffix.

Todo:: handle qr()i flag

Doxygen::Source::_warning_ ( $ stuff )

Special logging call used for trapping warnings.

Breaks up standard warning text so it doesn't overwrite lines in log.

Doxygen::Source::DESTROY ( )

Doxygen::Source::entity ( )

Return the top node from the entity stack.

The entity stack is for source entities. The stack always starts with a Doxygen::Item::File object to represent the file being parsed. Other objects that may be placed on the stack :

In general a file object will be on the bottom, then a class object (if applicable) and finally a function object.

Doxygen::Source::entityPop ( $ entity )

Pop the top entity from the entity stack.

If the $entity argument is defined, pop all entities down to and including that specified.

Doxygen::Source::entityPush ( $ entity )

Push a new current entity on the stack.

The stack starts with just the file object.

Parameters:

$entity

The entity to be pushed onto the stack.

Doxygen::Source::flag	(	$	name,
		$	docType
	)

Return value of named flag in source context.

Flags are specified at source creation. Flags are named either docType::flagName or flagName. The former describe flags specific to document types (filter types) and only visible to filters of the specified document type. In addition, the former, where applicable, override the latter. The latter are global to all filters and act as global flags and/or default values for specific flags.

When a flag is requested by name, if a $docType is specified it will be used to check for a filter-specific value first, then for the global value. The argument should be either the name of a filter class or an object of a filter class.

The $name argument should never specify names of the form docType::flagName, as that is specified via the optional $docType parameter.

Doxygen::Source::focus ( )

Return the current focus for adding comment lines.

Defaults to the value for the current source entity, but may be overridden by descendant classes modelling language-specific documentation entities.

Returns:: A doxy::Item object.

Doxygen::Source::generate ( % flags )

Generates output understandable by doxygen to standard output.

Should be run after running massage().

Must be overloaded by derived subclasses.

Reimplemented from Doxygen::Item.

Doxygen::Source::getFile ( $ path )

Get file object for this filter object, creating object if necessary.

  my  $file = $target->getFile($path);

The file object should be created early using the path so that it can be referred to freely without the pathname later:

  $doc->getFile->append($text);

Doxygen::Source::log	(	$	code,
		@@	stuff
	)

Formatted logging function.

The $code is a single-character from the following set:

I: Info
T: Trace
W: Warning
E: Error

Doxygen::Source::massage ( )

Massage items in file after parsing and before generating.

Each filter may have a massage method and/or a parse method. The order of parsing and massaging is undefined except that all parsing will complete prior to any massaging being done.

For the Source object, massage must iterate through the set of filters created during the parse phase and call the massage method on each one.

Doxygen::Source::new ( % flags )

Constructor for Doxygen::Source objects.

Takes a series of flags which initialize object fields. If the path flag is set the object is immediately parsed, otherwise it must be done later.

Useful flags:

info

If set to false will turn off the generation of 'informational' ([I]) log messages.

type

A hash reference that contains a series of objects that control how pathnames are processed or not processed. In general, the sub-objects specify regular expressions that are matched against pathnames.

In all cases regular expressions may be replaced by simple strings that are converted into regular expressions using the following expression:

    qr(\.$strings$)i

The following sub-flags may be specified within the type hash:

alias: Causes specific filter names to be handled by different filters. For example, Batch and Shell are both handled by the instantiated Script filter. There are no Batch and Shell filters (unless you instantiate them yourself). Each key can have a single value, new ones replace old ones, setting a key to point to itself is equivalent to removing it.
check: Specifies patterns for filters to see if files without suffixes are destined for these filters. For example, specify a pattern for the first line of a shell file (qr(^#!/bin/(?:ba|c|k|z)sh\b)) which may show up without a suffix. The keys are filter names, (e.g. Shell). Each key can have a single comment pattern, and a new one with the same key replaces the older one with that key.
cmnt: A hash reference to a list of keys and comment recognition patterns. The patterns must each have a single returned value ($1), that is to say, they must each return the comment text found. The keys are filter names, (e.g. Batch). Each key can have a single comment pattern, and a new one with the same key replaces the older one with that key.
docs: A hash reference to a list of keys and suffixes. The keys are filter names, for example POD invokes Doxygen::POD::Filter. Each key can have a single suffix pattern, and a new one with the same key replaces the older one with that key.
pass: An array reference to a list of suffixes that should be passed through unprocessed. Values are cumulative with the default value (qr(\.doxy?)i) but can be overidden by setting docs.
spawn: Hash reference from document types to command-line invocations. Define the suffix and document type in docs then define the spawning command line using the document type name as the key. The command line can have {} as a placeholder for the pathname of the file to be processed or it will be appended to the end.

path

Pathname of file to be parsed into the object. Calls Parse() method with the value after other initialization. The same can be done separately.

stats

Turns statistics generation on or off. Defaults to on, set to non-true value to override.

trace

Turns on generation of tracing ([T]) and hacking ([H]) messages.

Takes a pathname ($path) as an argument. During the construction of the object parses the file thus specified using as many applicable filters are possible.

If no filters apply, returns undef to indicate that other action is required (the file needs to be copied through).

In the latter case, if the pathname doesn't match one of the 'pass through' patterns a warning is logged.

Reimplemented from Doxygen::Item.

Doxygen::Source::parse ( $ path )

Parse the specified source file.

Applies all appropriate parsers the the source file. Each parser is able to store information on itself or this Doxygen::Source object.

Doxygen::Source::popLog ( )

Pop the last indentation level from the logging stream.

Doxygen::Source::pushLog ( $ spaces )

Indent the logging functionality accessible via log().

Specify the $spaces (as the actual indentation string) or it defaults to 2.

Doxygen::Source::spawn	(	$	doctype,
		$	path
	)

Spawn a sub-process via system() to execute a program to handle the current path.

The documentation for this class was generated from the following file:

Source/Source.pm

DoxyFilt: Doxygen::Source Class Reference

Doxygen::Source Class Reference