Preparing 1.0.0 release.

Author: ifazk

CHANGES.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] - 2022-01-12
+### Changed
+- Default flags have changed to padding with zeros, with separators and
+  prefixes, and zero printing behaves just like non-zero printing. Since the
+  primary purpose of this library is debugging, this should help.
+- `*.{make_pp_int,make_to_string}` no longer take an optional `flags` parameter,
+  and instead takes optional boolean parameters `zero_padding`, `left_padding`,
+  `separators`, `prefix`, `suffix`, `zero_special`.
+- Renamed `*.{pp_binary_int}` to `*.{pp_int_with}` for consistency.
+
+### Fixed
+- Padding with zeros no longer assumes prefixes are always 2 characters long.
+
 ## [0.1.1] - 2021-12-31
 ### Added
 - Support for `int32`, `int64`, and `nativeint`.

README.md

@@ -23,9 +23,11 @@ opam install pp-binary-ints
 The library provides four main functions.
 
 - `Int.to_string` converts ints to strings.
-- `Int.to_string_with ~flags ~min_width` converts ints to strings, customizing the output with `flags` and `min_width`.
+- `Int.make_to_string` converts ints to strings, customizing the output with the optional arguments.
 - `Int.pp_int` is a simple `Format` module style pretty printer.
-- `Int.pp_binary_int ~flags ~min_width` is a customizable `Format` module style pretty printer.
+- `Int.make_pp_int` is a customizable `Format` module style pretty printer with the customization controlled by the optional arguments.
+- `Int.to_string_with` is a lower level function converts ints to strings, customizing the output with the `~flags` and `~min_width` named arguments.
+- `Int.pp_int_with` is a lower level customizable `Format` module style pretty printer which takes in named arguments `~flags` and `~min_width`.
 
 There are also versions available for `int32`, `int64`, and `nativeint` in the
 modules
@@ -36,66 +38,87 @@ modules
 A generic functor to generate binary-int printers is provided in the `MakePP`
 module.
 
+The following demonstrates using the library in a toplevel/REPL.
+
 ## Basic use
 
 ```ocaml
 # #require "pp-binary-ints";;
 # module Pp_Bin = Pp_binary_ints.Int;;
 # Pp_Bin.to_string 0b110111;;
-- : string = "110111"
+- : string = "0b11_0111"
 # Pp_Bin.to_string 0o777;;
-- : string = "111111111"
+string = "0b1_1111_1111"
 # Pp_Bin.to_string 1234;;
-- : string = "10011010010"
+- : string = "0b100_1101_0010"
 ```
 
 ## Customizing padding and minimum width
 
 ```ocaml
 # #require "pp-binary-ints";;
 # module Pp_Bin = Pp_binary_ints.Int;;
-# (* Zero Padding *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with padding = Zeros } ~min_width:13 0b110111;;
-- : string = "0000000110111"
-# (* Default is space padding on the right *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.default ~min_width:13 0b110111;;
-- : string = "110111       "
+# (* Space Padding *);;
+# Pp_Bin.make_to_string ~zero_padding:false ~min_width:13 () 0b110111;;
+- : string = "0b11_0111    "
 # (* Space padding on the left is also possible *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with padding = Left} ~min_width:13 0b110111;;
-- : string = "       110111"
+# Pp_Bin.make_to_string ~zero_padding:false ~left_padding:true ~min_width:13 () 0b110111;;
+- : string = "    0b11_0111"
 ```
 
 ## Separators and prefixes
 
 ```ocaml
-# (* Separate every 4 digits with _ *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with separators = true } ~min_width:1 0b110111;;
-- : string = "11_0111"
-# (* Prefix non-zero *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with prefix_non_zero = true } ~min_width:1 0b110111;;
+# (* Turn off _ separators *);;
+# Pp_Bin.make_to_string ~separators:false ~min_width:1 () 0b110111;;
 - : string = "0b110111"
-# (* Prefix non-zero with separators *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with prefix_non_zero = true; separators = true } ~min_width:1 0b110111;;
-- : string = "0b11_0111"
+# (* Turn off prefixes *);;
+# Pp_Bin.make_to_string ~prefix:false ~min_width:1 () 0b110111;;
+- : string = "11_0111"
+# (* Turn off both separatorns and prefixes *);;
+# Pp_Bin.make_to_string ~separators:false ~prefix:false ~min_width:1 () 0b110111;;
+- : string = "110111"
 ```
 
 ## Zero printing behaviour
 
