Up

AGSParser...a class to get documention info from ObjC source

Authors

Richard Frith-Macdonald (richard@brainstorm.co.uk)
This is the AGSParser class... and some autogsdoc examples. The AGSParser class is designed to produce a property-list which can be handled by AGSOutput... one class is not much use without the other.

Copyright: (C) 2001 Free Software Foundation, Inc.

Software documentation for the AGSParser class

AGSParser : NSObject

Declared in:
AGSParser.h
Availability: OpenStep

The AGSParser class parses Objective-C header and source files to produce a property-list which can be handled by AGSOutput .

Instance Variables

Method summary

info 

- (NSMutableDictionary*) info;
Availability: OpenStep

Description forthcoming.

init 

- (id) init;
Availability: OpenStep

This is a designated initialiser for the class.
Simple initialiser

orderedSymbolDeclarationsByUnit 

- (NSDictionary*) orderedSymbolDeclarationsByUnit;
Availability: OpenStep

Returns the methods, functions and C data types in their header declaration order, by organizing them into arrays as described below. Methods are grouped by class, category or protocol references. For example, valid keys could be ClassName, ClassName(CategoryName) and (ProtocolName). Functions and C data types are grouped by header file names. For example, AGParser.h would a valid key. TODO: Collect functions and C data types. Only methods are currently included in the returned dictionary.

outputs 

- (NSMutableArray*) outputs;
Availability: OpenStep

Return the list of known output files depending on this source/header.
If there are any classes, categories, or protocols, there will be an output file for them whose name is based on the name of the header.
If there are any constants, variables, typedefs or functions, there will either be a shared output file for them (defined by a template name set in the user defaults system), or they will go in the same file as classes etc.

parseComment 

- (unsigned) parseComment;
Availability: OpenStep

In spite of its trivial name, this is one of the key methods - it parses and skips past comments, but it also recognizes special comments (with an additional asterisk after the start of the block comment) and extracts their contents, accumulating them into the 'comment' instance variable.
When the data provided by a comment is appended to the data stored in the 'comment' instance variable, a line break (<br />)is automatically forced to separate it from the proceding info.
In addition, the first extracted documentation is checked for the prsence of file header markup, which is extracted into the 'info' dictionary.
There are various sections we can extract from the document - at most one of each. If date and version are not supplied RCS Date and Revision tags will be extracted where available.

parseDeclaration 

- (NSMutableDictionary*) parseDeclaration;
Availability: OpenStep

We handle struct, union, and enum declarations by skipping the stuff enclosed in curly braces. If there was an identifier after the keyword we use it as the struct name, otherwise we use '...' to denote a nameless type.

parseFile: isSource: 

- (NSMutableDictionary*) parseFile: (NSString*)name isSource: (BOOL)isSource;
Availability: OpenStep

If this is parsing a header file (isSource == NO) then we reset the list of known source files associated with the header before proceeding.
We initially assume that the location of a source file is the same as the header, but if there is no file at that location, we expect the source to be in the documentatation directory or the current directory instead.

parseIdentifier 

- (NSString*) parseIdentifier;
Availability: OpenStep

Attempt to parse an identifier/keyword (with optional whitespace in front of it). Perform mappings using the wordMap dictionary. If a mapping produces an empty string, we treat it as if we had read whitespace and try again. If we read end of data, or anything which is invalid inside an identifier, we return nil.

parseImplementation 

- (NSMutableDictionary*) parseImplementation;
Availability: OpenStep

Description forthcoming.

parseInstanceVariables 

- (NSMutableDictionary*) parseInstanceVariables;
Availability: OpenStep

Description forthcoming.

parseInterface 

- (NSMutableDictionary*) parseInterface;
Availability: OpenStep

Description forthcoming.

parseMacro 

- (NSMutableDictionary*) parseMacro;
Availability: OpenStep

Parse a macro definition... we are expected to have read #define already
It's common to have macros which don't need commenting... like the ones used to protect a header against multiple inclusion for instance. For this reason, we ignore any macro which is not preceded by a documentation comment.

