From b61ee25ee7e922b36bb4ae6d505a5f6cbe5b23e6 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Thu, 12 Mar 2015 15:35:13 +0100 Subject: Update Getting Started Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Hans Bolinder. --- system/doc/getting_started/records_macros.xml | 88 ++++++++++++++------------- 1 file changed, 46 insertions(+), 42 deletions(-) (limited to 'system/doc/getting_started/records_macros.xml') diff --git a/system/doc/getting_started/records_macros.xml b/system/doc/getting_started/records_macros.xml index 73c8ce5c8d..bec751fea2 100644 --- a/system/doc/getting_started/records_macros.xml +++ b/system/doc/getting_started/records_macros.xml @@ -29,27 +29,32 @@ record_macros.xml

Larger programs are usually written as a collection of files with - a well defined interface between the various parts.

+ a well-defined interface between the various parts.

The Larger Example Divided into Several Files -

To illustrate this, we will divide the messenger example from - the previous chapter into five files.

- - mess_config.hrl - header file for configuration data - mess_interface.hrl - interface definitions between the client and the messenger - user_interface.erl - functions for the user interface - mess_client.erl - functions for the client side of the messenger - mess_server.erl - functions for the server side of the messenger - -

While doing this we will also clean up the message passing - interface between the shell, the client and the server and define - it using records, we will also introduce macros.

+

To illustrate this, the messenger example from + the previous section is divided into the following five files:

+ + +

mess_config.hrl

+

Header file for configuration data

 + +

mess_interface.hrl

+

Interface definitions between the client and the messenger

 + +

user_interface.erl

+

Functions for the user interface

 + +

mess_client.erl

+

Functions for the client side of the messenger

 + +

mess_server.erl

+

Functions for the server side of the messenger

 + +

While doing this, the message passing interface between the shell, + the client, and the server is cleaned up and is defined + using records. Also, macros are introduced:

%%%----FILE mess_config.hrl---- @@ -244,14 +249,14 @@ server_transfer(From, Name, To, Message, User_List) ->
Header Files -

You will see some files above with extension .hrl. These - are header files which are included in the .erl files by:

+

As shown above, some files have extension .hrl. These + are header files that are included in the .erl files by:

-include("File_Name").

for example:

-include("mess_interface.hrl"). -

In our case above the file is fetched from the same directory as +

In the case above the file is fetched from the same directory as all the other files in the messenger example. (*manual*).

.hrl files can contain any valid Erlang code but are most often used for record and macro definitions.

@@ -265,64 +270,63 @@ server_transfer(From, Name, To, Message, User_List) ->

For example:

-record(message_to,{to_name, message}). -

This is exactly equivalent to:

+

This is equivalent to:

{message_to, To_Name, Message} -

Creating record, is best illustrated by an example:

+

Creating a record is best illustrated by an example:

#message_to{message="hello", to_name=fred) -

This will create:

+

This creates:

{message_to, fred, "hello"} -

Note that you don't have to worry about the order you assign +

Notice that you do not have to worry about the order you assign values to the various parts of the records when you create it. The advantage of using records is that by placing their definitions in header files you can conveniently define - interfaces which are easy to change. For example, if you want to - add a new field to the record, you will only have to change + interfaces that are easy to change. For example, if you want to + add a new field to the record, you only have to change the code where the new field is used and not at every place the record is referred to. If you leave out a field when creating - a record, it will get the value of the atom undefined. (*manual*)

+ a record, it gets the value of the atom undefined. (*manual*)

Pattern matching with records is very similar to creating records. For example, inside a case or receive:

#message_to{to_name=ToName, message=Message} -> -

is the same as:

+

This is the same as:

{message_to, ToName, Message}
Macros -

The other thing we have added to the messenger is a macro. +

Another thing that has been added to the messenger is a macro. The file mess_config.hrl contains the definition:

%%% Configure the location of the server node, -define(server_node, messenger@super). -

We include this file in mess_server.erl:

+

This file is included in mess_server.erl:

-include("mess_config.hrl").

Every occurrence of ?server_node in mess_server.erl - will now be replaced by messenger@super.

-

The other place a macro is used is when we spawn the server - process:

+ is now replaced by messenger@super.

+

A macro is also used when spawning the server process:

spawn(?MODULE, server, []) -

This is a standard macro (i.e. defined by the system, not - the user). ?MODULE is always replaced by the name of - current module (i.e. the -module definition near the start +

This is a standard macro (that is, defined by the system, not by + the user). ?MODULE is always replaced by the name of the + current module (that is, the -module definition near the start of the file). There are more advanced ways of using macros with, - for example parameters (*manual*).

+ for example, parameters (*manual*).

The three Erlang (.erl) files in the messenger example are individually compiled into object code file (.beam). The Erlang system loads and links these files into the system - when they are referred to during execution of the code. In our - case we simply have put them in the same directory which is our - current working directory (i.e. the place we have done "cd" to). + when they are referred to during execution of the code. In this + case, they are simply put in our current working directory + (that is, the place you have done "cd" to). There are ways of putting the .beam files in other directories.

In the messenger example, no assumptions have been made about - what the message being sent is. It could be any valid Erlang term.

+ what the message being sent is. It can be any valid Erlang term.

-- cgit v1.2.3