#![recursion_limit = "512"]
// While under active devel, these warnings are kind of annoying.
#![allow(dead_code)]

//! Generates code to create a derived `glib::Object`
//!
//! The `gobject_gen!` macro defines an extension to the Rust language so
//! that one can create GObject implementations, or define
//! GTypeInterfaces, using only safe code.  All the boilerplate needed
//! to register the GObject type, its signals and properties, etc., is
//! automatically generated.
//!
//! # Syntax overview {#syntax-overview}
//!
//! The macro is invoked as follows:
//!
//! ```norun
//! // see "Necessary imports" below on why this is needed
//! #[macro_use]
//! extern crate glib;
//! use gobject_gen::gobject_gen;
//!
//! gobject_gen! {
//!     class Foo {
//!         private_field: Cell<u32>,
//!         another_field: RefCell<String>,
//!     }
//!
//!     // Methods and signals; their order defines
//!     // the ABI of your class
//!     impl Foo {
//!         pub fn a_static_method(&self) {
//!             // self.get_priv() gives us access to the private
//!             // fields declared in class Foo
//!             do_something(self.get_priv().private_field.get());
//!         }
//!
//!         virtual fn a_virtual_method(&self) {
//!             // default handler implementation goes here
//!         }
//!
//!         signal fn clicked(&self);
//!     }
//! }
//! ```
//!
//! Read on for the details on how to use specific GObject features.
//!
//! # Necessary imports
//!
//! The generated code depends on external crates:
//!
//! * The `glib` crate and its macros.
//! * The `gobject_gen` crate, declaring `proc_macro` use.
//!
//! You can put this at the top of your crate's main file:
//!
//! ```norun
//! #![feature(proc_macro)]
//! extern crate gobject_gen;
//!
//! #[macro_use]
//! extern crate glib;
//!
//! use gobject_gen::gobject_gen;
//! ```
//!
//! You need the following dependencies in `Cargo.toml`:
//!
//! ```norun
//! [dependencies]
//! glib = "0.5.0"
//! glib-sys = "0.6.0"
//! gobject-sys = "0.6.0"
//! libc = "0.2"
//! ```
//!
//! # Instance-private data
//!
//! GObject classes defined through this macro can have instance-private data
//! declared as struct fields inside the class.
//!
//! * **Declaration:** Declare struct fields inside `class Foo { ... }`
//!
//! * **Initialization:** Implement the `Default` trait for your
//! struct members, either with `#[derive(Default)]` or with an `impl Default`
//! if its missing. Note that you have to do this for each type used across
//! fields. When the generated code needs to initialize the instance-private
//! data, it will do so by calling the `Default::default()` method and assign it
//! to the internally private structure generated by the macro.
//!
//! * **Drop:** When the GObject instance gets finalized, your private
//! data will be `drop()`ed.  You can provide `impl Drop` for any fields
//! that need explicit resource management.
//!
//! # Declaring methods
//!
//! Inside an `impl MyClass` item, you can declare static methods
//! (cannot be overriden in derived classes), or virtual methods that
//! can be overriden:
//!
//! ```norun
//! impl MyClass {
//!     pub fn my_static_method(&self, x: u32) -> String {
//!         // implement your method here
//!     }
//!
//!     virtual fn my_virtual_method(&self) -> usize {
//!         // implement your method here
//!     }
//! }
//! ```
//!
//! A `pub` method is static and cannot be overriden in derived
//! classes.  A `virtual` method is assumed to be public and *can* be
//! overriden.
//!
//! The first argument must always be `&self`; gnome-class doesn't
//! support `&mut self`.  To have mutable fields in your instances,
//! you must use interior mutability with `Cell` or `RefCell`.
//!
//! Unlike normal Rust code, method arguments must be bare identifiers
//! with their types, like `x: u32`; they cannot be pattern-matched
//! captures.
//!
//! FIXME: mention limitations on argument and return types
//!
//! # Declaring signals
//!
//! Signals are declared in a similar way to methods, but using `signal` instad of `virtual`:
//! ```norun
//! impl MyClass {
//!     signal fn my_signal(&self, x: u32) {
//!         // implement your default signal handler here
//!     }
//! }
//! ```
//!
//! FIXME: mention limitations on argument and return types
//!
//! # Overriding methods from a parent class
//!
//! You can use the `impl ParentClass for Subclass` notation to override methods in your subclass:
//!
//! ```norun
//! class Foo {
//! }
//!
//! impl Foo {
//!     virtual fn hello(&self) {
//!         println!("hello");
//!     }
//! }
//!
//! class Bar {
//! }
//!
//! impl Foo for Bar {
//!     virtual fn hello(&self) {
//!         println!("overriden hello");
//!     }
//! }
//! ```
//!
//! As of 2018/Nov/15, it is hard to chain up to the parent class from
//! an overriden method.  See [issue
//! #46](https://gitlab.gnome.org/federico/gnome-class/issues/46)
//! about this.
//!
//! # ABI considerations
//!
//! The Application Binary Interface (ABI) of a GObject class is
//! defined by its virtual method table (vtable), which includes both virtual
//! methods and signals.  In gnome-class, this means that the order of
//! method or signal items inside an `impl MyClass` is significant:
//! adding, removing, or reordering the methods and signals will
//! change the ABI, since C code will see a `MyClass` struct with
//! fields to function pointers in a different order.
//!
//! Conventionally, GObject classes can reserve a number of empty
//! vtable slots for future expansion.  In gnome-class, you can use
//! the `reserve_slots` keyword:
//!
//! ```norun
//! impl Foo {
//!     virtual fn one_virtual_method(&self) { ... }
//!
//!     reserve_slots(10)
//! }
//! ```
//!
//! In the example above, there will be 10 unused function pointers at
//! the end of the generated class struct.  If you ever add another
//! method or signal, decrement the number passed to
//! `reserve_slots()`.
//!
//! # Debugging aids and examining generated code
//!
//! With gnome-class still under development, you may need to examine
//! the code that gets generated from the procedural macro.  First,
//! create a directory called `generated` under your crate's toplevel
//! directory.  Then, put a `generate` attribute for your class, like
//! this:
//!
//! ```norun
//! #[cfg(feature = "test-generated")]
//! include!("generated/foo-gen.rs");
//!
//! #[cfg(not(feature = "test-generated"))]
//! gobject_gen! {
//!    #[generate("generated/foo-gen.rs")]
//!     class Foo {
//!     }
//! }
//! ```
//!
//! Correspondingly, add this to `Cargo.toml` to declare the `test-generated` feature:
//!
//! ```norun
//! [features]
//! # If this feature is enabled, it executes the tests with
//! # the rust files generated during an earlier run.
//! test-generated = []
//! ```
//!
//! If you just `cargo build` your code, then it will output the file
//! `generated/foo-gen.rs` which you can examine.  You can then edit
//! that file and rebuild with `cargo build -- --features test-generated` - this will cause
//! the `foo-gen.rs` to get included, instead of using "fresh" generated code.
//!
//! **Remember that changes to the generated code will be overwritten
//! the next time the procedural macro runs!** Don't forget to [report
//! a bug][bugs] if gnome-class is generating incorrect code for you!
//!
//! [bugs]: https://gitlab.gnome.org/federico/gnome-class/issues

