Prepare for 0.2.2 release. Update names of Pastel.parse and Pastel.apply to be prefixed by unstable to reflect their currently experimental nature

pastel.json

@@ -1,6 +1,6 @@
 {
   "name": "@reason-native/pastel",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Native Reason ANSI terminal styling with an awesome API",
   "author": "Facebook Engineering",
   "homepage": "https://reason-native.com",

src/pastel/Pastel.rei

@@ -117,41 +117,48 @@ let createElement:
   ) =>
   string;
 
-  type style;
-  let emptyStyle: style;
-
-  let withColor: (ColorName.colorName, style) => style;
-  let resetColor: style => style;
-  let withBackgroundColor: (ColorName.colorName, style) => style;
-  let resetBackgroundColor: style => style;
-
-  let setBold: (bool, style) => style;
-  let withBold: style => style;
-  let setDim: (bool, style) => style;
-  let withDim: style => style;
-  let setItalic: (bool, style) => style;
-  let withItalic: style => style;
-  let setUnderline: (bool, style) => style;
-  let withUnderline: style => style;
-  let setInverse: (bool, style) => style;
-  let withInverse: style => style;
-  let setHidden: (bool, style) => style;
-  let withHidden: style => style;
-  let setStrikethrough: (bool, style) => style;
-  let withStrikethrough: style => style;
-  let withReset: style => style;
-  let setReset: (bool, style) => style;
-
-  let getColor: style => option(ColorName.colorName);
-  let getBackgroundColor: style => option(ColorName.colorName);
-  let isBold: style => bool;
-  let isDim: style => bool;
-  let isItalic: style => bool;
-  let isUnderline: style => bool;
-  let isInverse: style => bool;
-  let isHidden: style => bool;
-  let isStrikethrough: style => bool;
-  let isReset: style => bool;
-
-  let parse: string => list((style, string));
-  let apply: list((style, string)) => string;
+/** Pastel.style exposes a way to examine and manipulate the styles of existing text in
+   * order to perform additional formatting operations. This feature is intended to be used primarily
+   * by libraries (such as Frame). The style API itself is still subject to change until the parse/apply
+   * API is finalized, however it is extremely unlikely to change */
+type style;
+let emptyStyle: style;
+
+let withColor: (ColorName.colorName, style) => style;
+let resetColor: style => style;
+let withBackgroundColor: (ColorName.colorName, style) => style;
+let resetBackgroundColor: style => style;
+
+let setBold: (bool, style) => style;
+let withBold: style => style;
+let setDim: (bool, style) => style;
+let withDim: style => style;
+let setItalic: (bool, style) => style;
+let withItalic: style => style;
+let setUnderline: (bool, style) => style;
+let withUnderline: style => style;
+let setInverse: (bool, style) => style;
+let withInverse: style => style;
+let setHidden: (bool, style) => style;
+let withHidden: style => style;
+let setStrikethrough: (bool, style) => style;
+let withStrikethrough: style => style;
+let withReset: style => style;
+let setReset: (bool, style) => style;
+
+let getColor: style => option(ColorName.colorName);
+let getBackgroundColor: style => option(ColorName.colorName);
+let isBold: style => bool;
+let isDim: style => bool;
+let isItalic: style => bool;
+let isUnderline: style => bool;
+let isInverse: style => bool;
+let isHidden: style => bool;
+let isStrikethrough: style => bool;
+let isReset: style => bool;
+/** These functions are considered unstable and are subject to change
+   * unstable_parse takes a (potentially stylized by Pastel) string, and breaks it into segments that share the same styles
+   * unstable_apply takes a list of stylized segments and constructs a string that correctly displays those styles
+  */
+let unstable_parse: string => list((style, string));
+let unstable_apply: list((style, string)) => string;

src/pastel/PastelFactory.re

@@ -339,6 +339,6 @@ module Make = (()) => {
       };
 
   let emptyStyle = StateMachine.initialState;
-  let parse = s => selectedImplementation^.parse(s);
-  let apply = parts => selectedImplementation^.apply(parts);
+  let unstable_parse = s => selectedImplementation^.parse(s);
+  let unstable_apply = parts => selectedImplementation^.apply(parts);
 };

src/pastel/PastelSig.re

