qmljs_Serializer.mli

(*
    Copyright © 2011 MLstate

    This file is part of OPA.

    OPA is free software: you can redistribute it and/or modify it under the
    terms of the GNU Affero General Public License, version 3, as published by
    the Free Software Foundation.

    OPA is distributed in the hope that it will be useful, but WITHOUT ANY
    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for
    more details.

    You should have received a copy of the GNU Affero General Public License
    along with OPA. If not, see <http://www.gnu.org/licenses/>.
*)
(**
   Serializer for JsAst
   @author Mathieu Barbin
   @author Rudy Sicard
*)

(**
   During the compilation, we generate some opa-structures from the JsAst optained by compiling the client code.
   These opa-structures are manipulated by opa code present in the stdlib.
   It is a way for passing informations (the js ast) from compile time to runtime
*)

module JsIdent :
sig
  (**
     Retreive the name of the js expression from the [name] of OPA
     expression. Used for resolve [\@js_ident]. If the given string
     doesn't corresponding to an ident in OPA raise [Not_found].

     The function return a fresh ident refering to a toplevel declaration
     generated in an internal reference.
     If you call 2 time this function with the same name, you'll get 2 time
     the same ident.

     Example:

  *)
  val resolve : Ident.t -> Ident.t

  (**
     Get all the toplevel declaration corresponding to all previous call to
     [resolve_js_ident], and flush the internal reference. (clear it)

     Should be concatenated with the code.
     The code has no dependencies, and can be inserted anywhere before any utilisation.
  *)
  val get_toplevel_declarations : unit -> QmlAst.code

  (**
     As we need to perform some check about unbound values before that we reintroduce
     the memorized toplevel values generated by call to [resolve], and retrieve with
     [get_toplevel_declarations], we need a function to know, given an identifier
     if it will be defined in the returned [QmlAst.code].
  *)
  val is_toplevel_declaration : Ident.t -> bool
end


(**
   Binding with the module JsAst of the stdlib.
   This structure is used for generating at compile time some runtime JsAst,
   without caring about runtime representation (serialization of the structure)
*)
module JsSerializer :
sig

  type jsast_ident = string

  type jsast_mini_expr =
    | Verbatim of string
    | Ident of jsast_ident
    | Expr of QmlAst.expr
    | SetDistant of jsast_ident list
    | TypeUse of string
    | TypeDef of string
    | RpcUse of string
    | RpcDef of string

  type jsast_key_ident =
    | KI_key of string
    | KI_ident of jsast_ident
    | KI_key_ident of string * jsast_ident

  type jsast_code_elt = {
    ident : jsast_key_ident ;
    definition : [ `Rpc of string | `Type of string | `Nothing ];
    root : bool ;
    content : jsast_mini_expr list ;
  }

  type jsast_code = jsast_code_elt list

  (**
     A function for serializing the compile time JsAst. (from jslang).
     This function uses internally the Js Partial Printer defined in [JsPrinter].

     The [register_call] map is used for tagging register call, so that we know
     at runtime that they are not random side effects.
  *)
  val serialize :
    client_roots:IdentSet.t ->
    ?key:string ->
    JsAst.code_elt -> jsast_code_elt

end

(**
   Serializing the compile time structure to the runtime ast.
   The resulting expressions are meant to be part of the generated code.
*)
module QmlSerializer :
sig

  (**
     Build a qml expression of type [JsAst.code].
     Returns a code of needed generated toplevel intermediate values,
     and an expression of type [JsAst.code], ready to be registered.

     <!> This module is hard-linked with the representation implemented
     in the packages [stdlib.js], in the module [JsAst].
     Keep it synchronized.
  *)
  val insert_code : kind:[`ast|`adhoc] -> JsSerializer.jsast_code -> QmlAst.code -> QmlAst.code
end