syn-path 3.0.0

#![allow(clippy::tabs_in_doc_comments)]
#![warn(rust_2018_idioms, unreachable_pub)]
#![deny(elided_lifetimes_in_paths)]
#![forbid(unsafe_code)]

//! This crate contains macros to construct [`syn`]-types that contain paths inside a
//! procedural macro.
//!
//!  - The [`path!`] macro constructs a [`syn::Path`].
//!
//!    **Example:**
//!
//!    ```
//!    use syn_path::path;
//!    let path = path!(::std::option::Option<::std::string::String>);
//!    # assert_eq!(path, syn::parse_str("::std::option::Option<::std::string::String>").unwrap());
//!    ```
//!
//!  - The [`type_path!`] macro constructs a [`syn::TypePath`].
//!
//!    **Example:**
//!
//!    ```
//!    use syn_path::type_path;
//!    let type_path = type_path!(<i64 as ::std::str::FromStr>::Err);
//!    # assert_eq!(type_path, syn::parse_str("<i64 as ::std::str::FromStr>::Err").unwrap());
//!    ```
//!
//!  - The [`ty!`] macro constructs a [`syn::Type`].
//!
//!    **Example:**
//!
//!    ```
//!    use syn_path::ty;
//!    let ty = ty!(<i64 as ::std::str::FromStr>::Err);
//!    # assert_eq!(ty, syn::parse_str("<i64 as ::std::str::FromStr>::Err").unwrap());
//!    ```
//!
//! While we can just type whatever we need into [`quote!`] most of the time when writing
//! procedural macros, sometimes we need a certain syn type. The macros from this crate
//! help you out in these situations.
//!
//! ## Example: Making a type optional
//!
//! Some derive macros might need to transform a type to an optional type. For example,
//! this function takes a [`Field`](syn::Field) and returns its type or an option of its
//! type based on the `nullable` parameter:
//!
//! ```
//! # use syn::*; use syn::punctuated::Punctuated; use quote::quote;
//! use syn_path::type_path;
//!
//! fn field_ty(field: &Field, nullable: bool) -> Type {
//! 	let mut ty = field.ty.clone();
//! 	if nullable {
//! 		let mut args = Punctuated::new();
//! 		args.push(GenericArgument::Type(ty));
//! 		let mut type_path = type_path!(::core::option::Option);
//! 		type_path.path.segments.last_mut().unwrap().arguments = PathArguments::AngleBracketed(
//! 			AngleBracketedGenericArguments {
//! 				colon2_token: None,
//! 				lt_token: Default::default(),
//! 				args,
//! 				gt_token: Default::default()
//! 			}
//! 		);
//! 		ty = Type::Path(type_path);
//! 	}
//! 	ty
//! }
//!
//! # let strukt: ItemStruct = parse_str("struct Foo { x: String }").unwrap();
//! # let Fields::Named(fields) = strukt.fields else { unreachable!() };
//! let field = // x: String
//! # fields.named.first().unwrap();
//! let ty = field_ty(field, true);
//! assert_eq!(ty, syn::parse2(quote!(::core::option::Option<String>)).unwrap());
//! ```
//!
//! This example is adopted from the
//! [`openapi_type_derive`](https://crates.io/crates/openapi_type_derive)
//! crate. The full example can be found
//! [here](https://github.com/msrd0/openapi_type/blob/6ba01686a0a8b782dd2bfba711bbe5f50ddfdb08/derive/src/parser.rs#L98-L110).
//!
//! ## Example: Adding a where clause
//!
//! This example shows how to add `T: Send` clauses for each field of a struct. We cannot
//! just write `where T: Send` into [`quote!`] since there might or might
//! not be a where clause for the struct our derive macro received as an input.
//!
//! ```
//! # use syn::*; use quote::quote;
//! use syn_path::path;
//!
//! fn where_predicate_t_send(t: Type) -> WherePredicate {
//! 	WherePredicate::Type(PredicateType {
//! 		attrs: Vec::new(),
//! 		lifetimes: None,
//! 		bounded_ty: t,
//! 		colon_token: Default::default(),
//! 		bounds: [TypeParamBound::Trait(TraitBound {
//! 			paren_token: None,
//! 			modifiers: TraitBoundModifiers::default(),
//! 			lifetimes: None,
//! 			maybe: None,
//! 			path: path!(::std::marker::Send)
//! 		})].into_iter().collect()
//! 	})
//! }
//!
//! let strukt =
//! # parse_str::<ItemStruct>("
//! 	struct Foo<T> where T: Hash + Eq { foo: HashSet<T> }
//! # ").unwrap();
//! let ident = strukt.ident;
//! let (impl_generics, ty_generics, where_clause) = strukt.generics.split_for_impl();
//! let mut where_clause = where_clause.cloned().unwrap_or(WhereClause {
//! 	where_token: Default::default(),
//! 	predicates: Default::default()
//! });
//! for field in strukt.fields {
//! 	where_clause.predicates.push(where_predicate_t_send(field.ty));
//! }
//! assert_eq!(
//! 	quote!(impl #impl_generics MyTrait for #ident #ty_generics #where_clause {}).to_string(),
//! 	quote!(impl<T> MyTrait for Foo<T> where T: Hash + Eq, HashSet<T>: ::std::marker::Send {}).to_string()
//! )
//! ```
//!
//!  [`quote!`]: https://docs.rs/quote/1/quote/macro.quote.html

