Differences

This shows you the differences between two versions of the page.

--- tutorials:crystal_bbs:part_one [2017/03/19 22:39]
sardaukar
+++ tutorials:crystal_bbs:part_one [2018/03/29 01:58] (current)
@@ Line 17: / Line 17: @@
 This will create the skeleton inside the ''bbs'' subfolder of the current directory. Jump into it and have a look around at the files created.
-One thing the app creator leaves out is an easy way to compile the project - we //can// just type ''crystal build src/bbs.cr --release -o bbs_release'' every time we want to compile, but that would get old really quick. So instead we'll create a ''Makefile'' and use good old //make// to perform all these repetitive tasks on the project. Here's how it could look:
+One thing the app creator leaves out is an easy way to compile the project - we //can// just type ''crystal build src/bbs.cr --release -o bbs_release'' every time we want to compile, but that would get old real quick. So instead we'll create a ''Makefile'' and use good old //make// to perform all these repetitive tasks on the project. Here's how it could look:
 <code make>
@@ Line 50: / Line 50: @@
 Your ''src/bbs.cr'' file should look like this now:
-<code>
+<code ruby>
 require "./bbs/*"
@@ Line 61: / Line 61: @@
 Change it to:
-<code>
+<code ruby>
 require "./bbs/*"
@@ Line 67: / Line 67: @@
 </code>
-This will call a ''go!'' method on the BBS module's ''Main'' class. Let's create it, but on a separate file. Create a ''main.cr'' file inside the ''src'' directory with:
+This will call a ''go!'' method on the BBS module's ''Main'' class. Let's create it, but on a separate file. Create a ''main.cr'' file inside the ''src/bbs/'' directory with:
-<code>
+<code ruby>
 require "yaml"
 module BBS
   class Main
-    @config = YAML::Any
+    @config : YAML::Any
     def initialize
-      load_config
+      @config = load_config
     end
     def go!
-      puts config.inspect
+      puts @config.inspect
     end
-    private getter :config
     private def load_config
-      @config = YAML.parse(File.read("config.yml"))
+      YAML.parse(File.read("config.yml"))
     end
   end
@@ Line 93: / Line 91: @@
 </code>
-This file will be required by ''src/bbs.cr'' (as mandated by its line 1) and will add the method to the BBS module. Let's create a basic config file as ''config.yml'' on the root directory of the project (more info on YAML [[https://en.wikipedia.org/wiki/YAML|here]]:
+This file will be required by ''src/bbs.cr'' (as mandated by its line 1) and will add the class to the BBS module. Let's create a basic config file as ''config.yml'' on the root directory of the project (more info on YAML [[https://en.wikipedia.org/wiki/YAML|here]]:
 <code yaml>
@@ Line 111: / Line 109: @@
 Yay, we're live with the basics and our settings are being read! Let's recap for a bit, since this class introduces a few important concepts.
