Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Fix some README example problems, callout deep lists change. #41

Merged
merged 1 commit into from

2 participants

@seancribbs

Fixes #40

@seancribbs seancribbs was assigned
@russelldb russelldb was assigned
@russelldb
Owner

Read and did it. Works as advertised. +1

@seancribbs seancribbs merged commit 03618ad into master
@seancribbs seancribbs deleted the sdc-readme-corrections branch
@seancribbs seancribbs was assigned
@seancribbs seancribbs removed their assignment
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Mar 7, 2013
This page is out of date. Refresh to see the latest.
Showing with 30 additions and 5 deletions.
  1. +30 −5 README.markdown
View
35 README.markdown
@@ -10,7 +10,7 @@ make interfacing with the Protocol Buffers protocol easy.
Encoding is simple.
1> protobuffs:encode(1, 1, uint32).
- <<8,1>>
+ ["\b",[1]]
2> erlang:iolist_to_binary([
protobuffs:encode(1, <<"Nick">>, string),
protobuffs:encode(2, 25, uint32)
@@ -31,13 +31,20 @@ Decoding is simple too.
The main objective of this module is to allow developers to use .proto files
easily. This module provides very basic functionality to do so.
-Consider the `t/simple.proto` file.
+Consider the `test/erlang_protobuffs_SUITE_data/proto/simple.proto` file.
message Person {
required string name = 1;
required string address = 2;
required string phone_number = 3;
required int32 age = 4;
+ optional Location location = 5;
+ }
+
+ message Location
+ {
+ required string region = 1;
+ required string country = 2;
}
From that file we can create an Erlang module that can encode and decode the
@@ -46,14 +53,32 @@ Person message into records.
1> protobuffs_compile:scan_file("simple.proto").
ok
2> simple_pb:decode_person(<<10,4,78,105,99,107,18,13,77,111,...>>).
- {person,<<"Nick">>,<<"Mountain View">>, <<"+1 (000) 555-1234">>,25}
+ {person,<<"Nick">>,<<"Mountain View">>, <<"+1 (000) 555-1234">>,25,undefined}
3> simple_pb:encode_person({person, <<"Nick">>, <<"Mountain View">>,
- <<"+1 (000) 555-1234">>,25}).
- <<10,4,78,105,99,107,18,13,77,111,117,110,116,97,105,110,32,86,105,...>>
+ <<"+1 (000) 555-1234">>,25, undefined}).
+ [[["\n",[4],<<"Nick">>],
+ [[18],"\r",<<"Mountain View">>],
+ [[26],[17],<<"+1 (000) 555-1234">>],
+ [" ",[25]],
+ []]]
How cool is that? From .proto files, we create modules that export encode and
decode functions for the messages defined.
+## Deep lists
+
+You might have noticed that the examples above produce deep lists
+(also known as iolists), not binaries, when encoding messages. Since
+we assume most messages will be sent to another computer over the
+network or written to disk, we can delay flattening the encoding until
+the last instant, i.e. writing to the port that will send the message.
+All ports accept deep lists, so there's no reason to flatten them in
+our encoding or application code. If you absolutely must have a
+binary, use the `iolist_to_binary/1` BIF on the encoded message.
+
+Ref:
+[Erlang Efficiency Guide](http://www.erlang.org/doc/efficiency_guide/listHandling.html#id64578)
+
## no_debug_info
The protobuffs_compile module relies on the pokemon_pb module being compiled
Something went wrong with that request. Please try again.