Skip to content

Commit 379778e

Browse files
braindigitalisbraindigitalis
committed
docs for repl shell
1 parent 091ae63 commit 379778e

50 files changed

Lines changed: 1650 additions & 1350 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docpages/user-guide/07_INDEX.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Welcome to Retro Rocket! This guide is for everyone who wants to use the system,
77
- \subpage creating-boot-media
88
- \subpage getting-started
99
- \subpage installation
10-
- \subpage shell
10+
- \subpage desktop-shell
1111
- \subpage file-system
1212
- \subpage commands
1313
- \subpage working-with-programs

‎docpages/user-guide/commands/rocketsh.md‎

Lines changed: 71 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ It is launched by `init` at boot and is always available at the system prompt.
77

88
This page describes `rocketsh` in detail. For a simple overview of using the shell, see @ref desktop-and-shell "The Shell" in the User Guide.
99

10-
#### Command line entry
10+
### Command line entry
1111

1212
The `rocketsh` shell supports command line editing. You may use the cursor `LEFT` and `RIGHT` keys plus `HOME` and `END` to navigate in the current line and edit it, inserting into the line if neccessary.
1313

@@ -19,54 +19,101 @@ Pressing `ESC` will abort the current line entry, clearing its contents and adva
1919

2020
These interactive line editing facilities are also available to any other BASIC programs via the `ansi` library.
2121

22-
#### Rocket Shell Commands
22+
### Rocket Shell Commands
2323

2424
The `rocketsh` shell supports two forms of input; firstly any command you type is searched for as a program under the `/programs` directory. If it can be found it is executed. The path under which `rocketsh` searches for programs to run can be changed, as shown below.
2525

2626
If no matching program can be found, the line is passed to \ref EVAL "EVAL" instead and any changes to the program state will be inherited by `rocketsh`, including documented variables below.
2727

28-
#### Stopping running programs
28+
### BASIC execution
2929

30-
Any running program may be stopped by pressing CTRL+ESC at any time. This will raise an error in the program and if it does not trap the error, it will be ended. Errors of this nature in `rocketsh` are gracefully handled, and will end entry of the current command line.
30+
Any line entered at the prompt which is not resolved to a program is executed using \ref EVAL "EVAL".
3131

32-
#### Shell Variables
32+
This means the shell accepts full BASIC syntax directly at the prompt, including:
3333

34-
The `rocketsh` shell has several documented variables, which can be set via the command prompt. These are:
34+
- Variable assignment
35+
- Expressions
36+
- Procedure and function calls
37+
- Control flow (via multi-line entry)
3538

36-
##### PROMPT$
39+
All built-in BASIC keywords, operators, and functions are available exactly as they are within a BASIC program.
3740

38-
Change `PROMPT$` to change the shell prompt from the default of `ROCKETSH` to the specified value. ANSI escape sequences are supported. You can use `CHR$(27)` to insert the escape chracter:
41+
```basic
42+
A = 10
43+
PRINT A * 2
44+
PROCdemo
45+
```
46+
47+
Single-line input executes in the current shell context.
48+
49+
Multi-line input (see below) executes as an anonymous child program.
50+
51+
Changes made by single-line execution persist in the shell environment.
52+
53+
### Multi-line program entry
54+
55+
`rocketsh` supports entering and executing multi-line BASIC programs directly at the prompt.
56+
57+
- Enter `[` on a new line to begin multi-line entry mode.
58+
- The prompt will change to numbered lines (**1**, **2**, **3**, ...).
59+
- Enter BASIC statements line by line.
60+
- Enter `]` on a new line to execute the program.
61+
- To abort entering a multi-line program without running it, press ESC
62+
- You can use cursor keys to edit and recall previous lines
63+
- Each line you enter becomes part of the rocketsh command history
64+
65+
\image html repl-entry.png
66+
67+
The entered lines are combined and executed using \ref EVAL "EVAL" as an anonymous program.
68+
69+
### Built-in commands
70+
71+
#### cd / chdir
72+
73+
Change the current working directory.
3974

4075
```basic
41-
PROMPT$ = CHR$(27) + "[31mRED PROMPT" + CHR$(27) + "[37m"
76+
cd /harddisk
77+
chdir subdir
4278
```
4379

44-
and this will set the shell prompt to dark red:
80+
* Use `/` at the start to go to an absolute location.
81+
* Without `/`, the path is taken relative to your current location.
82+
83+
#### up
4584

46-
\image html redprompt.png
85+
Move to the parent directory (one level up).
86+
87+
```basic
88+
up
89+
```
4790

48-
##### PATH$
91+
For example, if you are in `/programs/tools`, `up` will take you to `/programs`.
4992

