Permalink
Browse files

Implemented example sections processing.

  • Loading branch information...
tomaz committed Sep 2, 2010
1 parent e6c6782 commit f54495f96b53fa502a14248e0d0a7fc9cee32b56
@@ -44,6 +44,12 @@
/** Returns the regex used for matching bug section with capture 1 containing description. */
@property (readonly) NSString *bugSectionRegex;
+/** Returns the regex used for matching example section with capture 1 containing example text. */
+@property (readonly) NSString *exampleSectionRegex;
+
+/** Returns the regex used for matching example lines with capture 1 containing example lines texts. */
+@property (readonly) NSString *exampleLinesRegex;
+
/** Returns the regex used for matching method parameter description with capture 1 containing parameter name and capture 2 description. */
@property (readonly) NSString *parameterDescriptionRegex;
@@ -18,8 +18,9 @@
@interface GBCommentComponentsProvider ()
-- (NSString *)singleCaptureRegexForKeyword:(NSString *)keyword;
-- (NSString *)doubleCaptureRegexForKeyword:(NSString *)keyword;
+- (NSString *)exampleRegexWithoutFlags;
+- (NSString *)descriptionCaptureRegexForKeyword:(NSString *)keyword;
+- (NSString *)nameDescriptionCaptureRegexForKeyword:(NSString *)keyword;
@end
@@ -52,36 +53,48 @@ - (NSString *)unorderedListPrefixRegex {
}
- (NSString *)warningSectionRegex {
- GBRETURN_ON_DEMAND([self singleCaptureRegexForKeyword:@"warning"]);
+ GBRETURN_ON_DEMAND([self descriptionCaptureRegexForKeyword:@"warning"]);
}
- (NSString *)bugSectionRegex {
- GBRETURN_ON_DEMAND([self singleCaptureRegexForKeyword:@"bug"]);
+ GBRETURN_ON_DEMAND([self descriptionCaptureRegexForKeyword:@"bug"]);
+}
+
+- (NSString *)exampleSectionRegex {
+ GBRETURN_ON_DEMAND(([NSString stringWithFormat:@"(?s:%@)", [self exampleRegexWithoutFlags]]));
+}
+
+- (NSString *)exampleLinesRegex {
+ GBRETURN_ON_DEMAND(([NSString stringWithFormat:@"(?m:%@)", [self exampleRegexWithoutFlags]]));
+}
+
+- (NSString *)exampleRegexWithoutFlags {
+ GBRETURN_ON_DEMAND(@"^[ ]*\\t(.*)");
}
- (NSString *)parameterDescriptionRegex {
- GBRETURN_ON_DEMAND([self doubleCaptureRegexForKeyword:@"param"]);
+ GBRETURN_ON_DEMAND([self nameDescriptionCaptureRegexForKeyword:@"param"]);
}
- (NSString *)returnDescriptionRegex {
- GBRETURN_ON_DEMAND([self singleCaptureRegexForKeyword:@"return"]);
+ GBRETURN_ON_DEMAND([self descriptionCaptureRegexForKeyword:@"return"]);
}
- (NSString *)exceptionDescriptionRegex {
- GBRETURN_ON_DEMAND([self doubleCaptureRegexForKeyword:@"exception"]);
+ GBRETURN_ON_DEMAND([self nameDescriptionCaptureRegexForKeyword:@"exception"]);
}
- (NSString *)crossReferenceRegex {
- GBRETURN_ON_DEMAND([self singleCaptureRegexForKeyword:@"(sa|see)"]);
+ GBRETURN_ON_DEMAND([self descriptionCaptureRegexForKeyword:@"(sa|see)"]);
}
#pragma mark Helper methods
-- (NSString *)singleCaptureRegexForKeyword:(NSString *)keyword {
+- (NSString *)descriptionCaptureRegexForKeyword:(NSString *)keyword {
return [NSString stringWithFormat:@"^\\s*.%@\\s+(?s:(.*))", keyword];
}
-- (NSString *)doubleCaptureRegexForKeyword:(NSString *)keyword {
+- (NSString *)nameDescriptionCaptureRegexForKeyword:(NSString *)keyword {
return [NSString stringWithFormat:@"^\\s*.%@\\s+([^\\s]+)\\s+(?s:(.*))", keyword];
}
View
@@ -19,10 +19,12 @@ - (void)registerOrderedListFromString:(NSString *)string toParagraph:(GBCommentP
- (void)registerListFromString:(NSString *)string ordered:(BOOL)ordered usingRegex:(NSString *)regex toParagraph:(GBCommentParagraph *)paragraph;
- (void)registerWarningFromString:(NSString *)string toParagraph:(GBCommentParagraph *)paragraph;
- (void)registerBugFromString:(NSString *)string toParagraph:(GBCommentParagraph *)paragraph;
+- (void)registerExampleFromString:(NSString *)string toParagraph:(GBCommentParagraph *)paragraph;
- (void)registerSpecialFromString:(NSString *)string type:(GBSpecialItemType)type usingRegex:(NSString *)regex toParagraph:(GBCommentParagraph *)paragraph;
- (void)registerTextFromString:(NSString *)string toParagraph:(GBCommentParagraph *)paragraph;
- (NSArray *)componentsSeparatedByEmptyLinesFromString:(NSString *)string;
- (NSArray *)componentsSeparatedByNewLinesFromString:(NSString *)string;
+@property (retain) NSString *newLinesRegexSymbols;
@property (retain) NSString *spaceAndNewLineTrimRegex;
@property (retain) id<GBApplicationSettingsProviding> settings;
@property (retain) id<GBStoreProviding> store;
@@ -45,8 +47,8 @@ - (id)initWithSettingsProvider:(id)settingsProvider {
GBLogDebug(@"Initializing comments processor with settings provider %@...", settingsProvider);
self = [super init];
if (self) {
- NSString *spaceAndNewLineRegex = [NSString stringWithUTF8String:"(?:\\r\n|[ \n\\v\\f\\r\302\205\\p{Zl}\\p{Zp}])+"];
- self.spaceAndNewLineTrimRegex = [NSString stringWithFormat:@"^%@|%@$", spaceAndNewLineRegex, spaceAndNewLineRegex];
+ self.newLinesRegexSymbols = [NSString stringWithUTF8String:"(?:\\r\n|[ \n\\v\\f\\r\302\205\\p{Zl}\\p{Zp}])+"];
+ self.spaceAndNewLineTrimRegex = [NSString stringWithFormat:@"^%1$@|%1$@$", self.newLinesRegexSymbols];
self.settings = settingsProvider;
}
return self;
@@ -70,27 +72,34 @@ - (void)processComment:(GBComment *)comment withStore:(id)store {
NSArray *components = [self componentsSeparatedByEmptyLinesFromString:[comment stringValue]];
__block GBCommentParagraph *currentParagraph = nil;
[components enumerateObjectsUsingBlock:^(NSString *component, NSUInteger idx, BOOL *stop) {
- // Match known parts.
- if ([component isMatchedByRegex:componizer.unorderedListRegex]) {
- GBRegister([self registerUnorderedListFromString:component toParagraph:currentParagraph]);
+ // As most components are given with preceeding new line, we should remove it to get cleaner testing.
+ NSString *trimmed = [component stringByReplacingOccurrencesOfRegex:self.spaceAndNewLineTrimRegex withString:@""];
+
+ // Match known parts. Note that order is important for certain items (lists must be processed before examples for example).
+ if ([trimmed isMatchedByRegex:componizer.unorderedListRegex]) {
+ GBRegister([self registerUnorderedListFromString:trimmed toParagraph:currentParagraph]);
+ return;
+ }
+ if ([trimmed isMatchedByRegex:componizer.orderedListRegex]) {
+ GBRegister([self registerOrderedListFromString:trimmed toParagraph:currentParagraph]);
return;
}
- if ([component isMatchedByRegex:componizer.orderedListRegex]) {
- GBRegister([self registerOrderedListFromString:component toParagraph:currentParagraph]);
+ if ([trimmed isMatchedByRegex:componizer.warningSectionRegex]) {
+ GBRegister([self registerWarningFromString:trimmed toParagraph:currentParagraph]);
return;
}
- if ([component isMatchedByRegex:componizer.warningSectionRegex]) {
- GBRegister([self registerWarningFromString:component toParagraph:currentParagraph]);
+ if ([trimmed isMatchedByRegex:componizer.bugSectionRegex]) {
+ GBRegister([self registerBugFromString:trimmed toParagraph:currentParagraph]);
return;
}
- if ([component isMatchedByRegex:componizer.bugSectionRegex]) {
- GBRegister([self registerBugFromString:component toParagraph:currentParagraph]);
+ if ([trimmed isMatchedByRegex:componizer.exampleSectionRegex]) {
+ GBRegister([self registerExampleFromString:trimmed toParagraph:currentParagraph]);
return;
}
// If no other match was found, this is simple text, so start new paragraph.
currentParagraph = [GBCommentParagraph paragraph];
- [self registerTextFromString:component toParagraph:currentParagraph];
+ [self registerTextFromString:trimmed toParagraph:currentParagraph];
[comment registerParagraph:currentParagraph];
}];
}
@@ -106,16 +115,14 @@ - (void)registerOrderedListFromString:(NSString *)string toParagraph:(GBCommentP
}
- (void)registerListFromString:(NSString *)string ordered:(BOOL)ordered usingRegex:(NSString *)regex toParagraph:(GBCommentParagraph *)paragraph {
- // Sometimes we can get newlines and spaces before or after the component, so remove them first, then use trimmed string as list's string value.
- NSString *trimmed = [string stringByReplacingOccurrencesOfRegex:self.spaceAndNewLineTrimRegex withString:@""];
- GBParagraphListItem *item = [GBParagraphListItem paragraphItemWithStringValue:trimmed];
+ GBParagraphListItem *item = [GBParagraphListItem paragraphItemWithStringValue:string];
item.isOrdered = ordered;
// Split the block of all list items to individual items, then process and register each one.
- NSArray *items = [trimmed componentsSeparatedByRegex:regex];
+ NSArray *items = [string componentsSeparatedByRegex:regex];
[items enumerateObjectsUsingBlock:^(NSString *description, NSUInteger idx, BOOL *stop) {
if ([description length] == 0) {
- GBLogWarn(@"%ld. item has empty description for list:\n%@", idx, trimmed);
+ GBLogWarn(@"%ld. item has empty description for list:\n%@", idx, string);
return;
}
GBCommentParagraph *paragraph = [GBCommentParagraph paragraph];
@@ -137,17 +144,41 @@ - (void)registerBugFromString:(NSString *)string toParagraph:(GBCommentParagraph
[self registerSpecialFromString:string type:GBSpecialItemTypeBug usingRegex:self.settings.commentComponents.bugSectionRegex toParagraph:paragraph];
}
+- (void)registerExampleFromString:(NSString *)string toParagraph:(GBCommentParagraph *)paragraph {
+ // Get the description from the string. If empty, warn and exit.
+ NSArray *lines = [string componentsMatchedByRegex:self.settings.commentComponents.exampleLinesRegex capture:1];
+ NSMutableString *example = [NSMutableString stringWithCapacity:[string length]];
+ [lines enumerateObjectsUsingBlock:^(NSString *line, NSUInteger idx, BOOL *stop) {
+ if ([example length] > 0) [example appendString:@"\n"];
+ [example appendString:line];
+ }];
+
+ // Warn if empty example was found.
+ if ([example length] == 0) {
+ GBLogWarn(@"Empty example section found!");
+ return;
+ }
+
+ // Prepare paragraph item and process the text.
+ GBParagraphSpecialItem *item = [GBParagraphSpecialItem specialItemWithType:GBSpecialItemTypeExample stringValue:string];
+ GBCommentParagraph *para = [GBCommentParagraph paragraph];
+ [para registerItem:[GBParagraphTextItem paragraphItemWithStringValue:example]];
+ [item registerParagraph:para];
+
+ // Register special item to paragraph.
+ [paragraph registerItem:item];
+}
+
- (void)registerSpecialFromString:(NSString *)string type:(GBSpecialItemType)type usingRegex:(NSString *)regex toParagraph:(GBCommentParagraph *)paragraph {
// Get the description from the string. If empty, warn and exit.
- NSString *trimmed = [string stringByReplacingOccurrencesOfRegex:self.spaceAndNewLineTrimRegex withString:@""];
- NSString *description = [trimmed stringByMatching:regex capture:1];
+ NSString *description = [string stringByMatching:regex capture:1];
if ([description length] == 0) {
GBLogWarn(@"Empty special section of type %ld found!", type);
return;
}
// Prepare paragraph item and process the text.
- GBParagraphSpecialItem *item = [GBParagraphSpecialItem specialItemWithType:type stringValue:trimmed];
+ GBParagraphSpecialItem *item = [GBParagraphSpecialItem specialItemWithType:type stringValue:string];
GBCommentParagraph *para = [GBCommentParagraph paragraph];
[self registerTextFromString:description toParagraph:para];
[item registerParagraph:para];
@@ -176,15 +207,17 @@ - (void)registerTextFromString:(NSString *)string toParagraph:(GBCommentParagrap
#pragma mark Helper methods
- (NSArray *)componentsSeparatedByEmptyLinesFromString:(NSString *)string {
- return [string componentsSeparatedByRegex:@"(?m:^\\s*$)"];
+ // We need to allow lines with tabs to properly detect empty example lines!
+ return [string componentsSeparatedByRegex:[NSString stringWithFormat:@"(?m:^[ %@]*$)", self.newLinesRegexSymbols]];
}
- (NSArray *)componentsSeparatedByNewLinesFromString:(NSString *)string {
- return [string componentsSeparatedByRegex:[NSString stringWithUTF8String:"(?:\\r\n|[\n\\v\\f\\r\302\205\\p{Zl}\\p{Zp}])"]];
+ return [string componentsSeparatedByRegex:[NSString stringWithFormat:@"(?:%@)", self.newLinesRegexSymbols]];
}
#pragma mark Properties
+@synthesize newLinesRegexSymbols;
@synthesize spaceAndNewLineTrimRegex;
@synthesize settings;
@synthesize store;
@@ -0,0 +1,19 @@
+//
+// GBParagraphExampleItem.h
+// appledoc
+//
+// Created by Tomaz Kragelj on 2.9.10.
+// Copyright (C) 2010, Gentle Bytes. All rights reserved.
+//
+
+#import "GBParagraphItem.h"
+
+/** Handles example sections for paragraphs.
+
+ Special items are containers for `GBCommentParagraph` which are formatted differently to catch user's attention. There can be several types of special items, to determine the type, use the value of `specialItemType` property.
+ */
+@interface GBParagraphExampleItem : NSObject {
+
+}
+
+@end
@@ -0,0 +1,13 @@
+//
+// GBParagraphExampleItem.m
+// appledoc
+//
+// Created by Tomaz Kragelj on 2.9.10.
+// Copyright (C) 2010, Gentle Bytes. All rights reserved.
+//
+
+#import "GBParagraphExampleItem.h"
+
+@implementation GBParagraphExampleItem
+
+@end
@@ -16,6 +16,8 @@ enum {
GBSpecialItemTypeWarning,
/** The `GBParagraphSpecialItem` represents a bug. */
GBSpecialItemTypeBug,
+ /** The `GBParagraphSpecialItem` represents an example section. */
+ GBSpecialItemTypeExample,
};
typedef NSUInteger GBSpecialItemType;
Oops, something went wrong.

0 comments on commit f54495f

Please sign in to comment.