extract the attrs code and better document meaning

Author: nikomatsakis

crates/formality-macros/src/attrs.rs

@@ -0,0 +1,56 @@
+//! Functions to manipulate the custom attributes that guide our macros in various ways.
+
+use syn::{Attribute, DeriveInput};
+
+/// Checks for any kind of attribute that indicates an "is-a" relationship,
+/// e.g. `#[cast]` and `#[variable]`.
+///
+/// See [`has_cast_attr`][] and [`has_variable_attr`][] for more details.
+pub(crate) fn has_isa_attr(attrs: &[Attribute]) -> bool {
+    has_cast_attr(attrs) || has_variable_attr(attrs)
+}
+
+/// The `#[cast]` attribute is placed on enum variants with a single binding,
+/// like `enum Foo { #[cast] Bar(Bar), ... }`. It indicates that `Foo` is an
+/// extension of `Bar`, so we should permit upcasts from `Bar` to `Foo`
+/// and generally ignore the fact that `Bar` is a variant of `Foo` (for example,
+/// in debug print-outs, we don't print `Bar(...)`, we just print `...`).
+pub(crate) fn has_cast_attr(attrs: &[Attribute]) -> bool {
+    attrs.iter().any(|a| a.path().is_ident("cast"))
+}
+
+/// The `#[variable]` attribute is a special-case of `#[cast]` that is used
+/// for variables. It can only be used on a single-entry variant in some type
+/// that is up/down-castable to the language's `Parameter` type (e.g., in Rust,
+/// this could be used in `Ty`, `Lifetime`, or `Const`).
+///
+/// `#[variable]` has subtle effects on folding and parsing:
+///
+/// * When folding a variable variant, we apply the substitution function, which yields
+///   a Parameter. We then downcast that to the type needed. If that downcast
+///   fails, we panic, as that indicates an ill-kinded substitution.
+/// * When parsing a variable variant, we parse an identifier and then check the in-scope
+///   bindings for variables with that name. If any are found, we extract the result
+///   (a parameter) and downcast it. If the resulting downcast fails, that is considered
+///   a parse error (ill-kinded term).
+pub(crate) fn has_variable_attr(attrs: &[Attribute]) -> bool {
+    attrs.iter().any(|a| a.path().is_ident("variable"))
+}
+
+/// Removes all attributes from the input that are specific to formality.
+pub(crate) fn remove_formality_attributes(input: &mut DeriveInput) {
+    remove_formality_attributes_from_vec(&mut input.attrs);
+    if let syn::Data::Enum(v) = &mut input.data {
+        for variant in &mut v.variants {
+            remove_formality_attributes_from_vec(&mut variant.attrs);
+        }
+    }
+}
+
+fn remove_formality_attributes_from_vec(attrs: &mut Vec<Attribute>) {
+    attrs.retain(|attr| {
+        !attr.path().is_ident("grammar")
+            && !attr.path().is_ident("cast")
+            && !attr.path().is_ident("variable")
+    });
+}

crates/formality-macros/src/cast.rs

@@ -1,17 +1,15 @@
 use proc_macro2::TokenStream;
 use quote::quote;
-use syn::{Attribute, Type};
+use syn::Type;
 use synstructure::VariantInfo;
 
-use crate::term::has_variable_attr;
+use crate::attrs::has_isa_attr;
 
 pub(crate) fn upcast_impls(s: synstructure::Structure) -> Vec<TokenStream> {
     let num_variants = s.variants().len();
     s.variants()
         .iter()
-        .filter(|v| {
-            num_variants == 1 || has_cast_attr(v.ast().attrs) || has_variable_attr(v.ast().attrs)
-        })
+        .filter(|v| num_variants == 1 || has_isa_attr(v.ast().attrs))
         .map(|v| upcast_to_variant(&s, v))
         .chain(Some(self_upcast(&s)))
         .collect()
@@ -50,9 +48,7 @@ pub(crate) fn downcast_impls(s: synstructure::Structure) -> Vec<TokenStream> {
     let num_variants = s.variants().len();
     s.variants()
         .iter()
-        .filter(|v| {
-            num_variants == 1 || has_cast_attr(v.ast().attrs) || has_variable_attr(v.ast().attrs)
-        })
+        .filter(|v| num_variants == 1 || has_isa_attr(v.ast().attrs))
         .map(|v| downcast_to_variant(&s, v))
         .chain(Some(self_downcast(&s)))
         .collect()
@@ -95,7 +91,3 @@ fn downcast_to_variant(s: &synstructure::Structure, v: &VariantInfo) -> TokenStr
         }
     })
 }
