Qualifiers should be annotation based. Resolves #16.

Author: afollestad

README.md

@@ -9,15 +9,10 @@
 > remain unknown to the Vikings' rivals for centuries, the Ulfberht was a revolutionary high-tech 
 > tool as well as a work of art.
 
-*A little more bad-ass than a Dagger, huh?*
-
-Dependency injection is a technique in which an application supplies dependencies of an object. 
-"Dependencies" in this context are not dependencies like in a Gradle file. Dependencies are services 
-(i.e. APIs, classes) that are needed in certain parts of your code.
-
-Dependency injection enables you to pass around services without manual construction - it keeps 
-track of everything for you and injects things where they are needed. The need for this is more 
-apparent when you deal with very large applications.
+*A little more bad-ass than a Dagger.* Dependency injection is a technique in which an application 
+supplies dependencies of an object. "Dependencies" in this context are not dependencies like in a 
+Gradle file. Dependencies are services (i.e. APIs, classes) that are needed in certain parts of 
+your code.
 
 ---
 
@@ -51,9 +46,9 @@ based rather than reflection-based, while still being written in Kotlin. And I w
 scoping support, especially on Android. _This is the result._
 
 You may be wondering what makes this library different than KOIN or other Kotlin "DI" libraries? 
-Ulfberht uses annotation processing to do actual dependency injection vs. plain service location. 
-A big example of this difference is that you don't need to manually tell this library how to fill 
-constructor parameters, they are filled for you by generated code.
+Libraries like KOIN are just service locators - you need to build the dependency graph manually, 
+filling in constructors, etc. Annotation processor based DI libraries handle this for you with 
+code generation, so you *don't* need to write boilerplate and you *don't* need to use reflection.
 
 ---
 
@@ -387,77 +382,66 @@ This code assumes that one of the modules going up the graph from `Component5` c
 
 # Qualifiers
 
-Qualifiers are simple identifiers that associate a type that may be broad, like a string, with a 
-very specific bound or provided instance. There are a few places where you can specify a qualifier.
-
-First, the `@Binds` and `@Provides` annotations take a qualifier:
+Qualifiers are simple identifiers that associate a type with a very specific bound or provided 
+instance. A qualifier is a special type of annotation, which is defined like this:
 
 ```kotlin
-const val QUALIFIER_ONE = "one"
-const val QUALIFIER_TWO = "two"
+@Qualifier
+annotation class DemoQualifier1
 
+@Qualifier
+annotation class DemoQualifier2
+```
+
+You use it to mark `@Binds` and `@Provides` functions:
+
+```kotlin
 @Module
 interface DemoModule1 {
-  @Binds(QUALIFIER_ONE)
-  fun demoClass1(impl: Demo1Impl): Demo1
-  
-  @Binds(QUALIFIER_ONE)
-  fun demoClass2(impl: Demo2Impl): Demo2
+  @Binds @Singleton @DemoQualifier1
+  fun demoClass(impl: Demo1Impl): Demo1
 }
 
 @Module
 abstract class DemoModule2 {
-  @Provides(QUALIFIER_TWO)
-  fun demoClass1(): Demo1 {
+  @Provides @Singleton @DemoQualifier2
+  fun demoClass(): Demo1 {
     return Demo1Impl()
   }
-  
-  @Provides(QUALIFIER_TWO)
-  fun demoClass2(): Demo2 {
-    return Demo2Impl()
-  }
 }
 ```
 
-Second, constructor parameters take a qualifier via a `@Param` annotation:
+Then, you can mark constructor parameters with it...
 
 ```kotlin
 class SomeInjectedClass(
-  @Param(QUALIFIER_ONE) val someDependency: Demo1,
-  @Param(QUALIFIER_TWO) val anotherDependency: Demo1
+  @DemoQualifier1 val someDependency: Demo1,
+  @DemoQualifier2 val anotherDependency: Demo1
 ) {
   ...
 }
 ```
 