50-
The directory to search in for programs ran at the command prompt. It defaults to `/programs`.
93+
#### run
5194

52-
```BASIC
53-
PATH$ = "/harddisk/progs"
95+
Run a program from the directory set in `PATH$`.
96+
97+
```basic
98+
run myprog
5499
```
55100

56-
##### GLOBAL LIB$
101+
This runs the program named `myprog` from the current program search path.
57102

58-
The `GLOBAL` variable LIB$ is the path that programs will use to load libraries from within BASIC. It defaults to `/programs/libraries` and is set from within `/programs/init` and passed down to `rocketsh`.
103+
#### task
59104

60-
You must remember the `GLOBAL` prefix if you wish for this value to be inherited by BASIC programs.
105+
Run a program from `PATH$` in the background.
61106

62-
```BASIC
63-
GLOBAL LIB$ = "/harddisk/progs/lib"
107+
```basic
108+
task myprog
64109
```
65110

66-
##### EDhist$(x)
111+
The program starts and runs independently, allowing you to continue using the shell.
67112

68-
Returns a value from the edit history. Each time a line is typed into `rocketsh` it is stored into the edit history, with the most recent line stored at array index 0.
113+
#### version
69114

70-
#### EDhistPtr
115+
Display version and copyright information for the shell.
71116

72-
Returns the last array index in the edit history array which contains valid data.
117+
```basic
118+
version
119+
```

‎docpages/user-guide/desktop-and-shell.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
\page shell The Shell
1+
\page desktop-shell The Shell
22

33
When Retro Rocket finishes booting you arrive at the **command shell** (called `rocketsh`).
44
This is a text-based interface where you type commands at a prompt:

‎docs/commands.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -155,8 +155,8 @@ <h3 class="doxsection"><a class="anchor" id="command-reference"></a>
155155
<li><a class="el" href="tree.html">tree command</a></li>
156156
<li><a class="el" href="triangle.html">triangle program</a></li>
157157
<li><a class="el" href="udptest.html#udptest">udptest</a></li>
158-
<li><a class="el" href="up.html">up command</a></li>
159-
<li><a class="el" href="version.html">version command</a></li>
158+
<li><a class="el" href="rocketsh.html#up">up</a></li>
159+
<li><a class="el" href="rocketsh.html#version">version</a></li>
160160
<li><a class="el" href="webserver.html#webserver">webserver</a></li>
161161
<li><a class="el" href="xmtest.html">xmtest command</a> </li>
162162
</ul>