+<code ruby>
+require "yaml"
+</code>
+This line requires in Crystal's built in [[https://crystal-lang.org/api/0.21.1/YAML.html|YAML handling functions]].
+<code>
+@config : YAML::Any
+</code>
+This specifies the type of the ''@config'' instance variable for the ''Main'' class - this is a requirement in Crystal in order to generate runtime code for the variable. You'll notice that Crystal is very much like Ruby, but this is where the line is drawn - Crystal needs //some// type annotations in the code. You might think this is a step back from Ruby or even Python, but as a long time dynamic languages coder I can assure you that once a codebase exceeds a certain size, type safety being enforced by a compiler is a life saver. Also, it makes Crystal a bazillion times faster than Ruby or Python! :D
+<code ruby>
+def initialize
+  @config = load_config
+end
+</code>
+As in Ruby, the constructor method for a class is called ''initialize'' - in our case, the constructor just assigns the result of the ''load_config'' method to the ''@config'' instance variable.
+<code ruby>
+def go!
+  puts @config.inspect
+end
+</code>
+This is the method called in ''bbs.cr'' (our main entry point for the whole project) after instantiating a new instance of the ''Main'' class. At this stage, it just prints out the hash parsed from the ''config.yml'' file that we created.
+<code ruby>
+private def load_config
+  YAML.parse(File.read("config.yml"))
+end
+</code>
+Finally, the method that parses the configuration file. It's marked as ''private'' since there's no real need for it being called outside of the ''Main'' class. It just returns the output of [[https://crystal-lang.org/api/0.21.1/YAML.html#parse%28data%3AString%7CIO%29%3AAny-class-method|YAML.parse]]. Like in Ruby, there's "implicit return" so we don't need to write ''return YAML.parse(File.read("config.yml"))'' here - the last value evaluated in a method is automatically returned. Note that there's no error handling whatsoever, as this is just a bare bones example.
+So far, so good. Now let's make the project do something a bit more interesting.
+Let's replace the ''go!'' method with our BBS server main loop. This means that while the program is running, it will be doing an infinite loop always listening on a socket, and assigning new connections to a handler function.
+First, we need to require more Crystal built-in functions. This time it will be [[https://crystal-lang.org/api/0.21.1/Socket.html|Socket]], which gives us a generic TCP server for free. So let's add to the top:
+<code ruby>
+require "socket"
+</code>
+Now, in the main ''go!'' method, let's get the config setting for our server port:
+<code ruby>
+telnet_port = @config["settings"]["port"].to_s.to_i
+</code>
+The weird ''.to_s.to_i'' first converts the ''YAML::Any'' value into a ''String'', then into a ''Int32'' (a number, which is what we need). It's not very good looking, so we'll optimize it later before we wrap-up the tutorial, but for now roll with it. Now, let's start the server itself:
+<code ruby>
+server = TCPServer.new("localhost", telnet_port)
+puts "now listening in port #{telnet_port}"
+loop do
+  if socket = server.accept?
+    spawn handle_connection(socket)
+  end
+end
+</code>
+So we start a new ''TCPServer'' bound to ''localhost'', on the port stored in the ''telnet_port'' variable. We then print a little info message, and go into the meat of this method - the main ''loop''. The loop halts on the ''server.accept?'' blocking call, until a connection is made to the server. Once a connection is accepted, the ''socket'' variable will be assigned all the remote endpoint's details to it. With the details in hand, we will ''spawn'' a method call to ''handle_connection''. Spawning is a concept unique to Crystal, and you can read an intro to it in [[https://crystal-lang.org/docs/guides/concurrency.html|the official docs on concurrency]], but think of it as creating a new thread specifically to handle the connection. So the main loop here will continue immediately and be ready to accept new connections //while// the ''handle_connection'' method handles the connection we just got.
+Finally, the new handler method:
+<code ruby>
+private def handle_connection(socket)
+  socket << "hello world\n"
+  socket.close
+end
+</code>
+This method will receive the socket info, write a string to it, and then close it. Let's try it out by running ''make'' - you should see:
+<code>
+$ make
+... (make output omitted)
+now listening in port 2023
+</code>
+Now with a telnet client (the normal command line one in macOS or Linux will do), you can connect to your running server:
+<code>
+$ telnet localhost 2023
+Trying 127.0.0.1...
+Connected to localhost.
+Escape character is '^]'.
+hello world
+Connection closed by foreign host.
+</code>
+Success! As expected, you can see the ''hello world'' message, and then the socket is closed!
+This part of the tutorial is running a bit long, so let's just optimize the YAML settings code, since it looks ugly now, and ugly code is not our style.
+Right now the issue is that Crystal had no idea what type each key or value of the file can be, so we always have to convert it to a type manually. Luckily, Crystal has a notion of a [[https://crystal-lang.org/api/0.21.1/YAML.html#mapping-macro|mapping]] that basically will do all the type converting work for us. The downside is that each new setting added will have to be present on the mapping, but think of it as documentation for your settings!
+Let's add a new class within the main module in ''main.cr'':
+<code ruby>
+class Config
+  YAML.mapping(
+    settings: Hash(String, Int32)
+  )
+end
+</code>
+This will tell Crystal the ''Config'' class is a mapping from YAML that features a ''settings'' key. That key is a ''Hash'' that has ''String'' keys and ''Int32'' values. If in the future we want to add settings with ''String'' values, we can change this to ''Hash(String, Int32 | String)'' but for now number values will suffice.
+With this in place, we need to change the type annotation for the ''@config'' instance variable.
+<code ruby>
+@config : Config
+</code>
+And the parser method needs to be adjusted too:
+<code ruby>
+private def load_config
+  Config.from_yaml(File.read("config.yml"))
+end
+</code>
+Finally, we can access the settings in a less ugly way:
+<code ruby>
+telnet_port = @config.settings["port"]
+</code>
+Much better! This concludes part one of the tutorial, tune in soon for [[tutorials:crystal_bbs:part_two|part two]] where we will be negotiating features with the client! For reference, here's the whole code for the ''src/bbs/main.cr'' file:
+<code ruby>
+require "yaml"
+require "socket"
+module BBS
+  class Config
+    YAML.mapping(
+      settings: Hash(String, Int32)
+    )
+  end
+  class Main
+    @config : Config
+    def initialize
+      @config = load_config
+    end
+    def go!
+      telnet_port = @config.settings["port"]
+      server = TCPServer.new("localhost", telnet_port)
+      puts "now listening in port #{telnet_port}"
+      loop do
+        if socket = server.accept?
+          spawn handle_connection(socket)
+        end
+      end
+    end
+    private def handle_connection(socket)
+      socket << "hello world\n"
+      socket.close
+    end
+    private def load_config
+      Config.from_yaml(File.read("config.yml"))
+    end
+  end
+end
+</code>

fsxNet Wiki

User Tools

Site Tools

Differences

Page Tools