cleaned up demo scripts locations
[urisagit/Stem.git] / demo / DEMO
1
2                        Stem Demonstration Scripts
3
4 Stem comes with several demonstration scripts and example configuration
5 files which are used by them. You can optionally install the executable
6 demonstrations and their configuration files.  Note that the actual
7 demonstration scripts don't do anything special to Stem, they just
8 create windows and execute run_stem inside them with selected
9 configuration files. They also create telnet connections inside other
10 windows which you can use to interact with Stem. You can manually create
11 the windows and do the same commands, these scripts are just
12 conveniences. In fact, a good way to learn more about Stem is to copy
13 and modify the configuration files used in the demonstrations and run
14 them yourself.
15
16 When you run any of the demo scripts, the commands used to fork off an
17 xterm are printed. You can manually run those commands in your own
18 terminal windows if you want to experiment with or explore the Stem
19 configurations. If you kill the script (e.g. with ^C), all the created
20 xterm windows will be killed off leaving you with a cleaned up desktop.
21
22 There are 4 demonstration scripts that come with Stem. They are briefly
23 described here and in more detail in other files. They all have some
24 common features which are also described in detail below.
25
26         chat_demo and chat2_demo demonstrate a simple 4 user chat
27         server. chat_demo runs with a single Stem Hub and chat2_demo
28         uses 2 Hubs. Both bring up an xterm for each Stem Hub and 4 more
29         for the telnet sessions. Read DEMO_CHAT for the full details on
30         how to use this demo.
31
32         inetd_demo emulates the inetd Unix super-daemon. It runs a
33         single Stem Hub in an xterm and 4 telnet sessions each in their
34         own xterm. The server process it runs is proc_serv in the bin
35         directory. You can run it directly from the command to see how
36         it behaves (it is a simple command/response program).  Read
37         DEMO_INETD for the full details on how to use this demo.
38
39         tail_demo monitors a typical log file and copies any new data it
40         finds there to a Stem Logical Log which writes it to a file and
41         optionally to other destinations. The status of the source file
42         is also sent to a Logical Log.  Read DEMO_TAIL for the full
43         details on how to use this demo.
44
45 Using the console Cell Stem::TtyMsg
46
47 All of the demo configurations include the Stem::TtyMsg module which
48 allows you to enter command messages from the keyboard to a running Stem
49 Hub (process). This module is not required to run Stem but it is in the
50 demo configurations so you can interact with Stem and learn more about
51 it.
52
53 It reads lines from STDIN (using the Stem::AsyncIO module so the rest of
54 the Stem Hub continues to run), parses them and sends out a command
55 messages based on the lines. It also can set key/values in the local
56 Hub's environment (%Stem::Vars::Env) which is used to control many Stem
57 operations.
58
59 Command messages can generate response messages which will be sent back
60 to the TtyMsg Cell. These responses will be printed to STDOUT (again,
61 using the Stem::AsyncIO module). Any Cell can just send a data message
62 to the TtyMsg Cell (which is also registered with the class Cell name
63 tty) and its data will get printed.
64
65 The rules for parsing lines input to TtyMsg are very simple. There are
66 three kinds of command lines:
67
68         Direct commands
69
70                 The only direct command is 'help' which has to be the
71                 only token on the line. It causes the help text to be
72                 printed.
73
74         Setting a Stem environment variable
75
76                 Key/values in the local Hub's environment can be set
77                 with lines of the form:
78
79                         name=value
80
81                 Token has to be only word characters ([a-zA-Z0-9_]) and
82                 the string after the = is the value (stripped of
83                 surrounding white space). The Hub environment variable
84                 with the name token is set to the parsed value. The
85                 token and value are printed.
86
87                 You can also set any environment variable in any remote
88                 Hub with the command message:
89
90                         hub:var set_env name=value 
91
92                 Note that 'hub' must be the real name of that Stem Hub,
93                 and var is already the registered class name of the
94                 Stem::Vars class Cell.
95
96                 See below for more on entering command messages and the
97                 env_notes document in /Design.
98
99         Sending a Command Message
100
101                 A command message line starts with a Cell address and
102                 then must have a command token. The rest of the line is
103                 optional data for the command message.  A minimal Cell
104                 address is just a Cell name. It can have an optional Hub
105                 name prefix. Also a target name can be suffixed after a
106                 trailing :. So the only legal Cell addresses look like
107                 this:
108
109                         cell
110                         hub:cell
111                         :cell:target
112                         hub:cell:target
113
114                 If the Hub is missing the message is destined for the
115                 local Hub and if the Cell doesn't exist here, it is
116                 routed to the DEFAULT Hub. Read the Cell and Message
117                 technical note for more on this.
118
119                 The next token on a message command line is the command
120                 name and it is required. It will be the value of the
121                 'cmd' field in the message. The rest of the line is used
122                 as the data field of the message.
123
124                 Some uses of command line messages are getting the
125                 status of various Class Cells since almost all of them
126                 have a status command. By listing all the registered
127                 Cells you can see which ones you can send messages to.
128
129                 This will print all of the Cells in this hub. The
130                 listing shows all object Cell and Class Cells with their
131                 aliases. Command line messages should use the aliases
132                 for the Cell name as the class names have colons in
133                 them.
134
135                 This will print all of the Cells in the local hub.
136
137                         reg status
138
139                 This will print all of the Cells in the hub named remote.
140
141                         remote:reg status
142
143                 This will print all of the Portals in this hub. You can
144                 use their hub names to send command messages to those
145                 hubs.
146
147                         port status
148
149                 If you are running either chat demo you can change the
150                 Switch maps which control which user get sent chat
151                 messages. Here are some examples. The Switch Cell is
152                 named sw, and the two Hubs in chat2_demo are named
153                 chat_client and chat_server. Note that the 'sw' Cell is
154                 only in the server Hub in chat2_demo, but since no 'sw'
155                 Cell exists in the client Hub, any message sent to 'sw'
156                 will still go to the server hub. So all of these map
157                 commands can be issued from either Hub input and they
158                 will work. The 'map' or 'status' token is the command
159                 and the tokens after 'map' are data to the map
160                 command. The first data token is the input map you are
161                 setting and the rest of the tokens are the output maps
162                 to send chat messages to.
163
164                 Print the current maps.
165
166                         sw status
167
168                 Change the a map to just b.
169
170                         sw map a b
171
172                 Change the d map to all users.
173
174                         sw map d a b c d