‎docs/desktop-shell.html‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2+
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
3+
<head>
4+
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
5+
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
6+
<meta name="generator" content="Doxygen 1.14.0"/>
7+
<meta name="viewport" content="width=device-width, initial-scale=1"/>
8+
<title>Retro Rocket OS: The Shell</title>
9+
<link href="tabs.css" rel="stylesheet" type="text/css"/>
10+
<script type="text/javascript" src="jquery.js"></script>
11+
<script type="text/javascript" src="dynsections.js"></script>
12+
<script type="text/javascript" src="clipboard.js"></script>
13+
<link href="navtree.css" rel="stylesheet" type="text/css"/>
14+
<script type="text/javascript" src="navtreedata.js"></script>
15+
<script type="text/javascript" src="navtree.js"></script>
16+
<script type="text/javascript" src="cookie.js"></script>
17+
<link href="search/search.css" rel="stylesheet" type="text/css"/>
18+
<script type="text/javascript" src="search/searchdata.js"></script>
19+
<script type="text/javascript" src="search/search.js"></script>
20+
<link href="doxygen.css" rel="stylesheet" type="text/css" />
21+
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
22+
<link href="style.css" rel="stylesheet" type="text/css"/>
23+
</head>
24+
<body>
25+
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
26+
<div id="titlearea">
27+
<table cellspacing="0" cellpadding="0">
28+
<tbody>
29+
<tr id="projectrow">
30+
<td id="projectlogo"><img alt="Logo" src="rr.png"/></td>
31+
<td id="projectalign">
32+
<div id="projectname">Retro Rocket OS
33+
</div>
34+
<div id="projectbrief">BASIC-Powered Operating System</div>
35+
</td>
36+
</tr>
37+
</tbody>
38+
</table>
39+
</div>
40+
<!-- end header part -->
41+
<!-- Generated by Doxygen 1.14.0 -->
42+
<script type="text/javascript">
43+
var searchBox = new SearchBox("searchBox", "search/",'.html');
44+
</script>
45+
<script type="text/javascript">
46+
$(function() { codefold.init(); });
47+
</script>
48+
<script type="text/javascript" src="menudata.js"></script>
49+
<script type="text/javascript" src="menu.js"></script>
50+
<script type="text/javascript">
51+
$(function() {
52+
initMenu('',true,false,'search.php','Search',true);
53+
$(function() { init_search(); });
54+
});
55+
</script>
56+
<div id="main-nav"></div>
57+
</div><!-- top -->
58+
<div id="side-nav" class="ui-resizable side-nav-resizable">
59+
<div id="nav-tree">
60+
<div id="nav-tree-contents">
61+
<div id="nav-sync" class="sync"></div>
62+
</div>
63+
</div>
64+
<div id="splitbar" style="-moz-user-select:none;"
65+
class="ui-resizable-handle">
66+
</div>
67+
</div>
68+
<script type="text/javascript">
69+
$(function(){initNavTree('desktop-shell.html','',''); });
70+
</script>
71+
<div id="container">
72+
<div id="doc-content">
73+
<!-- window showing the filter options -->
74+
<div id="MSearchSelectWindow"
75+
onmouseover="return searchBox.OnSearchSelectShow()"
76+
onmouseout="return searchBox.OnSearchSelectHide()"
77+
onkeydown="return searchBox.OnSearchSelectKey(event)">
78+
</div>
79+
80+
<!-- iframe showing the search results (closed by default) -->
81+
<div id="MSearchResultsWindow">
82+
<div id="MSearchResults">
83+
<div class="SRPage">
84+
<div id="SRIndex">
85+
<div id="SRResults"></div>
86+
<div class="SRStatus" id="Loading">Loading...</div>
87+
<div class="SRStatus" id="Searching">Searching...</div>
88+
<div class="SRStatus" id="NoMatches">No Matches</div>
89+
</div>
90+
</div>
91+
</div>
92+
</div>
93+
94+
<div><div class="header">
95+
<div class="headertitle"><div class="title">The Shell </div></div>
96+
</div><!--header-->
97+
<div class="contents">
98+
<div class="textblock"><p>When Retro Rocket finishes booting you arrive at the <b>command shell</b> (called <span class="tt">rocketsh</span>). This is a text-based interface where you type commands at a prompt:</p>
99+
<div class="image">
100+
<img src="shell.png" alt=""/>
101+
</div>
102+
<p>The shell is the starting point for everything you do in Retro Rocket. From here you can explore files, run BASIC programs, or start writing your own.</p>
103+
<h3 class="doxsection"><a class="anchor" id="using-the-shell"></a>
104+
Using the shell</h3>
105+
<ul>
106+
<li>Type a command at the prompt and press <b>Enter</b>.</li>
107+
<li>Commands that start external programs are generally written in <b>lowercase</b>, so it is obvious you are running an external program.</li>
108+
<li>External programs are looked for in the <span class="tt">/programs</span> directory.</li>
109+
<li>BASIC keywords are always in <b>uppercase</b>.</li>
110+
</ul>
111+
<h3 class="doxsection"><a class="anchor" id="editing-commands"></a>
112+
Editing commands</h3>
113+
<ul>
114+
<li>Use the <b>arrow keys</b> to move through the line and edit it.</li>
115+
<li>Use <b>UP/DOWN</b> arrows to move through recently entered commands.</li>
116+
<li>Pressing <b>ESC</b> clears the current line.</li>
117+
</ul>
118+
<p>These editing features are shared with BASIC programs that use the <span class="tt">ansi</span> library.</p>
119+
<h3 class="doxsection"><a class="anchor" id="more-about-rocketsh"></a>
120+
More about rocketsh</h3>
121+
<p>The shell has its own variables (<span class="tt">PROMPT$</span>, <span class="tt">PATH$</span>, and others) that let you customise it. For details, see the <a class="el" href="rocketsh.html">rocketsh command reference</a>. </p>
122+
</div></div><!-- contents -->
123+
</div><!-- PageDoc -->
124+
</div><!-- doc-content -->
125+
<div id="page-nav" class="page-nav-panel">
126+
<div id="page-nav-resize-handle"></div>
127+
<div id="page-nav-tree">
128+
<div id="page-nav-contents">
129+
</div><!-- page-nav-contents -->
130+
</div><!-- page-nav-tree -->
131+
</div><!-- page-nav -->
132+
</div><!-- container -->
133+
<!-- start footer part -->
134+
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
135+
<ul>
136+
<li class="navelem"><a href="index.html">Retro Rocket OS</a></li><li class="navelem"><a href="user-guide.html">User Guide</a></li>
137+
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.14.0 </li>
138+
</ul>
139+
</div>
140+
</body>
141+
</html>

