How devxoul/urlnavigator works
Project type and purpose
• This is an open-source Swift library (URLNavigator) plus an example iOS app demonstrating how to use it.
• Its purpose is to provide a URL-driven navigation engine that maps URL patterns to view controllers or handler closures.
File-structure analysis
• Top-level “Sources” folder contains two separate modules:
• URLMatcher – parses and matches incoming URLs against registered patterns.
• URLNavigator – exposes the Navigator API, registration functions, and UIKit integration.
• “Example” folder is a standalone iOS app that consumes the library, showing how to register URL maps in AppDelegate, define view controllers, and trigger push/present/open.
• “Tests” folder holds unit tests for both URLMatcher and URLNavigator modules.
• CI/CD workflows, Podspec, Package.swift, and codecov.yml reveal support for CocoaPods, SwiftPM, and continuous integration.
Key architectural insights from the README
• Core functionality is layered: pattern matching (URLMatcher) underpins the navigation logic (URLNavigator).
• Clients register URL patterns to initializers or handlers; Navigator resolves patterns, extracts placeholders, instantiates or calls closures.
• Integration points with iOS: UIApplicationDelegate launch/open URL callbacks, UIViewController extensions to find topmost controller, optional wrapping in UINavigationController.
• Extensibility: custom value converters, pluggable NavigatorProtocol, and ability to register handlers anywhere (global, IoC container, composition root).
Main components and interactions
• Component A: URLMatcher module
• URLConvertible, URLMatcher, URLMatchResult, URLPathComponent, converters
• Responsibility: parse URL strings, match against patterns, extract typed placeholder values
• Component B: URLNavigator module
• Navigator, NavigatorProtocol, NavigatorDelegate, UIViewController+TopMostViewController, UIViewControllerType
• Responsibility: hold registry of patterns → handler mappings, coordinate push/present/open calls, resolve top view controller
• Component C: Example App
• AppDelegate (initializes Navigator, registers map via NavigationMap), ViewControllers (UserList, UserView), Views (cells), Models (User, Repo), Networking (GitHub API)
• Responsibility: consume Navigator API, demonstrate URL-driven navigation flows
• Component D: External systems
• UIKit (UINavigationController, UIViewController, UIApplicationDelegate)
• CocoaPods / Swift Package Manager (distribution)
Data flows and relationships
• AppDelegate → calls URLNavigationMap.initialize(navigator) → Navigator.register(pattern, handler)
• User triggers Navigator.push/open/present(“scheme://…”) → Navigator uses URLMatcher to match URL → retrieves values → either instantiates UIViewController or executes handler closure → UIKit pushes/presents the resulting VC
• Tests invoke URLMatcher.match() and Navigator.open() directly to assert behavior
Architectural patterns and principles
• Separation of concerns: matching logic isolated in URLMatcher, navigation orchestration in URLNavigator, consumption in Example
• Protocol-oriented design: NavigatorProtocol allows mocking, extension points for delegate
• Inversion of control: clients supply closure or conforming type to handle matched URLs
• Single responsibility: each class or file has a narrow, well-defined role