CommandLineParser class reference

Inherits from	NSObject
Declared in	CommandLineParser.h CommandLineParser.m

Overview

This class parses the utility command line arguments and provides the values.

Since the class already knows how to interpret command line arguments, including verbose levels, which are used throughout the whole application objects, the class is implemented as a singleton.

Tasks

Properties - required

commandLine property The command line path to the executable including full path.
projectName property Project name.
inputPath property The path to the source files.
outputPath property The path to the output files (sub directories are created within this location).

Properties - doxygen

doxygenCommandLine property The command line to the doxygen utility including full path.
doxygenConfigFilename property The path to the doxygen configuration file including full path.

Properties - clean XML creation

fixClassLocations property If YES, class locations are fixed if (possibly) invalid location is detected.
removeEmptyParagraphs property If YES, empty paragraphs should be removed from clean XML.
mergeKnownCategoriesToClasses property If YES, documentation for categories to known classes should be merged to the class documentation.
keepMergedCategorySections property If YES, merged categories method sections should be preserved in the class.
objectReferenceTemplate property The template for creating references to members of another objects.
memberReferenceTemplate property The template for creating references to members of the same object.
dateTimeTemplate property The template for formatting date/time strings.

Properties - clean output creation

createCleanXHTML property If YES, clean XHTML documentation is created.
createDocSet property If YES, documentation set is created.
createMarkdown property If YES, Markdown documentaiton is created.

Properties - XHTML output creation

xhtmlUseBorderedExamples property If YES, use bordered XHTML example sections which results in more Apple like documentation.
xhtmlUseBorderedWarnings property If YES, use bordered XHTML warning sections which results in more Apple like documentation.
xhtmlUseBorderedBugs property If YES, use bordered XHTML bug sections which results in more Apple like documentation.

Properties - documentation set creation

docsetBundleID property The documentation set unique bundle ID.
docsetBundleFeed property The documentation set bundle feed which is displayed in the Xcode documentation window.
docsetSourcePlistPath property The documentation set source plist which contains identification and description.
docsetutilCommandLine property The docsetutil command line including full path.
docsetInstallPath property The documentation set installation path.

Properties - Markdown creation

markdownReferenceStyleLinks property If YES, object files links are created using reference style, otherwise inline links are created.
markdownLineLength property The maximum number of chars to use in one line.
markdownLineWrapThreshold property The minimum number of chars in the line before considering wrapping.
markdownLineWrapMargin property The maximum number of chars to use in one line.

Properties - miscellaneous

templatesPath property The path to the template files and global options.
cleanTempFilesAfterBuild property If YES, temporary files are removed after generation.
cleanOutputFilesBeforeBuild property If YES, the outputPath is deleted before starting processing.
verboseLevel property The desired verbose level.

Properties - undocumented

emitUtilityOutput property This is used to show or hide the output from the external utilities such as doxygen and docsetutil.

Initialization & disposal

+ sharedInstance Returns the shared instance of the class which can be used throughout the application.

Parsing handling

- parseCommandLineArguments:ofCount: Parses the given command line arguments and set ups the object values.
- printUsage Outputs the utility usage to the standard output.

CommandLineParser(ClassPrivateAPI)

- setupGlobalTemplates Setups the templates path.
- parseTemplatesPath: Determines if the given path is a valid templates path or not.
- validateCommandLineArguments Validates command line arguments after parsing.
- postProcessCommandLineArguments Post-processes command line arguments.
- setupFactoryDefaults Resets all parsed properties and variables required for parsing.
- replaceTemplatePlaceholdersForKey: Replaces template placeholders for the given parameters key.
- standardizePathForKey: Standardizes the path for the given parameters key.
- parseStringWithShortcut:andName:forKey: Parses the assigned command line for the string with the given name or shortcut.
- parseIntegerWithShortcut:andName:forKey: Parses the assigned command line for the integer with the given name or shortcut.
- parseBooleanWithShortcut:andName:withValue:forKey: Parses the assigned command line for the switch with the given name or shortcut.
- logCmdLineSwitch:andName:andValue: Logs the given command line switch usage as debug log entry.