-We support pretty printing `0` (zero) both how OCaml's `Printf` woould print it,
-as well as printing it similar to how we print non zero integers. The default
-behaviour is to follow `Printf`'s zero printing and not print a prefix, but this
-can be changed by setting the `zero_printing` flag to `InheritNonZero`.
+You can ask the library to treat `0` (zero) specially and not add a prefix to
+it. While it won't add a prefix to it, padding will still be added.
 
 ```ocaml
-# (* Prefix's are not added to zero by default *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with prefix_non_zero = true } ~min_width:1 0;;
+# (* Don't prefix zero *);;
+# Pp_Bin.make_to_string ~zero_special:true ~min_width:1 () 0;;
 - : string = "0"
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with prefix_non_zero = true; zero_printing = InheritNonZero } ~min_width:1 0;;
-- : string = "0b0"
-# (* All the above options can be combined *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ padding = Zeros; separators = true; prefix_non_zero = true; zero_printing = InheritNonZero } ~min_width:8 0;;
-- : string = "0b0_0000"
-# (* The library is careful not to write "0b_" when prefixing, 'b' is always followed by a digit *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ padding = Zeros; separators = true; prefix_non_zero = true; zero_printing = InheritNonZero } ~min_width:7 0;;
-- : string = "0b00000"
+# Pp_Bin.make_to_string ~zero_special:true ~min_width:1 () 0b110111;;
+- : string = "0b11_0111"
+(* Zero Padding still adds zeros to fill up the sapce *)
+# Pp_Bin.make_to_string ~zero_special:true ~min_width:9 () 0;;
+- : string = "0000_0000"
+# Pp_Bin.make_to_string ~zero_special:true ~min_width:9 () 0b110111;;
+- : string = "0b11_0111"
+```
+
+# Printing Binary Ints in the REPL
+
+```ocaml
+# #use "topfind";;
+# #require "pp-binary-ints";;
+# #install_printer Pp_binary_ints.Int.pp_int;;
+# 0;;
+- : int = 0b0
+# 7;;
+- : int = 0b111
+```
+
+
+You can also add the following to your `.ocamlinit` file so that integers are
+always printed using this library.
+
+```ocaml
+#use "topfind";;
+#require "pp-binary-ints";;
+#install_printer Pp_binary_ints.Int.pp_int;;
+#install_printer Pp_binary_ints.Int32.pp_int;;
+#install_printer Pp_binary_ints.Int64.pp_int;;
+#install_printer Pp_binary_ints.Nativeint.pp_int;;
 ```

dune-project