#[doc(hidden)]
pub mod private {
	pub use proc_macro2::{Ident, Span};
	pub use std::{
		boxed::Box,
		option::Option::{None, Some},
		stringify
	};
	pub use syn::{
		punctuated::Punctuated, AngleBracketedGenericArguments, GenericArgument, Path,
		PathArguments, PathSegment, QSelf, Type, TypePath
	};

	#[inline]
	pub fn default<T: Default>() -> T {
		T::default()
	}

	#[inline]
	pub const fn len<T, const LEN: usize>(_: &[T; LEN]) -> usize {
		LEN
	}
}

/// This macro takes type paths of the form `my_crate::my_mod::FooBar` and
/// `<my_crate::my_mod::FooBar as my_crate::my_mod::MyTrait>::MyType` and
/// turns them into a [`syn::Type`].
#[macro_export]
macro_rules! ty {
	($($body:tt)*) => {
		$crate::private::Type::Path($crate::type_path!($($body)*))
	};
}

/// This macro takes type paths of the form `my_crate::my_mod::FooBar` and
/// `<my_crate::my_mod::FooBar as my_crate::my_mod::MyTrait>::MyType` and
/// turns them into a [`syn::TypePath`].
#[macro_export]
macro_rules! type_path {
	(:: $($body:tt)*) => {
		$crate::type_path_impl!($crate::private::None, $crate::path!(:: $($body)*))
	};
	($segment:ident $($body:tt)*) => {
		$crate::type_path_impl!($crate::private::None, $crate::path!($segment $($body)*))
	};

	(< $($ty_segment:ident)::* > :: $($body:tt)*) => {
		$crate::type_path_impl!(
			$crate::private::Some($crate::private::QSelf {
				lt_token: $crate::private::default(),
				ty: Box::new($crate::ty!($($ty_segment)::*)),
				position: 0,
				as_token: $crate::private::None,
				gt_token: $crate::private::default()
			}),
			$crate::path!(:: $($body)*)
		)
	};
	(< :: $($ty_segment:ident)::* > :: $($body:tt)*) => {
		$crate::type_path_impl!(
			$crate::private::Some($crate::private::QSelf {
				lt_token: $crate::private::default(),
				ty: Box::new($crate::ty!(:: $($ty_segment)::*)),
				position: 0,
				as_token: $crate::private::None,
				gt_token: $crate::private::default()
			}),
			$crate::path!(:: $($body)*)
		)
	};

	(< $($ty_segment:ident)::* as $($as_segment:ident)::* > :: $($body:tt)*) => {
		$crate::type_path_impl!(
			$crate::private::Some($crate::private::QSelf {
				lt_token: $crate::private::default(),
				ty: Box::new($crate::ty!($($ty_segment)::*)),
				position: $crate::private::len(&[$($crate::private::stringify!($as_segment)),*]),
				as_token: $crate::private::Some($crate::private::default()),
				gt_token: $crate::private::default()
			}),
			$crate::path!($($as_segment)::* :: $($body)*)
		)
	};
	(< :: $($ty_segment:ident)::* as $($as_segment:ident)::* > :: $($body:tt)*) => {
		$crate::type_path_impl!(
			$crate::private::Some($crate::private::QSelf {
				lt_token: $crate::private::default(),
				ty: Box::new($crate::ty!(:: $($ty_segment)::*)),
				position: $crate::private::len(&[$($crate::private::stringify!($as_segment)),*]),
				as_token: $crate::private::Some($crate::private::default()),
				gt_token: $crate::private::default()
			}),
			$crate::path!($($as_segment)::* :: $($body)*)
		)
	};
	(< $($ty_segment:ident)::* as :: $($as_segment:ident)::* > :: $($body:tt)*) => {
		$crate::type_path_impl!(
			$crate::private::Some($crate::private::QSelf {
				lt_token: $crate::private::default(),
				ty: Box::new($crate::ty!($($ty_segment)::*)),
				position: $crate::private::len(&[$($crate::private::stringify!($as_segment)),*]),
				as_token: $crate::private::Some($crate::private::default()),
				gt_token: $crate::private::default()
			}),
			$crate::path!(:: $($as_segment)::* :: $($body)*)
		)
	};
	(< :: $($ty_segment:ident)::* as :: $($as_segment:ident)::* > :: $($body:tt)*) => {
		$crate::type_path_impl!(
			$crate::private::Some($crate::private::QSelf {
				lt_token: $crate::private::default(),
				ty: Box::new($crate::ty!(:: $($ty_segment)::*)),
				position: $crate::private::len(&[$($crate::private::stringify!($as_segment)),*]),
				as_token: $crate::private::Some($crate::private::default()),
				gt_token: $crate::private::default()
			}),
			$crate::path!(:: $($as_segment)::* :: $($body)*)
		)
	};
}

