//! The declared form's syntax tree.
//!
//! This is the grammar of wiki `quasi-declare-form` section 4, narrowed to what
//! a real screen has actually demanded. It grows one production at a time, and
//! every production here exists because a conversion needed it: nothing is
//! specified ahead of a screen that wants it.
//!
//! What the form refuses is as load-bearing as what it admits. There is no
//! expression node, no block in argument position, no closure and no struct
//! literal, because those four are what keep `Node: Eq` intact and keep an
//! argument from reopening into a sub-grammar. A shape that needs one of them
//! calls a supplier function beside the declaration instead.

use proc_macro2::Span;
use syn::{Ident, Type};

/// One declared shape: a header and the items its body emits.
pub struct Declaration {
    pub docs: Vec<String>,
    /// The bare attributes the generated function carries, `must_use` and
    /// `inline`. Nothing that takes an argument: an attribute with a body is a
    /// second grammar, and none of the converted screens has wanted one.
    pub flags: Vec<Ident>,
    pub vis: Option<syn::Visibility>,
    pub name: Ident,
    pub params: Vec<Param>,
    pub returns: Type,
    pub items: Vec<Item>,
}

#[derive(Clone)]
pub struct Param {
    pub name: Ident,
    pub ty: Type,
}

#[derive(Clone)]
pub enum Item {
    /// `let name = <source>;`
    Bind { name: Ident, source: Source },
    /// `<builder> <arg>* <guard>?;` -- one setting on the enclosing container.
    ///
    /// The ident is the **builder method's** name and not the struct field's,
    /// which is what ATTRIBUTE NAMING settles: `Slot::named` writes `name`, and
    /// a form that spelled the field would be naming something no caller can
    /// reach.
    ///
    /// A setting takes a guard for the same reason a member does: the rule is
    /// that a guard is allowed where something may be absent, and a setting
    /// that is sometimes not made is exactly that. `git_explore`'s `more` is
    /// the live instance -- a table says what it has not shown only when there
    /// is another page.
    Attribute {
        name: Ident,
        args: Vec<Arg>,
        guard: Option<Guard>,
    },
    /// `for <binder> in <hole> { .. }` -- the same body once per element.
    ///
    /// A loop is the one item that cannot be hoisted above its container: its
    /// members name the binder, which does not exist until the loop does.
    For {
        /// `&name` where the elements are references to values the members
        /// take by value. Written where the code writes it, as R8 requires,
        /// and a pattern rather than an expression.
        dereferenced: bool,
        binder: Ident,
        iterable: Hole,
        body: Vec<Item>,
    },
    /// Anything that puts something into the enclosing container.
    Emit(Emission),
}

#[derive(Clone)]
pub enum Source {
    /// A string literal, which may carry `{hole}` interpolations.
    Str(Interpolated),
    /// A hole: one eager evaluation whose owned result lands in a field.
    Hole(Hole),
    /// `given <hole> { <literal> -> <source>, .. }` in value position.
    ///
    /// This is the production the record's amendment 9 was reaching for and
    /// missed: it put `dispatch` on the statement side, where an arm is an
    /// emission and no emission is a value. Here a value dispatch is its own
    /// node whose arms are sources, so it produces a value by construction and
    /// cannot admit a block.
    Choose {
        scrutinee: Hole,
        arms: Vec<(Pattern, Source)>,
        otherwise: Box<Source>,
    },
}

/// A pattern in value-dispatch position. Literals only: a binding pattern would
/// need a scope, and a scope is how an arm becomes a block.
#[derive(Clone)]
pub enum Pattern {
    Int(i64),
    Str(String),
    Bool(bool),
    /// `Enum::Variant`, emitted verbatim so rustc judges exhaustiveness.
    Path(syn::Path),
}

/// A string with `{hole}` interpolations, compiled to a literal push or a
/// `format!` depending on whether it has any.
#[derive(Clone)]
pub struct Interpolated {
    pub parts: Vec<StrPart>,
    pub span: Span,
}

#[derive(Clone)]
pub enum StrPart {
    Lit(String),
    Hole(Hole),
}

/// One evaluation: a path, optionally called, then field and method steps.
///
/// A hole is deliberately not an expression. It cannot contain an operator, a
/// closure, a turbofish, an index or a block, so the macro can place its result
/// in a field without reasoning about evaluation order.
#[derive(Clone)]
pub struct Hole {
    pub root: HoleRoot,
    pub steps: Vec<Step>,
}

