-
Notifications
You must be signed in to change notification settings - Fork 1
/
go_tutorial.html
1381 lines (1380 loc) · 51.5 KB
/
go_tutorial.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!-- Um Tutorial para a Linguagem de Programação Go -->
<h2>Introdução</h2>
<p>
Este documento é um tutorial introdutório aos básicos da programação em linguagem Go,
destinada a programadores familiares com C ou C++. Não é um guia compreensivo para
a linguagem; no momento, o documento mais próximo disso é a
<a href='/doc/go_spec.html'>especificação da linguagem</a>.
Após ler este tutorial, você talvez queira olhar
<a href='/doc/effective_go.html'>Go Efetivo</a>,
que vai um pouco mais profundo em como a linguagem é usada.
Além disso, <i>slides</i> de um curso de 3 dias sobre Go estão disponíveis (em inglês):
<a href='/doc/GoCourseDay1.pdf'>Dia 1</a>,
<a href='/doc/GoCourseDay2.pdf'>Dia 2</a>,
<a href='/doc/GoCourseDay3.pdf'>Dia 3</a>.
<p>
A apresentação aqui procede através de uma série de programas modestos para ilustrar
características-chave da linguagem. Todos os programas funcionam (no momento em que este
documento foi escrito) e estão disponíveis no repositório no diretório
<a href='/doc/progs'><code>/doc/progs/</code></a>.
<p>
Trechos de código são anotados com o número da linha no arquivo original; por questões
de estética, linhas em branco permanecem brancas.
<p>
<h2>Hello, World</h2>
<p>
Vamos começar do modo clássico:
<p>
<pre> <!-- progs/helloworld.go /package/ END -->
05 package main
<p>
07 import fmt "fmt" // Pacote implementando E/S (entrada/saída) formatada.
<p>
09 func main() {
10 fmt.Printf("Hello, world; or Καλημέρα κόσμε; or こんにちは 世界\n");
11 }
</pre>
<p>
Todo arquivo fonte Go declara, usando a declaração <code>package</code>, o pacote a que faz parte.
Ele pode também importar outros pacotes para usar suas facilidades.
Este programa importa o pacote <code>fmt</code> para obter acesso ao nosso velho - agora capitalizado e
qualificado via pacote - amigo, <code>fmt.Printf</code>.
<p>
Funções são introduzidas com a palavra-chave <code>func</code>.
A função <code>main</code> do pacote <code>main</code> é onde o programa começa executando (após qualquer inicialização).
<p>
Constantes <i>String</i> podem conter caracteres <i>Unicode</i>, codificados emUTF-8.
(De fato, arquivos fonte Go são definidos para ser codificados em UTF-8.)
<p>
A convenção de comentários é a mesma do C++:
<p>
<pre>
/* ... */
// ...
</pre>
<p>
Depois falaremos mais sobre impressão.
<p>
<h2>Compilando</h2>
<p>
Go é uma linguagem compilada. No momento existem dois compiladores.
<code>Gccgo</code> é um compilador Go que usa o GCC como <i>back end</i>.
Existe também uma suíte de compiladores com diferentes (e estranhos) nomes para cada arquitetura:
<code>6g</code> para x86 64-bit, <code>8g</code> para x86 32-bit, e mais.
Esses compiladores executam significantemente mais rápidos, mas geram código menos eficiente
que o <code>gccgo</code>. Na época da escrita deste documento (final de 2009), eles também têm
um sistema de tempo de execução mais robusto, apesar de o <code>gccgo</code> estar acompanhando rapidamente.
<p>
Eis um exemplo de como compilar e executar um programa com, por exemplo, o <code>6g</code>:
<p>
<pre>
$ 6g helloworld.go # compila; código objeto vai para helloworld.6
$ 6l helloworld.6 # <i>linka</i>; saída vai para 6.out
$ 6.out
Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
$
</pre>
<p>
Com o <code>gccgo</code> o processo parece um pouco mais tradicional:
<p>
<pre>
$ gccgo helloworld.go
$ a.out
Hello, world; or Καλημέρα κόσμε; or こんにちは 世界
$
</pre>
<p>
<h2>Echo</h2>
<p>
A seguir, uma versão do utilitário Unix <code>echo(1)</code>:
<p>
<pre> <!-- progs/echo.go /package/ END -->
05 package main
<p>
07 import (
08 "os";
09 "flag"; // command line option parser
10 )
<p>
12 var omitNewline = flag.Bool("n", false, "don't print final newline")
<p>
14 const (
15 Space = " ";
16 Newline = "\n";
17 )
<p>
19 func main() {
20 flag.Parse(); // Scans the arg list and sets up flags
21 var s string = "";
22 for i := 0; i < flag.NArg(); i++ {
23 if i > 0 {
24 s += Space
25 }
26 s += flag.Arg(i);
27 }
28 if !*omitNewline {
29 s += Newline
30 }
31 os.Stdout.WriteString(s);
32 }
</pre>
<p>
This program is small but it's doing a number of new things. In the last example,
we saw <code>func</code> introduce a function. The keywords <code>var</code>, <code>const</code>, and <code>type</code>
(not used yet) also introduce declarations, as does <code>import</code>.
Notice that we can group declarations of the same sort into
parenthesized, semicolon-separated lists if we want, as on lines 7-10 and 14-17.
But it's not necessary to do so; we could have said
<p>
<pre>
const Space = " "
const Newline = "\n"
</pre>
<p>
Semicolons aren't needed here; in fact, semicolons are unnecessary after any
top-level declaration, although they are needed as separators <i>within</i>
a parenthesized list of declarations.
<p>
You can use semicolons just the way you would in C, C++, or Java, but if you
prefer you can also leave them out in many cases. They <i>separate</i> statements
rather than terminate them, so they aren't needed (but are still OK) at the end of the last
statement in a block.
They're also optional after braces, as in C.
Have a look at the source to <code>echo</code>.
The only necessary semicolons in that program are on lines 8, 15, and 21
and of course between the elements of the <code>for</code> loop on line 22.
The ones on line 9, 16, 26, and 31 are optional but are there because a semicolon
on the end of a list of statements makes it easier to edit the list later.
<p>
This program imports the <code>"os"</code> package to access its <code>Stdout</code> variable, of type
<code>*os.File</code>. The <code>import</code> statement is actually a declaration: in its general form,
as used in our ``hello world'' program,
it names the identifier (<code>fmt</code>)
that will be used to access members of the package imported from the file (<code>"fmt"</code>),
found in the current directory or in a standard location.
In this program, though, we've dropped the explicit name from the imports; by default,
packages are imported using the name defined by the imported package,
which by convention is of course the file name itself. Our ``hello world'' program
could have said just <code>import "fmt"</code>.
<p>
You can specify your
own import names if you want but it's only necessary if you need to resolve
a naming conflict.
<p>
Given <code>os.Stdout</code> we can use its <code>WriteString</code> method to print the string.
<p>
Having imported the <code>flag</code> package, line 12 creates a global variable to hold
the value of echo's <code>-n</code> flag. The variable <code>omitNewline</code> has type <code>*bool</code>, pointer
to <code>bool</code>.
<p>
In <code>main.main</code>, we parse the arguments (line 20) and then create a local
string variable we will use to build the output.
<p>
The declaration statement has the form
<p>
<pre>
var s string = "";
</pre>
<p>
This is the <code>var</code> keyword, followed by the name of the variable, followed by
its type, followed by an equals sign and an initial value for the variable.
<p>
Go tries to be terse, and this declaration could be shortened. Since the
string constant is of type string, we don't have to tell the compiler that.
We could write
<p>
<pre>
var s = "";
</pre>
<p>
or we could go even shorter and write the idiom
<p>
<pre>
s := "";
</pre>
<p>
The <code>:=</code> operator is used a lot in Go to represent an initializing declaration.
There's one in the <code>for</code> clause on the next line:
<p>
<pre> <!-- progs/echo.go /for/ -->
22 for i := 0; i < flag.NArg(); i++ {
</pre>
<p>
The <code>flag</code> package has parsed the arguments and left the non-flag arguments
in a list that can be iterated over in the obvious way.
<p>
The Go <code>for</code> statement differs from that of C in a number of ways. First,
it's the only looping construct; there is no <code>while</code> or <code>do</code>. Second,
there are no parentheses on the clause, but the braces on the body
are mandatory. The same applies to the <code>if</code> and <code>switch</code> statements.
Later examples will show some other ways <code>for</code> can be written.
<p>
The body of the loop builds up the string <code>s</code> by appending (using <code>+=</code>)
the flags and separating spaces. After the loop, if the <code>-n</code> flag is not
set, the program appends a newline. Finally, it writes the result.
<p>
Notice that <code>main.main</code> is a niladic function with no return type.
It's defined that way. Falling off the end of <code>main.main</code> means
''success''; if you want to signal an erroneous return, call
<p>
<pre>
os.Exit(1)
</pre>
<p>
The <code>os</code> package contains other essentials for getting
started; for instance, <code>os.Args</code> is a slice used by the
<code>flag</code> package to access the command-line arguments.
<p>
<h2>An Interlude about Types</h2>
<p>
Go has some familiar types such as <code>int</code> and <code>float</code>, which represent
values of the ''appropriate'' size for the machine. It also defines
explicitly-sized types such as <code>int8</code>, <code>float64</code>, and so on, plus
unsigned integer types such as <code>uint</code>, <code>uint32</code>, etc. These are
distinct types; even if <code>int</code> and <code>int32</code> are both 32 bits in size,
they are not the same type. There is also a <code>byte</code> synonym for
<code>uint8</code>, which is the element type for strings.
<p>
Speaking of <code>string</code>, that's a built-in type as well. Strings are
<i>immutable values</i>—they are not just arrays of <code>byte</code> values.
Once you've built a string <i>value</i>, you can't change it, although
of course you can change a string <i>variable</i> simply by
reassigning it. This snippet from <code>strings.go</code> is legal code:
<p>
<pre> <!-- progs/strings.go /hello/ /ciao/ -->
11 s := "hello";
12 if s[1] != 'e' { os.Exit(1) }
13 s = "good bye";
14 var p *string = &s;
15 *p = "ciao";
</pre>
<p>
However the following statements are illegal because they would modify
a <code>string</code> value:
<p>
<pre>
s[0] = 'x';
(*p)[1] = 'y';
</pre>
<p>
In C++ terms, Go strings are a bit like <code>const strings</code>, while pointers
to strings are analogous to <code>const string</code> references.
<p>
Yes, there are pointers. However, Go simplifies their use a little;
read on.
<p>
Arrays are declared like this:
<p>
<pre>
var arrayOfInt [10]int;
</pre>
<p>
Arrays, like strings, are values, but they are mutable. This differs
from C, in which <code>arrayOfInt</code> would be usable as a pointer to <code>int</code>.
In Go, since arrays are values, it's meaningful (and useful) to talk
about pointers to arrays.
<p>
The size of the array is part of its type; however, one can declare
a <i>slice</i> variable, to which one can assign a pointer to
any array
with the same element type or—much more commonly—a <i>slice
expression</i> of the form <code>a[low : high]</code>, representing
the subarray indexed by <code>low</code> through <code>high-1</code>.
Slices look a lot like arrays but have
no explicit size (<code>[]</code> vs. <code>[10]</code>) and they reference a segment of
an underlying, often anonymous, regular array. Multiple slices
can share data if they represent pieces of the same array;
multiple arrays can never share data.
<p>
Slices are much more common in Go programs than
regular arrays; they're more flexible, have reference semantics,
and are efficient. What they lack is the precise control of storage
layout of a regular array; if you want to have a hundred elements
of an array stored within your structure, you should use a regular
array.
<p>
When passing an array to a function, you almost always want
to declare the formal parameter to be a slice. When you call
the function, take the address of the array and Go will
create (efficiently) a slice reference and pass that.
<p>
Using slices one can write this function (from <code>sum.go</code>):
<p>
<pre> <!-- progs/sum.go /sum/ /^}/ -->
09 func sum(a []int) int { // returns an int
10 s := 0;
11 for i := 0; i < len(a); i++ {
12 s += a[i]
13 }
14 return s
15 }
</pre>
<p>
and invoke it like this:
<p>
<pre> <!-- progs/sum.go /1,2,3/ -->
19 s := sum(&[3]int{1,2,3}); // a slice of the array is passed to sum
</pre>
<p>
Note how the return type (<code>int</code>) is defined for <code>sum()</code> by stating it
after the parameter list.
The expression <code>[3]int{1,2,3}</code>—a type followed by a
brace-bounded
expression—is a constructor for a value, in this case an array
of 3 <code>ints</code>.
Putting an <code>&</code>
in front gives us the address of a unique instance of the value. We pass the
pointer to <code>sum()</code> by (implicitly) promoting it to a slice.
<p>
If you are creating a regular array but want the compiler to count the
elements for you, use <code>...</code> as the array size:
<p>
<pre>
s := sum(&[...]int{1,2,3});
</pre>
<p>
In practice, though, unless you're meticulous about storage layout within a
data structure, a slice itself—using empty brackets and no
<code>&</code>—is all you need:
<p>
<pre>
s := sum([]int{1,2,3});
</pre>
<p>
There are also maps, which you can initialize like this:
<p>
<pre>
m := map[string]int{"one":1 , "two":2}
</pre>
<p>
The built-in function <code>len()</code>, which returns number of elements,
makes its first appearance in <code>sum</code>. It works on strings, arrays,
slices, maps, and channels.
<p>
By the way, another thing that works on strings, arrays, slices, maps
and channels is the <code>range</code> clause on <code>for</code> loops. Instead of writing
<p>
<pre>
for i := 0; i < len(a); i++ { ... }
</pre>
<p>
to loop over the elements of a slice (or map or ...) , we could write
<p>
<pre>
for i, v := range a { ... }
</pre>
<p>
This assigns <code>i</code> to the index and <code>v</code> to the value of the successive
elements of the target of the range. See
<a href='/doc/effective_go.html'>Effective Go</a>
for more examples of its use.
<p>
<p>
<h2>An Interlude about Allocation</h2>
<p>
Most types in Go are values. If you have an <code>int</code> or a <code>struct</code>
or an array, assignment
copies the contents of the object.
To allocate a new variable, use <code>new()</code>, which
returns a pointer to the allocated storage.
<p>
<pre>
type T struct { a, b int }
var t *T = new(T);
</pre>
<p>
or the more idiomatic
<p>
<pre>
t := new(T);
</pre>
<p>
Some types—maps, slices, and channels (see below)—have reference semantics.
If you're holding a slice or a map and you modify its contents, other variables
referencing the same underlying data will see the modification. For these three
types you want to use the built-in function <code>make()</code>:
<p>
<pre>
m := make(map[string]int);
</pre>
<p>
This statement initializes a new map ready to store entries.
If you just declare the map, as in
<p>
<pre>
var m map[string]int;
</pre>
<p>
it creates a <code>nil</code> reference that cannot hold anything. To use the map,
you must first initialize the reference using <code>make()</code> or by assignment from an
existing map.
<p>
Note that <code>new(T)</code> returns type <code>*T</code> while <code>make(T)</code> returns type
<code>T</code>. If you (mistakenly) allocate a reference object with <code>new()</code>,
you receive a pointer to a nil reference, equivalent to
declaring an uninitialized variable and taking its address.
<p>
<h2>An Interlude about Constants</h2>
<p>
Although integers come in lots of sizes in Go, integer constants do not.
There are no constants like <code>0LL</code> or <code>0x0UL</code>. Instead, integer
constants are evaluated as large-precision values that
can overflow only when they are assigned to an integer variable with
too little precision to represent the value.
<p>
<pre>
const hardEight = (1 << 100) >> 97 // legal
</pre>
<p>
There are nuances that deserve redirection to the legalese of the
language specification but here are some illustrative examples:
<p>
<pre>
var a uint64 = 0 // a has type uint64, value 0
a := uint64(0) // equivalent; uses a "conversion"
i := 0x1234 // i gets default type: int
var j int = 1e6 // legal - 1000000 is representable in an int
x := 1.5 // a float
i3div2 := 3/2 // integer division - result is 1
f3div2 := 3./2. // floating point division - result is 1.5
</pre>
<p>
Conversions only work for simple cases such as converting <code>ints</code> of one
sign or size to another, and between <code>ints</code> and <code>floats</code>, plus a few other
simple cases. There are no automatic numeric conversions of any kind in Go,
other than that of making constants have concrete size and type when
assigned to a variable.
<p>
<h2>An I/O Package</h2>
<p>
Next we'll look at a simple package for doing file I/O with the usual
sort of open/close/read/write interface. Here's the start of <code>file.go</code>:
<p>
<pre> <!-- progs/file.go /package/ /^}/ -->
05 package file
<p>
07 import (
08 "os";
09 "syscall";
10 )
<p>
12 type File struct {
13 fd int; // file descriptor number
14 name string; // file name at Open time
15 }
</pre>
<p>
The first few lines declare the name of the
package—<code>file</code>—and then import two packages. The <code>os</code>
package hides the differences
between various operating systems to give a consistent view of files and
so on; here we're going to use its error handling utilities
and reproduce the rudiments of its file I/O.
<p>
The other item is the low-level, external <code>syscall</code> package, which provides
a primitive interface to the underlying operating system's calls.
<p>
Next is a type definition: the <code>type</code> keyword introduces a type declaration,
in this case a data structure called <code>File</code>.
To make things a little more interesting, our <code>File</code> includes the name of the file
that the file descriptor refers to.
<p>
Because <code>File</code> starts with a capital letter, the type is available outside the package,
that is, by users of the package. In Go the rule about visibility of information is
simple: if a name (of a top-level type, function, method, constant or variable, or of
a structure field or method) is capitalized, users of the package may see it. Otherwise, the
name and hence the thing being named is visible only inside the package in which
it is declared. This is more than a convention; the rule is enforced by the compiler.
In Go, the term for publicly visible names is ''exported''.
<p>
In the case of <code>File</code>, all its fields are lower case and so invisible to users, but we
will soon give it some exported, upper-case methods.
<p>
First, though, here is a factory to create a <code>File</code>:
<p>
<pre> <!-- progs/file.go /newFile/ /^}/ -->
17 func newFile(fd int, name string) *File {
18 if fd < 0 {
19 return nil
20 }
21 return &File{fd, name}
22 }
</pre>
<p>
This returns a pointer to a new <code>File</code> structure with the file descriptor and name
filled in. This code uses Go's notion of a ''composite literal'', analogous to
the ones used to build maps and arrays, to construct a new heap-allocated
object. We could write
<p>
<pre>
n := new(File);
n.fd = fd;
n.name = name;
return n
</pre>
<p>
but for simple structures like <code>File</code> it's easier to return the address of a nonce
composite literal, as is done here on line 21.
<p>
We can use the factory to construct some familiar, exported variables of type <code>*File</code>:
<p>
<pre> <!-- progs/file.go /var/ /^.$/ -->
24 var (
25 Stdin = newFile(0, "/dev/stdin");
26 Stdout = newFile(1, "/dev/stdout");
27 Stderr = newFile(2, "/dev/stderr");
28 )
</pre>
<p>
The <code>newFile</code> function was not exported because it's internal. The proper,
exported factory to use is <code>Open</code>:
<p>
<pre> <!-- progs/file.go /func.Open/ /^}/ -->
30 func Open(name string, mode int, perm int) (file *File, err os.Error) {
31 r, e := syscall.Open(name, mode, perm);
32 if e != 0 {
33 err = os.Errno(e);
34 }
35 return newFile(r, name), err
36 }
</pre>
<p>
There are a number of new things in these few lines. First, <code>Open</code> returns
multiple values, a <code>File</code> and an error (more about errors in a moment).
We declare the
multi-value return as a parenthesized list of declarations; syntactically
they look just like a second parameter list. The function
<code>syscall.Open</code>
also has a multi-value return, which we can grab with the multi-variable
declaration on line 31; it declares <code>r</code> and <code>e</code> to hold the two values,
both of type <code>int</code> (although you'd have to look at the <code>syscall</code> package
to see that). Finally, line 35 returns two values: a pointer to the new <code>File</code>
and the error. If <code>syscall.Open</code> fails, the file descriptor <code>r</code> will
be negative and <code>newFile</code> will return <code>nil</code>.
<p>
About those errors: The <code>os</code> library includes a general notion of an error.
It's a good idea to use its facility in your own interfaces, as we do here, for
consistent error handling throughout Go code. In <code>Open</code> we use a
conversion to translate Unix's integer <code>errno</code> value into the integer type
<code>os.Errno</code>, which implements <code>os.Error</code>.
<p>
Now that we can build <code>Files</code>, we can write methods for them. To declare
a method of a type, we define a function to have an explicit receiver
of that type, placed
in parentheses before the function name. Here are some methods for <code>*File</code>,
each of which declares a receiver variable <code>file</code>.
<p>
<pre> <!-- progs/file.go /Close/ END -->
38 func (file *File) Close() os.Error {
39 if file == nil {
40 return os.EINVAL
41 }
42 e := syscall.Close(file.fd);
43 file.fd = -1; // so it can't be closed again
44 if e != 0 {
45 return os.Errno(e);
46 }
47 return nil
48 }
<p>
50 func (file *File) Read(b []byte) (ret int, err os.Error) {
51 if file == nil {
52 return -1, os.EINVAL
53 }
54 r, e := syscall.Read(file.fd, b);
55 if e != 0 {
56 err = os.Errno(e);
57 }
58 return int(r), err
59 }
<p>
61 func (file *File) Write(b []byte) (ret int, err os.Error) {
62 if file == nil {
63 return -1, os.EINVAL
64 }
65 r, e := syscall.Write(file.fd, b);
66 if e != 0 {
67 err = os.Errno(e);
68 }
69 return int(r), err
70 }
<p>
72 func (file *File) String() string {
73 return file.name
74 }
</pre>
<p>
There is no implicit <code>this</code> and the receiver variable must be used to access
members of the structure. Methods are not declared within
the <code>struct</code> declaration itself. The <code>struct</code> declaration defines only data members.
In fact, methods can be created for almost any type you name, such as an integer or
array, not just for <code>structs</code>. We'll see an example with arrays later.
<p>
The <code>String</code> method is so called because of a printing convention we'll
describe later.
<p>
The methods use the public variable <code>os.EINVAL</code> to return the (<code>os.Error</code>
version of the) Unix error code <code>EINVAL</code>. The <code>os</code> library defines a standard
set of such error values.
<p>
We can now use our new package:
<p>
<pre> <!-- progs/helloworld3.go /package/ END -->
05 package main
<p>
07 import (
08 "./file";
09 "fmt";
10 "os";
11 )
<p>
13 func main() {
14 hello := []byte{'h', 'e', 'l', 'l', 'o', ',', ' ', 'w', 'o', 'r', 'l', 'd', '\n'};
15 file.Stdout.Write(hello);
16 file, err := file.Open("/does/not/exist", 0, 0);
17 if file == nil {
18 fmt.Printf("can't open file; err=%s\n", err.String());
19 os.Exit(1);
20 }
21 }
</pre>
<p>
The ''<code>./</code>'' in the import of ''<code>./file</code>'' tells the compiler to use our own package rather than
something from the directory of installed packages.
<p>
Finally we can run the program:
<p>
<pre>
% helloworld3
hello, world
can't open file; err=No such file or directory
%
</pre>
<p>
<h2>Rotting cats</h2>
<p>
Building on the <code>file</code> package, here's a simple version of the Unix utility <code>cat(1)</code>,
<code>progs/cat.go</code>:
<p>
<pre> <!-- progs/cat.go /package/ END -->
05 package main
<p>
07 import (
08 "./file";
09 "flag";
10 "fmt";
11 "os";
12 )
<p>
14 func cat(f *file.File) {
15 const NBUF = 512;
16 var buf [NBUF]byte;
17 for {
18 switch nr, er := f.Read(&buf); true {
19 case nr < 0:
20 fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", f.String(), er.String());
21 os.Exit(1);
22 case nr == 0: // EOF
23 return;
24 case nr > 0:
25 if nw, ew := file.Stdout.Write(buf[0:nr]); nw != nr {
26 fmt.Fprintf(os.Stderr, "cat: error writing from %s: %s\n", f.String(), ew.String());
27 }
28 }
29 }
30 }
<p>
32 func main() {
33 flag.Parse(); // Scans the arg list and sets up flags
34 if flag.NArg() == 0 {
35 cat(file.Stdin);
36 }
37 for i := 0; i < flag.NArg(); i++ {
38 f, err := file.Open(flag.Arg(i), 0, 0);
39 if f == nil {
40 fmt.Fprintf(os.Stderr, "cat: can't open %s: error %s\n", flag.Arg(i), err);
41 os.Exit(1);
42 }
43 cat(f);
44 f.Close();
45 }
46 }
</pre>
<p>
By now this should be easy to follow, but the <code>switch</code> statement introduces some
new features. Like a <code>for</code> loop, an <code>if</code> or <code>switch</code> can include an
initialization statement. The <code>switch</code> on line 18 uses one to create variables
<code>nr</code> and <code>er</code> to hold the return values from <code>f.Read()</code>. (The <code>if</code> on line 25
has the same idea.) The <code>switch</code> statement is general: it evaluates the cases
from top to bottom looking for the first case that matches the value; the
case expressions don't need to be constants or even integers, as long as
they all have the same type.
<p>
Since the <code>switch</code> value is just <code>true</code>, we could leave it off—as is also
the situation
in a <code>for</code> statement, a missing value means <code>true</code>. In fact, such a <code>switch</code>
is a form of <code>if-else</code> chain. While we're here, it should be mentioned that in
<code>switch</code> statements each <code>case</code> has an implicit <code>break</code>.
<p>
Line 25 calls <code>Write()</code> by slicing the incoming buffer, which is itself a slice.
Slices provide the standard Go way to handle I/O buffers.
<p>
Now let's make a variant of <code>cat</code> that optionally does <code>rot13</code> on its input.
It's easy to do by just processing the bytes, but instead we will exploit
Go's notion of an <i>interface</i>.
<p>
The <code>cat()</code> subroutine uses only two methods of <code>f</code>: <code>Read()</code> and <code>String()</code>,
so let's start by defining an interface that has exactly those two methods.
Here is code from <code>progs/cat_rot13.go</code>:
<p>
<pre> <!-- progs/cat_rot13.go /type.reader/ /^}/ -->
26 type reader interface {
27 Read(b []byte) (ret int, err os.Error);
28 String() string;
29 }
</pre>
<p>
Any type that has the two methods of <code>reader</code>—regardless of whatever
other methods the type may also have—is said to <i>implement</i> the
interface. Since <code>file.File</code> implements these methods, it implements the
<code>reader</code> interface. We could tweak the <code>cat</code> subroutine to accept a <code>reader</code>
instead of a <code>*file.File</code> and it would work just fine, but let's embellish a little
first by writing a second type that implements <code>reader</code>, one that wraps an
existing <code>reader</code> and does <code>rot13</code> on the data. To do this, we just define
the type and implement the methods and with no other bookkeeping,
we have a second implementation of the <code>reader</code> interface.
<p>
<pre> <!-- progs/cat_rot13.go /type.rotate13/ /end.of.rotate13/ -->
31 type rotate13 struct {
32 source reader;
33 }
<p>
35 func newRotate13(source reader) *rotate13 {
36 return &rotate13{source}
37 }
<p>
39 func (r13 *rotate13) Read(b []byte) (ret int, err os.Error) {
40 r, e := r13.source.Read(b);
41 for i := 0; i < r; i++ {
42 b[i] = rot13(b[i])
43 }
44 return r, e
45 }
<p>
47 func (r13 *rotate13) String() string {
48 return r13.source.String()
49 }
50 // end of rotate13 implementation
</pre>
<p>
(The <code>rot13</code> function called on line 42 is trivial and not worth reproducing here.)
<p>
To use the new feature, we define a flag:
<p>
<pre> <!-- progs/cat_rot13.go /rot13Flag/ -->
14 var rot13Flag = flag.Bool("rot13", false, "rot13 the input")
</pre>
<p>
and use it from within a mostly unchanged <code>cat()</code> function:
<p>
<pre> <!-- progs/cat_rot13.go /func.cat/ /^}/ -->
52 func cat(r reader) {
53 const NBUF = 512;
54 var buf [NBUF]byte;
<p>
56 if *rot13Flag {
57 r = newRotate13(r)
58 }
59 for {
60 switch nr, er := r.Read(&buf); {
61 case nr < 0:
62 fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", r.String(), er.String());
63 os.Exit(1);
64 case nr == 0: // EOF
65 return;
66 case nr > 0:
67 nw, ew := file.Stdout.Write(buf[0:nr]);
68 if nw != nr {
69 fmt.Fprintf(os.Stderr, "cat: error writing from %s: %s\n", r.String(), ew.String());
70 }
71 }
72 }
73 }
</pre>
<p>
(We could also do the wrapping in <code>main</code> and leave <code>cat()</code> mostly alone, except
for changing the type of the argument; consider that an exercise.)
Lines 56 through 58 set it all up: If the <code>rot13</code> flag is true, wrap the <code>reader</code>
we received into a <code>rotate13</code> and proceed. Note that the interface variables
are values, not pointers: the argument is of type <code>reader</code>, not <code>*reader</code>,
even though under the covers it holds a pointer to a <code>struct</code>.
<p>
Here it is in action:
<p>
<pre>
% echo abcdefghijklmnopqrstuvwxyz | ./cat
abcdefghijklmnopqrstuvwxyz
% echo abcdefghijklmnopqrstuvwxyz | ./cat --rot13
nopqrstuvwxyzabcdefghijklm
%
</pre>
<p>
Fans of dependency injection may take cheer from how easily interfaces
allow us to substitute the implementation of a file descriptor.
<p>
Interfaces are a distinctive feature of Go. An interface is implemented by a
type if the type implements all the methods declared in the interface.
This means
that a type may implement an arbitrary number of different interfaces.
There is no type hierarchy; things can be much more <i>ad hoc</i>,
as we saw with <code>rot13</code>. The type <code>file.File</code> implements <code>reader</code>; it could also
implement a <code>writer</code>, or any other interface built from its methods that
fits the current situation. Consider the <i>empty interface</i>
<p>
<pre>
type Empty interface {}
</pre>
<p>
<i>Every</i> type implements the empty interface, which makes it
useful for things like containers.
<p>
<h2>Sorting</h2>
<p>
Interfaces provide a simple form of polymorphism. They completely
separate the definition of what an object does from how it does it, allowing
distinct implementations to be represented at different times by the
same interface variable.
<p>
As an example, consider this simple sort algorithm taken from <code>progs/sort.go</code>:
<p>
<pre> <!-- progs/sort.go /func.Sort/ /^}/ -->
13 func Sort(data Interface) {
14 for i := 1; i < data.Len(); i++ {
15 for j := i; j > 0 && data.Less(j, j-1); j-- {
16 data.Swap(j, j-1);
17 }
18 }
19 }
</pre>
<p>
The code needs only three methods, which we wrap into sort's <code>Interface</code>:
<p>
<pre> <!-- progs/sort.go /interface/ /^}/ -->
07 type Interface interface {
08 Len() int;
09 Less(i, j int) bool;
10 Swap(i, j int);
11 }
</pre>
<p>
We can apply <code>Sort</code> to any type that implements <code>Len</code>, <code>Less</code>, and <code>Swap</code>.
The <code>sort</code> package includes the necessary methods to allow sorting of
arrays of integers, strings, etc.; here's the code for arrays of <code>int</code>
<p>
<pre> <!-- progs/sort.go /type.*IntArray/ /Swap/ -->
33 type IntArray []int
<p>
35 func (p IntArray) Len() int { return len(p); }
36 func (p IntArray) Less(i, j int) bool { return p[i] < p[j]; }
37 func (p IntArray) Swap(i, j int) { p[i], p[j] = p[j], p[i]; }
</pre>
<p>
Here we see methods defined for non-<code>struct</code> types. You can define methods
for any type you define and name in your package.
<p>
And now a routine to test it out, from <code>progs/sortmain.go</code>. This
uses a function in the <code>sort</code> package, omitted here for brevity,
to test that the result is sorted.
<p>
<pre> <!-- progs/sortmain.go /func.ints/ /^}/ -->
12 func ints() {
13 data := []int{74, 59, 238, -784, 9845, 959, 905, 0, 0, 42, 7586, -5467984, 7586};
14 a := sort.IntArray(data);
15 sort.Sort(a);
16 if !sort.IsSorted(a) {
17 panic()
18 }
19 }
</pre>
<p>
If we have a new type we want to be able to sort, all we need to do is
to implement the three methods for that type, like this:
<p>
<pre> <!-- progs/sortmain.go /type.day/ /Swap/ -->
30 type day struct {
31 num int;
32 shortName string;
33 longName string;
34 }
<p>
36 type dayArray struct {
37 data []*day;
38 }
<p>
40 func (p *dayArray) Len() int { return len(p.data); }
41 func (p *dayArray) Less(i, j int) bool { return p.data[i].num < p.data[j].num; }
42 func (p *dayArray) Swap(i, j int) { p.data[i], p.data[j] = p.data[j], p.data[i]; }
</pre>
<p>
<p>
<h2>Printing</h2>
<p>
The examples of formatted printing so far have been modest. In this section
we'll talk about how formatted I/O can be done well in Go.
<p>
We've seen simple uses of the package <code>fmt</code>, which
implements <code>Printf</code>, <code>Fprintf</code>, and so on.
Within the <code>fmt</code> package, <code>Printf</code> is declared with this signature:
<p>
<pre>
Printf(format string, v ...) (n int, errno os.Error)
</pre>
<p>
That <code>...</code> represents the variadic argument list that in C would
be handled using the <code>stdarg.h</code> macros but in Go is passed using
an empty interface variable (<code>interface {}</code>) and then unpacked
using the reflection library. It's off topic here but the use of
reflection helps explain some of the nice properties of Go's <code>Printf</code>,
due to the ability of <code>Printf</code> to discover the type of its arguments
dynamically.
<p>
For example, in C each format must correspond to the type of its
argument. It's easier in many cases in Go. Instead of <code>%llud</code> you
can just say <code>%d</code>; <code>Printf</code> knows the size and signedness of the
integer and can do the right thing for you. The snippet
<p>
<pre> <!-- progs/print.go NR==10 NR==11 -->
10 var u64 uint64 = 1<<64-1;
11 fmt.Printf("%d %d\n", u64, int64(u64));
</pre>
<p>
prints
<p>
<pre>
18446744073709551615 -1
</pre>
<p>
In fact, if you're lazy the format <code>%v</code> will print, in a simple
appropriate style, any value, even an array or structure. The output of
<p>
<pre> <!-- progs/print.go NR==14 NR==17 -->
14 type T struct { a int; b string };
15 t := T{77, "Sunset Strip"};
16 a := []int{1, 2, 3, 4};
17 fmt.Printf("%v %v %v\n", u64, t, a);
</pre>
<p>
is
<p>
<pre>
18446744073709551615 {77 Sunset Strip} [1 2 3 4]
</pre>
<p>
You can drop the formatting altogether if you use <code>Print</code> or <code>Println</code>
instead of <code>Printf</code>. Those routines do fully automatic formatting.
The <code>Print</code> function just prints its elements out using the equivalent
of <code>%v</code> while <code>Println</code> inserts spaces between arguments
and adds a newline. The output of each of these two lines is identical
to that of the <code>Printf</code> call above.
<p>
<pre> <!-- progs/print.go NR==18 NR==19 -->
18 fmt.Print(u64, " ", t, " ", a, "\n");
19 fmt.Println(u64, t, a);
</pre>
<p>
If you have your own type you'd like <code>Printf</code> or <code>Print</code> to format,
just give it a <code>String()</code> method that returns a string. The print
routines will examine the value to inquire whether it implements
the method and if so, use it rather than some other formatting.
Here's a simple example.
<p>
<pre> <!-- progs/print_string.go NR==9 END -->
09 type testType struct { a int; b string }
<p>
11 func (t *testType) String() string {
12 return fmt.Sprint(t.a) + " " + t.b
13 }
<p>
15 func main() {
16 t := &testType{77, "Sunset Strip"};