#[macro_export]
#[doc(hidden)]
macro_rules! type_path_impl {
	($qself:expr, $path:expr) => {
		$crate::private::TypePath {
			attrs: $crate::private::default(),
			qself: $qself,
			path: $path
		}
	};
}

/// This macro takes paths of the form `my_crate::my_mod::FooBar` and
/// `::my_crate::my_mod::FooBar` and turns them into a [`syn::Path`].
#[macro_export]
macro_rules! path {
	(:: $($segment:ident)::*) => {
		$crate::path_impl!(
			$crate::private::Some($crate::private::default()),
			$crate::private::PathArguments::None,
			$($segment),*
		)
	};
	($($segment:ident)::*) => {
		$crate::path_impl!(
			$crate::private::None,
			$crate::private::PathArguments::None,
			$($segment),*
		)
	};
	// note: the last $tt will capture the '>'
	(:: $($segment:ident)::* < $($args:tt)*) => {
		$crate::path_impl!(
			$crate::private::Some($crate::private::default()),
			$crate::path_args_impl!($crate::private::default(), $crate::private::None, $($args)*),
			$($segment),*
		)
	};
	($($segment:ident)::* < $($args:tt)*) => {
		$crate::path_impl!(
			$crate::private::None,
			$crate::path_args_impl!($crate::private::default(), $crate::private::None, $($args)*),
			$($segment),*
		)
	};
}

#[macro_export]
#[doc(hidden)]
macro_rules! path_impl {
	($leading_colon:expr, $args:expr, $($segment:ident),*) => {
		{
			#[allow(unused_mut)]
			let mut segments: $crate::private::Punctuated<$crate::private::PathSegment, _> = $crate::private::default();
			$(
				segments.push($crate::private::PathSegment {
					ident: $crate::private::Ident::new(
						$crate::private::stringify!($segment),
						$crate::private::Span::call_site()
					),
					arguments: $crate::private::PathArguments::None
				});
			)*
			if let Some(last_segment) = segments.last_mut() {
				last_segment.arguments = $args;
			}
			$crate::private::Path {
				leading_colon: $leading_colon,
				segments
			}
		}
	};
}

