git.iko.soy/rowtype-yoga/purescript-protobuf
on master help sign in
Some cleanup and comments.
commit1b6e29cccb762a85939c9d7d8160042fdbe8e0ef authorJames Brock <jamesbrock@gmail.com> dateSat 13 Mar 2021, 15:18 (6 years ago) parentd2b03ab
5 files changed+25−23
compare with master
unifiedsplit
README.md+22−9 default.nix−1 nix/pkgs.nix−10 src/Protobuf/Library.purs+1−1 src/Protobuf/Runtime.purs+2−2
README.md+22−9
@@ -63,10 +63,16 @@ To generate Purescript .purs files from .proto files, run:
6363[nix-shell]$
6464```
6565
66−If you don't want to use Nix, then install the Purescript toolchain and *protoc*.
66+If you don't want to use Nix, then install the Purescript toolchain and `protoc`,
67+and add the executable script
68+[`bin/protoc-gen-purescript`](bin/protoc-gen-purescript)
69+to your `PATH`.
6770
6871## Writing programs with the generated code
6972
73+The code generator will use the `package` import statement in the `.proto` file
74+and the base `.proto` file name as the Purescript module name for that file.
75+
7076A message in a `shapes.proto` file declared as
7177
7278```
@@ -78,7 +84,8 @@ message Rectangle {
7884}
7985```
8086
81−will export these four names in a generated `shapes.Interproc.purs` file.
87+will export these four names from module `Interproc.Shapes` in a
88+generated `shapes.Interproc.purs` file.
8289
83901. A message data type
8491
@@ -86,6 +93,9 @@ will export these four names in a generated `shapes.Interproc.purs` file.
8693 newtype Rectangle = Rectangle { width :: Maybe Number, height :: Maybe Number }
8794 ```
8895
96+ The message data type will also include an `__unknown_fields` field which
97+ is required for conformance.
98+
89992. A message maker which constructs a message from a `Record`
90100 with some message fields
91101
@@ -93,7 +103,11 @@ will export these four names in a generated `shapes.Interproc.purs` file.
93103 mkRectangle :: forall r. Record r -> Rectangle
94104 ```
95105
96− All message fields are optional, and can be omitted from the `Record`. If we want the compiler to check that we've explicitly supplied all the fields,
106+ All message fields are optional, and can be elided when making a message.
107+ There are some extra type constraints, not shown here, which will cause a
108+ compiler error if we try to add a field which is not in the message data type.
109+
110+ If we want the compiler to check that we've explicitly supplied all the fields,
97111 then we can use the ordinary message data type constructor.
98112
991133. A message encoder which works with
@@ -235,10 +249,7 @@ The path to the protobuf definition which failed to parse will be included
235249in the `ParseError String` and delimited by `'/'`, something
236250like `"Message1 / string_field_1 / Invalid UTF8 encoding."`.
237251
238−### Imports
239−
240−The code generator will use the `package` statement in the `.proto` file
241−and the base file name as the Purescript module name for that file.
252+### Protobuf Imports
242253
243254The Protobuf
244255[`import`](https://developers.google.com/protocol-buffers/docs/proto3#importing_definitions)
@@ -251,10 +262,12 @@ statement in the imported file.
251262
252263For that reason, we can only use top-level
253264(not [nested](https://developers.google.com/protocol-buffers/docs/proto3#nested))
254−`message` and `enum` types from an `import`.
265+`message` and `enum` types from a Protobuf `import`.
266+
267+### PureScript Imports
255268
256269The generated Purescript code will usually have module imports which cause
257−the `purs` compiler to emit warnings. Sorry.
270+the `purs` compiler to emit warnings. We beg your pardon.
258271
259272## Nix derivation
260273
default.nix−1
@@ -44,7 +44,6 @@ pkgs.stdenv.mkDerivation {
4444 install-spago-style
4545 '';
4646 buildPhase = ''
47− ls -la .spago/unsafe-coerce
4847 build-spago-style "./src/**/*.purs"
4948 '';
5049 installPhase = ''
nix/pkgs.nix−10
@@ -1,5 +1,4 @@
11# https://nixos.org/guides/towards-reproducibility-pinning-nixpkgs.html
2−# { pkgs ? import <nixpkgs> { } }:
32{ pkgs ? import (builtins.fetchTarball {
43 url = "https://github.com/NixOS/nixpkgs/archive/20.03.tar.gz";
54 sha256 = "0182ys095dfx02vl2a20j1hz92dx3mfgz2a6fhn31bqlp1wa8hlq";
@@ -11,24 +10,15 @@ let
1110 (builtins.fetchGit {
1211 url = "https://github.com/justinwoo/easy-purescript-nix.git";
1312 rev = "1ec689df0adf8e8ada7fcfcb513876307ea34226";
14− # (pkgs.fetchFromGitHub {
15− # owner = "justinwoo";
16− # repo = "easy-purescript-nix";
17− # rev = "1ec689df0adf8e8ada7fcfcb513876307ea34226";
18− # sha256 = "12hk2zbjkrq2i5fs6xb3x254lnhm9fzkcxph0a7ngxyzfykvf4hi";
1913 }) { inherit pkgs; };
2014
2115 spago2nix = import (builtins.fetchGit {
22− #url = "git@github.com:justinwoo/spago2nix.git";
23− #rev = "22bd974ec44c98d2831c31f4f4402a9afa8aecea";
24− # url = "git@github.com:xc-jp/spago2nix.git";
2516 url = "https://github.com/xc-jp/spago2nix.git";
2617 ref = "ls-transitive";
2718 rev = "1e65ec78def30b9c10bfc165cfb5f3b1c42bbd80";
2819 }) { inherit pkgs; };
2920
3021 node2nix = import (builtins.fetchGit {
31− # url = "git@github.com:svanderburg/node2nix.git";
3222 url = "https://github.com/svanderburg/node2nix.git";
3323 rev = "c6cc7edc7c180ef01f23bc2aff31a1cbb5524b0d";
3424 }) { inherit pkgs; };
src/Protobuf/Library.purs+1−1
@@ -9,7 +9,7 @@ module Protobuf.Library
99where
1010
1111import Protobuf.Common (Bytes(..))
12−import Protobuf.Runtime (label)
12+import Protobuf.Runtime (label, UnknownField(..))
1313import Text.Parsing.Parser (ParserT, fail)
1414import Control.Monad.Except (ExceptT, runExceptT)
1515import Control.Monad (class Monad, (>>=), pure)
src/Protobuf/Runtime.purs+2−2
@@ -4,7 +4,7 @@
44-- | See package README for explanation.
55module Protobuf.Runtime
66( parseMessage
7−, UnknownField
7+, UnknownField(..)
88, parseFieldUnknown
99, putFieldUnknown
1010, parseLenDel
@@ -255,4 +255,4 @@ parseEnum = do
255255-- | to the error `String` in the `ParseError`.
256256label :: forall m s a. Monad m => String -> ParserT s m a -> ParserT s m a
257257label messagePrefix p = catchError p $ \ (ParseError message pos) ->
258− throwError $ ParseError (messagePrefix <> message) pos
258+ throwError $ ParseError (messagePrefix <> message) pos