‎docs/doxygen_crawl.html‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -884,6 +884,10 @@
884884
<a href="delete.html"/>
885885
<a href="delete.html#delete-full-pathname"/>
886886
<a href="demo.html"/>
887+
<a href="desktop-shell.html"/>
888+
<a href="desktop-shell.html#editing-commands"/>
889+
<a href="desktop-shell.html#more-about-rocketsh"/>
890+
<a href="desktop-shell.html#using-the-shell"/>
887891
<a href="dir-full-pathname.html"/>
888892
<a href="dir-full-pathname.html#dir-directory"/>
889893
<a href="dir_13a9d05c4a05693a50c631f2c7a67b45.html"/>
@@ -938,7 +942,7 @@
938942
<a href="glossary.html#network-interface"/>
939943
<a href="glossary.html#pixel-art"/>
940944
<a href="glossary.html#program"/>
941-
<a href="glossary.html#prompt-1"/>
945+
<a href="glossary.html#prompt"/>
942946
<a href="glossary.html#prompt-string"/>
943947
<a href="glossary.html#ram-disk"/>
944948
<a href="glossary.html#retrofs"/>
@@ -1097,15 +1101,16 @@
10971101
<a href="rmdir.html"/>
10981102
<a href="rmdir.html#rmdir-full-pathname"/>
10991103
<a href="rocketsh.html"/>
1104+
<a href="rocketsh.html#basic-execution"/>
1105+
<a href="rocketsh.html#built-in-commands"/>
1106+
<a href="rocketsh.html#cd--chdir"/>
11001107
<a href="rocketsh.html#command-line-entry"/>
1101-
<a href="rocketsh.html#edhistptr"/>
1102-
<a href="rocketsh.html#edhistx"/>
1103-
<a href="rocketsh.html#global-lib"/>
1104-
<a href="rocketsh.html#path"/>
1105-
<a href="rocketsh.html#prompt"/>
1108+
<a href="rocketsh.html#multi-line-program-entry"/>
11061109
<a href="rocketsh.html#rocket-shell-commands"/>
1107-
<a href="rocketsh.html#shell-variables"/>
1108-
<a href="rocketsh.html#stopping-running-programs"/>
1110+
<a href="rocketsh.html#run"/>
1111+
<a href="rocketsh.html#task"/>
1112+
<a href="rocketsh.html#up"/>
1113+
<a href="rocketsh.html#version"/>
11091114
<a href="saving-your-work.html"/>
11101115
<a href="saving-your-work.html#installed-system"/>
11111116
<a href="saving-your-work.html#livecd-mode"/>
@@ -1118,10 +1123,6 @@
11181123
<a href="servertest.html#servertest"/>
11191124
<a href="servertest.html#usage-1"/>
11201125
<a href="servertest.html#what-it-does-1"/>
1121-
<a href="shell.html"/>
1122-
<a href="shell.html#editing-commands"/>
1123-
<a href="shell.html#more-about-rocketsh"/>
1124-
<a href="shell.html#using-the-shell"/>
11251126
<a href="sine.html"/>
11261127
<a href="socktest.html"/>
11271128
<a href="sound-and-graphics.html"/>

‎docs/glossary.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ <h3 class="doxsection"><a class="anchor" id="mount"></a>
118118
<h3 class="doxsection"><a class="anchor" id="program"></a>
119119
Program</h3>
120120
<p>A file written in BASIC that Retro Rocket can run. Programs live in <span class="tt">/programs</span>.</p>
121-
<h3 class="doxsection"><a class="anchor" id="prompt-1"></a>
121+
<h3 class="doxsection"><a class="anchor" id="prompt"></a>
122122
Prompt</h3>
123123
<p>The <span class="tt">&gt;</span> symbol you see in the shell where you type commands.</p>
124124
<h3 class="doxsection"><a class="anchor" id="ram-disk"></a>

‎docs/navtreeindex1.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ var NAVTREEINDEX1 =
88
"cube.html":[0,7,10],
99
"delete.html":[0,7,11],
1010
"demo.html":[0,7,12],
11+
"desktop-shell.html":[0,5],
1112
"dir-full-pathname.html":[0,7,13],
1213
"edit.html":[0,7,14],
1314
"edit.html#editing-text":[0,7,14,0,2],
@@ -60,7 +61,6 @@ var NAVTREEINDEX1 =
6061
"saving-your-work.html":[0,11],
6162
"search.html":[0,7,34],
6263
"servertest.html":[0,7,36],
63-
"shell.html":[0,5],
6464
"sine.html":[0,7,35],
6565
"socktest.html":[0,7,37],
6666
"sound-and-graphics.html":[0,9],

‎docs/repl-entry.png‎

6.62 KB
Loading

0 commit comments

Comments
 (0)