12008-07-14
2
3	Command parsing
4
5Command parsing results in a list of "pipe" structures.
6This list correspond not only to usual "pipe1 || pipe2 && pipe3"
7lists, but it also controls execution of if, while, etc statements.
8Every such statement is a list for hush. List consists of pipes.
9
10struct pipe fields:
11  smallint res_word - "none" for normal commands,
12                      "if" for if condition etc
13  struct child_prog progs[] - array of commands in pipe
14  smallint followup - how this pipe is related to next: is it
15                      "pipe; pipe", "pipe & pipe" "pipe && pipe",
16                      "pipe || pipe"?
17
18Blocks of commands { pipe; pipe; } and (pipe; pipe) are represented
19as one pipe struct with one progs[0] element which is a "group" -
20struct child_prog can contain a list of pipes. Sometimes these
21"groups" are created implicitly, e.g. every control
22statement (if, while, etc) sits inside its own group.
23
24res_word controls statement execution. Examples:
25
26"echo Hello" -
27pipe 0 res_word=NONE followup=SEQ prog[0] 'echo' 'Hello'
28pipe 1 res_word=NONE followup=SEQ
29
30"echo foo || echo bar" -
31pipe 0 res_word=NONE followup=OR  prog[0] 'echo' 'foo'
32pipe 1 res_word=NONE followup=SEQ prog[0] 'echo' 'bar'
33pipe 2 res_word=NONE followup=SEQ
34
35"if true; then echo Hello; true; fi" -
36res_word=NONE followup=SEQ
37 prog 0 group {}:
38  pipe 0 res_word=IF followup=SEQ prog[0] 'true'
39  pipe 1 res_word=THEN followup=SEQ prog[0] 'echo' 'Hello'
40  pipe 2 res_word=THEN followup=SEQ prog[0] 'true'
41  pipe 3 res_word=FI followup=SEQ
42  pipe 4 res_word=NONE followup=(null)
43pipe 1 res_word=NONE followup=SEQ
44
45Above you see that if is a list, and it sits in a {} group
46implicitly created by hush. Also note two THEN res_word's -
47it is explained below.
48
49"if true; then { echo Hello; true; }; fi" -
50pipe 0 res_word=NONE followup=SEQ
51 prog 0 group {}:
52  pipe 0 res_word=IF followup=SEQ prog[0] 'true'
53  pipe 1 res_word=THEN followup=SEQ
54   prog 0 group {}:
55    pipe 0 res_word=NONE followup=SEQ prog[0] 'echo' 'Hello'
56    pipe 1 res_word=NONE followup=SEQ prog[0] 'true'
57    pipe 2 res_word=NONE followup=SEQ
58  pipe 2 res_word=NONE followup=(null)
59pipe 1 res_word=NONE followup=SEQ
60
61"for v in a b; do echo $v; true; done" -
62pipe 0 res_word=NONE followup=SEQ
63 prog 0 group {}:
64  pipe 0 res_word=FOR followup=SEQ prog[0] 'v'
65  pipe 1 res_word=IN followup=SEQ prog[0] 'a' 'b'
66  pipe 2 res_word=DO followup=SEQ prog[0] 'echo' '$v'
67  pipe 3 res_word=DO followup=SEQ prog[0] 'true'
68  pipe 4 res_word=DONE followup=SEQ
69  pipe 5 res_word=NONE followup=(null)
70pipe 1 res_word=NONE followup=SEQ
71
72Note how "THEN" and "DO" does not just mark the first pipe,
73it "sticks" to all pipes in the body. This is used when
74hush executes parsed pipes.
75
76Dummy trailing pipes with no commands are artifacts of imperfect
77parsing algorithm - done_pipe() appends new pipe struct beforehand
78and last one ends up empty and unused.
79
80"for" and "case" statements (ab)use progs[] to keep their data
81instead of argv vector progs[] usually do. "for" keyword is forcing
82pipe termination after first word, which makes hush see
83"for v in..." as "for v; in...". "case" keyword does the same.
84Other judiciuosly placed hacks make hush see
85"case word in a) cmd1;; b) cmd2;; esac" as if it was
86"case word; match a; cmd; match b; cmd2; esac"
87("match" is a fictitious keyword here):
88
89"case word in a) cmd1;; b) cmd2; esac" -
90pipe 0 res_word=NONE followup=1 SEQ
91 prog 0 group {}:
92  pipe 0 res_word=CASE followup=SEQ prog[0] 'word'
93  pipe 1 res_word=MATCH followup=SEQ prog[0] 'a'
94  pipe 2 res_word=CASEI followup=SEQ prog[0] 'cmd1'
95  pipe 3 res_word=MATCH followup=SEQ prog[0] 'b'
96  pipe 4 res_word=CASEI followup=SEQ prog[0] 'cmd2'
97  pipe 5 res_word=CASEI followup=SEQ prog[0] 'cmd3'
98  pipe 6 res_word=ESAC followup=SEQ
99  pipe 7 res_word=NONE followup=(null)
100pipe 1 res_word=NONE followup=SEQ
101
102
1032008-01
104
105	Command execution
106
107/* callsite: process_command_subs */
108generate_stream_from_list(struct pipe *head) - handles `cmds`
109  create UNIX pipe
110  [v]fork
111  child:
112  redirect pipe output to stdout
113  _exit(run_list(head));   /* leaks memory */
114  parent:
115  return UNIX pipe's output fd
116  /* head is freed by the caller */
117
118/* callsite: parse_and_run_stream */
119run_and_free_list(struct pipe *)
120  run_list(struct pipe *)
121  free_pipe_list(struct pipe *)
122
123/* callsites: generate_stream_from_list, run_and_free_list, pseudo_exec, run_pipe */
124run_list(struct pipe *) - handles "cmd; cmd2 && cmd3", while/for/do loops
125  run_pipe - for every pipe in list
126
127/* callsite: run_list */
128run_pipe - runs "cmd1 | cmd2 | cmd3 [&]"
129  run_list - used if only one cmd and it is of the form "{cmds;}"
130  forks for every cmd if more than one cmd or if & is there
131  pseudo_exec - runs each "cmdN" (handles builtins etc)
132
133/* callsite: run_pipe */
134pseudo_exec - runs "cmd" (handles builtins etc)
135  exec - execs external programs
136  run_list - used if cmdN is "(cmds)" or "{cmds;}"
137  /* problem: putenv's malloced strings into environ -
138  ** with vfork they will leak into parent process
139  */
140  /* problem with ENABLE_FEATURE_SH_STANDALONE:
141  ** run_applet_no_and_exit(a, argv) uses exit - this can interfere
142  ** with vfork - switch to _exit there?
143  */
144