183bef5cf6
Well, not really, of course. All of this will make sense once we start adding support for fields and non-struct types. Refactoring the code now before we start to add actual member field parsing is much easier. How do I know that this will work out? Well, my crystal ball knows it. Don't believe me? Okay, ChatGPT told me ... Alright alright, I went through the entire process of implementing this feature *twice* at this point and have a pretty good idea of where to draw the abstraction lines so that everything falls neatly into place. You'll have to trust me on this one. (Or, you know, check out old branches in my xmpp-rs repo. That might work, too. `feature/derive-macro-streaming-full` might be a name to look for if you dare.)
656 lines
24 KiB
Rust
656 lines
24 KiB
Rust
// Copyright (c) 2024 Jonas Schäfer <jonas@zombofant.net>
|
|
//
|
|
// This Source Code Form is subject to the terms of the Mozilla Public
|
|
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
|
|
//! State machines for parsing and serialising of structs and enums.
|
|
|
|
use proc_macro2::TokenStream;
|
|
use quote::{quote, ToTokens};
|
|
use syn::*;
|
|
|
|
/// A single state in a parser or serializer state machine.
|
|
pub(crate) struct State {
|
|
/// Name of the state enum variant for this state.
|
|
name: Ident,
|
|
|
|
/// Declaration of members of the state enum in this state.
|
|
decl: TokenStream,
|
|
|
|
/// Destructuring of members of the state enum in this state.
|
|
destructure: TokenStream,
|
|
|
|
/// Right-hand-side of the match arm for this state.
|
|
advance_body: TokenStream,
|
|
}
|
|
|
|
impl State {
|
|
/// Create a new state with the a builder data field.
|
|
///
|
|
/// This is a convenience wrapper around `new()` and `add_field()`. This
|
|
/// wrapper, or its equivalent, **must** be used for states used in
|
|
/// [`FromEventsStateMachine`] state machines, as those expect that the
|
|
/// first field is the builder data at render time.
|
|
pub(crate) fn new_with_builder(
|
|
name: Ident,
|
|
builder_data_ident: &Ident,
|
|
builder_data_ty: &Type,
|
|
) -> Self {
|
|
let mut result = Self::new(name);
|
|
result.add_field(builder_data_ident, builder_data_ty);
|
|
result
|
|
}
|
|
|
|
/// Create a new, empty state.
|
|
///
|
|
/// Note that an empty state will generate invalid code. At the very
|
|
/// least, a body must be added using [`Self::set_impl`] or
|
|
/// [`Self::with_impl`]. The various state machines may also have
|
|
/// additional requirements.
|
|
pub(crate) fn new(name: Ident) -> Self {
|
|
Self {
|
|
name,
|
|
decl: TokenStream::default(),
|
|
destructure: TokenStream::default(),
|
|
advance_body: TokenStream::default(),
|
|
}
|
|
}
|
|
|
|
/// Add a field to this state's data.
|
|
///
|
|
/// - `name` is the name under which the data will be accessible in the
|
|
/// state's implementation.
|
|
/// - `ty` must be the data field's type.
|
|
pub(crate) fn add_field(&mut self, name: &Ident, ty: &Type) {
|
|
self.decl.extend(quote! { #name: #ty, });
|
|
self.destructure.extend(quote! { #name, });
|
|
}
|
|
|
|
/// Modify the state to include another field and return the modified
|
|
/// state.
|
|
///
|
|
/// This is a consume-and-return-style version of [`Self::add_field`].
|
|
pub(crate) fn with_field(mut self, name: &Ident, ty: &Type) -> Self {
|
|
self.add_field(name, ty);
|
|
self
|
|
}
|
|
|
|
/// Set the `advance` implementation of this state.
|
|
///
|
|
/// `body` must be the body of the right hand side of the match arm for
|
|
/// the `advance` implementation of the state machine.
|
|
///
|
|
/// See [`FromEventsStateMachine::advance_match_arms`] and
|
|
/// [`IntoEventsSubmachine::compile`] for the respective
|
|
/// requirements on the implementations.
|
|
pub(crate) fn with_impl(mut self, body: TokenStream) -> Self {
|
|
self.advance_body = body;
|
|
self
|
|
}
|
|
}
|
|
|
|
/// A partial [`FromEventsStateMachine`] which only covers the builder for a
|
|
/// single compound.
|
|
///
|
|
/// See [`FromEventsStateMachine`] for more information on the state machines
|
|
/// in general.
|
|
pub(crate) struct FromEventsSubmachine {
|
|
/// Additional items necessary for the statemachine.
|
|
pub(crate) defs: TokenStream,
|
|
|
|
/// States and state transition implementations.
|
|
pub(crate) states: Vec<State>,
|
|
|
|
/// Initializer expression.
|
|
///
|
|
/// This expression must evaluate to a
|
|
/// `Result<#state_ty_ident, xso::FromEventsError>`.
|
|
pub(crate) init: TokenStream,
|
|
}
|
|
|
|
impl FromEventsSubmachine {
|
|
/// Convert a partial state machine into a full state machine.
|
|
///
|
|
/// This converts the abstract [`State`] items into token
|
|
/// streams for the respective parts of the state machine (the state
|
|
/// definitions and the match arms), rendering them effectively immutable.
|
|
pub(crate) fn compile(self) -> FromEventsStateMachine {
|
|
let mut state_defs = TokenStream::default();
|
|
let mut advance_match_arms = TokenStream::default();
|
|
|
|
for state in self.states {
|
|
let State {
|
|
name,
|
|
decl,
|
|
destructure,
|
|
advance_body,
|
|
} = state;
|
|
|
|
state_defs.extend(quote! {
|
|
#name { #decl },
|
|
});
|
|
|
|
// XXX: nasty hack, but works: the first member of the enum always
|
|
// exists and it always is the builder data, which we always need
|
|
// mutably available. So we can just prefix the destructuring
|
|
// token stream with `mut` to make that first member mutable.
|
|
advance_match_arms.extend(quote! {
|
|
Self::#name { mut #destructure } => {
|
|
#advance_body
|
|
}
|
|
});
|
|
}
|
|
|
|
FromEventsStateMachine {
|
|
defs: self.defs,
|
|
state_defs,
|
|
advance_match_arms,
|
|
variants: vec![FromEventsEntryPoint { init: self.init }],
|
|
}
|
|
}
|
|
|
|
/// Update the [`init`][`Self::init`] field in-place.
|
|
///
|
|
/// The function will receive a reference to the current `init` value,
|
|
/// allowing to create "wrappers" around that existing code.
|
|
pub(crate) fn with_augmented_init<F: FnOnce(&TokenStream) -> TokenStream>(
|
|
mut self,
|
|
f: F,
|
|
) -> Self {
|
|
let new_init = f(&self.init);
|
|
self.init = new_init;
|
|
self
|
|
}
|
|
}
|
|
|
|
/// A partial [`IntoEventsStateMachine`] which only covers the builder for a
|
|
/// single compound.
|
|
///
|
|
/// See [`IntoEventsStateMachine`] for more information on the state machines
|
|
/// in general.
|
|
pub(crate) struct IntoEventsSubmachine {
|
|
/// Additional items necessary for the statemachine.
|
|
pub(crate) defs: TokenStream,
|
|
|
|
/// States and state transition implementations.
|
|
pub(crate) states: Vec<State>,
|
|
|
|
/// A pattern match which destructures the target type into its parts, for
|
|
/// use by `init`.
|
|
pub(crate) destructure: TokenStream,
|
|
|
|
/// An expression which uses the names bound in `destructure` to create a
|
|
/// an instance of the state enum.
|
|
///
|
|
/// The state enum type is available as `Self` in that context.
|
|
pub(crate) init: TokenStream,
|
|
}
|
|
|
|
impl IntoEventsSubmachine {
|
|
/// Convert a partial state machine into a full state machine.
|
|
///
|
|
/// This converts the abstract [`State`] items into token
|
|
/// streams for the respective parts of the state machine (the state
|
|
/// definitions and the match arms), rendering them effectively immutable.
|
|
///
|
|
/// This requires that the [`State::advance_body`] token streams evaluate
|
|
/// to an `Option<rxml::Event>`. If it evaluates to `Some(.)`, that is
|
|
/// emitted from the iterator. If it evaluates to `None`, the `advance`
|
|
/// implementation is called again.
|
|
///
|
|
/// Each state implementation is augmented to also enter the next state,
|
|
/// causing the iterator to terminate eventually.
|
|
pub(crate) fn compile(self) -> IntoEventsStateMachine {
|
|
let mut state_defs = TokenStream::default();
|
|
let mut advance_match_arms = TokenStream::default();
|
|
|
|
for (i, state) in self.states.iter().enumerate() {
|
|
let State {
|
|
ref name,
|
|
ref decl,
|
|
ref destructure,
|
|
ref advance_body,
|
|
} = state;
|
|
|
|
let footer = match self.states.get(i + 1) {
|
|
Some(State {
|
|
name: ref next_name,
|
|
destructure: ref construct_next,
|
|
..
|
|
}) => {
|
|
quote! {
|
|
::core::result::Result::Ok((::core::option::Option::Some(Self::#next_name { #construct_next }), event))
|
|
}
|
|
}
|
|
// final state -> exit the state machine
|
|
None => {
|
|
quote! {
|
|
::core::result::Result::Ok((::core::option::Option::None, event))
|
|
}
|
|
}
|
|
};
|
|
|
|
state_defs.extend(quote! {
|
|
#name { #decl },
|
|
});
|
|
|
|
advance_match_arms.extend(quote! {
|
|
Self::#name { #destructure } => {
|
|
let event = #advance_body;
|
|
#footer
|
|
}
|
|
});
|
|
}
|
|
|
|
IntoEventsStateMachine {
|
|
defs: self.defs,
|
|
state_defs,
|
|
advance_match_arms,
|
|
variants: vec![IntoEventsEntryPoint {
|
|
init: self.init,
|
|
destructure: self.destructure,
|
|
}],
|
|
}
|
|
}
|
|
|
|
/// Update the [`init`][`Self::init`] field in-place.
|
|
///
|
|
/// The function will receive a reference to the current `init` value,
|
|
/// allowing to create "wrappers" around that existing code.
|
|
pub(crate) fn with_augmented_init<F: FnOnce(&TokenStream) -> TokenStream>(
|
|
mut self,
|
|
f: F,
|
|
) -> Self {
|
|
let new_init = f(&self.init);
|
|
self.init = new_init;
|
|
self
|
|
}
|
|
}
|
|
|
|
/// Container for a single entrypoint into a [`FromEventsStateMachine`].
|
|
pub(crate) struct FromEventsEntryPoint {
|
|
pub(crate) init: TokenStream,
|
|
}
|
|
|
|
/// A single variant's entrypoint into the event iterator.
|
|
pub(crate) struct IntoEventsEntryPoint {
|
|
/// A pattern match which destructures the target type into its parts, for
|
|
/// use by `init`.
|
|
destructure: TokenStream,
|
|
|
|
/// An expression which uses the names bound in `destructure` to create a
|
|
/// an instance of the state enum.
|
|
///
|
|
/// The state enum type is available as `Self` in that context.
|
|
init: TokenStream,
|
|
}
|
|
|
|
/// # State machine to implement `xso::FromEventsBuilder`
|
|
///
|
|
/// This struct represents a state machine consisting of the following parts:
|
|
///
|
|
/// - Extra dependencies ([`Self::defs`])
|
|
/// - States ([`Self::state_defs`])
|
|
/// - Transitions ([`Self::advance_match_arms`])
|
|
/// - Entrypoints ([`Self::variants`])
|
|
///
|
|
/// Such a state machine is best constructed by constructing one or
|
|
/// more [`FromEventsSubmachine`] structs and converting/merging them using
|
|
/// `into()` and [`merge`][`Self::merge`].
|
|
///
|
|
/// A state machine has an output type (corresponding to
|
|
/// `xso::FromEventsBuilder::Output`), which is however only implicitly defined
|
|
/// by the expressions generated in the `advance_match_arms`. That means that
|
|
/// merging submachines with different output types works, but will then generate
|
|
/// code which will fail to compile.
|
|
///
|
|
/// When converted to Rust code, the state machine will manifest as (among other
|
|
/// things) an enum type which contains all states and which has an `advance`
|
|
/// method. That method consumes the enum value and returns either a new enum
|
|
/// value, an error, or the output type of the state machine.
|
|
#[derive(Default)]
|
|
pub(crate) struct FromEventsStateMachine {
|
|
/// Extra items which are needed for the state machine implementation.
|
|
defs: TokenStream,
|
|
|
|
/// A sequence of enum variant declarations, separated and terminated by
|
|
/// commas.
|
|
state_defs: TokenStream,
|
|
|
|
/// A sequence of `match self { .. }` arms, where `self` is the state
|
|
/// enumeration type.
|
|
///
|
|
/// Each match arm must either diverge or evaluate to a
|
|
/// `Result<ControlFlow<State, Output>, xso::error::Error>`, where `State`
|
|
/// is the state enumeration and `Output` is the state machine's output
|
|
/// type.
|
|
advance_match_arms: TokenStream,
|
|
|
|
/// The different entrypoints for the state machine.
|
|
///
|
|
/// This may only contain more than one element if an enumeration is being
|
|
/// constructed by the resulting state machine.
|
|
variants: Vec<FromEventsEntryPoint>,
|
|
}
|
|
|
|
impl FromEventsStateMachine {
|
|
/// Render the state machine as a token stream.
|
|
///
|
|
/// The token stream contains the following pieces:
|
|
/// - Any definitions necessary for the statemachine to operate
|
|
/// - The state enum
|
|
/// - The builder struct
|
|
/// - The `xso::FromEventsBuilder` impl on the builder struct
|
|
/// - A `fn new(rxml::QName, rxml::AttrMap) -> Result<Self>` on the
|
|
/// builder struct.
|
|
pub(crate) fn render(
|
|
self,
|
|
vis: &Visibility,
|
|
builder_ty_ident: &Ident,
|
|
state_ty_ident: &Ident,
|
|
output_ty: &Type,
|
|
) -> Result<TokenStream> {
|
|
let Self {
|
|
defs,
|
|
state_defs,
|
|
advance_match_arms,
|
|
variants,
|
|
} = self;
|
|
|
|
let mut init_body = TokenStream::default();
|
|
for variant in variants {
|
|
let FromEventsEntryPoint { init } = variant;
|
|
init_body.extend(quote! {
|
|
let (name, mut attrs) = match { { let _ = &mut attrs; } #init } {
|
|
::core::result::Result::Ok(v) => return ::core::result::Result::Ok(v),
|
|
::core::result::Result::Err(::xso::error::FromEventsError::Invalid(e)) => return ::core::result::Result::Err(::xso::error::FromEventsError::Invalid(e)),
|
|
::core::result::Result::Err(::xso::error::FromEventsError::Mismatch { name, attrs }) => (name, attrs),
|
|
};
|
|
})
|
|
}
|
|
|
|
let output_ty_ref = make_ty_ref(output_ty);
|
|
|
|
let docstr = format!("Build a {0} from XML events.\n\nThis type is generated using the [`macro@xso::FromXml`] derive macro and implements [`xso::FromEventsBuilder`] for {0}.", output_ty_ref);
|
|
|
|
Ok(quote! {
|
|
#defs
|
|
|
|
enum #state_ty_ident {
|
|
#state_defs
|
|
}
|
|
|
|
impl #state_ty_ident {
|
|
fn advance(mut self, ev: ::xso::exports::rxml::Event) -> ::core::result::Result<::std::ops::ControlFlow<Self, #output_ty>, ::xso::error::Error> {
|
|
match self {
|
|
#advance_match_arms
|
|
}.and_then(|__ok| {
|
|
match __ok {
|
|
::std::ops::ControlFlow::Break(st) => ::core::result::Result::Ok(::std::ops::ControlFlow::Break(st)),
|
|
::std::ops::ControlFlow::Continue(result) => {
|
|
::core::result::Result::Ok(::std::ops::ControlFlow::Continue(result))
|
|
}
|
|
}
|
|
})
|
|
}
|
|
}
|
|
|
|
impl #builder_ty_ident {
|
|
fn new(
|
|
name: ::xso::exports::rxml::QName,
|
|
attrs: ::xso::exports::rxml::AttrMap,
|
|
) -> ::core::result::Result<Self, ::xso::error::FromEventsError> {
|
|
#state_ty_ident::new(name, attrs).map(|ok| Self(::core::option::Option::Some(ok)))
|
|
}
|
|
}
|
|
|
|
#[doc = #docstr]
|
|
#vis struct #builder_ty_ident(::core::option::Option<#state_ty_ident>);
|
|
|
|
impl ::xso::FromEventsBuilder for #builder_ty_ident {
|
|
type Output = #output_ty;
|
|
|
|
fn feed(&mut self, ev: ::xso::exports::rxml::Event) -> ::core::result::Result<::core::option::Option<Self::Output>, ::xso::error::Error> {
|
|
let inner = self.0.take().expect("feed called after completion");
|
|
match inner.advance(ev)? {
|
|
::std::ops::ControlFlow::Continue(value) => ::core::result::Result::Ok(::core::option::Option::Some(value)),
|
|
::std::ops::ControlFlow::Break(st) => {
|
|
self.0 = ::core::option::Option::Some(st);
|
|
::core::result::Result::Ok(::core::option::Option::None)
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
impl #state_ty_ident {
|
|
fn new(
|
|
name: ::xso::exports::rxml::QName,
|
|
mut attrs: ::xso::exports::rxml::AttrMap,
|
|
) -> ::core::result::Result<Self, ::xso::error::FromEventsError> {
|
|
#init_body
|
|
{ let _ = &mut attrs; }
|
|
::core::result::Result::Err(::xso::error::FromEventsError::Mismatch { name, attrs })
|
|
}
|
|
}
|
|
})
|
|
}
|
|
}
|
|
|
|
/// # State machine to implement an `Iterator<Item = rxml::Event>`.
|
|
///
|
|
/// This struct represents a state machine consisting of the following parts:
|
|
///
|
|
/// - Extra dependencies ([`Self::defs`])
|
|
/// - States ([`Self::state_defs`])
|
|
/// - Transitions ([`Self::advance_match_arms`])
|
|
/// - Entrypoints ([`Self::variants`])
|
|
///
|
|
/// Such a state machine is best constructed by constructing one or
|
|
/// more [`FromEventsSubmachine`] structs and converting/merging them using
|
|
/// `into()` and [`merge`][`Self::merge`].
|
|
///
|
|
/// A state machine has an output type (corresponding to
|
|
/// `xso::FromEventsBuilder::Output`), which is however only implicitly defined
|
|
/// by the expressions generated in the `advance_match_arms`. That means that
|
|
/// merging submachines with different output types works, but will then generate
|
|
/// code which will fail to compile.
|
|
///
|
|
/// When converted to Rust code, the state machine will manifest as (among other
|
|
/// things) an enum type which contains all states and which has an `advance`
|
|
/// method. That method consumes the enum value and returns either a new enum
|
|
/// value, an error, or the output type of the state machine.
|
|
#[derive(Default)]
|
|
pub(crate) struct IntoEventsStateMachine {
|
|
/// Extra items which are needed for the state machine implementation.
|
|
defs: TokenStream,
|
|
|
|
/// A sequence of enum variant declarations, separated and terminated by
|
|
/// commas.
|
|
state_defs: TokenStream,
|
|
|
|
/// A sequence of `match self { .. }` arms, where `self` is the state
|
|
/// enumeration type.
|
|
///
|
|
/// Each match arm must either diverge or evaluate to a
|
|
/// `Result<(Option<State>, Option<Event>), xso::error::Error>`, where
|
|
/// where `State` is the state enumeration.
|
|
///
|
|
/// If `Some(.)` is returned for the event, that event is emitted. If
|
|
/// `None` is returned for the event, the advance implementation is called
|
|
/// again after switching to the state returned in the `Option<State>`
|
|
/// field.
|
|
///
|
|
/// If `None` is returned for the `Option<State>`, the iterator
|
|
/// terminates yielding the `Option<Event>` value directly (even if it is
|
|
/// `None`). After the iterator has terminated, it yields `None`
|
|
/// indefinitely.
|
|
advance_match_arms: TokenStream,
|
|
|
|
/// The different entrypoints for the state machine.
|
|
///
|
|
/// This may only contain more than one element if an enumeration is being
|
|
/// serialised by the resulting state machine.
|
|
variants: Vec<IntoEventsEntryPoint>,
|
|
}
|
|
|
|
impl IntoEventsStateMachine {
|
|
/// Render the state machine as a token stream.
|
|
///
|
|
/// The token stream contains the following pieces:
|
|
/// - Any definitions necessary for the statemachine to operate
|
|
/// - The state enum
|
|
/// - The iterator struct
|
|
/// - The `Iterator` impl on the builder struct
|
|
/// - A `fn new(T) -> Result<Self>` on the iterator struct.
|
|
pub(crate) fn render(
|
|
self,
|
|
vis: &Visibility,
|
|
input_ty: &Type,
|
|
state_ty_ident: &Ident,
|
|
event_iter_ty_ident: &Ident,
|
|
) -> Result<TokenStream> {
|
|
let Self {
|
|
defs,
|
|
state_defs,
|
|
advance_match_arms,
|
|
mut variants,
|
|
} = self;
|
|
|
|
let input_ty_ref = make_ty_ref(input_ty);
|
|
let docstr = format!("Convert a {0} into XML events.\n\nThis type is generated using the [`macro@xso::IntoXml`] derive macro and implements [`std::iter:Iterator`] for {0}.", input_ty_ref);
|
|
|
|
let init_body = if variants.len() == 1 {
|
|
let IntoEventsEntryPoint { destructure, init } = variants.remove(0);
|
|
quote! {
|
|
{
|
|
let #destructure = value;
|
|
#init
|
|
}
|
|
}
|
|
} else {
|
|
let mut match_arms = TokenStream::default();
|
|
for IntoEventsEntryPoint { destructure, init } in variants {
|
|
match_arms.extend(quote! {
|
|
#destructure => #init,
|
|
});
|
|
}
|
|
|
|
quote! {
|
|
match value {
|
|
#match_arms
|
|
}
|
|
}
|
|
};
|
|
|
|
Ok(quote! {
|
|
#defs
|
|
|
|
enum #state_ty_ident {
|
|
#state_defs
|
|
}
|
|
|
|
impl #state_ty_ident {
|
|
fn advance(mut self) -> ::core::result::Result<(::core::option::Option<Self>, ::core::option::Option<::xso::exports::rxml::Event>), ::xso::error::Error> {
|
|
match self {
|
|
#advance_match_arms
|
|
}
|
|
}
|
|
|
|
fn new(
|
|
value: #input_ty,
|
|
) -> ::core::result::Result<Self, ::xso::error::Error> {
|
|
::core::result::Result::Ok(#init_body)
|
|
}
|
|
}
|
|
|
|
#[doc = #docstr]
|
|
#vis struct #event_iter_ty_ident(::core::option::Option<#state_ty_ident>);
|
|
|
|
impl ::std::iter::Iterator for #event_iter_ty_ident {
|
|
type Item = ::core::result::Result<::xso::exports::rxml::Event, ::xso::error::Error>;
|
|
|
|
fn next(&mut self) -> ::core::option::Option<Self::Item> {
|
|
let mut state = self.0.take()?;
|
|
loop {
|
|
let (next_state, ev) = match state.advance() {
|
|
::core::result::Result::Ok(v) => v,
|
|
::core::result::Result::Err(e) => return ::core::option::Option::Some(::core::result::Result::Err(e)),
|
|
};
|
|
if let ::core::option::Option::Some(ev) = ev {
|
|
self.0 = next_state;
|
|
return ::core::option::Option::Some(::core::result::Result::Ok(ev));
|
|
}
|
|
// no event, do we have a state?
|
|
if let ::core::option::Option::Some(st) = next_state {
|
|
// we do: try again!
|
|
state = st;
|
|
continue;
|
|
} else {
|
|
// we don't: end of iterator!
|
|
self.0 = ::core::option::Option::None;
|
|
return ::core::option::Option::None;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
impl #event_iter_ty_ident {
|
|
fn new(value: #input_ty) -> ::core::result::Result<Self, ::xso::error::Error> {
|
|
#state_ty_ident::new(value).map(|ok| Self(::core::option::Option::Some(ok)))
|
|
}
|
|
}
|
|
})
|
|
}
|
|
}
|
|
|
|
/// Construct a path for an intradoc link from a given type.
|
|
fn doc_link_path(ty: &Type) -> Option<String> {
|
|
match ty {
|
|
Type::Path(ref ty) => {
|
|
let (mut buf, offset) = match ty.qself {
|
|
Some(ref qself) => {
|
|
let mut buf = doc_link_path(&qself.ty)?;
|
|
buf.push_str("::");
|
|
(buf, qself.position)
|
|
}
|
|
None => {
|
|
let mut buf = String::new();
|
|
if ty.path.leading_colon.is_some() {
|
|
buf.push_str("::");
|
|
}
|
|
(buf, 0)
|
|
}
|
|
};
|
|
let last = ty.path.segments.len() - 1;
|
|
for i in offset..ty.path.segments.len() {
|
|
let segment = &ty.path.segments[i];
|
|
buf.push_str(&segment.ident.to_string());
|
|
if i < last {
|
|
buf.push_str("::");
|
|
}
|
|
}
|
|
Some(buf)
|
|
}
|
|
_ => None,
|
|
}
|
|
}
|
|
|
|
/// Create a markdown snippet which references the given type as cleanly as
|
|
/// possible.
|
|
///
|
|
/// This is used in documentation generation functions.
|
|
///
|
|
/// Not all types can be linked to; those which cannot be linked to will
|
|
/// simply be wrapped in backticks.
|
|
fn make_ty_ref(ty: &Type) -> String {
|
|
match doc_link_path(ty) {
|
|
Some(mut path) => {
|
|
path.reserve(4);
|
|
path.insert_str(0, "[`");
|
|
path.push_str("`]");
|
|
path
|
|
}
|
|
None => format!("`{}`", ty.to_token_stream()),
|
|
}
|
|
}
|