diff --git a/docs/examples/Document.lbf b/docs/examples/Document.lbf index 8393ed08..72ef796b 100644 --- a/docs/examples/Document.lbf +++ b/docs/examples/Document.lbf @@ -1,5 +1,8 @@ module Document +-- Importing types +import Prelude (Text, List, Set, Bytes) + -- Author sum Author = Ivan | Jovan | Savo @@ -9,7 +12,7 @@ sum Reviewer = Bob | Alice -- Document record Document a = { author : Author, - reviewers : List Reviewer, + reviewers : Set Reviewer, content : Chapter a } @@ -20,29 +23,7 @@ record Chapter a = { } -- Some actual content -sum RichContent = Image Image String | Gif Gif String | Text String - -sum Image = FunnyImage | BoringImage - -sum Gif = FunnyGif | InspiringGif +sum RichContent = Image Bytes | Gif Bytes | Text Text -- Rich document - prod RichDocument = (Document RichContent) - --- # Some basic types - --- ## We need a list type -sum List a = Nil | Cons a (List a) - --- ## We need a Char type that is either a letter, number or punctuation -sum Char = Letter Letter | Number Number | Punctuation Punctuation - -sum Letter = A | B | C - -sum Number = Num0 | Num1 | Num2 - -sum Punctuation = Dot | Question - --- ## String -prod String = (List Char) \ No newline at end of file diff --git a/docs/haskell.md b/docs/haskell.md index b8a4f643..73ea913d 100644 --- a/docs/haskell.md +++ b/docs/haskell.md @@ -3,32 +3,30 @@ Let's take a look at how LambdaBuffers modules map into Haskell modules and how LambdaBuffers type definitions map into Haskell type definitions. -Note that in this chapter we work with a 'pure' LambdaBuffers module, no -`opaque`s or type clasess, to demonstrate how pure type definition mapping -works. - -We'll use the `lbf-to-haskell` CLI tool which is just a convenient wrapper over +We'll use the `lbf-prelude-to-haskell` CLI tool which is just a convenient wrapper over the raw `lbf` CLI. We can get this tool by either loading the LambdaBuffers Nix environment that comes packaged with all the CLI tools: ```shell $ nix develop github:mlabs-haskell/lambda-buffers#lb -$ lb -lbc lbf lbg lbg-purescript lbg-haskelll lbf-to-purescript lbf-to-haskell +$ lbf +lbf lbf-plutus-to-purescript lbf-prelude-to-purescript +lbf-plutus-to-haskell lbf-prelude-to-haskell ``` -Or we can simply just refer directly to the `lbf-to-haskell` CLI by `nix run -github:mlabs-haskell/lambda-buffers#lbf-to-haskell`. +Or we can simply just refer directly to the `lbf-prelude-to-haskell` CLI by `nix run +github:mlabs-haskell/lambda-buffers#lbf-prelude-to-haskell`. In this chapter, we're going to use the latter option. -Let's now use `lbf-to-haskell` to process the - -[Document.lbf](examples/Document.lbf) schema +Let's now use `lbf-prelude-to-haskell` to process the [Document.lbf](examples/Document.lbf) schema. ```purescript module Document +-- Importing types +import Prelude (Text, List, Set, Bytes) + -- Author sum Author = Ivan | Jovan | Savo @@ -38,7 +36,7 @@ sum Reviewer = Bob | Alice -- Document record Document a = { author : Author, - reviewers : List Reviewer, + reviewers : Set Reviewer, content : Chapter a } @@ -49,43 +47,19 @@ record Chapter a = { } -- Some actual content -sum RichContent = Image Image String | Gif Gif String | Text String - -sum Image = FunnyImage | BoringImage - -sum Gif = FunnyGif | InspiringGif +sum RichContent = Image Bytes | Gif Bytes | Text Text -- Rich document - prod RichDocument = (Document RichContent) - --- # Some basic types - --- ## We need a list type -sum List a = Nil | Cons a (List a) - --- ## We need a Char type that is either a letter, number or punctuation -sum Char = Letter Letter | Number Number | Punctuation Punctuation - -sum Letter = A | B | C - -sum Number = Num0 | Num1 | Num2 - -sum Punctuation = Dot | Question - --- ## String -prod String = (List Char) ``` ```shell -$ nix run github:mlabs-haskell/lambda-buffers#lbf-to-haskell -- Document.lbf +$ nix run github:mlabs-haskell/lambda-buffers#lbf-prelude-to-haskell -- Document.lbf $ find autogen/ autogen/ -autogen/build.json autogen/LambdaBuffers autogen/LambdaBuffers/Document.hs -$ ghc autogen/LambdaBuffers/Document.hs -[1 of 1] Compiling LambdaBuffers.Document ( autogen/LambdaBuffers/Document.hs, autogen/LambdaBuffers/Document.o ) +autogen/build.json ``` As we can see the `autogen` directory has been created that contains the generated Haskell modules. @@ -94,90 +68,57 @@ Note the `autogen/build.json` file as it contains all the necessary Hackage depe The outputted Haskell module in `autogen/LambdaBuffers/Document.hs`: ```haskell -module LambdaBuffers.Document - ( Author (..), - Chapter (..), - Char (..), - Document (..), - Gif (..), - Image (..), - Letter (..), - List (..), - Number (..), - Punctuation (..), - Reviewer (..), - RichContent (..), - RichDocument (..), - String (..), - ) -where - +module LambdaBuffers.Document (Author(..) + , Chapter(..) + , Document(..) + , Reviewer(..) + , RichContent(..) + , RichDocument(..)) where + +import qualified LambdaBuffers.Prelude import qualified Prelude -data Author = Author'Ivan | Author'Jovan | Author'Savo deriving (Prelude.Show) - -data Chapter a = Chapter - { chapter'content :: a, - chapter'subChapters :: List (Chapter a) - } - deriving (Prelude.Show) - -data Char - = Char'Letter Letter - | Char'Number Number - | Char'Punctuation Punctuation - deriving (Prelude.Show) - -data Document a = Document - { document'author :: Author, - document'reviewers :: List Reviewer, - document'content :: Chapter a - } - deriving (Prelude.Show) -data Gif = Gif'FunnyGif | Gif'InspiringGif deriving (Prelude.Show) +data Author = Author'Ivan | Author'Jovan | Author'Savo deriving Prelude.Show -data Image = Image'FunnyImage | Image'BoringImage deriving (Prelude.Show) +data Chapter a = Chapter { chapter'content :: a + , chapter'subChapters :: LambdaBuffers.Prelude.List (Chapter a)} deriving Prelude.Show -data Letter = Letter'A | Letter'B | Letter'C deriving (Prelude.Show) +data Document a = Document { document'author :: Author + , document'reviewers :: LambdaBuffers.Prelude.Set Reviewer + , document'content :: Chapter a} deriving Prelude.Show -data List a = List'Nil | List'Cons a (List a) deriving (Prelude.Show) +data Reviewer = Reviewer'Bob | Reviewer'Alice deriving Prelude.Show -data Number = Number'Num0 | Number'Num1 | Number'Num2 deriving (Prelude.Show) +data RichContent = RichContent'Image LambdaBuffers.Prelude.Bytes + | RichContent'Gif LambdaBuffers.Prelude.Bytes + | RichContent'Text LambdaBuffers.Prelude.Text deriving Prelude.Show -data Punctuation - = Punctuation'Dot - | Punctuation'Question - deriving (Prelude.Show) - -data Reviewer = Reviewer'Bob | Reviewer'Alice deriving (Prelude.Show) - -data RichContent - = RichContent'Image Image String - | RichContent'Gif Gif String - | RichContent'Text String - deriving (Prelude.Show) +newtype RichDocument = RichDocument (Document RichContent) deriving Prelude.Show +``` -newtype RichDocument = RichDocument (Document RichContent) deriving (Prelude.Show) +We can compile the code with the following commands. +Note the dev shell `dev-prelude-haskell` as it includes the `LambdaBuffers.Prelude` dependency. -newtype String = String (List Char) deriving (Prelude.Show) +```shell +$ nix develop github:mlabs-haskell/lambda-buffers#dev-prelude-haskell +$ ghc autogen/LambdaBuffers/Document.hs +[1 of 1] Compiling LambdaBuffers.Document ( autogen/LambdaBuffers/Document.hs, autogen/LambdaBuffers/Document.o ) ``` ## Sum types -The types `Author`, `Reviewer`, `RichContent`, `Image`, `Gif`, `List`, `Char`, -`Letter`, `Number` and `Punctuation` have been declared as sum types in the -LamdaBuffers schema using the `sum` keyword. +The types `Author`, `Reviewer`, and `RichContent` have been declared as sum types in the LamdaBuffers schema using the `sum` keyword. -As we can see, notihing too surprising here, all the `sum` types become `data` -in haskell. +As we can see, nothing too surprising here, all the `sum` types become `data` +in Haskell. The only thing to notice is that the type name was prepended with `'` (single quote) to the defined constructor names as to make sure they are unique. ## Product types -The types `RichDocument` and `String` have been declared as product types in the +The type `RichDocument` have been declared as a product type in the LamdaBuffers schema using the `prod` keyword. They become Haskell `newtype` if they have a single type in their body, otherwise they are `data`. @@ -195,4 +136,4 @@ type in their body, otherwise they are `data`. Also like with product types, the constructor has the same name as the type. The field names, similar to sum constructor names, are prepended with the -lowercased named of the type with a single quote (`'`) to maintain uniqueness. +lowercased name of the type with a single quote (`'`) to maintain uniqueness. diff --git a/docs/purescript.md b/docs/purescript.md index 20b207fc..c45535bb 100644 --- a/docs/purescript.md +++ b/docs/purescript.md @@ -3,32 +3,30 @@ Let's take a look at how LambdaBuffers modules map into Purescript modules and how LambdaBuffers type definitions map into Purescript type definitions. -Note that in this chapter we work with a 'pure' LambdaBuffers module, no -`opaque`s or type clasess, to demonstrate how pure type definition mapping -works. - -We'll use the `lbf-to-purescript` CLI tool which is just a convenient wrapper over +We'll use the `lbf-prelude-to-purescript` CLI tool which is just a convenient wrapper over the raw `lbf` CLI. We can get this tool by either loading the LambdaBuffers Nix environment that comes packaged with all the CLI tools: ```shell -$ nix develop github:mlabs-purescript/lambda-buffers#lb -$ lb -lbc lbf lbg lbg-purescript lbg-haskelll lbf-to-purescript lbf-to-haskell +$ nix develop github:mlabs-haskell/lambda-buffers#lb +$ lbf +lbf lbf-plutus-to-purescript lbf-prelude-to-purescript +lbf-plutus-to-haskell lbf-prelude-to-haskell ``` -Or we can simply just refer directly to the `lbf-to-purescript` CLI by `nix run -github:mlabs-purescript/lambda-buffers#lbf-to-purescript`. +Or we can simply just refer directly to the `lbf-prelude-to-purescript` CLI by `nix run +github:mlabs-haskell/lambda-buffers#lbf-prelude-to-purescript`. In this chapter, we're going to use the latter option. -Let's now use `lbf-to-purescript` to process the - -[Document.lbf](examples/Document.lbf) schema +Let's now use `lbf-prelude-to-purescript` to process the [Document.lbf](examples/Document.lbf) schema ```purescript module Document +-- Importing types +import Prelude (Text, List, Set, Bytes) + -- Author sum Author = Ivan | Jovan | Savo @@ -38,7 +36,7 @@ sum Reviewer = Bob | Alice -- Document record Document a = { author : Author, - reviewers : List Reviewer, + reviewers : Set Reviewer, content : Chapter a } @@ -49,36 +47,14 @@ record Chapter a = { } -- Some actual content -sum RichContent = Image Image String | Gif Gif String | Text String - -sum Image = FunnyImage | BoringImage - -sum Gif = FunnyGif | InspiringGif +sum RichContent = Image Bytes | Gif Bytes | Text Text -- Rich document - prod RichDocument = (Document RichContent) - --- # Some basic types - --- ## We need a list type -sum List a = Nil | Cons a (List a) - --- ## We need a Char type that is either a letter, number or punctuation -sum Char = Letter Letter | Number Number | Punctuation Punctuation - -sum Letter = A | B | C - -sum Number = Num0 | Num1 | Num2 - -sum Punctuation = Dot | Question - --- ## String -prod String = (List Char) ``` ```shell -$ nix run github:mlabs-purescript/lambda-buffers#lbf-to-purescript -- Document.lbf +$ nix run github:mlabs-haskell/lambda-buffers#lbf-prelude-to-purescript -- Document.lbf $ find autogen/ autogen/ autogen/build.json @@ -94,89 +70,46 @@ The outputted Purescript module in `autogen/LambdaBuffers/Document.hs`: ```purescript module LambdaBuffers.Document (Author(..) , Chapter(..) - , Char(..) , Document(..) - , Gif(..) - , Image(..) - , Letter(..) - , List(..) - , Number(..) - , Punctuation(..) , Reviewer(..) , RichContent(..) - , RichDocument(..) - , String(..)) where + , RichDocument(..)) where +import LambdaBuffers.Prelude as LambdaBuffers.Prelude import Data.Generic.Rep as Data.Generic.Rep import Data.Newtype as Data.Newtype import Data.Show as Data.Show import Data.Show.Generic as Data.Show.Generic -data Author = Author'Ivan | Author'Jovan | Author'Savo +data Author = Author'Ivan | Author'Jovan | Author'Savo derive instance Data.Generic.Rep.Generic Author _ instance Data.Show.Show Author where show = Data.Show.Generic.genericShow -newtype Chapter a = Chapter { content :: a, subChapters :: List (Chapter a)} +newtype Chapter a = Chapter { content :: a + , subChapters :: LambdaBuffers.Prelude.List (Chapter a)} derive instance Data.Newtype.Newtype (Chapter a) _ derive instance Data.Generic.Rep.Generic (Chapter a) _ instance (Data.Show.Show a) => Data.Show.Show (Chapter a) where show = Data.Show.Generic.genericShow -data Char = Char'Letter Letter - | Char'Number Number - | Char'Punctuation Punctuation -derive instance Data.Generic.Rep.Generic Char _ -instance Data.Show.Show Char where - show = Data.Show.Generic.genericShow - newtype Document a = Document { author :: Author - , reviewers :: List Reviewer + , reviewers :: LambdaBuffers.Prelude.Set Reviewer , content :: Chapter a} derive instance Data.Newtype.Newtype (Document a) _ derive instance Data.Generic.Rep.Generic (Document a) _ instance (Data.Show.Show a) => Data.Show.Show (Document a) where show = Data.Show.Generic.genericShow -data Gif = Gif'FunnyGif | Gif'InspiringGif -derive instance Data.Generic.Rep.Generic Gif _ -instance Data.Show.Show Gif where - show = Data.Show.Generic.genericShow - -data Image = Image'FunnyImage | Image'BoringImage -derive instance Data.Generic.Rep.Generic Image _ -instance Data.Show.Show Image where - show = Data.Show.Generic.genericShow - -data Letter = Letter'A | Letter'B | Letter'C -derive instance Data.Generic.Rep.Generic Letter _ -instance Data.Show.Show Letter where - show = Data.Show.Generic.genericShow - -data List a = List'Nil | List'Cons a (List a) -derive instance Data.Generic.Rep.Generic (List a) _ -instance (Data.Show.Show a) => Data.Show.Show (List a) where - show = Data.Show.Generic.genericShow - -data Number = Number'Num0 | Number'Num1 | Number'Num2 -derive instance Data.Generic.Rep.Generic Number _ -instance Data.Show.Show Number where - show = Data.Show.Generic.genericShow - -data Punctuation = Punctuation'Dot | Punctuation'Question -derive instance Data.Generic.Rep.Generic Punctuation _ -instance Data.Show.Show Punctuation where - show = Data.Show.Generic.genericShow - -data Reviewer = Reviewer'Bob | Reviewer'Alice +data Reviewer = Reviewer'Bob | Reviewer'Alice derive instance Data.Generic.Rep.Generic Reviewer _ instance Data.Show.Show Reviewer where show = Data.Show.Generic.genericShow -data RichContent = RichContent'Image Image String - | RichContent'Gif Gif String - | RichContent'Text String +data RichContent = RichContent'Image LambdaBuffers.Prelude.Bytes + | RichContent'Gif LambdaBuffers.Prelude.Bytes + | RichContent'Text LambdaBuffers.Prelude.Text derive instance Data.Generic.Rep.Generic RichContent _ instance Data.Show.Show RichContent where show = Data.Show.Generic.genericShow @@ -186,21 +119,13 @@ derive instance Data.Newtype.Newtype RichDocument _ derive instance Data.Generic.Rep.Generic RichDocument _ instance Data.Show.Show RichDocument where show = Data.Show.Generic.genericShow - -newtype String = String (List Char) -derive instance Data.Newtype.Newtype String _ -derive instance Data.Generic.Rep.Generic String _ -instance Data.Show.Show String where - show = Data.Show.Generic.genericShow ``` ## Sum types -The types `Author`, `Reviewer`, `RichContent`, `Image`, `Gif`, `List`, `Char`, -`Letter`, `Number` and `Punctuation` have been declared as sum types in the -LamdaBuffers schema using the `sum` keyword. +The types `Author`, `Reviewer`, and `RichContent` have been declared as sum types in the LamdaBuffers schema using the `sum` keyword. -As we can see, notihing too surprising here, all the `sum` types become `data` +As we can see, nothing too surprising here, all the `sum` types become `data` in Purescript. The only thing to notice is that the type name was prepended with `'` (single @@ -208,7 +133,7 @@ quote) to the defined constructor names as to make sure they are unique. ## Product types -The types `RichDocument` and `String` have been declared as product types in the +The type `RichDocument` have been declared as a product type in the LamdaBuffers schema using the `prod` keyword. They become Purescript `newtype` if they have a single type in their body, otherwise they are `data`.