Jaidyn Lev authored on 2018-12-18 04:48:56
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,150 @@
1
+===============================================================================
2
+FACILSERVIL : `Easy Server`                           Dead-simple, dead-useful.
3
+===============================================================================
4
+
5
+Sometimes, it's just annoying and time-draining to deal with all of the
6
+intricacies of :usockets-- if, to that, you say something like...
7
+
8
+        "I just want to write a simple TCP server, dammit!
9
+         There's got to be an easier way!"
10
+
11
+... then Facilservil is for you!
12
+
13
+Facilservil ("easy server") abstracts away the entire server bits, allowing you
14
+to focus on flexibility.
15
+
16
+
17
+----------------------------------------
18
+FEATURES
19
+----------------------------------------
20
+
21
+ * Multi-user
22
+ * Shutdown protection
23
+ * Input-handling
24
+ * Simple logging system
25
+ * Flexibility
26
+ * UTF-8
27
+
28
+
29
+----------------------------------------
30
+DEMONSTRATION
31
+----------------------------------------
32
+
33
+Load up Facilservil, then run this in your repl:
34
+    
35
+       (facilservil:ex-server 8888)
36
+
37
+Now, connect your computer on port 8888!
38
+If you're on LiGNUx or BSD, you can use "telnet localhost 8888"
39
+
40
+It'll show you a pretty example server. :)
41
+
42
+In reality, 'ex-server is just a small function for demonstration-- the
43
+example server really looks like this:
44
+
45
+        (facilservil:server "0.0.0.0" port
46
+	                    'facilservil:connect-ex 'facilservil:disconnect-ex
47
+			    'facilservil:input-handle-ex)
48
+
49
+It runs #'connect-ex when you connect, #'disconnect-ex when you disconnect,
50
+and #'input-handle-ex after you finish a command, to handle your input.
51
+
52
+If you wanna see this example's code (is there a better way to learn?), look
53
+in "/src/ex.lisp".
54
+
55
+For a different kind of example (less interesting, since it takes no user
56
+input), look at QOTDD (https://git.eunichx.us/qotdd).
57
+
58
+For a more comprehensive guide to Facilservil, look to USAGE, coming right up.
59
+
60
+
61
+----------------------------------------
62
+USAGE
63
+----------------------------------------
64
+
65
+To use Facilservil, just use the `facilservil:server` function somewhere:
66
+
67
+        (facilservil:server host port
68
+                            connecting disconnecting input-handler
69
+                            &key (command-byte 10) (halting 'halt-ex))
70
+
71
+"host" and "port" are, obviously, the host-IP and port, respectively.
72
+"connecting"	is the function that will be executed when a user connects.
73
+"disconnecting"	is the function that will run when someone disconnects.
74
+"input-handler"	interprets the input of a user, when they complete a command.
75
+"command-byte"	is the byte which determines if they've completed a command.
76
+            	it's 10 by default, which is newline.
77
+"halting"    	is the function executed when the server shuts down.
78
+
79
+
80
+Basically, you write the "connecting", "disconnecting", and "input-handler"
81
+functions (maybe "halting"), and you've got a handy-dandy server.
82
+
83
+These functions you write must accept the following arguments:
84
+        connecting	(socket client-id)
85
+        disconnecting	(socket client-id)
86
+        input-handler	(socket client-id input-string)
87
+	halting    	()
88
+
89
+Let's say that you want to write a connecting function which sends a friendly
90
+"welcome" message. You'd do that like this, just about:
91
+
92
+        (defun my-connecting-function (socket client-id)
93
+	  (client-write socket
94
+	    (format nil "Hey, welcome to this server, ~A! <3" client-id)
95
+	    'T))
96
+
97
+This will write to the connecting user's socket (which is passed to your
98
+function), "Hey, welcome to this server," followed by their client-id.
99
+
100
+Every user, upon connection, is given a client ID number which is correlated
101
+with their connection socket. This ID number is random, and can be up to
102
+999999 in value.
103
+
104
+To send a message to a user, get their socket, and run
105
+          (facilservil:client-write socket string &optional newline)
106
+
107
+"newline", which defaults to nil, determines whether or not your message is
108
+followed with a newline.
109
+
110
+I'll give you one more quick example-- then you'll probably get usage.
111
+
112
+Let's write a quick input handler.
113
+           (defun my-input-handler (socket client-id input-string)
114
+	     (if (equal input-string "Hello")
115
+		(facilservil:client-write socket "And hi to you!" 't)
116
+		(facilservil:client-write socket "You won't even say hi?" 'T)))
117
+
118
+It should be pretty self-explanatory.
119
+You just scale up from them-- write a nice command parser or something, and
120
+you're on your way! :)
121
+
122
+Now, one more thing: to run the server with your new functions, just do this:
123
+
124
+            (facilservil:server host port
125
+	    'my-connecting-function 'facilservil:disconnect-ex
126
+	    'my-input-handler)
127
+
128
+
129
+TIP: When it comes to user data, you might want to use a hash-table or two which
130
+     correlate client-ids and user data. ^_^
131
+
132
+
133
+----------------------------------------
134
+NON-FEATURES (TODO)
135
+----------------------------------------
136
+
137
+ * Ctrl-C etc will crash servers
138
+ * Some UTF characters don't go over well
139
+ * Internationalization should be supported--
140
+   right now, logs etc are always in English.
141
+   Not cool.
142
+ * You should be able to log to a file.
143
+
144
+
145
+----------------------------------------
146
+BORING STUFF
147
+----------------------------------------
148
+License is in COPYING (GNU GPLv3)
149
+Author is Jaidyn Ann <jadedctrl@teknik.io>
150
+Sauce is at https://git.eunichx.us/facilservil