-Third, `@Provides` method parameters take a qualifier also via the `@Param` annotation:
-
-```kotlin
-@Module
-abstract class DemoModule2 {
-  @Provides 
-  fun demoClass1(
-    @Param(QUALIFIER_ONE) neededDependency: Demo2
-  ): Demo1 {
-    return Demo1Impl()
-  }
-}
-```
-
-Finally, the `@Inject` annotation takes a qualifier as well:
+...along with `@Inject` targets (the `field:` prefix on the annotation name is important in Kotlin):
 
 ```kotlin
 class SomeClass {
-  @Inject(QUALIFIER_ONE) 
-  lateinit var someDependency: Demo1
-  @Inject(QUALIFIER_TWO) 
-  lateinit var anotherDependency: Demo1
+  @Inject @field:DemoQualifier1
+  lateinit var someDependency1: Demo1
+  @Inject @field:DemoQualifier2 
+  lateinit var someDependency2: Demo1
 
   init {
     component<SomeComponent>().inject(this)
   }
 }
-``` 
+```
+
+You will get two completely separate instances of `Demo1`, since two different qualifiers are being 
+used. `@Singleton` was applied for demo purposes to show that it'll store two different instances.
+But even without that, you're providing two different things. This could be useful if you were 
+providing primitives, like strings, or an interface for something like preferences. There's a lot of
+possibilities. 
 
 ---
 
@@ -467,43 +451,48 @@ Sometimes your app may need to be able to inject something that is defined at ru
 that cannot be constructed in a module. A good example of when this would be necessary is in 
 an Android application, like if you needed to inject the Application context.
 
-First, you tag constructor parameters that need to be provided at runtime with the `@Param` 
-annotation, which is discussed in [Qualifiers](#qualifiers) above.
+First, you tag constructor parameters or fields that need to be provided at runtime with a 
+qualifier annotation, which is discussed in [Qualifiers](#qualifiers) above.
 
 ```kotlin
-const val APP_CONTEXT: String = "app_context"
+@Qualifier
+annotation class AppContext
+
+@Qualifier
+annotation class ApiKey
 
 class StringRetriever(
-  @Param(APP_CONTEXT) val appContext: Context
+  @AppContext val appContext: Context,
+  @ApiKey val apiKey: String
 ) {
   fun getString(@IdRes res: Int): String {
     return appContext.resources.getString(res)
   }
 }
 ```
 
-At injection time, you pass mapped runtime dependencies into the `component` method. They are available 
-for injection until the component is destroyed, or its parents destroy it. 
+At injection time, you pass mapped runtime dependencies into the `component<>()` method. They are 
+available for injection until the component is destroyed, or its parents destroy it. 
 
 ```kotlin