-
-pub(crate) fn has_cast_attr(attrs: &[Attribute]) -> bool {
-    attrs.iter().any(|a| a.path().is_ident("cast"))
-}

crates/formality-macros/src/debug.rs

@@ -4,7 +4,10 @@ use proc_macro2::{Ident, Literal, TokenStream};
 use quote::{quote, quote_spanned};
 use syn::{spanned::Spanned, Attribute};
 
-use crate::spec::{self, FieldMode, FormalitySpec, FormalitySpecOp};
+use crate::{
+    attrs,
+    spec::{self, FieldMode, FormalitySpec, FormalitySpecOp},
+};
 
 /// Derive the `Parse` impl, using an optional grammar supplied "from the outside".
 /// This is used by the `#[term(G)]` macro, which supplies the grammar `G`.
@@ -62,7 +65,7 @@ fn debug_variant(
         quote! {
             write!(fmt, #literal)?;
         }
-    } else if crate::cast::has_cast_attr(variant.ast().attrs) {
+    } else if attrs::has_isa_attr(variant.ast().attrs) {
         let streams: Vec<_> = variant
             .bindings()
             .iter()

crates/formality-macros/src/fold.rs

@@ -3,7 +3,7 @@ extern crate proc_macro;
 use proc_macro2::TokenStream;
 use quote::quote;
 
-use crate::term::has_variable_attr;
+use crate::attrs::has_variable_attr;
 
 pub(crate) fn derive_fold(mut s: synstructure::Structure) -> TokenStream {
     s.underscore_const(true);

crates/formality-macros/src/lib.rs

@@ -5,6 +5,7 @@ use spec::FormalitySpec;
 
 extern crate proc_macro;
 
+mod attrs;
 mod cast;
 mod debug;
 mod fixed_point;

crates/formality-macros/src/parse.rs

@@ -7,7 +7,7 @@ use synstructure::BindingInfo;
 
 use crate::{
     spec::{self, FieldMode, FormalitySpec, FormalitySpecOp},
-    term::has_variable_attr,
+    attrs::{has_variable_attr, has_cast_attr},
 };
 
 /// Derive the `Parse` impl, using an optional grammar supplied "from the outside".
@@ -108,7 +108,7 @@ fn parse_variant(
             ast.ident.span() =>
             parse::parse_variable(scope, text, #type_name)
         })
-    } else if crate::cast::has_cast_attr(variant.ast().attrs) {
+    } else if has_cast_attr(variant.ast().attrs) {
         // Has the `#[cast]` attribute -- just parse the bindings (comma separated, if needed)
         let build: Vec<TokenStream> = parse_bindings(variant.bindings());
         let construct = variant.construct(field_ident);

crates/formality-macros/src/term.rs

@@ -1,8 +1,9 @@
 use proc_macro2::TokenStream;
 use quote::quote;
-use syn::{Attribute, DeriveInput};
+use syn::DeriveInput;
 
 use crate::{
+    attrs::remove_formality_attributes,
     cast::{downcast_impls, upcast_impls},
     debug::derive_debug_with_spec,
     fold::derive_fold,
@@ -35,18 +36,6 @@ pub fn term(spec: Option<FormalitySpec>, mut input: DeriveInput) -> syn::Result<
     })
 }
 
-fn remove_formality_attributes(input: &mut DeriveInput) {
-    if let syn::Data::Enum(v) = &mut input.data {
-        for variant in &mut v.variants {
-            variant.attrs.retain(|attr| {
-                !attr.path().is_ident("grammar")
-                    && !attr.path().is_ident("cast")
-                    && !attr.path().is_ident("variable")
-            });
-        }
-    }
-}
-
 fn derive_term(mut s: synstructure::Structure) -> TokenStream {
     s.underscore_const(true);
     s.bind_with(|_| synstructure::BindStyle::Move);
@@ -59,7 +48,3 @@ fn derive_term(mut s: synstructure::Structure) -> TokenStream {
         }
     })
 }
-
-pub(crate) fn has_variable_attr(attrs: &[Attribute]) -> bool {
-    attrs.iter().any(|a| a.path().is_ident("variable"))
-}