@@ -82,8 +82,8 @@ module type PastelSig = {
   let isStrikethrough: style => bool;
   let isReset: style => bool;
 
-  let parse: string => list((style, string));
-  let apply: list((style, string)) => string;
+  let unstable_parse: string => list((style, string));
+  let unstable_apply: list((style, string)) => string;
 
   let createElement:
     (

tests/__tests__/pastel/Parse_test.re

@@ -20,7 +20,7 @@ let runTestSuite = (mode, name) => {
                 "hello"
                 <Pastel color=Red> "world" </Pastel>
               </Pastel>;
-            let parts = Pastel.parse(input);
+            let parts = Pastel.unstable_parse(input);
             expect.int(List.length(parts)).toBe(2);
             let (firstStyle, firstText, secondStyle, secondText) =
               switch (parts) {
@@ -50,7 +50,7 @@ let runTestSuite = (mode, name) => {
                 <Pastel color=Red> "world" </Pastel>
                 <Pastel color=Blue> "and goodbye" </Pastel>
               </Pastel>;
-            let parts = Pastel.parse(input);
+            let parts = Pastel.unstable_parse(input);
 
             expect.int(List.length(parts)).toBe(3);
             let (
@@ -96,7 +96,7 @@ let runTestSuite = (mode, name) => {
                 "hello"
                 <Pastel color=Red> "world" </Pastel>
               </Pastel>;
-            let parts = Pastel.parse(input);
+            let parts = Pastel.unstable_parse(input);
 
             expect.int(List.length(parts)).toBe(2);
             let (firstRegion, secondRegion) =
@@ -108,11 +108,11 @@ let runTestSuite = (mode, name) => {
               | _ => raise(Invalid_argument("already verified length"))
               };
             let reconstructed =
-              Pastel.apply([
+              Pastel.unstable_apply([
                 (firstRegion, "goodbye"),
                 (secondRegion, "everybody"),
               ]);
-            let reconstructedParts = Pastel.parse(reconstructed);
+            let reconstructedParts = Pastel.unstable_parse(reconstructed);
 
             expect.int(List.length(reconstructedParts)).toBe(2);
             let (firstText, secondText) =
@@ -139,7 +139,7 @@ let runTestSuite = (mode, name) => {
                 "hello"
                 <Pastel color=Red> "world" </Pastel>
               </Pastel>;
-            let parts = Pastel.parse(input);
+            let parts = Pastel.unstable_parse(input);
 
             expect.int(List.length(parts)).toBe(2);
             let (firstRegion, secondRegion) =
@@ -151,12 +151,12 @@ let runTestSuite = (mode, name) => {
               | _ => raise(Invalid_argument("already verified length"))
               };
             let reconstructed =
-              Pastel.apply([
+              Pastel.unstable_apply([
                 (firstRegion, "goodbye"),
                 (Pastel.emptyStyle, "unstyled text!"),
                 (secondRegion, "everybody"),
               ]);
-            let reconstructedParts = Pastel.parse(reconstructed);
+            let reconstructedParts = Pastel.unstable_parse(reconstructed);
 
             expect.int(List.length(reconstructedParts)).toBe(3);
             let (firstText, secondText, thirdText, secondStyle) =
@@ -187,7 +187,7 @@ let runTestSuite = (mode, name) => {
                 "hello"
                 <Pastel color=Red> "world" </Pastel>
               </Pastel>;
-            let parts = Pastel.parse(input);
+            let parts = Pastel.unstable_parse(input);
             expect.int(List.length(parts)).toBe(2);
             let (firstStyle, firstText, secondStyle, secondText) =
               switch (parts) {
@@ -200,14 +200,14 @@ let runTestSuite = (mode, name) => {
               | _ => raise(Invalid_argument("already verified length"))
               };
             let result =
-              Pastel.apply([
+              Pastel.unstable_apply([
                 (firstStyle |> Pastel.withUnderline, firstText),
                 (
                   secondStyle |> Pastel.withDim |> Pastel.withColor(Magenta),
                   secondText,
                 ),
               ]);
-            let resultParts = Pastel.parse(result);
+            let resultParts = Pastel.unstable_parse(result);
             expect.int(List.length(resultParts)).toBe(2);
             let (firstStyle, firstText, secondStyle, secondText) =
               switch (resultParts) {
@@ -245,7 +245,7 @@ describe("disabled deconstruction", ({test}) => {
             "hello "
             <Pastel color=Red> "world" </Pastel>
           </Pastel>;
-        let parts = Pastel.parse(input);
+        let parts = Pastel.unstable_parse(input);
 
         expect.int(List.length(parts)).toBe(1);
         let (style, text) = List.hd(parts);
@@ -260,7 +260,7 @@ describe("disabled deconstruction", ({test}) => {
       Disabled,
       () => {
         let result =
-          Pastel.apply([
+          Pastel.unstable_apply([
             (Pastel.emptyStyle |> Pastel.withColor(Black), "hello "),
             (Pastel.emptyStyle |> Pastel.withHidden, "world"),
           ]);

tests/__tests__/pastel/Pastel_reset_test.re

@@ -11,22 +11,22 @@ describe("Pastel.reset", ({test}) => {
       HumanReadablePastel.(emptyStyle |> withReset),
       "hello",
     );
-    let result = HumanReadablePastel.apply([stateRegion]);
+    let result = HumanReadablePastel.unstable_apply([stateRegion]);
 
     expect.string(String.escaped(result)).toEqual("<reset>hello</reset>");
     ();
   });
   test("apply reset state terminal", ({expect}) => {
     let stateRegion = TerminalPastel.(emptyStyle |> withReset, "hello");
-    let result = TerminalPastel.apply([stateRegion]);
+    let result = TerminalPastel.unstable_apply([stateRegion]);
 
     expect.string(String.escaped(result)).toEqual("\\027[0mhello\\027[0m\\027[0m");
     ();
   });
   test("apply reset state with other state human readable", ({expect}) => {
     let result =
       HumanReadablePastel.(
-        apply([
+        unstable_apply([
           (emptyStyle |> withReset, "hello"),
           (emptyStyle |> withColor(Green), "world"),
         ])