added check for connected when triggered method is called. can't trigger
[urisagit/Stem.git] / DEMO
CommitLineData
4536f655 1
2 Stem Demonstration Scripts
3
4Stem comes with several demonstration scripts and example configuration
5files which are used by them. You can optionally install the executable
6demonstrations and their configuration files. Note that the actual
7demonstration scripts don't do anything special to Stem, they just
8create windows and execute run_stem inside them with selected
9configuration files. They also create telnet connections inside other
10windows which you can use to interact with Stem. You can manually create
11the windows and do the same commands, these scripts are just
12conveniences. In fact, a good way to learn more about Stem is to copy
13and modify the configuration files used in the demonstrations and run
14them yourself.
15
16When you run any of the demo scripts, the commands used to fork off an
17xterm are printed. You can manually run those commands in your own
18terminal windows if you want to experiment with or explore the Stem
19configurations. If you kill the script (e.g. with ^C), all the created
20xterm windows will be killed off leaving you with a cleaned up desktop.
21
22There are 4 demonstration scripts that come with Stem. They are briefly
23described here and in more detail in other files. They all have some
24common 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
45Using the console Cell Stem::TtyMsg
46
47All of the demo configurations include the Stem::TtyMsg module which
48allows you to enter command messages from the keyboard to a running Stem
49Hub (process). This module is not required to run Stem but it is in the
50demo configurations so you can interact with Stem and learn more about
51it.
52
53It reads lines from STDIN (using the Stem::AsyncIO module so the rest of
54the Stem Hub continues to run), parses them and sends out a command
55messages based on the lines. It also can set key/values in the local
56Hub's environment (%Stem::Vars::Env) which is used to control many Stem
57operations.
58
59Command messages can generate response messages which will be sent back
60to the TtyMsg Cell. These responses will be printed to STDOUT (again,
61using the Stem::AsyncIO module). Any Cell can just send a data message
62to the TtyMsg Cell (which is also registered with the class Cell name
63tty) and its data will get printed.
64
65The rules for parsing lines input to TtyMsg are very simple. There are
66three 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