alibaba/OCAnnotation

Name: OCAnnotation

Owner: Alibaba

Description: A light-weighted framework empowering Objective-C with annotation feature.

Created: 2017-08-03 03:05:02.0

Updated: 2018-05-03 14:36:52.0

Pushed: 2018-02-05 07:35:04.0

Homepage: null

Size: 1005

Language: Objective-C

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Introduction

OCAnnotation is a light-weighted framework empowering the Objective-C language with the ability of annotation. As in Java, annotation is a form of syntactic metadata that can be added to the source code. It provides a handy way to apply certain behaviors to related program elements, such as class, methods, etc. By embedding this feature, we could make Objective-C a more flexible language, and bring our iOS development work more convenience and possibilities.

This framework is developed and maintained by the Ant Wealth software development team. It is already applied in our project in multiple modules, including but not limited to logging?network layer and data layer. We would like to share this exquisite tool with you, and be expectantly looking forward to you exploring its usage with all your imagination.

Feature

• support annotations in all .h/.m files
• support annotations added to @interface, @implementation, @property, method, etc.
• support custom definition of annotation type
• support custom definition of annotation key-values

Installation

1. Download the .gem and install it:

   install ocannotation
   

2. Copy the config file (.oca.config) to your project's root path, modify your custom configuration as needed.

3. Under your project's directory, run the set-up command (we also provide command oca_clean, you could use it to reset your status):

   setup
   

   If you run it successfully, you would get the result much like the following:

   

4. Add OCAnnotation in your Podfile:

   'OCAnnotation'
   

   Well now you are all set to go~

How to Use

Setup

Basically the mistery behind this tool is to scan all annotations in your project and do the modeling. Thus, at the launch time of your app, some setup work is required to be done. Here is an example code segment:

OOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 

OCAAnnotationManager *annotationManager = [OCAAnnotationManager sharedManager];

// custom annotation type registration (optional)
[annotationManager registerAnnotationType:@"RemoteLog"
                                 position:OCAAnnotationPositionMethod
                                    class:[AFWRemoteLogMethodAnnotation class]];

// annotation setup
NSDictionary *configs = kAFWAnnotationConfigs; // using the macro name you write in the Annotation/.config file
[[OCAAnnotationManager sharedManager] addConfigsWithConfigDic:configs];

Notice: After the scanning, the generated file (CustomFileName.gen.h) will be copied to your project path. You need to use 'Add file to…' to add file reference to your project so that you could access the generated macro successfully.

Custom Annotations

'Type' is a custom variable representing a certain type of group of annotations. Generally, a type is related to a specific use scenario. To make your own custom annotation type, you are required to create an annotation class for that type, and the class should be a subclass of OCABaseAnnotation. In OCAnnotation.framework?OCABaseAnnotation is the base annotation model class defining some basic behaviors. We also provide OCABaseClassAnnotation/OCABaseMethodAnnotation/OCABasePropertyAnnotation, which are base models for annotations attached to class/method/property. You could inherit them as well. As stated in the section above, you need to register your custom type at launch time:

ustom annotation type registration (optional)
otationManager registerAnnotationType:@"RemoteLog"
                             position:OCAAnnotationPositionMethod
                                class:[AFWRemoteLogMethodAnnotation class]];

In your subclass, you could do anything magic in the init method, with all the information in annotations packed in the variable 'params' for you. Quick example:

nstancetype)initWithSourceFile:(NSString *)sourceFile
                     className:(NSString *)className
                        params:(NSDictionary *)params
                methodSelector:(NSString *)methodSelector
                          type:(NSString *)type

self = [super initWithSourceFile:sourceFile
                       className:className
                          params:params
                  methodSelector:methodSelector
                            type:type];
if (self) {
    self.remoteLogId = self.parameters[@"remoteLogId"];
    self.remoteLogMethod = self.parameters[@"remoteLogMethod"];

    @weakify(self);
    self.onAnnotationCreated = ^(OCABaseAnnotation *anno){
        @strongify(self);
        [self registerRemoteLogAOP];
    };

}
return self;

Add Annotations

Above any program element, add your annotation in format ?#pragma annotation(key:“value”)?. For example, if you would like to add annotation on @interface UIApplicationDelegate (Different key-value pair can use comma/space as separator. Key and value can be related by colon or equals sign):

gma annotation(type:"default",param1:"value1",param2:"value2")
erface UIApplicationDelegate()

That's it. You have successfully added an annotation to @interface UIApplicationDelegate.

Demo

We provide a demo project named OCAnnotationDemo in which we show the basic usage of this tool. You are welcome to download and play with it.

To-do

• SwiftAnnotation