<commit_before>//
//  SQLClient.swift
//  LittlinkRouterPerfect
//
//  Created by <NAME> on 10/30/16.
//
//

import Foundation

/// Represents a potential source of SQL data.
/// 
/// A type conforming to `SQLClient` is never instantiated and in fact usually 
/// ought to be an `enum` with no cases. Rather, it specifies a series of 
/// associated types and methods which together represent all of the functionality 
/// needed by the `SQLDatabase`, `SQLConnection`, `SQLQuery`, `SQLRowIterator`, 
/// and `SQLRow` types.
/// 
/// The associated types specified in `SQLClient` are opaque instances which back 
/// each of these types. Client authors can use these if they wish to expose 
/// types of the underlying database client library for low-level access, or they 
/// can instead provide totally opaque types with no user-visible API surface.
/// 
/// Users only use `SQLClient`-conforming types as generic parameters to 
/// other types: `SQLDatabase<SomeClient>`, `SQLQuery<SomeClient>`, etc. The 
/// best name for a `SQLClient`-conforming type thus usually does *not* include 
/// `Client`, but merely names the engine: `PostgreSQL`, `SQLite`, etc.
public protocol SQLClient: _SQLClient {
    /// The state backing a `SQLDatabase<Self>` instance.
    associatedtype DatabaseState
    
    /// The state backing a `SQLConnection<Self>` instance.
    associatedtype ConnectionState
    
    /// The state backing a `SQLQuery<Self>` instance.
    associatedtype QueryState
    <commit_msg>Add notes on SQLClient’s design<commit_after>//
//  SQLClient.swift
//  LittlinkRouterPerfect
//
//  Created by <NAME> on 10/30/16.
//
//

import Foundation

/// Represents a potential source of SQL data.
/// 
/// A type conforming to `SQLClient` is never instantiated and in fact usually 
/// ought to be an `enum` with no cases. Rather, it specifies a series of 
/// associated types and methods which together represent all of the functionality 
/// needed by the `SQLDatabase`, `SQLConnection`, `SQLQuery`, `SQLRowIterator`, 
/// and `SQLRow` types.
/// 
/// The associated types specified in `SQLClient` are opaque instances which back 
/// each of these types. Client authors can use these if they wish to expose 
/// types of the underlying database client library for low-level access, or they 
/// can instead provide totally opaque types with no user-visible API surface.
/// 
/// Users only use `SQLClient`-conforming types as generic parameters to 
/// other types: `SQLDatabase<SomeClient>`, `SQLQuery<SomeClient>`, etc. The 
/// best name for a `SQLClient`-conforming type thus usually does *not* include 
/// `Client`, but merely names the engine: `PostgreSQL`, `SQLite`, etc.
public protocol SQLClient: _SQLClient {
    // This protocol has an awkward design which mixes different concerns into 
    // a single type, doesn't allow instantiation, includes many opaque types,  
    // and generally is not very easy to use or even sane.
    // 
    // This is intentional.
    // 
    // SQLKit's primary goal is to provide a uniform interface to disparate 
    // SQL clients. To that end, it provides uniform types like `SQLConnection` 
    // and `SQLQuery` and forces you to use them. If `SQLClient` were 
    // decomposed into several sensible protocols--such as 
    // `SQLConnectionProtocol`, `SQLQueryProtocol`, etc.--then it would be 
    // very convenient to use client-specific types directly, and those 
    // client-specific types could easily add non-uniform members which 
    // people might use instead of the standardized SQLKit members.
    // 
    // By instead designing `SQLClient` as a single, monolitic protocol with 
    // a minimal interface and various awkward features, `SQLKit` avoids this 
    // danger and can force uniformity, which will help developers who find 
    // themselves switching SQL clients, wanting to mock a SQL client during 
    // testing, using SQLite in development, etc.
    // 
    // It is, of course, possible for a client to extend `SQLConnection where 
    // Client == SomeClient` and thereby add client-specific members. But this 
    // is a little more difficult, so hopefully people won't do it as casually.
    
    /// The state backing a `SQLDatabase<Self>` instance.
    associatedtype DatabaseState
    
    /// The state backing a `SQLConnection<Self>` instance.
    associatedtype ConnectionState
    
    /// The state backing a `SQLQuery<Self>` instance.
    associatedtype QueryState
    
{'fraction_non_alphanumeric': 0.09439857174737781, 'fraction_numerical': 0.0026779736665922785, 'mean_word_length': 3.0597826086956523, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7365913', 'n_tokens_mistral': 1186, 'n_tokens_neox': 1124, 'n_words': 542}