parseMethodIsDeclaration: 

- (NSMutableDictionary*) parseMethodIsDeclaration: (BOOL)flag;
Availability: OpenStep

Description forthcoming.

parseMethodType 

- (NSString*) parseMethodType;
Availability: OpenStep

Description forthcoming.

parseMethodsAreDeclarations: 

- (NSMutableDictionary*) parseMethodsAreDeclarations: (BOOL)flag;
Availability: OpenStep

Description forthcoming.

parsePreprocessor 

- (unsigned) parsePreprocessor;
Availability: OpenStep

Parse a preprocessor statement, handling preprocessor conditionals in a rudimentary way. We keep track of the level of conditional nesting, and we also track the use of #ifdef and #ifndef with some well-known constants to tell us which standards are currently supported.

parseProtocol 

- (NSMutableDictionary*) parseProtocol;
Availability: OpenStep

Description forthcoming.

parseProtocolList 

- (NSMutableArray*) parseProtocolList;
Availability: OpenStep

Description forthcoming.

parseSpace 

- (unsigned) parseSpace;
Availability: OpenStep

Description forthcoming.

parseSpace: 

- (unsigned) parseSpace: (NSCharacterSet*)spaceSet;
Availability: OpenStep

Skip past any whitespace characters (as defined by the supplied set) including comments.
Calls parseComment if neccesary, ensuring that any documentation in comments is appended to our 'comment' ivar.

parseVersion 

- (NSString*) parseVersion;
Availability: OpenStep

Description forthcoming.

reset 

- (void) reset;
Availability: OpenStep

Description forthcoming.

setDeclared: 

- (void) setDeclared: (NSString*)name;
Availability: OpenStep

Set the name of the file in which classes are to be documented as being declared. The default value of this is the last part of the path of the source file being parsed.

setDocumentAllInstanceVariables: 

- (void) setDocumentAllInstanceVariables: (BOOL)flag;
Availability: OpenStep

This method is used to enable (or disable) documentation of all instance variables. If it is turned off, only those instance variables that are explicitly declared 'public' or 'protected' will be documented.

setDocumentInstanceVariables: 

- (void) setDocumentInstanceVariables: (BOOL)flag;
Availability: OpenStep

This method is used to enable (or disable) documentation of instance variables. If it is turned off, instance variables will not be documented.

setGenerateStandards: 

- (void) setGenerateStandards: (BOOL)flag;
Availability: OpenStep

Turn on or off parsing of preprocessor conditional compilation info indicating the standards complied with. When this is turned on, we assume that all standards are complied with by default.
You should only turn this on while parsing the GNUstep source code.

setStandards: 

- (void) setStandards: (NSMutableDictionary*)dict;
Availability: OpenStep

Store the current standards information derived from preprocessor conditionals in the supplied dictionary... this will be used by the AGSOutput class to put standards markup in the gsdoc output.

setWordMap: 

- (void) setWordMap: (NSDictionary*)map;
Availability: OpenStep

Sets up a dictionary used for mapping identifiers/keywords to other words. This is used to help cope with cases where C preprocessor definitions are confusing the parsing process.

setupBuffer 

- (void) setupBuffer;
Availability: OpenStep

Read in the file to be parsed and store it in a temporary unicode buffer. Perform basic transformations on the buffer to simplify the parsing process later - including stripping out of escaped end-of-line sequences. Create mapping information to convert positions in the new character buffer to line numbers in the original data (for logging purposes).

skipArray 

- (unsigned) skipArray;
Availability: OpenStep

Skip until we encounter an ']' marking the end of an array. Expect the current character position to be pointing to the '[' at the start of an array.

skipBlock 

- (unsigned) skipBlock;
Availability: OpenStep

Skip a bracketed block. Expect the current character position to be pointing to the bracket at the start of a block.

skipBlock: 

- (unsigned) skipBlock: (BOOL*)isEmpty;
Availability: OpenStep

Description forthcoming.

skipLiteral 

- (unsigned) skipLiteral;
Availability: OpenStep

Description forthcoming.

