qubit-validator 0.1.0

Type-safe validation traits and registries for Qubit applications
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================

//! Validator registrations for the next-generation registry.

use super::ValidatorDescriptor;
use crate::RegistrationSource;
use crate::ValidatorId;

/// One validator definition associated with a stable identifier.
///
/// # Examples
///
/// ```
/// use std::sync::Arc;
///
/// use qubit_validator::{
///     ArgumentReader, BindError, BoundValidationContext, ExecutionError, InputType,
///     PreparedOutcome, PreparedValidator, RegistrationSource, ValidationValue, ValidatorDescriptor,
///     ValidatorId, ValidatorRegistration, ValidatorSignature,
/// };
///
/// struct Accept;
/// impl PreparedValidator for Accept {
///     fn input_type(&self) -> InputType { InputType::Text }
///     fn dependency_specs(&self) -> &'static [qubit_validator::DependencySpec] { &[] }
///     fn validate(
///         &self,
///         _: ValidationValue<'_>,
///         _: &BoundValidationContext<'_>,
///     ) -> Result<PreparedOutcome, ExecutionError> {
///         Ok(PreparedOutcome::valid())
///     }
/// }
/// fn prepare(_reader: &mut ArgumentReader<'_>) -> Result<Arc<dyn PreparedValidator>, BindError> {
///     Ok(Arc::new(Accept))
/// }
/// static SIGNATURES: &[ValidatorSignature] = &[
///     ValidatorSignature::new(InputType::Text, &[], prepare),
/// ];
/// static DESCRIPTOR: ValidatorDescriptor = ValidatorDescriptor::new(SIGNATURES);
///
/// let registration = ValidatorRegistration::new(
///     ValidatorId::new("text.non_blank"),
///     &DESCRIPTOR,
///     RegistrationSource::new("rules", "rules::text", "src/text.rs", 12),
/// );
/// assert_eq!(registration.id().as_str(), "text.non_blank");
/// ```
#[derive(Clone, Copy, Debug)]
pub struct ValidatorRegistration {
    /// Stable identifier claimed by the registration.
    id: ValidatorId,
    /// Immutable descriptor for every supported input shape.
    descriptor: &'static ValidatorDescriptor,
    /// Compile-time source metadata used in duplicate diagnostics.
    source: RegistrationSource,
}

impl ValidatorRegistration {
    /// Creates a validator registration from its identifier, descriptor, and
    /// source.
    ///
    /// `id` is the stable validator identifier, `descriptor` defines the
    /// supported signatures, and `source` records where the registration was
    /// declared. The descriptor must live for the duration of the program.
    /// This constructor only stores the supplied values and does not access
    /// the file system. It can be used for local registrations as well as the
    /// registrations generated by `register_validator!`.
    ///
    /// # Parameters
    ///
    /// - `id`: Stable identifier claimed by the registration.
    /// - `descriptor`: Static definition of the supported signatures.
    /// - `source`: Compile-time metadata identifying the declaration site.
    ///
    /// # Returns
    ///
    /// A registration containing the supplied identifier, descriptor, and
    /// source metadata.
    #[must_use]
    #[inline]
    pub const fn new(id: ValidatorId, descriptor: &'static ValidatorDescriptor, source: RegistrationSource) -> Self {
        Self { id, descriptor, source }
    }

    /// Returns the stable identifier.
    ///
    /// # Returns
    ///
    /// The identifier claimed by this registration.
    #[must_use]
    #[inline]
    pub const fn id(&self) -> ValidatorId {
        self.id
    }

    /// Returns the immutable descriptor.
    ///
    /// # Returns
    ///
    /// The static descriptor defining this registration's supported
    /// signatures.
    #[must_use]
    #[inline]
    pub const fn descriptor(&self) -> &'static ValidatorDescriptor {
        self.descriptor
    }

    /// Returns the source location used for duplicate diagnostics.
    ///
    /// # Returns
    ///
    /// The compile-time source metadata associated with this registration.
    #[must_use]
    #[inline]
    pub const fn source(&self) -> RegistrationSource {
        self.source
    }
}

// Supports callers that still hold static references to registrations.
impl From<&ValidatorRegistration> for ValidatorRegistration {
    /// Copies a registration borrowed from a static-compatible reference.
    #[inline]
    fn from(value: &ValidatorRegistration) -> Self {
        *value
    }
}