Server-class is functional
[gopher-lib.git] / README.md
1 # gopher-lib
2 A node library for communication via the Gopher Internet protocol.<br>
3 Useful for implementing Gopher clients and servers (server class coming soon).
4
5 ```bash
6 npm install gopher-lib
7 ```
8
9 ```javascript
10 const Gopher = require('gopher-lib');
11
12 var client = new Gopher.Client();
13
14 client.get('gopher://gopher.floodgap.com/0/gopher/relevance.txt', (err, reply)=>{
15         if(err) {
16         console.error(err);
17     } else {
18         console.log(reply.text);
19     }
20 });
21 ```
22
23 # API
24
25 ### Class: Server
26
27 ```bash
28 npm install
29 ./node_modules/jsdoc/jsdoc.js server.js common.js
30 firefox out/index.html
31 ```
32
33 ### Class: Client([{timeout: 5000, parseDir: true}])
34 If timeout is set false, no timeout is used.<br>
35 If parseDir is set false, the directory in the result will be a buffer with the raw text from the server instead of being an Array of GopherResource.
36
37 ```javascript
38 var client = new Gopher.Client();
39 ```
40 ##### Method: Client.get(URI|GopherResource, replyHandler [, fileName])
41 If an URI is used, it must be accepted by GopherResource.<br>
42 If fileName is provided, all received data is streamed directly to the file on disk regardless of type.<br>
43 NOTE: If parseDir===true, then 'i' entries will have all info execpt name stripped before the GopherResource is created.
44
45 ```javascript
46 replyHandler = (err, reply)=>{};
47
48 err = Error; // If error is set, reply may contain useful debug information (may).
49
50 reply = {
51         request: {
52         resource: GopherResource,       // The resource used for making this request
53         start: null | Date,                     // Request begin time
54         stop: null | Date,                      // Request end time
55         elapsed: null | Integer,        // Elapsed time
56         remoteAddress: null | ip,               // The IP address that the host name resolved to
57         bytesSent: null | Integer,              // How many bytes were sent to the server
58         bytesReceived: null | Integer,  // How many bytes were received from the server
59         fileName: null | String,                // If a fileName was given, received data was saved to filaName
60     },
61     // The following properties are not added if the get method was provided with a fileName.
62     directory: null | [GopherResource],         // If res.type is directory or search
63     buffer: null | Buffer,                                      // If res.type is binary file
64     text: null | String                                         // If res.type is text, html or encoded file
65 };
66 ```
67
68 ### Class: Resource(URI|[host,port,selector,type,name[,query]]) 
69 Valid URI: [gopher://]host[:port][/[type][selector][?query][#name]]
70 Selectors, queries and names can contain spaces or be uriencoded (%20=space)
71 Name will only be set in the resource, it is not used in interaction with the server.
72
73 ```javascript
74 var resourcea = new Gopher.Resource( 'gopher://dusted.dk/0/computers/computers.txt#DusteDs%20computers' );
75 var resourceb = new Gopher.Resource( 'dusted.dk', '70', '/computers/computers.txt', '0', 'DusteDs computers' );
76 var resourcec = new Gopher.Resource( 'floodgap.com' );
77 ```
78 ##### Method: Resource.toJson()
79 ##### Method: Resource.toURI()
80 ##### Method: Resource.toShortURI()
81 ##### Method: Resource.toDirectoryEntity()
82
83 ```javascript
84 var res = new Gopher.Resource('dusted.dk', '70', Gopher.Types.text, '/pages/about/this_server.txt', 'About my Server');
85
86 console.log(res.toJson());
87 //{"host":"dusted.dk","port":"70","type":"0","selector":"/pages/about/this_server.txt","query":false,"name":"About my Server"}
88
89 console.log(res.toURI());
90 //gopher://dusted.dk:70/0/pages/about/this_server.txt#About%20my%20Server
91
92 console.log(res.toShortURI());
93 //gopher://dusted.dk:70/0/pages/about/this_server.txt
94
95 console.log(res.toDirectoryEntity());
96 //0About my Server    /pages/about/this_server.txt    dusted.dk       70
97 ```
98
99 ### File: example-client.js
100 ```bash
101 # A simple command-line client for interacting with gopher servers and downloading files.
102 node example-client.js gopher://dusted.dk/
103 node example-client.js gopher://dusted.dk/9/pages/goatlove/LD28_GoatLove_linux_b0021.tar.bz2 goatlove.tar.bz2
104 ```
105
106 ### File: test.js
107 ```bash
108 # Unit test (of the Resource capability to parse a URI)
109 npm test
110 ```