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
-
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.
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:
~/.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:
.
See also
- replaceTemplatePlaceholdersForKey:
- validateCommandLineArguments
- setupFactoryDefaults
- setupGlobalTemplates
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
andshortcut
arenil
or the argument is found, but it doesn't have a value associated. Also thrown if the givenkey
isnil
.
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
andshortcut
arenil
or the argument is found, but it doesn't have a value associated. Also thrown if the givenkey
isnil
.
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
andshortcut
arenil
orkey
isnil
.
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):
~/.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
© 2008-2009 Tomaz Kragelj. All rights reserved. (Last updated: 2009-08-24)
Back to index / hierarchy.