Skip to content
This repository
Fetching contributors…

Cannot retrieve contributors at this time

file 191 lines (132 sloc) 10.741 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
//
// GBCommentKeywordsProvider.h
// appledoc
//
// Created by Tomaz Kragelj on 30.8.10.
// Copyright (C) 2010, Gentle Bytes. All rights reserved.
//

#import <Foundation/Foundation.h>

@class GBApplicationSettingsProvider;

/** Provides comment keywords and helpers for the rest of the application.
The main responsibility of the class is to determine if a string contains special section definition. In addition, they also return section parameters. This encapsulates keywords and sections handling and simplifies the rest of the application.
*/
@interface GBCommentComponentsProvider : NSObject

///---------------------------------------------------------------------------------------
/// @name Initialization & disposal
///---------------------------------------------------------------------------------------

/** Returns a new autoreleased `GBCommentComponentsProvider` instance.
*/
+ (id)provider;

///---------------------------------------------------------------------------------------
/// @name Parameters
///---------------------------------------------------------------------------------------

/** Sets cross reference markers.
The given string should include optional prefix, followed by `%@` and lastly optional suffix. If either prefix or suffix isn't allowed, just pass `%@`. At the runtime, `%@` is replaced by the actual regex for mathching particular cross reference type - actually the whole string becomes the regex for matching cross reference, therefore prefix and suffix can be arbitrary regex expressions themselves! On the other hand, this imposes some limitations to what can be used for them:
- Prefix and suffix must not contain any capturing components as this will break matching code (you can still include groups, but make sure any open parenthesis is marked as non-capturing like this: `(?:...)`!
- Prefix must not contain any marker used for formatting such as *, _ or combinations. This is actually not checked, but in such case results may be not what you wanted.
@warning *Important:* Note that the given string must contain exactly one `%@` marker. If none is included cross references will not be matched during runtime. If more than one is included, unpredicted behavior may occur. So take care!
@warning *Important:* This value must be set before accessing any cross reference regex property! The accessors prepare and cache the value on first usage. From then on, cached value is returned, so any change is not propagated!
*/
@property (copy) NSString *crossReferenceMarkersTemplate;

///---------------------------------------------------------------------------------------
/// @name Sections definitions
///---------------------------------------------------------------------------------------

/** Returns the regex used for matching warning section with capture 1 containing directive and capture 2 description text. */
@property (readonly) NSString *warningSectionRegex;

/** Returns the regex used for matching bug section with capture 1 containing directive and capture 2 description text. */
@property (readonly) NSString *bugSectionRegex;

/** Returns the regex used for matching note section with capture 1 containing directive and capture 2 description text. */
@property (readonly) NSString *noteSectionRegex;


///---------------------------------------------------------------------------------------
/// @name Method specific definitions
///---------------------------------------------------------------------------------------

/** Returns the regex used for matching method groups with capture 1 containing section name. */
@property (readonly) NSString *methodGroupRegex;

/** Returns the regex used for matching method parameter description with capture 1 containing directive, capture 2 parameter name and capture 3 description text. */
@property (readonly) NSString *parameterDescriptionRegex;

/** Returns the regex used for matching method return description with capture 1 containing directive and capture 2 description text. */
@property (readonly) NSString *returnDescriptionRegex;

/** Returns the regex used for matching method exception description with capture 1 containing directive, capture 2 exception name and capture 3 description text. */
@property (readonly) NSString *exceptionDescriptionRegex;

/** Returns the regex used for matching cross reference directive with capture 1 containing directive, capture 3 link. */
@property (readonly) NSString *relatedSymbolRegex;

/** Returns the regex used for matching cross reference directive with capture 1 containing directive, capture 2 description text. */
@property (readonly) NSString *availabilityRegex;

///---------------------------------------------------------------------------------------
/// @name Markdown specific definitions
///---------------------------------------------------------------------------------------

/** Returns the regex used for matching Markdown inline style links with capture 1 containing link description part without brackets, 2 the address and 3 optional title.
Here's a diagram of captures for better orientation:
[ description ]( address " title " )
^^^^^^^^^^^ ^^^^^^^ ^^^^^
| | |
| | +-- capture3
| +-- capture2
+-- capture1
@see markdownReferenceLinkRegex
*/
@property (readonly) NSString *markdownInlineLinkRegex;