#[macro_export]
#[doc(hidden)]
macro_rules! path_args_impl {
	// end of recursion: no tokens at all. the '>' was captured by the path! macro.
	($args:expr, $leading_colon:expr, $(>)?) => {
		$crate::private::PathArguments::AngleBracketed(
			$crate::private::AngleBracketedGenericArguments {
				colon2_token: $leading_colon,
				lt_token: $crate::private::default(),
				args: $args,
				gt_token: $crate::private::default()
			}
		)
	};
	// match first argument: no following tokens, but the '>' was captured by the path! macro.
	($args:expr, $leading_colon:expr, :: $($segment:ident)::* $(>)?) => {
		$crate::path_args_impl!(
			{
				let mut args: $crate::private::Punctuated<$crate::private::GenericArgument, _> = $args;
				args.push($crate::private::GenericArgument::Type($crate::ty!(:: $($segment)::*)));
				args
			},
			$leading_colon,
		)
	};
	($args:expr, $leading_colon:expr, $($segment:ident)::* $(>)?) => {
		$crate::path_args_impl!(
			{
				let mut args: $crate::private::Punctuated<$crate::private::GenericArgument, _> = $args;
				args.push($crate::private::GenericArgument::Type($crate::ty!($($segment)::*)));
				args
			},
			$leading_colon,
		)
	};
	// match first argument: following tokens, last will capture the '>'
	($args:expr, $leading_colon:expr, :: $($segment:ident)::* $(, $($body:tt)*)?) => {
		$crate::path_args_impl!(
			{
				let mut args: $crate::private::Punctuated<$crate::private::GenericArgument, _> = $args;
				args.push($crate::private::GenericArgument::Type($crate::ty!(:: $($segment)::*)));
				args
			},
			$leading_colon,
			$($($body)*)?
		)
	};
	($args:expr, $leading_colon:expr, $($segment:ident)::* $(, $($body:tt)*)?) => {
		$crate::path_args_impl!(
			{
				let mut args: $crate::private::Punctuated<$crate::private::GenericArgument, _> = $args;
				args.push($crate::private::GenericArgument::Type($crate::ty!($($segment)::*)));
				args
			},
			$leading_colon,
			$($($body)*)?
		)
	};
}

#[cfg(test)]
mod tests {
	use std::fmt::Debug;
	use syn::parse::Parse;