Class methods

sharedInstance

Returns the shared instance of the class which can be used throughout the application.

+ (CommandLineParser *)sharedInstance

Discussion

To make the class as accessible for the rest of the application, it is implemented as a singleton through + sharedInstance. Although nothing will prevent clients creating additional instances, it is reccommended to use the singleton interface to prevent possible problems.

Declared in

CommandLineParser.h

Instance methods

parseCommandLineArguments:ofCount:

Parses the given command line arguments and set ups the object values.

- (void)parseCommandLineArguments:(const char **)        argv
 ofCount:(int)        argc

Parameters

argv: The array of zero terminated c strings.
argc: The number of items in the argv array.

Exceptions

NSException: Thrown if parsing fails.

Discussion

This message must be sent to the class after construction before all the properties can be used. It will parse and validate the given arguments. If any inconsistency is detected, an exception will be thrown. After parsing all command line arguments, the method checks if all required data is provided and returns YES if so. If not, it returns NO which indicates that the user doesn't know how to use the utility and - printUsage should probably be called.

Note that parsing code may be called as many times as needed. Eact time, the properties are reset and then the given command line parsed.

Declared in

CommandLineParser.h

printUsage

Outputs the utility usage to the standard output.

- (void)printUsage

Declared in

CommandLineParser.h

setupGlobalTemplates

Setups the templates path.

- (void)setupGlobalTemplates

Discussion

This method checks if template files are found on one of the known locations. It searches the following paths in this order:

~/.appledoc/
~/Library/Application Support/appledoc/ If all required template files are found in one of these paths, the template path is automatically set to it.

This will send - parseTemplatesPath: message for each known location.

Declared in

CommandLineParser.m

parseTemplatesPath:

Determines if the given path is a valid templates path or not.

- (BOOL)parseTemplatesPath:(NSString *)        path

Parameters

path: The path to test.

Return value

Returns YES if the given path is valid templates path, NO otherwise.

Discussion

A path is considered valid templates path if it exists and contains all required template files. If the detected templates path also contains global parameters file Globals.plist, the file defaults are automatically read. These are all overriden by command line as expected.

If parsing global parameters fails, error is logged but the execution continues.

Declared in

CommandLineParser.m

validateCommandLineArguments

Validates command line arguments after parsing.

- (void)validateCommandLineArguments

Exceptions

NSException: Thrown if validation fails.

Discussion

This function will make sure all required arguments and their values were correctly passed to the utility through the command line. This message is automatically sent from - parseCommandLineArguments:ofCount: immediately after parsing the command line.

Declared in

CommandLineParser.m

postProcessCommandLineArguments

Post-processes command line arguments.

- (void)postProcessCommandLineArguments

Discussion

This message is sent after parsing the command line is finished. It will replace all template parameters (either from factory defaults or from globals plist) with the actual values and will prepare all dependent values. The message is automatically sent from - parseCommandLineArguments:ofCount:.

Declared in

CommandLineParser.m

setupFactoryDefaults

Resets all parsed properties and variables required for parsing.

- (void)setupFactoryDefaults

Declared in

CommandLineParser.m

replaceTemplatePlaceholdersForKey:

Replaces template placeholders for the given parameters key.

- (void)replaceTemplatePlaceholdersForKey:(NSString *)        key

Parameters

key: The parameters key to update.

Discussion

This is where template placeholders from globals plist or factory defaults are replaced with the actual values from command line. Allowed placeholders are:

$PROJECT is replaced by the value from the --project switch.
$INPUT is replaced by the value from the --input switch.
$OUTPUT is replaced by the value from the --output switch.

Declared in

CommandLineParser.m

standardizePathForKey:

Standardizes the path for the given parameters key.

- (void)standardizePathForKey:(NSString *)        key

Parameters

key: The parameters key to update.

Discussion

This will simply replace the NSString value of the given key with the existing value to which it will send stringByStandardizingPath message. It is just a convenience method that makes paths handling code simpler.