#[derive(Clone)]
pub enum HoleRoot {
    /// A bare lowercase ident: a binding, innermost first.
    Binding(Ident),
    /// A `::`-qualified or uppercase-initial path: a Rust path, binding nothing.
    Path(syn::Path),
    /// A module function called at the root of a hole.
    Call { path: syn::Path, args: Vec<Arg> },
}

#[derive(Clone)]
pub enum Step {
    Field(Ident),
    Method { name: Ident, args: Vec<Arg> },
}

#[derive(Clone)]
pub enum Arg {
    Str(Interpolated),
    /// `[ <arg>, .. ]`, which is an array literal and never a collection: what
    /// it can hold is an arg, so it cannot reopen into a sub-grammar.
    List(Vec<Arg>),
    Hole(Hole),
    Int(i64),
    Bool(bool),
    /// `&<hole>`. Nothing borrows implicitly, so the ampersand is written where
    /// the code writes it.
    Borrow(Box<Arg>),
}

/// Everything that emits into the enclosing container.
#[derive(Clone)]
pub enum Emission {
    /// `<member> <arg>* ( "{" { item } "}" | ";" )` -- one of `Node`'s own
    /// constructors, by its own name, and whatever it is told afterwards.
    ///
    /// The body is what `forum_memberships` demanded: `Node::empty` carries a
    /// way out (`offering`) on the library's pane and not on the settings pane,
    /// so an empty state is a member with a setting rather than a bare one.
    Simple {
        member: Ident,
        args: Vec<Arg>,
        body: Vec<Item>,
    },
    /// `chip <value> to <action> { .. }`, and `removable <value> to <action>`.
    ///
    /// Its own emission rather than a `Simple` member because `Tag::chip` takes
    /// an `Action`, and an action is spelled `to <verb>` rather than as an arg.
    ///
    /// One emission for both because they differ by one constructor and nothing
    /// else. `Tag` has three constructors and the form now says all three:
    /// `badge` is the inert one, `chip` goes somewhere, and `removable` goes
    /// somewhere and says the going takes it off.
    Chip {
        value: Arg,
        action: Action,
        /// Whether the tag says it can be taken off, which is `Tag::removable`.
        removable: bool,
        body: Vec<Item>,
    },
    /// `screen <arrangement> <arg> { .. }`
    Screen {
        arrangement: Ident,
        /// What the arrangement is told. Every one takes a title; `list_detail`
        /// takes whether it is tabbed as well, which is why this is a list
        /// rather than the one title it was until wave 9.
        args: Vec<Arg>,
        body: Vec<Item>,
    },
    /// `row <arg> { .. }`
    Row { primary: Arg, body: Vec<Item> },
    /// `form <action> { submit <arg>; field .. }`
    Form { action: Action, body: Vec<Item> },
    /// `field <kind> <name> <label> ( { .. } | ; )`
    Field {
        kind: Ident,
        name: Arg,
        label: Arg,
        body: Vec<Item>,
    },
    /// `list { .. }` -- the rows built in place rather than supplied.
    ///
    /// Its own member rather than a container in the general sense: a `Vec`
    /// does not chain, so the one thing that accretes by pushing is kept where
    /// it can be read instead of bending every other container's shape.
    List(Vec<Item>),
    /// `act <arg> to <action> ( { .. } | ; )`
    Act {
        label: Arg,
        action: Action,
        body: Vec<Item>,
    },
    /// `offers <arg> to <action> ( { .. } | ; )` -- `act`'s held-back twin.
    ///
    /// A control a row carries but does not show: `Row::offers` pushes onto the
    /// menu a host reveals when it is asked, where `Row::act` puts the control
    /// in the row. One word apart because that is the whole of the difference,
    /// and a member rather than a setting because a menu control is told the
    /// same things an inline one is -- audiofiles' sidebar greys a vault's
    /// Delete when it is the last vault, which a control written as an
    /// expression cannot say.
    Offers {
        label: Arg,
        action: Action,
        body: Vec<Item>,
    },
    /// `table { column ..; cells { .. } }`
    ///
    /// Columns and rows accrete rather than arriving as two lists, which is
    /// what `Table::column` and `Row::cell` were added to `quasi-router` for.
    /// The form has no expression to hold a list in, and a production that
    /// admitted one would be the door this grammar exists to keep shut.
    Table(Vec<Item>),
    /// `column <name> ( "{" .. "}" | ";" )` -- one column and how it narrows.
    Column { name: Arg, body: Vec<Item> },
    /// `cells { cell ..; }` -- one row of a table.
    ///
    /// A row's cells are all positional or all named; mixing the two is what
    /// `Row::at`'s own docs warn against.
    Cells(Vec<Item>),
    /// `cell [ "at" <column> ] <value> ( "{" .. "}" | ";" )`
    ///
    /// Positional without the column, named with it. `item_sales` demanded the
    /// named form: its columns are module consts and its cells are a function
    /// away, so a row written by position would be lined up against headings
    /// nobody reading the row can see. Naming is `Row::at`, and the two are
    /// not mixed in one row -- that warning is `at`'s own.
    Cell {
        column: Option<Arg>,
        value: Arg,
        body: Vec<Item>,
    },
    /// `offering <arg> to <action> ( "{" { item } "}" | ";" )` -- the way out an
    /// empty or failed state offers.
    ///
    /// Spelled like `act` and placed like a setting, because `Node::offering`
    /// takes an `Act` and a setting's arguments are args. Its own member rather
    /// than an `act` the container reinterprets: a body holding a control and a
    /// body holding a way out would otherwise read the same and mean different
    /// things.
    Offering {
        label: Arg,
        action: Action,
        body: Vec<Item>,
    },
    /// `removes <arg> to <action> ( "{" { item } "}" | ";" )` -- the control one
    /// slot of a repeating question carries to take itself away.
    ///
    /// `act`'s shape and `Slot::removes`'s meaning, which is one word apart for
    /// the reason `offers` was: a control that takes its own region away is told
    /// the same things every other control is, and written as an expression in
    /// argument position it can be told none of them. audiofiles' rule editor is
    /// the site, twice.
    Removes {
        label: Arg,
        action: Action,
        body: Vec<Item>,
    },
    /// `repeats <arg> adds <arg> to <action> ( "{" { item } "}" | ";" )`
    ///
    /// A region that is a repeating question: what one of them is called, the
    /// control that adds another, and how few may be left standing. The add
    /// control is in the header rather than the body because `Repeating::new`
    /// takes it, and the body is that type's own settings.
    ///
    /// Spelled `repeats` and not `repeating`, which is the setting it calls,
    /// because `Field::repeating` takes a different type and one name cannot
    /// mean both. Same rule and same remedy as `underway` and `proportion`.
    Repeats {
        one: Arg,
        label: Arg,
        action: Action,
        body: Vec<Item>,
    },
    /// `activate to <action>;` -- what opening this row or cell does.
    ///
    /// A setting in shape, and a member in the tree, because the thing it sets
    /// is an action and a setting's arguments are args. Rows, rows of cells and
    /// single cells all carry one.
    Activate(Action),
    /// `include <hole>;` -- whatever another shape built.
    Include(Hole),
    /// `include each <shape>`: a shape answering many members, spliced whole.
    ///
    /// The plural of [`Include`](Self::Include), and a separate emission rather
    /// than a flag on it because what it places is a run and not a node: only
    /// a container that holds many members can take one.
    IncludeEach(Hole),
    /// `link <arg> to <action>;`
    Link { text: Arg, action: Action },
    /// `region <arg> as <kind> { .. }`
    Region {
        name: Arg,
        kind: RegionKind,
        body: Vec<Item>,
    },
    /// `across <fallback> { .. }`
    Across { fallback: Ident, body: Vec<Item> },
    /// `beside <priority> <emission>`
    ///
    /// An `Arg` rather than an `Ident`, which is rule R1(4) reaching the last
    /// vocabulary slot that did not have it: `tone`, `width`, `priority` and
    /// `fit` have all taken a hole since wave 2, and a bare uppercase ident
    /// still reads as the variant, so every existing site is unchanged.
    /// audiofiles' toolbar is what asked -- its six panel toggles each carry
    /// what they are worth, and a rank that has to be a literal cannot say it.
    /// `framed <label> <emission>` -- a member placed as a named frame.
    ///
    /// The placement modifier for a region that shows one member at a time. The
    /// name belongs to the placement rather than to the member, because it names
    /// the control that reveals it (quasicoherent `2cdc6761`), and a member
    /// written in another `declare!` cannot carry one at all: a shape answers a
    /// `Slot`, and since that ruling a `Slot` has no label.
    ///
    /// Inside one invocation the macro hoists a child region's own `label`
    /// instead, so the common spelling is unchanged. This is for the case a
    /// hoist cannot reach, which is exactly the case that went wrong: goingson's
    /// `summary_body` is its own shape and its parent includes it.
    Framed { label: Arg, inner: Box<Emission> },
    Beside {
        priority: Arg,
        /// How much of the row it asks for, where it said.
        ///
        /// Optional because most members have no opinion: a strip's members and
        /// a band's take what they need, which is what a run already drew.
        /// Written between the rank and the member (`beside Essential Fill
        /// include pane(x)`) and told from the member by R1's rule -- a member
        /// is one of the known lowercase words, so anything else in that
        /// position is the width.
        ///
        /// A row only. The body of a region is a stack and its members each get
        /// the whole width, so a width there is refused rather than ignored.
        width: Option<Arg>,
        inner: Box<Emission>,
    },
    /// `at <arg> <emission>` -- one thing on an axis, and where it sits.
    ///
    /// Only inside a `timeline`, where the argument is a `Placement` and the
    /// emission is the row that sits at it. The keyword is `cell at <arg>`'s,
    /// and the container is the whole of how the two are told apart, exactly as
    /// it is for `beside` and for `include`. A timeline holds nothing but
    /// entries and a row of cells holds nothing but cells, so no body can be
    /// read both ways.
    At { at: Arg, inner: Box<Emission> },
    /// `<emission> when <predicate>` / `unless <predicate>`.
    ///
    /// A guard suppresses the emission and nothing else. R9: the holes inside
    /// it are still evaluated, because a hole is one eager evaluation and a
    /// guard is not a scope.
    Guarded { guard: Guard, inner: Box<Emission> },
    /// `given <hole> { <pattern> -> <emission> .. }` in member position.
    ///
    /// Every arm emits exactly one member, which is what makes the dispatch a
    /// member itself rather than a statement. R7: this is a real `match`, so
    /// exhaustiveness and arm order are rustc's.
    Given {
        scrutinee: Hole,
        arms: Vec<(Pattern, Box<Emission>)>,
        otherwise: Option<Box<Emission>>,
    },
}

