//
// Copyright (c) 2009, Brian Frank and Andy Frank
// Licensed under the Academic Free License version 3.0
//
// History:
//   14 Jul 09  Brian Frank  Creation
//   04 Feb 10  Brian Frank  Rework from old Symbol design
//

**************************************************************************
** Serializable
**************************************************************************

**
** Serializable is a facet used to annotate types which can be serialized.
** Objects are serialized via `sys::OutStream.writeObj` and deserialized
** via `sys::InStream.readObj`.
**
** See the [Serialization Doc]`docLang::Serialization` for details.
**
@FacetMeta { inherited = true }
facet class Serializable
{
  **
  ** Simples are serialized atomically via a customized string representation
  ** using the following rules:
  **   - Override `sys::Obj.toStr` to return a suitable string representation
  **     of the object.
  **   - Must declare a static method called 'fromStr' which takes one 'Str'
  **     parameter and returns an instance of the declaring type.  The 'fromStr'
  **     method may contain additional parameters if they declare defaults.
  **
  const Bool simple := false

  **
  ** Collections are serialized with a collection of child objects
  ** using the following  rules where 'Item' is the item type:
  **   - Provide an 'add(Item)' method to add child items during 'readObj'
  **   - Provide an 'each(|Item| f)' method to iterate child items
  **     during 'writeObj'
  **
  const Bool collection := false
}

**************************************************************************
** Transient
**************************************************************************

**
** Transient annotates fields which should not be serialized.  It is used inside
** a `Serializable` type.  See the [Serialization Doc]`docLang::Serialization`
** for details.
**
facet class Transient {}

**************************************************************************
** Js
**************************************************************************

**
** Used to annoate types which should be compiled into JavaScript.
**
facet class Js {}

**************************************************************************
** NoDoc
**************************************************************************

**
** Annotate a type or slot as undocumented.  This facet indicates an API
** should not be documented with automated tools such as [Fandoc]`fandoc::pod-doc`.
** As a developer you should avoid using these types and slots since they
** are explicitly marked as not part of the public API.
**
facet class NoDoc {}

**************************************************************************
** Deprecated
**************************************************************************

**
** Indicates that a type or slot is obsolete
**
facet class Deprecated
{
  **
  ** Message for compiler output when deprecated type or slot is used.
  **
  const Str msg := ""
}

**************************************************************************
** Operator
**************************************************************************

**
** Used on methods to indicate method may be used as an operator.
** The operator symbol is determined by the method name:
**
**   prefix     symbol    degree
**   ------     ------    ------
**   negate     -a        unary
**   increment  ++a       unary
**   decrement  --a       unary
**   plus       a + b     binary
**   minus      a - b     binary
**   mult       a * b     binary
**   div        a / b     binary
**   mod        a % b     binary
**   get        a[b]      binary
**   set        a[b] = c  ternary
**   add        a { b, }
**
** In the case of binary operators multiple methods may
** be declared for a given symbol as long as every method starts
** with correct name, for example "plus" and "plusInt".  For
** unary/ternary operators there can only be one method and it must
** be named exactly "negate", "increment", "decrement", or "set".
**
** See [docLang]`docLang::Methods#operators` for additional details.
**
facet class Operator {}

**************************************************************************
** FacetUsage
**************************************************************************

**
** Facet meta-data applied to facet classes.
**
facet class FacetMeta
{
  **
  ** Indicates whether the facet is inherited by sub-types.
  ** See [docLang]`docLang::Facets#inheritance` for additional details.
  **
  const Bool inherited := false
}