tutorial/tutorial.thrift

   1 #!/usr/local/bin/thrift -cpp -java -py -php -rb -perl -erl -xsd -r
   2 #
   3 # Thrift Tutorial
   4 # Mark Slee (mcslee@facebook.com)
   5 #
   6 # This file aims to teach you how to use Thrift, in a .thrift file. Neato. The
   7 # first thing to notice is that .thrift files support standard shell comments.
   8 # This lets you make your thrift file executable and include your Thrift build
   9 # step on the top line. And you can place comments like this anywhere you like.
  10 #
  11 # Before running this file, you will need to have installed the thrift compiler
  12 # into /usr/local/bin.
  13
  14 /**
  15  * The first thing to know about are types. The available types in Thrift are:
  16  *
  17  *  bool        Boolean, one byte
  18  *  byte        Signed byte
  19  *  i16         Signed 16-bit integer
  20  *  i32         Signed 32-bit integer
  21  *  i64         Signed 64-bit integer
  22  *  double      64-bit floating point value
  23  *  string      String
  24  *  map<t1,t2>  Map from one type to another
  25  *  list<t1>    Ordered list of one type
  26  *  set<t1>     Set of unique elements of one type
  27  *
  28  * Did you also notice that Thrift supports C style comments?
  29  */
  30
  31 // Just in case you were wondering... yes. We support simple C comments too.
  32
  33 /**
  34  * Thrift files can reference other Thrift files to include common struct
  35  * and service definitions. These are found using the current path, or by
  36  * searching relative to any paths specified with the -I compiler flag.
  37  *
  38  * Included objects are accessed using the name of the .thrift file as a
  39  * prefix. i.e. shared.SharedObject
  40  */
  41 include "shared.thrift"
  42
  43 /**
  44  * Thrift files can namespace, package, or prefix their output in various
  45  * target languages.
  46  */
  47 cpp_namespace tutorial
  48 java_package tutorial
  49 php_namespace tutorial
  50 perl_package tutorial
  51 smalltalk_category Thrift-Tutorial
  52
  53 /**
  54  * Thrift lets you do typedefs to get pretty names for your types. Standard
  55  * C style here.
  56  */
  57 typedef i32 MyInteger
  58
  59 /**
  60  * Thrift also lets you define constants for use across languages. Complex
  61  * types and structs are specified using JSON notation.
  62  */
  63 const i32 INT32CONSTANT = 9853
  64 const map<string,string> MAPCONSTANT = {'hello':'world', 'goodnight':'moon'}
  65
  66 /**
  67  * You can define enums, which are just 32 bit integers. Values are optional
  68  * and start at 1 if not supplied, C style again.
  69  */
  70 enum Operation {
  71   ADD = 1,
  72   SUBTRACT = 2,
  73   MULTIPLY = 3,
  74   DIVIDE = 4
  75 }
  76
  77 /**
  78  * Structs are the basic complex data structures. They are comprised of fields
  79  * which each have an integer identifier, a type, a symbolic name, and an
  80  * optional default value.
  81  */
  82 struct Work {
  83   1: i32 num1 = 0,
  84   2: i32 num2,
  85   3: Operation op
  86 }
  87
  88 /**
  89  * Structs can also be exceptions, if they are nasty.
  90  */
  91 exception InvalidOperation {
  92   1: i32 what,
  93   2: string why
  94 }
  95
  96 /**
  97  * Ahh, now onto the cool part, defining a service. Services just need a name
  98  * and can optionally inherit from another service using the extends keyword.
  99  */
 100 service Calculator extends shared.SharedService {
 101
 102   /**
 103    * A method definition looks like C code. It has a return type, arguments,
 104    * and optionally a list of exceptions that it may throw. Note that argument
 105    * lists and exception lists are specified using the exact same syntax as
 106    * field lists in struct or exception definitions.
 107    */
 108
 109    void ping(),
 110
 111    i32 add(1:i32 num1, 2:i32 num2),
 112
 113    i32 calculate(1:i32 logid, 2:Work w) throws (1:InvalidOperation ouch),
 114
 115    /**
 116     * This method has an async modifier. That means the client only makes
 117     * a request and does not listen for any response at all. Async methods
 118     * must be void.
 119     */
 120    async void zip()
 121
 122 }
 123
 124 /**
 125  * That just about covers the basics. Take a look in the test/ folder for more
 126  * detailed examples. After you run this file, your generated code shows up
 127  * in folders with names gen-<language>. The generated code isn't too scary
 128  * to look at. It even has pretty indentation.
 129  */