Declared in

CommandLineParser.m

parseStringWithShortcut:andName:forKey:

Parses the assigned command line for the string with the given name or shortcut.

- (BOOL)parseStringWithShortcut:(NSString *)        shortcut
 andName:(NSString *)        name
 forKey:(NSString *)        key

Parameters

shortcut: Optional shortcut of the argument ir nil if not used.
name: Optional long name of the argument or nil if not used.
key: The key for which to set the value if found.

Exceptions

NSException: Thrown if both name and shortcut are nil or the argument is found, but it doesn't have a value associated. Also thrown if the given key is nil.

Return value

Returns YES if the given option was found, NO otherwise.

Discussion

If the argument is found, it's value is set to the parameters dictionary to the given key. If the argument is found, but value is missing, exception is thrown. For each argument, only one value is possible. The value should be separated by a whitespace. The argument may either consist of a long name (ussually started with double minus), shortcut (ussually started with a single minus) or both. However, at least one must be passed; the method will thrown exception if both, name and shortcut, are nil.

Declared in

CommandLineParser.m

parseIntegerWithShortcut:andName:forKey:

Parses the assigned command line for the integer with the given name or shortcut.

- (BOOL)parseIntegerWithShortcut:(NSString *)        shortcut
 andName:(NSString *)        name
 forKey:(NSString *)        key

Parameters

shortcut: Optional shortcut of the argument ir nil if not used.
name: Optional long name of the argument or nil if not used.
key: The key for which to set the value if found.

Exceptions

NSException: Thrown if both name and shortcut are nil or the argument is found, but it doesn't have a value associated. Also thrown if the given key is nil.

Return value

Returns YES if the given option was found, NO otherwise.

Discussion

If the argument is found, it's value is set to the parameters dictionary to the given key. If the argument is found, but value is missing, exception is thrown. For each argument, only one value is possible. The value should be separated by a whitespace. The argument may either consist of a long name (ussually started with double minus), shortcut (ussually started with a single minus) or both. However, at least one must be passed; the method will thrown exception if both, name and shortcut, are nil.

Declared in

CommandLineParser.m

parseBooleanWithShortcut:andName:withValue:forKey:

Parses the assigned command line for the switch with the given name or shortcut.

- (BOOL)parseBooleanWithShortcut:(NSString *)        shortcut
 andName:(NSString *)        name
 withValue:(BOOL)        value
 forKey:(NSString *)        key

Parameters

shortcut: Optional shortcut of the switch ir nil if not used.
name: Optional long name of the switch or nil if not used.
key: The key for which to set the value if found.
value: The desired value to set for the given key if the switch is found.

Exceptions

NSException: Thrown if both name and shortcut are nil or key is nil.

Return value

Returns YES if the given option was found, NO otherwise.

Discussion

If the switch is found, the given value is set to the parameters dictionary for the given key. The switch may either consist of a long name (ussually started with double minus), shortcut (ussually started with a single minus) or both. However, at least one must be passed; the method will thrown exception if both, name and shortcut, are nil.

Note that in case name is specified, the method will automatically check if the negative form of the option is found and will use the negated value in such case. This is useful for overriding global parameters for example. If the name is --option, the method assumes the negative form is --no-option. If both forms are found in the command line, the last one encountered is used. Note that this only works properly for option names starting with a -- prefix.

Declared in

CommandLineParser.m

logCmdLineSwitch:andName:andValue:

Logs the given command line switch usage as debug log entry.

- (void)logCmdLineSwitch:(NSString *)        shortcut
 andName:(NSString *)        name
 andValue:(NSString *)        value

Parameters

shortcut: Options shortcut of the switch or nil if not used.
name: Optional name of the switch or nil if not used.
value: Optional value of the switch or nil if this is boolean switch.

Discussion

Note that the method automatically outputs shortcut and/or name and automatically handles the value if passed. If any of the parameters are not applicable, pass nil instead.

Declared in

CommandLineParser.m

Properties

commandLine

The command line path to the executable including full path.