/// What kind of region this is: a variant, or a hole that answers with one.
///
/// `RegionKind::Widget` carries a name, so it is the one kind a bare ident
/// cannot spell. `media_picker` has three widget regions and a `widget(name)`
/// helper beside them, which is the deferred table's own remedy for a value the
/// form cannot say; this lets the declaration call it.
///
/// Told apart by R1's rule and not by a keyword: a bare uppercase ident is a
/// variant, and anything else is a hole.
#[derive(Clone)]
pub enum RegionKind {
    Variant(Ident),
    Supplied(Hole),
}

/// `when <predicate>`, or `unless <predicate>`, which is its negation.
#[derive(Clone)]
pub struct Guard {
    pub negated: bool,
    pub predicate: Predicate,
    pub span: Span,
}

#[derive(Clone)]
pub enum Predicate {
    /// `<clause> and <clause>`, or `<clause> or <clause>`. One connective per
    /// predicate: mixing them would need precedence, and precedence is how a
    /// predicate becomes an expression.
    Joined {
        connective: Ident,
        clauses: Vec<Predicate>,
    },
    /// `not <clause>`.
    Not(Box<Predicate>),
    /// A hole that is already a `bool`.
    Truth(Hole),
    /// `<hole> <compare> <arg>`. The comparison is a word rather than an
    /// operator, so nothing in the form is an expression.
    Comparison {
        left: Hole,
        compare: Ident,
        right: Arg,
    },
}

#[derive(Clone)]
pub struct Action {
    /// One of the verbs, or `doing`, which takes the whole action from a
    /// supplier. Amendment 6: a screen whose action is decided by something
    /// the form cannot say gets a function beside it rather than a production.
    pub verb: Ident,
    pub target: Option<Arg>,
    pub modifiers: Vec<Modifier>,
}

/// One word after the verb, and whatever it needs to say it.
#[derive(Clone)]
pub struct Modifier {
    pub name: Ident,
    pub args: Vec<Arg>,
}