	#[track_caller]
	fn assert_eq<T>(t: T, s: &str)
	where
		T: Debug + Eq + Parse
	{
		let expected: T = syn::parse_str(s).unwrap();
		// assert_eq!(expected, t);
		if expected != t {
			panic!(
				r#"assertion `left == right` failed
  left: {expected:#?}
 right: {t:#?}"#
			)
		}
	}

	// ### ty! macro tests

	#[test]
	fn type_with_leading_colon() {
		assert_eq(
			ty!(::my_crate::my_mod::FooBar),
			"::my_crate::my_mod::FooBar"
		);
	}

	#[test]
	fn type_without_leading_colon() {
		assert_eq(ty!(my_crate::my_mod::FooBar), "my_crate::my_mod::FooBar");
	}

	#[test]
	fn type_with_qself_with_leading_colon() {
		assert_eq(
			ty!(<::my_crate::my_mod::FooBar>::MyType),
			"<::my_crate::my_mod::FooBar>::MyType"
		);
	}

	#[test]
	fn type_with_qself_without_leading_colon() {
		assert_eq(
			ty!(<my_crate::my_mod::FooBar>::MyType),
			"<my_crate::my_mod::FooBar>::MyType"
		);
	}

	#[test]
	fn type_with_qself_with_leading_colon_with_as_with_leading_colon() {
		assert_eq(
			ty!(<::my_crate::my_mod::FooBar as ::my_crate::my_mod::MyTrait>::MyType),
			"<::my_crate::my_mod::FooBar as ::my_crate::my_mod::MyTrait>::MyType"
		);
	}

	#[test]
	fn type_with_qself_with_leading_colon_with_as_without_leading_colon() {
		assert_eq(
			ty!(<::my_crate::my_mod::FooBar as my_crate::my_mod::MyTrait>::MyType),
			"<::my_crate::my_mod::FooBar as my_crate::my_mod::MyTrait>::MyType"
		);
	}

	#[test]
	fn type_with_qself_without_leading_colon_with_as_with_leading_colon() {
		assert_eq(
			ty!(<my_crate::my_mod::FooBar as ::my_crate::my_mod::MyTrait>::MyType),
			"<my_crate::my_mod::FooBar as ::my_crate::my_mod::MyTrait>::MyType"
		);
	}

	#[test]
	fn type_with_qself_without_leading_colon_with_as_without_leading_colon() {
		assert_eq(
			ty!(<my_crate::my_mod::FooBar as my_crate::my_mod::MyTrait>::MyType),
			"<my_crate::my_mod::FooBar as my_crate::my_mod::MyTrait>::MyType"
		);
	}

	// ### type_path! macro tests

	#[test]
	fn type_path_with_leading_colon() {
		assert_eq(
			type_path!(::my_crate::my_mod::FooBar),
			"::my_crate::my_mod::FooBar"
		);
	}

	#[test]
	fn type_path_without_leading_colon() {
		assert_eq(
			type_path!(my_crate::my_mod::FooBar),
			"my_crate::my_mod::FooBar"
		);
	}

	#[test]
	fn type_path_with_qself_with_leading_colon() {
		assert_eq(
			type_path!(<::my_crate::my_mod::FooBar>::MyType),
			"<::my_crate::my_mod::FooBar>::MyType"
		);
	}

	#[test]
	fn type_path_with_qself_without_leading_colon() {
		assert_eq(
			type_path!(<my_crate::my_mod::FooBar>::MyType),
			"<my_crate::my_mod::FooBar>::MyType"
		);
	}

	#[test]
	fn type_path_with_qself_with_leading_colon_with_as_with_leading_colon() {
		assert_eq(
			type_path!(
				<::my_crate::my_mod::FooBar as ::my_crate::my_mod::MyTrait>::MyType
			),
			"<::my_crate::my_mod::FooBar as ::my_crate::my_mod::MyTrait>::MyType"
		);
	}

	#[test]
	fn type_path_with_qself_with_leading_colon_with_as_without_leading_colon() {
		assert_eq(
			type_path!(<::my_crate::my_mod::FooBar as my_crate::my_mod::MyTrait>::MyType),
			"<::my_crate::my_mod::FooBar as my_crate::my_mod::MyTrait>::MyType"
		);
	}

	#[test]
	fn type_path_with_qself_without_leading_colon_with_as_with_leading_colon() {
		assert_eq(
			type_path!(<my_crate::my_mod::FooBar as ::my_crate::my_mod::MyTrait>::MyType),
			"<my_crate::my_mod::FooBar as ::my_crate::my_mod::MyTrait>::MyType"
		);
	}

	#[test]
	fn type_path_with_qself_without_leading_colon_with_as_without_leading_colon() {
		assert_eq(
			type_path!(<my_crate::my_mod::FooBar as my_crate::my_mod::MyTrait>::MyType),
			"<my_crate::my_mod::FooBar as my_crate::my_mod::MyTrait>::MyType"
		);
	}

	// ### path! macro tests

	#[test]
	fn path_with_leading_colon() {
		assert_eq(
			path!(::my_crate::my_mod::FooBar),
			"::my_crate::my_mod::FooBar"
		);
	}

	#[test]
	fn path_without_leading_colon() {
		assert_eq(path!(my_crate::my_mod::FooBar), "my_crate::my_mod::FooBar");
	}

	#[test]
	fn path_with_leading_colon_with_args() {
		assert_eq(
			path!(::my_crate::my_mod::FooBar<::some::Argument, AnotherArgument>),
			"::my_crate::my_mod::FooBar<::some::Argument, AnotherArgument>"
		)
	}

	#[test]
	fn path_without_leading_colon_with_args() {
		assert_eq(
			path!(my_crate::my_mod::FooBar<::some::Argument, AnotherArgument>),
			"my_crate::my_mod::FooBar<::some::Argument, AnotherArgument>"
		)
	}
}