Commits

Paweł Wieczorek committed 4671c90

added docs

Comments (0)

Files changed (8)

+Pawel Wieczorek <wieczyk gmail>
+author          = "Pawel Wieczorek"
 name            = "stringpainter"
 version         = "0.1"
 description     = "Pretty printing combinators, designed for printing ASTs."
-<src/*.cmx>: for-pack(StringPainter)
+<*/**.cmx>: for-pack(StringPainter)
  * http://bitbucket.org/wieczyk/ocaml-stringpainter
  ********************************************************************************************************************)
 
-
 include Engine
 
+(** * Basic combinator for... *)
 let sp_indent_when_multiline sp =
     if any_multiline sp
     then sp_indent sp
  * http://bitbucket.org/wieczyk/ocaml-stringpainter
  ********************************************************************************************************************)
 
+(**
+   This module contains basic painters. They are only usefull for small stuff.
+ *)
+
+
+(** Te type of painter *)
 type painter
 
 val is_multiline : painter -> bool

src/Prioritized.ml

  * http://bitbucket.org/wieczyk/ocaml-stringpainter
  ********************************************************************************************************************)
 
-type painter = int * Basic.painter
+type priority = int
+
+type painter = priority * Basic.painter
+
 
 type associativity
     = LeftAssociative
     let embed_sp1 prio sp x1 =
         with_priority prio (sp x1)
 
+    let unhask_sp0 f (_, sp) = f sp
+
     let embed_sp2 prio sp x1 x2 =
         with_priority prio (sp x1 x2)
 
 
 open Embedding
 
+
+let with_priority = Embedding.with_priority
+
 let get_priority p = fst p
 
 let get_painter  p = snd p
 
 let psp_max_priority = pred max_int / 2
 
+let is_multiline    = unhask_sp0 Basic.is_multiline
+
+let any_multiline   = List.exists is_multiline
+
 (*--------------------------------------------------------------------------------------------------------------------
  * Basic combinators
  *)

src/Prioritized.mli

  * http://bitbucket.org/wieczyk/ocaml-stringpainter
  ********************************************************************************************************************)
 
+(**
+ Prioritized painters are designed for printing ASTs where indentation
+ and brackets are important aspect. This module provides fundamental
+ painters.
+ *)
+
+
+
+(** painter type *)
 type painter
 
+(** priority *)
+type priority = int
+
+
+(** associtivity *)
 type associativity
     = LeftAssociative
     | RightAssociative
     | NoAssociative
 
-val get_priority : painter -> int
+(**
+    The [ with_priority prio sp ] embeds a basic string pinter [ sp ] with priority [ prio ]
+    as prioritrized painter.
+ *) 
+val with_priority : priority -> Basic.painter -> painter
 
+(** Is multiline? *)
+val is_multiline : painter -> bool
+
+val any_multiline : painter list -> bool
+
+(** Returns priority of given painter. *)
+val get_priority : painter -> priority
+
+(** Returns basic painter from prioritized one. *)
 val get_painter :  painter -> Basic.painter
 
-val psp_nested : int -> painter list -> painter
+(** Combine list of painters priorityo one painter with given priority. *)
+val psp_nested : priority -> painter list -> painter
 
-val psp_indent : int->  painter list -> painter
+val psp_indent : priority->  painter list -> painter
 
-val psp_reprioritize : int -> painter -> painter
+(** Return painter with different priority. *)
+val psp_reprioritize : priority -> painter -> painter
 
-val psp_max_priority : int
+(** Maximal priority. *)
+val psp_max_priority : priority
 
+(** Breaks not empty line. *)
 val psp_break : painter
 
+(** Breaks line. *)
 val psp_newline : painter
 
+(** Paints a word. *)
 val psp_word : string -> painter
 
+(** Paints a keyword. *)
 val psp_keyword : string -> painter
 
+(** Paints a value. *)
 val psp_value : string -> painter
 
+(** Paints a value-keyword. *)
 val psp_value_keyword : string -> painter
 
+(** Paints an operator. *)
 val psp_operator : string -> painter
 
+(** Paints a syntax-construct. *)
 val psp_syntax : string -> painter
 
+(** Paints an integer value.  *)
 val psp_value_int : int -> painter
 
+(** Paints an boolean value.  *)
 val psp_value_bool : bool -> painter
 
-val psp_bracket : painter -> painter -> int -> painter -> painter
+(**
+   The [ psp_bracket opening closing prio elem ] parenthesis [ elem ] with given brackets.
+ *)
+val psp_bracket : painter -> painter -> priority -> painter -> painter
 
+(**
+    Specialized version of [ psp_bracket ] for standard brackets and maximal priority.
+  *)
 val psp_std_bracket : painter -> painter
 
+(**
+    Specialized version of [ psp_bracket ] for standard square brackets and maximal priority.
+  *)
 val psp_square_bracket : painter -> painter
 
+(**
+    Specialized version of [ psp_bracket ] for empty symbols as brackets and with maximal priority.
+ *) 
 val psp_no_bracket : painter -> painter
 
 val psp_decide_bracket : (painter -> painter) -> bool -> painter -> painter
 
 val psp_decide_std_bracket : bool -> painter -> painter
 
-val psp_associative_infix : (int -> int -> bool) -> (int -> int -> bool) -> int
-                         -> painter -> painter -> painter -> painter
+(**
+   The [ psp_infix assoc prio oper left right ] paints an infix operators with auto-parenthesis. 
+ *)
+val psp_infix : associativity -> priority -> painter -> painter -> painter -> painter
 
-val psp_left_associative_infix : int -> painter -> painter -> painter -> painter
-
-val psp_right_associative_infix : int -> painter -> painter -> painter -> painter
-
-val psp_no_associative_infix : int -> painter -> painter -> painter -> painter
-
-val psp_infix : associativity -> int -> painter -> painter -> painter -> painter
-
+(**
+   Prints on standard output with newline.
+ *)
 val print_painter_nl  : painter -> unit
 
+(**
+   Prints on standard output..
+ *)
 val print_painter     : painter -> unit
 
+(**
+    Renders painter into string.
+ *)
 val render_painter    : painter -> string
 

src/StringPainter.odocl

-StringPainter
 Basic
 Prioritized