/** Returns the regex used for matching Markdown reference style links with capture 1 reference ID, 2 address and 3 optional title.
Here's a diagram of captures for better orientation:
[ ID ]: address " title "
^^ ^^^^^^^ ^^^^^
| | |
| | +-- capture3
| +-- capture2
+-- capture1
@see markdownInlineLinkRegex
*/
@property (readonly) NSString *markdownReferenceLinkRegex;

///---------------------------------------------------------------------------------------
/// @name Cross references definitions
///---------------------------------------------------------------------------------------

/** Returns the regex used for matching (possible) remote member cross references with capture 1 containing optional - or + prefix, capture 2 object name and capture 3 member selector.
The result of the method depends on the templated value: if the value is `YES`, the string includes template from `crossReferenceMarkersTemplate`, otherwise it only contains "pure" regex. The first option should be used for in-text cross references detection, while the second for `crossReferenceRegex` matching.
@param templated If `YES` templated regex is returned, otherwise pure one.
@return Returns the regex used for matching cross reference.
*/
- (NSString *)remoteMemberCrossReferenceRegex:(BOOL)templated;

/** Returns the regex used for matching (possible) local member cross reference with capture 1 containing optional - or + prefix and capture 2 member selector.
The result of the method depends on the templated value: if the value is `YES`, the string includes template from `crossReferenceMarkersTemplate`, otherwise it only contains "pure" regex. The first option should be used for in-text cross references detection, while the second for `crossReferenceRegex` matching.
@param templated If `YES` templated regex is returned, otherwise pure one.
@return Returns the regex used for matching cross reference.
*/
- (NSString *)localMemberCrossReferenceRegex:(BOOL)templated;

/** Returns the regex used for matching (possible) category cross reference with capture 1 containing category name.
The result of the method depends on the templated value: if the value is `YES`, the string includes template from `crossReferenceMarkersTemplate`, otherwise it only contains "pure" regex. The first option should be used for in-text cross references detection, while the second for `crossReferenceRegex` matching.
@param templated If `YES` templated regex is returned, otherwise pure one.
@return Returns the regex used for matching cross reference.
*/
- (NSString *)categoryCrossReferenceRegex:(BOOL)templated;

/** Returns the regex used for matching (possible) class or protocol cross reference with capture 1 containing object name.
The result of the method depends on the templated value: if the value is `YES`, the string includes template from `crossReferenceMarkersTemplate`, otherwise it only contains "pure" regex. The first option should be used for in-text cross references detection, while the second for `crossReferenceRegex` matching.
@param templated If `YES` templated regex is returned, otherwise pure one.
@return Returns the regex used for matching cross reference.
*/
- (NSString *)objectCrossReferenceRegex:(BOOL)templated;

/** Returns the regex used for matching (possible) static document cross reference with capture 1 containing document name.
The result of the method depends on the templated value: if the value is `YES`, the string includes template from `crossReferenceMarkersTemplate`, otherwise it only contains "pure" regex. The first option should be used for in-text cross references detection, while the second for `crossReferenceRegex` matching.
@param templated If `YES` templated regex is returned, otherwise pure one.
@return Returns the regex used for matching cross reference.
*/
- (NSString *)documentCrossReferenceRegex:(BOOL)templated;

/** Returns the regex used for matching URL cross reference with caption 1 contining the URL itself.
The result of the method depends on the templated value: if the value is `YES`, the string includes template from `crossReferenceMarkersTemplate`, otherwise it only contains "pure" regex. The first option should be used for in-text cross references detection, while the second for `crossReferenceRegex` matching.
@param templated If `YES` templated regex is returned, otherwise pure one.
@return Returns the regex used for matching cross reference.
*/
- (NSString *)urlCrossReferenceRegex:(BOOL)templated;

///---------------------------------------------------------------------------------------
/// @name Common definitions
///---------------------------------------------------------------------------------------

/** Returns the regex containing all possible symbols for matching new lines. */
@property (readonly) NSString *newLineRegex;

/** Our custom code span start marker. */
@property (readonly) NSString *codeSpanStartMarker;

/** Our custom code span end marker. */
@property (readonly) NSString *codeSpanEndMarker;

/** Our custom appledoc style bold start marker. */
@property (readonly) NSString *appledocBoldStartMarker;

/** Our custom appledoc style bold end marker. */
@property (readonly) NSString *appledocBoldEndMarker;

@end
Something went wrong with that request. Please try again.