Restructure the deeplink artifact

1. Simplified the base package from "deeplink.parseIntent.singleModule" to "deeplink.basic".
2. Added `ui` and `deeplinkutil` packages to separate sample ui code from parsing/matching helpers
3. Separate classes within DeepLinkUtil into their own separate files
4. Separate DeepLinkRequest into two separate classes
     - DeepLinkRequest: parse uri and store parse result
     - DeepLinkMatcher: takes a request + pattern and matches the two
5. Change type <T> upper bound to NavKey to make the helpers more general

Other misc non-structural changes:
1. Added kdocs in CreateDeepLinkActivity to explain how this recipe works
2. inlined String parsers into #getTypeParser

Author: claraf3

app/src/main/AndroidManifest.xml

@@ -141,12 +141,12 @@
             android:exported="true"
             android:theme="@style/Theme.Nav3Recipes"/>
         <activity
-            android:name=".deeplink.parseintent.singleModule.CreateDeepLinkActivity"
+            android:name=".deeplink.basic.CreateDeepLinkActivity"
             android:exported="true"
             android:theme="@style/Theme.Nav3Recipes">
         </activity>
         <activity
-            android:name=".deeplink.parseintent.singleModule.MainActivity"
+            android:name=".deeplink.basic.MainActivity"
             android:exported="true"
             android:theme="@style/Theme.Nav3Recipes">
             <intent-filter android:autoVerify="true">

app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt

@@ -31,7 +31,7 @@ import com.example.nav3recipes.basicdsl.BasicDslActivity
 import com.example.nav3recipes.basicsaveable.BasicSaveableActivity
 import com.example.nav3recipes.commonui.CommonUiActivity
 import com.example.nav3recipes.conditional.ConditionalActivity
-import com.example.nav3recipes.deeplink.parseintent.singleModule.CreateDeepLinkActivity
+import com.example.nav3recipes.deeplink.basic.CreateDeepLinkActivity
 import com.example.nav3recipes.dialog.DialogActivity
 import com.example.nav3recipes.modular.hilt.ModularActivity
 import com.example.nav3recipes.passingarguments.viewmodels.basic.BasicViewModelsActivity

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/CreateDeepLinkActivity.kt renamed to app/src/main/java/com/example/nav3recipes/deeplink/basic/CreateDeepLinkActivity.kt

@@ -1,4 +1,4 @@
-package com.example.nav3recipes.deeplink.parseintent.singleModule
+package com.example.nav3recipes.deeplink.basic
 
 import android.os.Bundle
 import androidx.activity.ComponentActivity