extern crate proc_macro;

use crate::errors::*;
#[macro_use]
mod errors;

mod ast;
mod checking;
mod gen;
mod glib_utils;
mod hir;
mod ident_ext;
mod param;
use quote::ToTokens;

/// Generates the code to create a derived glib::Object
///
/// See the [crate's toplevel documentation][crate] for usage instructions.
///
/// [crate]: index.html
#[proc_macro]
#[cfg_attr(rustfmt, rustfmt_skip)]
pub fn gobject_gen(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
    match gobject_gen_inner(input) {
        Ok(tokens) => tokens,
        Err(err) => { err.into_token_stream().into() },
    }
}

mod parser;

fn gobject_gen_inner(input: proc_macro::TokenStream) -> Result<proc_macro::TokenStream> {
    let ast_program = parser::parse_program(input)?;
    let hir_program = hir::Program::from_ast_program(&ast_program)?;
    gen::gir::generate(&hir_program)?;
    let tokens = gen::codegen(&hir_program);

    Ok(tokens.into())
}

#[doc(hidden)]
#[proc_macro]
pub fn testme(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
    testme_inner(input).unwrap_or_else(|err| err.into_token_stream().into())
}

fn testme_inner(input: proc_macro::TokenStream) -> Result<proc_macro::TokenStream> {
    checking::tests::run()?;
    glib_utils::tests::run();
    hir::tests::run()?;
    parser::tests::run()?;
    gen::tests::run();
    Ok(input)
}