@@ -7,7 +7,7 @@
 (maintainers "Ifaz Kabir")
 (source (github ifazk/pp-binary-ints))
 (documentation https://ifazk.github.io/pp-binary-ints/)
-(version 0.1.1)
+(version 1.0.0)
 
 (package
  (name pp-binary-ints)

lib/Flags.ml

@@ -4,19 +4,28 @@ type padding =
   | Zeros
 
 type zero_printing =
-  | OCaml (* depends on padding setting: bunch of zeros (no separators, no prefixs), or space padding on the left or right *)
+  | OCaml (* depends on padding setting: no prefixes for zero padding, or space padding on the left or right *)
   | InheritNonZero
 
 type flags =
   { padding: padding
   ; separators: bool
   ; prefix_non_zero: bool
+  ; suffix : bool
   ; zero_printing: zero_printing
   }
 
 let default =
-  { padding = Right
-  ; separators =  false
-  ; prefix_non_zero =  false
-  ; zero_printing = OCaml
+  { padding = Zeros
+  ; separators =  true
+  ; prefix_non_zero = true
+  ; suffix = true
+  ; zero_printing = InheritNonZero
   }
+
+let make_flags ?(zero_padding = true) ?(left_padding=false) ?(separators=true)
+    ?(prefix=true) ?(suffix=true) ?(zero_special=false) () =
+  let padding = if zero_padding then Zeros else (if left_padding then Left else Right) in
+  let prefix_non_zero = prefix in
+  let zero_printing = if zero_special then OCaml else InheritNonZero in
+  { padding; separators; prefix_non_zero; suffix; zero_printing }

lib/Flags.mli

@@ -13,9 +13,22 @@ type flags = {
   padding : padding;
   separators : bool;
   prefix_non_zero : bool;
+  suffix : bool;
   zero_printing : zero_printing;
 }
 (** [flags] are passed to pretty printing functions to customize the output. *)
 
 val default : flags
 (** A default set of flags. *)
+
+val make_flags : ?zero_padding:bool -> ?left_padding:bool -> ?separators:bool -> ?prefix:bool -> ?suffix:bool -> ?zero_special:bool -> unit -> flags
+(** A function for creating flags. The [left_padding] prameter is ignored if
+    [zero_padding] is set to [true]. The default values are as follows.
+{ul {- [zero_padding=true]}
+    {- [left_padding=false]}
+    {- [separators=true]}
+    {- [prefix=true]}
+    {- [suffix=true]}
+    {- [zero_special=false]}
+}
+*)

lib/index.mld

@@ -10,9 +10,11 @@ The library provides four main functions.
 
 {ul
 {- {!module-Pp_binary_ints.module-Int.val-to_string} converts ints to strings.}
-{- {!module-Pp_binary_ints.module-Int.val-to_string_with} converts ints to strings, customizing the output with the [~flags] and [~min_width] named arguments.}
+{- {!module-Pp_binary_ints.module-Int.val-make_to_string} converts ints to strings, customizing the output with the optional arguments.}
 {- {!module-Pp_binary_ints.module-Int.val-pp_int} is a simple {!module-Format} module style pretty printer.}
-{- {!module-Pp_binary_ints.module-Int.val-pp_binary_int} is a customizable {!module-Format} module style pretty printer which takes in named arguments [~flags] and [~min_width].}
+{- {!module-Pp_binary_ints.module-Int.val-make_pp_int} is a customizable {!module-Format} pretty printer with the customization controlled by the optional arguments.}
+{- {!module-Pp_binary_ints.module-Int.val-to_string_with} is a lower level function converts ints to strings, customizing the output with the [~flags] and [~min_width] named arguments.}
+{- {!module-Pp_binary_ints.module-Int.val-pp_int_with} is a lower level customizable {!module-Format} module style pretty printer which takes in named arguments [~flags] and [~min_width].}
 }
 
 The options to customize the outputs can be found in {!module-Pp_binary_ints.Flags}.
@@ -25,66 +27,87 @@ the following modules.
     {- {!module-Pp_binary_ints.module-Nativeint}}
 }
 
+The following demonstrates using the library in a toplevel/REPL.
+
 {2 Basic use}
 
 {[
 # #require "pp-binary-ints";;
 # module Pp_Bin = Pp_binary_ints.Int;;
 # Pp_Bin.to_string 0b110111;;
-- : string = "110111"
+- : string = "0b11_0111"
 # Pp_Bin.to_string 0o777;;
-- : string = "111111111"
+string = "0b1_1111_1111"
 # Pp_Bin.to_string 1234;;
-- : string = "10011010010"
+- : string = "0b100_1101_0010"
 ]}
 
 {2 Customizing padding and minimum width}
 
 {[
 # #require "pp-binary-ints";;
 # module Pp_Bin = Pp_binary_ints.Int;;
-# (* Zero Padding *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with padding = Zeros } ~min_width:13 0b110111;;
-- : string = "0000000110111"
-# (* Default is space padding on the right *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.default ~min_width:13 0b110111;;
-- : string = "110111       "
+# (* Space Padding *);;
+# Pp_Bin.make_to_string ~zero_padding:false ~min_width:13 () 0b110111;;
+- : string = "0b11_0111    "
 # (* Space padding on the left is also possible *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with padding = Left} ~min_width:13 0b110111;;
-- : string = "       110111"
+# Pp_Bin.make_to_string ~zero_padding:false ~left_padding:true ~min_width:13 () 0b110111;;
+- : string = "    0b11_0111"
 ]}
 
 {2 Separators and prefixes}
 
 {[
-# (* Separate every 4 digits with _ *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with separators = true } ~min_width:1 0b110111;;
-- : string = "11_0111"
-# (* Prefix non-zero *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with prefix_non_zero = true } ~min_width:1 0b110111;;
+# (* Turn off _ separators *);;
+# Pp_Bin.make_to_string ~separators:false ~min_width:1 () 0b110111;;
 - : string = "0b110111"
-# (* Prefix non-zero with separators *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with prefix_non_zero = true; separators = true } ~min_width:1 0b110111;;
-- : string = "0b11_0111"
+# (* Turn off prefixes *);;
+# Pp_Bin.make_to_string ~prefix:false ~min_width:1 () 0b110111;;
+- : string = "11_0111"
+# (* Turn off both separatorns and prefixes *);;
+# Pp_Bin.make_to_string ~separators:false ~prefix:false ~min_width:1 () 0b110111;;
+- : string = "110111"
 ]}
 
 {2 Zero printing behaviour}
 
-We support pretty printing `0` (zero) both how OCaml's `Printf` woould print it,
-as well as printing it similar to how we print non zero integers. The default
-behaviour is to follow [Printf]'s zero printing and not print a prefix, but this
-can be changed by setting the [zero_printing] flag to [InheritNonZero].
+You can ask the library to treat [0] (zero) specially and not add a prefix to
+it. While it won't add a prefix to it, padding will still be added.
 
 {[
-# (* Prefix's are not added to zero by default *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with prefix_non_zero = true } ~min_width:1 0;;
+# (* Don't prefix zero *);;
+# Pp_Bin.make_to_string ~zero_special:true ~min_width:1 () 0;;
 - : string = "0"
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ default with prefix_non_zero = true; zero_printing = InheritNonZero } ~min_width:1 0;;
-- : string = "0b0"
-# (* All the above options can be combined *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ padding = Zeros; separators = true; prefix_non_zero = true; zero_printing = InheritNonZero } ~min_width:8 0;;
-- : string = "0b0_0000"
-# (* The library is careful not to write "0b_" when prefixing, 'b' is always followed by a digit *);;
-# Pp_Bin.to_string_with ~flags:Pp_Bin.Flags.{ padding = Zeros; separators = true; prefix_non_zero = true; zero_printing = InheritNonZero } ~min_width:7 0;;
-- : string = "0b00000"
+# Pp_Bin.make_to_string ~zero_special:true ~min_width:1 () 0b110111;;
+- : string = "0b11_0111"
+(* Zero Padding still adds zeros to fill up the sapce *)
+# Pp_Bin.make_to_string ~zero_special:true ~min_width:9 () 0;;
+- : string = "0000_0000"
+# Pp_Bin.make_to_string ~zero_special:true ~min_width:9 () 0b110111;;
+- : string = "0b11_0111"
+]}
+
+{1 Printing Binary Ints in the REPL}
+
+{[
+# #use "topfind";;
+# #require "pp-binary-ints";;
+# #install_printer Pp_binary_ints.Int.pp_int;;
+# 0;;
+- : int = 0b0
+# 7;;
+- : int = 0b111
+]}
+
+
+You can also add the following to your [.ocamlinit] file so that integers are
+always printed using this library.
+
+{[
+#use "topfind";;
+#require "pp-binary-ints";;
+#install_printer Pp_binary_ints.Int.pp_int;;
+#install_printer Pp_binary_ints.Int32.pp_int;;
+#install_printer Pp_binary_ints.Int64.pp_int;;
+#install_printer Pp_binary_ints.Nativeint.pp_int;;
 ]}