@@ -9,9 +9,47 @@ import androidx.compose.runtime.mutableStateMapOf
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
+import com.example.nav3recipes.deeplink.basic.ui.DeepLinkButton
+import com.example.nav3recipes.deeplink.basic.ui.EMPTY
+import com.example.nav3recipes.deeplink.basic.ui.EntryScreen
+import com.example.nav3recipes.deeplink.basic.ui.FIRST_NAME_JOHN
+import com.example.nav3recipes.deeplink.basic.ui.FIRST_NAME_JULIE
+import com.example.nav3recipes.deeplink.basic.ui.FIRST_NAME_MARY
+import com.example.nav3recipes.deeplink.basic.ui.FIRST_NAME_TOM
+import com.example.nav3recipes.deeplink.basic.ui.LOCATION_BC
+import com.example.nav3recipes.deeplink.basic.ui.LOCATION_BR
+import com.example.nav3recipes.deeplink.basic.ui.LOCATION_CA
+import com.example.nav3recipes.deeplink.basic.ui.LOCATION_US
+import com.example.nav3recipes.deeplink.basic.ui.MenuDropDown
+import com.example.nav3recipes.deeplink.basic.ui.MenuTextInput
+import com.example.nav3recipes.deeplink.basic.ui.PATH_BASE
+import com.example.nav3recipes.deeplink.basic.ui.PATH_INCLUDE
+import com.example.nav3recipes.deeplink.basic.ui.PATH_SEARCH
+import com.example.nav3recipes.deeplink.basic.ui.STRING_LITERAL_HOME
+import com.example.nav3recipes.deeplink.basic.ui.SearchKey
+import com.example.nav3recipes.deeplink.basic.ui.TextContent
+import com.example.nav3recipes.deeplink.basic.ui.HomeKey
+import com.example.nav3recipes.deeplink.basic.ui.UsersKey
 
 /**
- * This activity allows the user to create a deep link and make a request with it
+ * This activity allows the user to create a deep link and make a request with it.
+ *
+ * **HOW THIS RECIPE WORKS** it consists of two activities - [CreateDeepLinkActivity] to construct
+ * and trigger the deeplink request, and the [MainActivity] to show how an app can handle
+ * that request.
+ *
+ * **DEMONSTRATED FORMS OF DEEPLINK** The [MainActivity] has a several backStack keys to
+ * demonstrate different types of supported deeplinks:
+ * 1. [HomeKey] - deeplink with an exact url (no deeplink arguments)
+ * 2. [UsersKey] - deeplink with path arguments
+ * 3. [SearchKey] - deeplink with query arguments
+ * See [MainActivity.deepLinkPatterns] for the actual url pattern of each.
+ *
+ * **RECIPE STRUCTURE** This recipe consists of three main packages:
+ * 1. basic.deeplink - Contains the two activities
+ * 2. basic.deeplink.ui - Contains the activity UI code, i.e. Screens, global string variables etc
+ * 3. basic.deeplink.deeplinkutil - Contains the classes and helper methods to parse and match
+ * the deeplinks
  *
  * See [MainActivity] for how the requested deeplink is handled.
  */