@property NSString *commandLine

Declared in

CommandLineParser.h

projectName

Project name.

@property NSString *projectName

Declared in

CommandLineParser.h

inputPath

The path to the source files.

@property NSString *inputPath

Declared in

CommandLineParser.h

outputPath

The path to the output files (sub directories are created within this location).

@property NSString *outputPath

Declared in

CommandLineParser.h

doxygenCommandLine

The command line to the doxygen utility including full path.

@property NSString *doxygenCommandLine

Declared in

CommandLineParser.h

doxygenConfigFilename

The path to the doxygen configuration file including full path.

@property NSString *doxygenConfigFilename

Declared in

CommandLineParser.h

fixClassLocations

If YES, class locations are fixed if (possibly) invalid location is detected.

@property BOOL fixClassLocations

Declared in

CommandLineParser.h

removeEmptyParagraphs

If YES, empty paragraphs should be removed from clean XML.

@property BOOL removeEmptyParagraphs

Declared in

CommandLineParser.h

mergeKnownCategoriesToClasses

If YES, documentation for categories to known classes should be merged to the class documentation.

@property BOOL mergeKnownCategoriesToClasses

Declared in

CommandLineParser.h

keepMergedCategorySections

If YES, merged categories method sections should be preserved in the class.

@property BOOL keepMergedCategorySections

This option can create cluttered class documentation, so experiment to see if if works for you or not.

Declared in

CommandLineParser.h

objectReferenceTemplate

The template for creating references to members of another objects.

@property NSString *objectReferenceTemplate

Discussion

This is used to generate the actual reference name and is visible on the final output.

Declared in

CommandLineParser.h

memberReferenceTemplate

The template for creating references to members of the same object.

@property NSString *memberReferenceTemplate

Discussion

This is used to generate the actual reference name and is visible on the final output.

Declared in

CommandLineParser.h

dateTimeTemplate

The template for formatting date/time strings.

@property NSString *dateTimeTemplate

Declared in

CommandLineParser.h

createCleanXHTML

If YES, clean XHTML documentation is created.

@property BOOL createCleanXHTML

Declared in

CommandLineParser.h

createDocSet

If YES, documentation set is created.

@property BOOL createDocSet

Discussion

Note That createCleanXHTML is a prerequisite for documentation set.

Declared in

CommandLineParser.h

createMarkdown

If YES, Markdown documentaiton is created.

@property BOOL createMarkdown

Declared in

CommandLineParser.h

xhtmlUseBorderedExamples

If YES, use bordered XHTML example sections which results in more Apple like documentation.

@property BOOL xhtmlUseBorderedExamples

Declared in

CommandLineParser.h

xhtmlUseBorderedWarnings

If YES, use bordered XHTML warning sections which results in more Apple like documentation.

@property BOOL xhtmlUseBorderedWarnings

Declared in

CommandLineParser.h

xhtmlUseBorderedBugs

If YES, use bordered XHTML bug sections which results in more Apple like documentation.

@property BOOL xhtmlUseBorderedBugs

Declared in

CommandLineParser.h

docsetBundleID

The documentation set unique bundle ID.

@property NSString *docsetBundleID

Declared in

CommandLineParser.h

docsetBundleFeed

The documentation set bundle feed which is displayed in the Xcode documentation window.

@property NSString *docsetBundleFeed

Declared in

CommandLineParser.h

docsetSourcePlistPath

The documentation set source plist which contains identification and description.

@property NSString *docsetSourcePlistPath

Declared in

CommandLineParser.h

docsetutilCommandLine

The docsetutil command line including full path.

@property NSString *docsetutilCommandLine

Declared in

CommandLineParser.h

docsetInstallPath

The documentation set installation path.

@property NSString *docsetInstallPath

Discussion

This should be set to one of the known locations which Xcode searches. By default it is set to user's documentation set directory.

Declared in

CommandLineParser.h

markdownReferenceStyleLinks

If YES, object files links are created using reference style, otherwise inline links are created.

@property BOOL markdownReferenceStyleLinks

