CommandLineParser class reference

NSObject
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

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

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.

See also
Declared in
CommandLineParser.h

printUsage

Outputs the utility usage to the standard output.

- (void)printUsage
See also
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:

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:.

See also
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:

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.

See also
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.

See also
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.

See also
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.

See also
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.

See also
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):

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

© 2008-2009 Tomaz Kragelj. All rights reserved. (Last updated: 2009-08-24)
Back to index / hierarchy.