-// Should ideally be the same constant above, rather than being defined twice
-const val APP_CONTEXT: String = "app_context"
-
 class LoginActivity : AppCompatActivity() {
   @Inject 
-  lateinit var stringRetriever: StringRetriever 
+  lateinit var stringRetriever: StringRetriever  
 
   override fun onCreate(savedInstanceState: Bundle?) {
     super.onCreate(savedInstanceState)
 
     component<LoginComponent>(
-      APP_CONTEXT to applicationContext 
+      AppContext::class to applicationContext,
+      ApiKey::class to "hello, world!"
     ).inject(this)
   }
 }
 ```
 
-Runtime dependencies in a component are made available to all of the component's children too. In an Android application, providing the application context at the `Application` level will make it available to all Activities and Fragments that use child components.
+Runtime dependencies in a component are made available to all of the component's children too. 
+In an Android application, providing the application context at the `Application` level will make 
+it available to all Activities and Fragments that use child components.
 
 ---
 
@@ -579,4 +568,4 @@ just inject the `ViewModel` as you would inject anything else.
 However, you can only inject a `ViewModel` into an `androidx.fragment.app.Fragment` or 
 `androidx.fragment.app.FragmentActivity` (includes `AppCompatActivity` and descendants). Why? 
 Internally, Ulfberht's generated code delegates through `ViewModelProviders` which must attach to 
-an Activity or Fragment.
+an Activity or Fragment.

annotations/src/main/kotlin/com/afollestad/ulfberht/annotation/Binds.kt

@@ -24,4 +24,4 @@ package com.afollestad.ulfberht.annotation
  */
 @Retention(AnnotationRetention.SOURCE)
 @Target(AnnotationTarget.FUNCTION)
-annotation class Binds(val qualifier: String = "")
+annotation class Binds

annotations/src/main/kotlin/com/afollestad/ulfberht/annotation/Inject.kt

@@ -24,4 +24,4 @@ package com.afollestad.ulfberht.annotation
  */
 @Retention(AnnotationRetention.SOURCE)
 @Target(AnnotationTarget.FIELD)
-annotation class Inject(val qualifier: String = "")
+annotation class Inject

annotations/src/main/kotlin/com/afollestad/ulfberht/annotation/Provides.kt

@@ -24,4 +24,4 @@ package com.afollestad.ulfberht.annotation
  */
 @Retention(AnnotationRetention.SOURCE)
 @Target(AnnotationTarget.FUNCTION)
-annotation class Provides(val qualifier: String = "")
+annotation class Provides

annotations/src/main/kotlin/com/afollestad/ulfberht/annotation/Param.kt annotations/src/main/kotlin/com/afollestad/ulfberht/annotation/Qualifier.kt

@@ -18,10 +18,10 @@
 package com.afollestad.ulfberht.annotation
 
 /**
- * Used to add an injection qualifier to a constructor or function parameter.
+ * Marks another annotation class as a qualifier.
  *
  * @author Aidan Follestad (@afollestad)
  */
-@Retention(AnnotationRetention.RUNTIME)
-@Target(AnnotationTarget.TYPE_PARAMETER, AnnotationTarget.VALUE_PARAMETER)
-annotation class Param(val qualifier: String)
+@Retention(AnnotationRetention.SOURCE)
+@Target(AnnotationTarget.ANNOTATION_CLASS)
+annotation class Qualifier

core/src/main/kotlin/com/afollestad/ulfberht/Components.kt

@@ -95,15 +95,16 @@ internal object Components {
  * @author Aidan Follestad (@afollestad)
  */
 inline fun <reified T : Any> component(
-  vararg runtimeDependencies: Pair<String?, Any>
+  vararg runtimeDependencies: Pair<KClass<*>, Any>
 ): T {
   return Components.get(T::class)
-      .withRuntimeDependencies(runtimeDependencies.toMap())
+      .withRuntimeDependencies(
+          runtimeDependencies.toMap().mapKeys { "@${it.key.qualifiedName}" })
 }
 
 @PublishedApi
 internal inline fun <reified T : Any> Any.withRuntimeDependencies(
-  runtimeDependencies: Map<String?, Any>
+  runtimeDependencies: Map<String, Any>
 ): T {
   return if (runtimeDependencies.isEmpty()) {
     this as T

core/src/main/kotlin/com/afollestad/ulfberht/common/BaseComponent.kt

@@ -34,7 +34,7 @@ interface BaseComponent : ScopeObserver {
   val parentType: KClass<*>?
   val children: MutableSet<BaseComponent>
   val modules: Set<BaseModule>
-  var runtimeDependencies: Map<String?, Any>?
+  var runtimeDependencies: Map<String, Any>?
 
   @Suppress("UNCHECKED_CAST")
   fun <T : Any> get(

processor/src/main/kotlin/com/afollestad/ulfberht/components/ComponentBuilder.kt

@@ -246,7 +246,7 @@ internal class ComponentBuilder(
 
   private fun propertyRuntimeDependencies(): PropertySpec {
     val propertyType = MAP
-        .parameterizedBy(NULLABLE_KOTLIN_STRING, ANY)
+        .parameterizedBy(STRING, ANY)
         .copy(nullable = true)
     return PropertySpec.builder(RUNTIME_DEPS_NAME, propertyType, OVERRIDE)
         .mutable()

processor/src/main/kotlin/com/afollestad/ulfberht/util/ProcessorUtil.kt

@@ -16,12 +16,9 @@
 package com.afollestad.ulfberht.util
 
 import com.afollestad.ulfberht.Provider
-import com.afollestad.ulfberht.annotation.Binds
 import com.afollestad.ulfberht.annotation.Inject
-import com.afollestad.ulfberht.annotation.Param
-import com.afollestad.ulfberht.annotation.Provides
+import com.afollestad.ulfberht.annotation.Qualifier
 import com.afollestad.ulfberht.util.Names.MODULES_LIST_NAME
-import com.afollestad.ulfberht.util.Names.QUALIFIER
 import com.afollestad.ulfberht.util.Types.VIEW_MODEL
 import com.squareup.kotlinpoet.BOOLEAN
 import com.squareup.kotlinpoet.ClassName
@@ -71,6 +68,13 @@ internal object ProcessorUtil {
     return getAnnotationMirror<T>() != null
   }
 
+  private fun Element.getQualifier(): String? {
+    return annotationMirrors.singleOrNull { ann ->
+      ann.annotationType.asElement()
+        .hasAnnotationMirror<Qualifier>()
+    }?.toString()
+  }
+
   fun TypeMirror.asTypeAndArgs(
     env: ProcessingEnvironment,
     nullable: Boolean = false,
@@ -124,23 +128,20 @@ internal object ProcessorUtil {
   fun VariableElement.asTypeAndArgs(
     env: ProcessingEnvironment
   ): TypeAndArgs {
-    val qualifier = getAnnotationMirror<Param>().qualifier
     return asType().asTypeAndArgs(
         env = env,
         nullable = isNullable(),
-        qualifier = qualifier
+        qualifier = getQualifier()
     )
   }
 
   fun ExecutableElement.returnTypeAsTypeAndArgs(
     env: ProcessingEnvironment
   ): TypeAndArgs {
-    val qualifier = (getAnnotationMirror<Provides>() ?: getAnnotationMirror<Binds>())
-        .qualifier
     return returnType.asTypeAndArgs(
         env = env,
         nullable = isNullable(),
-        qualifier = qualifier
+        qualifier = getQualifier()
     )
   }
 
@@ -166,7 +167,7 @@ internal object ProcessorUtil {
   fun Collection<Element>.injectedFieldsAndQualifiers(): Sequence<Pair<VariableElement, String?>> {
     return filterFields()
         .filter { it.getAnnotationMirror<Inject>() != null }
-        .map { Pair(it, it.getAnnotationMirror<Inject>()!!.getParameter<String>("qualifier")) }
+        .map { Pair(it, it.getQualifier()) }
   }
 
   fun Collection<Element>.filterMethods(): Sequence<ExecutableElement> {
@@ -317,22 +318,12 @@ internal object ProcessorUtil {
         asTypeElement().getSuperClass(env).isViewModel(env)
   }
 
-//  fun TypeMirror?.isActivityOrFragment(): Boolean {
-//    return
-//  }
-
   val AnnotationMirror?.name: String?
     get() {
       val qualifier: String = this?.getParameter("name") ?: return null
       return if (qualifier.isEmpty()) null else qualifier
     }
 
-  private val AnnotationMirror?.qualifier: String?
-    get() {
-      val qualifier: String = this?.getParameter(QUALIFIER) ?: return null
-      return if (qualifier.isEmpty()) null else qualifier
-    }
-
   private fun Element.getSuperClass(env: ProcessingEnvironment): TypeMirror? {
     return env.typeUtils.directSupertypes(this.asType())
         .asSequence()

sample-android/src/main/kotlin/com/afollestad/ulfberhtsample/ScopeNames.kt

@@ -19,7 +19,3 @@ object ScopeNames {
   const val LOGIN = "login_scope"
   const val MAIN = "main_scope"
 }
-
-object ParamNames {
-  const val APP_CONTEXT = "param_app_context"
-}

sample-android/src/main/kotlin/com/afollestad/ulfberhtsample/api/Authenticator.kt

@@ -16,8 +16,7 @@
 package com.afollestad.ulfberhtsample.api
 
 import android.util.Log
-import com.afollestad.ulfberht.annotation.Param
-import com.afollestad.ulfberhtsample.Qualifiers.API_KEY
+import com.afollestad.ulfberhtsample.app.ApiKey
 
 interface Authenticator {
   fun login(
@@ -27,7 +26,7 @@ interface Authenticator {
 }
 
 class RealAuthenticator(
-  @Param(API_KEY) private val apiKey: String,
+  @ApiKey private val apiKey: String,
   private val session: Session
 ) : Authenticator {
   override fun login(