/*!
Base requirements for indexable document mappings.

Structures that can be indexed in Elasticsearch should implement `DocumentType`.
The `DocumentType` is composed of typical mapping metadata, as well as the mapping
for each of its properties.

Documents can be mapped as indexable types, or as an object field on another type.

# Examples

Define your Elasticsearch types using _Plain Old Rust Structures_.

## Derive Mapping

Mapping can be generated by deriving `ElasticType` on a struct:

```
# #[macro_use]
# extern crate json_str;
# #[macro_use]
# extern crate serde_derive;
# #[macro_use]
# extern crate elastic_types_derive;
# #[macro_use]
# extern crate elastic_types;
# extern crate serde;
# use elastic_types::prelude::*;
#[derive(Serialize, ElasticType)]
pub struct MyType {
    pub my_date: Date<DefaultDateFormat>,
    pub my_string: String,
    pub my_num: i32
}
# fn main() {
# }
```

This will produce the following field mapping:

```
# #[macro_use]
# extern crate json_str;
# #[macro_use]
# extern crate serde_derive;
# #[macro_use]
# extern crate elastic_types_derive;
# #[macro_use]
# extern crate elastic_types;
# extern crate serde;
# extern crate serde_json;
# use elastic_types::prelude::*;
# #[derive(Serialize, ElasticType)]
# pub struct MyType {
#   pub my_date: Date<DefaultDateFormat>,
#   pub my_string: String,
#   pub my_num: i32
# }
# fn main() {
# let mapping = standalone_field_ser(MyTypeMapping).unwrap();
# let json = json_str!(
{
    "type": "nested",
    "properties": {
        "my_date": {
            "type": "date",
            "format": "basic_date_time"
        },
        "my_string": {
            "type": "text",
            "fields": {
                "keyword":{
                    "type":"keyword",
                    "ignore_above":256
                }
            }
        },
        "my_num": {
            "type": "integer"
        }
    }
}
# );
# assert_eq!(json, mapping);
# }
```

It's also possible to adjust the mapping using the `#[elastic]` attribute.

### Override Default Mapping Properties

You can override the mapping meta properties for an object by providing your own mapping type with `#[elastic(mapping="{TypeName}")]`:

```
# #[macro_use]
# extern crate json_str;
# #[macro_use]
# extern crate serde_derive;
# #[macro_use]
# extern crate elastic_types_derive;
# #[macro_use]
# extern crate elastic_types;
# extern crate serde;
# use elastic_types::prelude::*;
#[derive(Serialize, ElasticType)]
#[elastic(mapping="MyTypeMapping")]
pub struct MyType {
    pub my_date: Date<DefaultDateFormat>,
    pub my_string: String,
    pub my_num: i32
}

#[derive(Default)]
pub struct MyTypeMapping;
impl DocumentMapping for MyTypeMapping {
    //Give your own name to a type
    fn name() -> &'static str { "my_type" }

    fn data_type() -> &'static str { OBJECT_DATATYPE }
}
# fn main() {
# }
```

This will produce the following field mapping:

```
# #[macro_use]
# extern crate json_str;
# #[macro_use]
# extern crate serde_derive;
# #[macro_use]
# extern crate elastic_types_derive;
# #[macro_use]
# extern crate elastic_types;
# extern crate serde;
# extern crate serde_json;
# use elastic_types::prelude::*;
# #[derive(Default, Serialize, Deserialize, ElasticType)]
# #[elastic(mapping="MyTypeMapping")]
# pub struct MyType {
#   pub my_date: Date<DefaultDateFormat>,
#   pub my_string: String,
#   pub my_num: i32
# }
#
# #[derive(Default)]
# pub struct MyTypeMapping;
# impl DocumentMapping for MyTypeMapping {
#   fn name() -> &'static str { "my_type" }
#   fn data_type() -> &'static str { OBJECT_DATATYPE }
# }
# fn main() {
# let mapping = standalone_field_ser(MyTypeMapping).unwrap();
# let json = json_str!(
{
    "type": "object",
    "properties": {
        "my_date": {
            "type": "date",
            "format": "basic_date_time"
        },
        "my_string": {
            "type": "text",
            "fields": {
                "keyword":{
                    "type":"keyword",
                    "ignore_above":256
                }
            }
        },
        "my_num": {
            "type": "integer"
        }
    }
}
# );
# assert_eq!(json, mapping);
# }
```

### Ignore or Rename Fields

You can then serialise type mappings with `#[serde]` attributes:

```
# #[macro_use]
# extern crate json_str;
# #[macro_use]
# extern crate serde_derive;
# #[macro_use]
# extern crate elastic_types_derive;
# #[macro_use]
# extern crate elastic_types;
# extern crate serde;
# use elastic_types::prelude::*;
#[derive(ElasticType, Serialize)]
pub struct MyType {
    #[serde(rename="my_renamed_date")]
    pub my_date: Date<DefaultDateFormat>,
    #[serde(skip_serializing)]
    pub ignored: String,
    pub my_num: i32
}
# fn main() {
# }
```

> NOTE: Fields with a `#[serde(skip_deserializing)]` attribute will still be mapped, because they can
still be indexed in Elasticsearch.

## Limitations

Automatically deriving mapping has the following limitations:

- Generics aren't supported by auto deriving.
So you can't `#[derive(ElasticType)]` on `MyType<T>`.
- Mapping types can't be shared. This is because they need to map the type fields, so are specific to that type.
So you can't share `MyTypeMapping` between `MyType` and `MyOtherType`.

All of the above limitations can be worked around by implementing the mapping manually.

Remember that Elasticsearch will automatically update mappings based on the objects it sees though,
so if your 'un-mapped' field is serialised, then an inferred mapping will be added for it.

## Manually Implement Mapping

You can build object mappings by manually implementing the [`DocumentMapping`](mapping/trait.DocumentMapping.html) and [`PropertiesMapping`](mapping/trait.PropertiesMapping.html) traits:

```
# #[macro_use]
# extern crate json_str;
# #[macro_use]
# extern crate serde_derive;
# #[macro_use]
# extern crate elastic_types_derive;
# #[macro_use]
# extern crate elastic_types;
# extern crate serde;
# use elastic_types::prelude::*;
#[derive(Serialize)]
pub struct MyType {
    pub my_date: Date<DefaultDateFormat>,
    pub my_string: String,
    pub my_num: i32
}

//Implement DocumentType for your type. This binds it to the mapping
impl DocumentType for MyType {
    type Mapping = MyTypeMapping;
}

//Define the type mapping for our type
#[derive(Default)]
pub struct MyTypeMapping;
impl DocumentMapping for MyTypeMapping {
    fn name() -> &'static str { "my_type" }
}
impl PropertiesMapping for MyTypeMapping {
    fn props_len() -> usize { 3 }

    fn serialize_props<S>(state: &mut S) -> Result<(), S::Error>
    where S: serde::ser::SerializeStruct {
        try!(field_ser(state, "my_date", Date::<DefaultDateFormat>::mapping()));
        try!(field_ser(state, "my_string", String::mapping()));
        try!(field_ser(state, "my_num", i32::mapping()));

        Ok(())
    }
}
# fn main() {
# }
```

# Links
- [Field Types](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html)
- [Document Types](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html)
*/

pub mod mapping;

mod impls;
pub use self::impls::*;

pub mod prelude {
    /*!
    Includes all types for document types.
    
    This is a convenience module to make it easy to build mappings for multiple types without too many `use` statements.
    */

    pub use super::impls::*;
    pub use super::mapping::*;
}