skipRemainderOfLine 

- (unsigned) skipRemainderOfLine;
Availability: OpenStep

Description forthcoming.

skipSpaces 

- (unsigned) skipSpaces;
Availability: OpenStep

Description forthcoming.

skipStatement 

- (unsigned) skipStatement;
Availability: OpenStep

Skip until we encounter a semicolon or closing brace. Strictly speaking, we don't skip all statements that way, since we only skip part of an if...else statement.

skipStatementLine 

- (unsigned) skipStatementLine;
Availability: OpenStep

Special method to skip a statement and up to the end of the last line it was on, discarding any comments so they don't get used by the next construct that actually needs documenting.

skipToEndOfLine 

- (unsigned) skipToEndOfLine;
Availability: OpenStep

Description forthcoming.

skipUnit 

- (unsigned) skipUnit;
Availability: OpenStep

Skip until we encounter an '@end' marking the end of an interface, implementation, or protocol.

sources 

- (NSMutableArray*) sources;
Availability: OpenStep

Description forthcoming.



Instance Variables for AGSParser Class

buffer

@protected unichar* buffer;
Availability: OpenStep

Description forthcoming.

comment

@protected NSString* comment;
Availability: OpenStep

Documentation accumulator.

commentsRead

@protected BOOL commentsRead;
Availability: OpenStep

Description forthcoming.

declared

@protected NSString* declared;
Availability: OpenStep

Where classes were declared.

documentAllInstanceVariables

@protected BOOL documentAllInstanceVariables;
Availability: OpenStep

Description forthcoming.

documentInstanceVariables

@protected BOOL documentInstanceVariables;
Availability: OpenStep

Description forthcoming.

fileName

@protected NSString* fileName;
Availability: OpenStep

Not retained - file being parsed.

haveOutput

@protected BOOL haveOutput;
Availability: OpenStep

Description forthcoming.

haveSource

@protected BOOL haveSource;
Availability: OpenStep

Description forthcoming.

identStart

@protected NSCharacterSet* identStart;
Availability: OpenStep

Legit initial char of identifier

identifier

@protected NSCharacterSet* identifier;
Availability: OpenStep

Legit char in identifier

ifStack

@protected NSMutableArray* ifStack;
Availability: OpenStep

Track preprocessor conditionals.

inArgList

@protected BOOL inArgList;
Availability: OpenStep

Description forthcoming.

inHeader

@protected BOOL inHeader;
Availability: OpenStep

Description forthcoming.

inInstanceVariables

@protected BOOL inInstanceVariables;
Availability: OpenStep

Description forthcoming.

inUnclosedExample

@protected BOOL inUnclosedExample;
Availability: OpenStep

Description forthcoming.

info

@protected NSMutableDictionary* info;
Availability: OpenStep

All information parsed.

itemName

@protected NSString* itemName;
Availability: OpenStep

Not retained - item being parsed.

length

@protected unsigned int length;
Availability: OpenStep

Description forthcoming.

lines

@protected NSArray* lines;
Availability: OpenStep

Not retained - line number mapping.

orderedSymbolDeclsByUnit

@protected NSMutableDictionary* orderedSymbolDeclsByUnit;
Availability: OpenStep

Description forthcoming.

pos

@protected unsigned int pos;
Availability: OpenStep

Description forthcoming.

source

@protected NSMutableArray* source;
Availability: OpenStep

Names of source files.

spacenl

@protected NSCharacterSet* spacenl;
Availability: OpenStep

Blanks excluding newline

spaces

@protected NSCharacterSet* spaces;
Availability: OpenStep

All blank characters

standards

@protected BOOL standards;
Availability: OpenStep

Description forthcoming.

unitName

@protected NSString* unitName;
Availability: OpenStep

Not retained - unit being parsed.

verbose

@protected BOOL verbose;
Availability: OpenStep

Description forthcoming.

warn

@protected BOOL warn;
Availability: OpenStep

Description forthcoming.

wordMap

@protected NSDictionary* wordMap;
Availability: OpenStep

Description forthcoming.





Up