haas/fall2026/unix/projects/upf1.md
... ...
@@ -0,0 +1,273 @@
1
+# CSCS1730 UNIX/Linux Fundamentals
2
+
3
+# PROJECT: UNIX PIPE FUN (upf1)
4
+
5
+## ERRATA
6
+
7
+ * revision #: <description> (DATESTAMP)
8
+
9
+## OBJECTIVE
10
+
11
+To continue to cultivate your problem solving skills, to practice your
12
+shell skills, and to demonstrate your basic scripting skills.
13
+
14
+## BACKGROUND
15
+
16
+Pipes and command expansions are important concepts and skills that you
17
+need to be familiar with as we proceed down the shell scripting rabbit
18
+hole.
19
+
20
+This project has us playing with various examples that will require
21
+regular use of these skills, for the purpose of converting units.
22
+
23
+## GET STARTED
24
+
25
+This week's project has 2 points of origin.
26
+
27
+First, in the **upf1/** sub-directory of the UNIX Public Directory,
28
+under a directory by the name of your username, you will find the
29
+following file:
30
+
31
+ * **TASK**
32
+
33
+Copy this file into your project directory.
34
+
35
+The **TASK** file will contain the particular units to start with and
36
+convert to.
37
+
38
+Next, you will want to grab the latest version of the **unittools**
39
+suite from the following URL:
40
+
41
+ * https://lab46.g7n.org/~wedge/projects/unittools/
42
+
43
+You will want to use a tool like **wget(1)** or **curl(1)** to
44
+non-interactively download it onto your lab46 account, and similarly
45
+extract, compile, and install that (check its own README file).
46
+
47
+There may be multiple versions of **unittools** available at the
48
+download link. Unless you have specific reason otherwise (for this
49
+project, you do not), you want to go for the latest version, which will
50
+be reflected by the most recent datestamp encoded in the file's name.
51
+
52
+For example, say you have the following:
53
+
54
+ * unittools-20160731-10.tar.gz
55
+ * unittools-20161024-14.tar.gz
56
+ * unittools-20170123-13.tar.gz
57
+ * unittools-20170201-09.tar.gz
58
+
59
+From visual inspection, you would select the "20170201-09" one, because
60
+the date it encodes (Feb 1st, 2017 at 9am) is the most recent in that
61
+group. You will find this to be a common practice with many software
62
+projects on the internet.
63
+
64
+Note, however, that visual inspection alone is not good enough for your
65
+steps file. New versions may be released, and your steps file needs to
66
+obtain the most recent version available. To facilitate this task, the
67
+latest and greatest version of unittools will be listed in a file called
68
+**LATEST** (which you should see near the top of the directory index
69
+listing). You can make use of this file to assist you in automating the
70
+process of determining and downloading the latest version of the
71
+unittools tools.
72
+
73
+Once those two steps are complete, you can begin on the tasks listed in
74
+your **TASK** file.
75
+
76
+### UNITTOOLS SUITE
77
+
78
+The unittools suite is a collection of command-line tools that perform
79
+various unit conversions you may find useful for this project. The tools
80
+include:
81
+
82
+ * **cm2in** - convert centimeters to inches
83
+ * **cu2mm** - convert cubits to millimeters
84
+ * **dm2cm** - convert decimeters to centimeters
85
+ * **Dm2mi** - convert Decameters to miles
86
+ * **ft2hm** - convert feet to hectometers
87
+ * **ft2yd** - convert feet to yards
88
+ * **hm2dm** - convert hectometers to decimeters
89
+ * **hm2Dm** - convert hectometers to Decameters (if not available,
90
+ use **hm2dcm** instead)
91
+ * **in2cu** - convert inches to cubits
92
+ * **in2ft** - convert inches to feet
93
+ * **km2ft** - convert kilometers to feet
94
+ * **mi2km** - convert miles to kilometers
95
+ * **mi2yd** - convert miles to yards
96
+ * **mm2dm** - convert millimeters to decimeters
97
+ * **st2mi** - convert stadions to miles
98
+ * **yd2mi** - convert yards to miles
99
+ * **yd2st** - convert yards to stadions
100
+
101
+The tools by default expect input via STDIN, and will output to STDOUT.
102
+
103
+These tools have command-line arguments which can alter their default
104
+behavior. You may want to review the options and defaults (try running
105
+them with the **-h** argument to see what sort of functionality is
106
+available).
107
+
108
+## PROCESS
109
+
110
+In the **TASK** file, you will be given a set of source quantities/units
111
+and destination units you need to construct command-lines for to solve,
112
+using the tools provided to you in the **unittools** suite. You will
113
+also want to make use of pipes and command expansions in your solutions.
114
+
115
+As an example, take the following (formatted as it would appear in your
116
+**TASK** file):
117
+
118
+```
119
+task: 0
120
+precision: 3
121
+input_value: 35
122
+input_unit: cm
123
+output_unit: ft
124
+chain_delim: " >> "
125
+```
126
+
127
+With these in mind, we can set about solving this problem, using the
128
+tools in combination to arrive at the desired result.
129
+
130
+A potential solution would be as follows:
131
+
132
+```
133
+lab46:~/src/SEMESTER/unix/upf1$ echo "35" | cm2in
134
+13.78 in
135
+lab46:~/src/SEMESTER/unix/upf1$ echo "13.78" | in2ft
136
+1.15 ft
137
+lab46:~/src/SEMESTER/unix/upf1$
138
+```
139
+
140
+But that's not very optimized. We could instead do something better,
141
+like:
142
+
143
+```
144
+lab46:~/src/SEMESTER/unix/upf1$ echo "35.000 cm" | cm2in OPTIONS | in2ft OPTIONS
145
+35.000 cm >> 13.780 in >> 1.148 ft
146
+lab46:~/src/SEMESTER/unix/upf1$
147
+```
148
+
149
+Note that with **precision**, you need to instruct the tools to display
150
+out to the specified number of decimal places.
151
+
152
+We'll want to record our command-lines in the appropriate place. Since
153
+this is task #0, we'll want to record it in a file called:
154
+**task0.cli**, which should basically just contain the command-lines you
155
+ran, merely placed in a text file.
156
+
157
+For final output, we'll want to display the chain of conversions we went
158
+through. So, for the above example:
159
+
160
+```
161
+lab46:~/src/SEMESTER/unix/upf1$ ./task0.cli
162
+35.000cm >> 13.780in >> 1.148ft
163
+lab46:~/src/SEMESTER/unix/upf1$
164
+```
165
+
166
+Basically, each task#.cli will be its own script. If we were to execute
167
+it, the correct result should be produced.
168
+
169
+## UPF1STEPS
170
+
171
+You will once again be creating a steps file that can automate your
172
+project (ie it contains a list of non-interactive steps to complete the
173
+task).
174
+
175
+As in previous projects, **upf1steps** will contain the steps you took
176
+from the point of creating your project directory, copying the **TASK**
177
+file, and downloading the unittools suite, up until the submit step
178
+(hint: just run the task#.cli scripts within the steps script).
179
+
180
+To clarify: YES, I want to see steps creating a project directory,
181
+copying and downloading files in question, extracting, compiling,
182
+installing, and then of course running each individual task#.cli script.
183
+
184
+There are some additional constraints you need to keep in mind:
185
+
186
+ * your script should not produce ANY STDERR output
187
+ * your script should ONLY produce STDOUT output in conformance with the
188
+ below stated requirements. Any other output needs to be silenced.
189
+ * You will want one unified command-line producing the end result, not
190
+ separate one-step transitions. The idea is to utilize pipes.
191
+ * semi-colons used to separate commands do not constitute one
192
+ command-line, but several.
193
+ * For each task, you'll want to display things as follows:
194
+ * "Task X conversion chain: CHAIN"
195
+ * where X is the task number (0, 1, 2, etc.)
196
+ * where CHAIN is the conversion chain output matching the TASK file
197
+ result requested (ie, you must run your task#.cli script to
198
+ produce this output).
199
+ * note that the task#.cli output appears on the SAME line as the
200
+ "Task X conversion chain:" text, and there is a single space
201
+ separating it from the colon.
202
+ * there is NO space between value and unit
203
+
204
+For example, a sample output of your **upf1steps** script should appear
205
+as follows (but your # values will of course be different based on your
206
+individual **TASK** file):
207
+
208
+```
209
+lab46:~/src/SEMESTER/unix/upf1$ ./upf1steps
210
+Task 0 conversion chain: 35.000cm >> 13.780in >> 1.148ft
211
+...
212
+lab46:~/src/SEMESTER/unix/upf1$
213
+```
214
+
215
+## SUBMISSION
216
+
217
+By successfully performing this project, you should have a set of
218
+`task#.cli` files (one for each task). You will want to submit these,
219
+along with a **upf1steps** file.
220
+
221
+### SUBMIT TOOL USAGE
222
+
223
+To submit this project to me using the **submit** tool, run the
224
+following command at your lab46 prompt:
225
+
226
+```
227
+$ submit unix upf1 upf1steps task*.cli
228
+Submitting unix project "upf1":
229
+ -> upf1steps(OK)
230
+ -> task0.cli(OK)
231
+ -> task1.cli(OK)
232
+ -> task2.cli(OK)
233
+ -> task3.cli(OK)
234
+ ...
235
+
236
+SUCCESSFULLY SUBMITTED
237
+```
238
+
239
+You should get some sort of confirmation indicating successful
240
+submission if all went according to plan. If not, check for typos and or
241
+locational mismatches.
242
+
243
+### RUBRIC
244
+
245
+I'll be looking for the following:
246
+
247
+```
248
+234:upf1:final tally of results (234/234)
249
+*:upf1:upf1steps has valid list of non-interactive instructions [13/13]
250
+*:upf1:upf1steps only modifies files if USER matches [13/13]
251
+*:upf1:upf1steps builds the various task#.cli files it runs [13/13]
252
+*:upf1:upf1steps obtains the latest unittools release from site [13/13]
253
+*:upf1:upf1steps only displays specified STDOUT output [13/13]
254
+*:upf1:upf1steps errorlessly creates local project directory [13/13]
255
+*:upf1:upf1steps makes clear, effective use of wildcards [13/13]
256
+*:upf1:upf1steps defines and uses custom variables [13/13]
257
+*:upf1:upf1steps uses command expansions to get information [13/13]
258
+*:upf1:upf1steps uses a loop to drive numbers in final output [13/13]
259
+*:upf1:upf1steps automates the task when run [13/13]
260
+*:upf1:all files are organized, clear, and easy to read [13/13]
261
+*:upf1:task#.cli files output using specified precision [13/13]
262
+*:upf1:task#.cli files output using specified delimiter [13/13]
263
+*:upf1:task#.cli files output only correct value and unit, in format [13/13]
264
+*:upf1:task#.cli files display no STDERR output [13/13]
265
+*:upf1:task#.cli files have solution within given constraints [13/13]
266
+*:upf1:task#.cli files only contain the solution command-line [13/13]
267
+```
268
+
269
+Additionally:
270
+ * Solutions not abiding by spirit of project will be subject to a 25% overall deduction
271
+ * Solutions not utilizing descriptive why and how comments will be subject to a 25% overall deduction
272
+ * Solutions not utilizing indentation to promote scope and clarity will be subject to a 25% overall deduction
273
+ * Solutions not organized and easy to read (within 90 char width) are subject to a 25% overall deduction