@@ -24,7 +62,7 @@ class CreateDeepLinkActivity : ComponentActivity() {
              * UI for deeplink sandbox
              */
             EntryScreen("Sandbox - Build Your Deeplink") {
-                TextContent("Base url:\n$PATH_BASE/")
+                TextContent("Base url:\n${PATH_BASE}/")
                 var showFilterOptions by remember { mutableStateOf(false) }
                 val selectedPath = remember { mutableStateOf(MENU_OPTIONS_PATH[KEY_PATH]?.first()) }
 
@@ -42,10 +80,12 @@ class CreateDeepLinkActivity : ComponentActivity() {
                             showQueryOptions = true
                             showFilterOptions = false
                         }
+
                         PATH_INCLUDE -> {
                             showQueryOptions = false
                             showFilterOptions = true
                         }
+
                         else -> {
                             showQueryOptions = false
                             showFilterOptions = false
@@ -64,7 +104,7 @@ class CreateDeepLinkActivity : ComponentActivity() {
                 if (showFilterOptions) {
                     MenuDropDown(
                         menuOptions = MENU_OPTIONS_FILTER,
-                    )  { _, selected ->
+                    ) { _, selected ->
                         selectedFilter = selected
                     }
                 }
@@ -104,9 +144,10 @@ class CreateDeepLinkActivity : ComponentActivity() {
                             }
                         }
                     }
+
                     else -> ""
                 }
-                val finalUrl = "$PATH_BASE/${selectedPath.value}$arguments"
+                val finalUrl = "${PATH_BASE}/${selectedPath.value}$arguments"
                 TextContent("Final url:\n$finalUrl")
                 // deeplink to target
                 DeepLinkButton(
@@ -133,7 +174,13 @@ private val MENU_OPTIONS_FILTER = mapOf(
 )
 
 private val MENU_OPTIONS_SEARCH = mapOf(
-    SearchKey::firstName.name to listOf(EMPTY, FIRST_NAME_JOHN, FIRST_NAME_TOM, FIRST_NAME_MARY, FIRST_NAME_JULIE),
+    SearchKey::firstName.name to listOf(
+        EMPTY,
+        FIRST_NAME_JOHN,
+        FIRST_NAME_TOM,
+        FIRST_NAME_MARY,
+        FIRST_NAME_JULIE
+    ),
     SearchKey::location.name to listOf(EMPTY, LOCATION_CA, LOCATION_BC, LOCATION_BR, LOCATION_US)
 )
 

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/MainActivity.kt renamed to app/src/main/java/com/example/nav3recipes/deeplink/basic/MainActivity.kt

@@ -1,4 +1,4 @@
-package com.example.nav3recipes.deeplink.parseintent.singleModule
+package com.example.nav3recipes.deeplink.basic
 
 import android.net.Uri
 import android.os.Bundle
@@ -10,6 +10,21 @@ import androidx.navigation3.runtime.NavKey
 import androidx.navigation3.runtime.entryProvider
 import androidx.navigation3.runtime.rememberNavBackStack
 import androidx.navigation3.ui.NavDisplay
+import com.example.nav3recipes.deeplink.basic.deeplinkutil.DeepLinkMatcher
+import com.example.nav3recipes.deeplink.basic.deeplinkutil.DeepLinkPattern
+import com.example.nav3recipes.deeplink.basic.deeplinkutil.DeepLinkRequest
+import com.example.nav3recipes.deeplink.basic.deeplinkutil.DeepLinkMatchResult
+import com.example.nav3recipes.deeplink.basic.deeplinkutil.KeyDecoder
+import com.example.nav3recipes.deeplink.basic.ui.EntryScreen
+import com.example.nav3recipes.deeplink.basic.ui.FriendsList
+import com.example.nav3recipes.deeplink.basic.ui.HomeKey
+import com.example.nav3recipes.deeplink.basic.ui.LIST_USERS
+import com.example.nav3recipes.deeplink.basic.ui.SearchKey
+import com.example.nav3recipes.deeplink.basic.ui.TextContent
+import com.example.nav3recipes.deeplink.basic.ui.URL_HOME_EXACT
+import com.example.nav3recipes.deeplink.basic.ui.URL_SEARCH
+import com.example.nav3recipes.deeplink.basic.ui.URL_USERS_WITH_FILTER
+import com.example.nav3recipes.deeplink.basic.ui.UsersKey
 
 /**
  * Parses a target deeplink into a NavKey. There are several crucial steps involved:
@@ -37,7 +52,8 @@ import androidx.navigation3.ui.NavDisplay
  */
 class MainActivity : ComponentActivity() {
     /** STEP 1. Parse supported deeplinks */
-    private val deepLinkPatterns: List<DeepLinkPattern<out NavRecipeKey>> = listOf(
+    // internal so that landing activity can link to this in the kdocs
+    internal val deepLinkPatterns: List<DeepLinkPattern<out NavKey>> = listOf(
         // "https://www.nav3recipes.com/home"
         DeepLinkPattern(HomeKey.serializer(), (URL_HOME_EXACT).toUri()),
         // "https://www.nav3recipes.com/users/with/{filter}"
@@ -54,10 +70,10 @@ class MainActivity : ComponentActivity() {
         // associate the target with the correct backstack key
         val key: NavKey = uri?.let {
             /** STEP 2. Parse requested deeplink */
-            val target = DeepLinkRequest(uri)
+            val request = DeepLinkRequest(uri)
             /** STEP 3. Compared requested with supported deeplink to find match*/
-            val match = deepLinkPatterns.firstNotNullOfOrNull { candidate ->
-                target.match(candidate)
+            val match = deepLinkPatterns.firstNotNullOfOrNull { pattern ->
+                DeepLinkMatcher(request, pattern).match()
             }
             /** STEP 4. If match is found, associate match to the correct key*/
             match?.let {
@@ -98,9 +114,9 @@ class MainActivity : ComponentActivity() {
                             TextContent("<matches query parameters, if any>")
                             val matchingUsers = LIST_USERS.filter { user ->
                                 (search.firstName == null || user.firstName == search.firstName) &&
-                                (search.location == null || user.location == search.location) &&
-                                (search.ageMin == null || user.age >= search.ageMin) &&
-                                (search.ageMax == null || user.age <= search.ageMax)
+                                        (search.location == null || user.location == search.location) &&
+                                        (search.ageMin == null || user.age >= search.ageMin) &&
+                                        (search.ageMax == null || user.age <= search.ageMax)
                             }
                             FriendsList(matchingUsers)
                         }

app/src/main/java/com/example/nav3recipes/deeplink/basic/deeplinkutil/DeepLinkMatcher.kt

@@ -0,0 +1,80 @@
+package com.example.nav3recipes.deeplink.basic.deeplinkutil
+
+import android.util.Log
+import androidx.navigation3.runtime.NavKey
+import kotlinx.serialization.KSerializer
+
+internal class DeepLinkMatcher<T : NavKey>(
+    val request: DeepLinkRequest,
+    val deepLinkPattern: DeepLinkPattern<T>
+) {
+    /**
+     * Match a [DeepLinkRequest] to a [DeepLinkPattern].
+     *
+     * Returns a [DeepLinkMatchResult] if this matches the pattern, returns null otherwise
+     */
+    fun match(): DeepLinkMatchResult<T>? {
+        if (request.pathSegments.size != deepLinkPattern.pathSegments.size) return null
+        // exact match (url does not contain any arguments)
+        if (request.uri == deepLinkPattern.uriPattern)
+            return DeepLinkMatchResult(deepLinkPattern.serializer, mapOf())
+
+        val args = mutableMapOf<String, Any>()
+        // match the path
+        request.pathSegments
+            .asSequence()
+            // zip to compare the two objects side by side, order matters here so we
+            // need to make sure the compared segments are at the same position within the url
+            .zip(deepLinkPattern.pathSegments.asSequence())
+            .forEach { it ->
+                // retrieve the two path segments to compare
+                val requestedSegment = it.first
+                val candidateSegment = it.second
+                // if the potential match expects a path arg for this segment, try to parse the
+                // requested segment into the expected type
+                if (candidateSegment.isParamArg) {
+                    val parsedValue = try {
+                        candidateSegment.typeParser.invoke(requestedSegment)
+                    } catch (e: IllegalArgumentException) {
+                        Log.e(TAG_LOG_ERROR, "Failed to parse path value:[$requestedSegment].", e)
+                        return null
+                    }
+                    args[candidateSegment.stringValue] = parsedValue
+                } else if(requestedSegment != candidateSegment.stringValue){
+                    // if it's path arg is not the expected type, its not a match
+                    return null
+                }
+            }
+        // match queries (if any)
+        request.queries.forEach { query ->
+            val name = query.key
+            val queryStringParser = deepLinkPattern.queryValueParsers[name]
+            val queryParsedValue = try {
+                queryStringParser!!.invoke(query.value)
+            } catch (e: IllegalArgumentException) {
+                Log.e(TAG_LOG_ERROR, "Failed to parse query name:[$name] value:[${query.value}].", e)
+                return null
+            }
+            args[name] = queryParsedValue
+        }
+        // provide the serializer of the matching key and map of arg names to parsed arg values
+        return DeepLinkMatchResult(deepLinkPattern.serializer, args)
+    }
+}
+
+
+/**
+ * Created when a requested deeplink matches with a supported deeplink
+ *
+ * @param [T] the backstack key associated with the deeplink that matched with the requested deeplink
+ * @param serializer serializer for [T]
+ * @param args The map of argument name to argument value. The value is expected to have already
+ * been parsed from the raw url string back into its proper KType as declared in [T].
+ * Includes arguments for all parts of the uri - path, query, etc.
+ * */
+internal data class DeepLinkMatchResult<T : NavKey>(
+    val serializer: KSerializer<T>,
+    val args: Map<String, Any>
+)
+
+const val TAG_LOG_ERROR = "Nav3RecipesDeepLink"