Declared in

CommandLineParser.h

markdownLineLength

The maximum number of chars to use in one line.

@property int markdownLineLength

Discussion

This is the desired maximum line length.

Declared in

CommandLineParser.h

markdownLineWrapThreshold

The minimum number of chars in the line before considering wrapping.

@property int markdownLineWrapThreshold

Discussion

This value controls line wrapping when adding non-wrappable phrases. It works in pair with markdownLineLength and markdownLineWrapMargin.

If the line has less chars than this value, a non-wrappable phrase is still appended if the total line length including the phrase is below the sum of markdownLineLength and markdownLineWrapMargin.

Declared in

CommandLineParser.h

markdownLineWrapMargin

The maximum number of chars to use in one line.

@property int markdownLineWrapMargin

Discussion

This value controls line wrapping when adding non-wrappable phrases. It works in pair with markdownLineLength and markdownLineWrapThreshold.

If the line length is below or equal to the threshold, the phrase is added to it even if the new line length is over the markdownLineLength however below the given margin.

Declared in

CommandLineParser.h

templatesPath

The path to the template files and global options.

@property NSString *templatesPath

Discussion

This is automatically determined by checking the known locations which are (in order of preference):

~/.appledoc
~/Application Support/appledoc

Declared in

CommandLineParser.h

cleanTempFilesAfterBuild

If YES, temporary files are removed after generation.

@property BOOL cleanTempFilesAfterBuild

Discussion

This will effectively remove all but the "last" generated files. Which files will be removed it depends on what is the desired output. If this is one of the clean outputs, all doxygen and clean XML files will be removed. If this is documentation set, the clean HTML files will be removed too (other final output files will remain if chosen).

Declared in

CommandLineParser.h

cleanOutputFilesBeforeBuild

If YES, the outputPath is deleted before starting processing.

@property BOOL cleanOutputFilesBeforeBuild

Discussion

This is important because otherwise deleted or renamed files will remain in the final documentation. @ warning Be careful when using this option - it will remove the outputPath directory too, so if you keep any files which are not automatically generated there (should not really!), such as source files or plists etc., these will also be removed!

Declared in

CommandLineParser.h

verboseLevel

The desired verbose level.

@property int verboseLevel

Discussion

This is used by the log macros, so in most cases, you'll not use it directly in code.

Declared in

CommandLineParser.h

emitUtilityOutput

This is used to show or hide the output from the external utilities such as doxygen and docsetutil.

@property BOOL emitUtilityOutput

Declared in

CommandLineParser.h

CommandLineParser class reference

Overview

Tasks

Properties - required

Properties - doxygen

Properties - clean XML creation

Properties - clean output creation

Properties - XHTML output creation

Properties - documentation set creation

Properties - Markdown creation

Properties - miscellaneous

Properties - undocumented

Initialization & disposal

Parsing handling

CommandLineParser(ClassPrivateAPI)

Class methods

sharedInstance

Discussion

Declared in

Instance methods

parseCommandLineArguments:ofCount:

Parameters

Exceptions

Discussion

See also

Declared in

printUsage

See also

Declared in

setupGlobalTemplates

Discussion

Declared in

parseTemplatesPath:

Parameters

Return value

Discussion

Declared in

validateCommandLineArguments

Exceptions

Discussion

Declared in

postProcessCommandLineArguments

Discussion

See also

Declared in

setupFactoryDefaults

Declared in

replaceTemplatePlaceholdersForKey:

Parameters

Discussion

Declared in

standardizePathForKey:

Parameters

Discussion

Declared in

parseStringWithShortcut:andName:forKey:

Parameters

Exceptions

Return value

Discussion

See also

Declared in

parseIntegerWithShortcut:andName:forKey:

Parameters

Exceptions

Return value

Discussion

See also

Declared in

parseBooleanWithShortcut:andName:withValue:forKey:

Parameters

Exceptions

Return value

Discussion

See also

Declared in

logCmdLineSwitch:andName:andValue:

Parameters

Discussion

Declared in