NOTES

== SOURCES ==

POSIX.1-2008 / IEEE Std 1003.1-2008 / Open Group Base Specifications Issue 7
    http://pubs.opengroup.org/onlinepubs/9699919799/toc.htm
    http://pubs.opengroup.org/onlinepubs/9699919799/nframe.html



== TODO ==
[] summary information should come from utilAnnotate, not annotate

[] add completion support

[] styling
    [] when to use monospace, when not?
    [] is OpenSans worth the load time and internet dependence?
    
[] setAnno needs writing...

[] need to capture control-c now! (or implement exit)



[] ls w/json out

[] rename recho to args
[] rationalize exit codes

[] export some bracket like function to work with exceptions
  [] also some ignoreErrors like function

>> execute based on type
    [] properly handle variable assignments
    [] property handle redirections that on specials (or at least flag 'em)

[] built-ins that default to external command execution

[] set -j for jsonin, jsonout pipes (as well as STDJSON env var. to signal)
    [] or should we just always do it?

[] input handling (how?)

[] pseudo-tty for in/out
    [] but if we do this, we won't be able to tell stdout from stderr?

[] normalize where to import <$> form: Data.Functor or Control.Applicative
    [] use it instead of fmap (or even liftM?) on monadic actions




== POSIX Shell Features ==

P = Parsing implemented
E = Execution implemented (Et = in test mode, Er = in real mode)
D = DocTest written
u = unlikely to be implemented

command lists
PEt     basic sequencing
P-      last command w/semi-colon and w/o
PEt     one command, mutliple
P       sequential vs. background

and/or lists
P       linebreaks after operators
PEtD    two operators
PEt     inversion of pipeline value

pipelines
P       linebreaks after pipes

command
P-      assignment suffling
P-      redirect shuffling
PEtD    simple arguments
P-D     single quoted arguments
P-D     backslash arguments
        double quotes
        backquotes
        $ substitutions

compound commands
        brace groups
        subshells
        for
        case
        if
        while / until

features
        functions
        alias
        special parameters
        variables
        special variables
PED     redirection
        here documents
PED     pipelines
 E      program execution

word expansions
-ED     tilde expansion
PED     parameter expansion - simple
        parameter expansion - expression
        parameter expansion - pattern
        command substitution
        arithmetic expansion
-ED     field splitting
-ED     pathname expansion
-E      quote removal

repl
        secondary prompts

special parameters
P       @
PED     *
PED     #
PED     ?
PED     -
P       $
P       !
P       0
        
flags
        allexport   -a
        errexit     -e
u       hashall     -h
        ignoreeof   
        interactive -i
        monitor     -m
        noclobber   -C
        noexec      -n
        noglob      -f
        nolog       
        notify      -b
        nounset     -u
        verbose     -v
u       vi          
        xtrace      -x


== Parsing Tokens ==

§2.3 as written

-- there is a token-in-progress ("tip")
-- we are looking at next character ("c")
-- "delim" means, if tip isn't empty, emit it as a token, and set tip to empty
-- "cycle c" means, restart with character c on the next pass

first match wins:

1. if EOF, delim
2. if tip is an operator, and c isn't quoted and tip+c is an operator,
    append c to tip
3. if tip is an operator (and #2 didn't match), delim & cycle c
4. if c is \, ', or " -- slurp the quoted text, and append to tip
5. if c is $ or ` -- slurp the parsed text, and append to tip
6. if c isn't quoted, and can start an operator, delim, set tip to c
7. if c is an unquoted newline, delim & cycle c
8. if c is an unquoted blank, delim & discared c
9. if tip isn't empty and isn't an operator, append c to tip
10. if c is #, discared it and all upto (but not including) the next newline
11. set tip to c

§2.10.1 says

1. a newline returns as a NEWLINE token
2. operators are TOK_XXX
3. if string is only digits, and immediately folled by < or >, then IO_NUMBER
4. else TOKEN, which can in turn be WORD, NAME, ASSIGNMENT, or reserved word


Seems to me that §2.10 happens first, then §2.3 once one has a TOKEN, though operator parsing seems mixed in stragely --- the issue is newline, which I'm going to take as always representing a single token of itself (except when removed via backslash...)

----

what we want is a set of rules written the other way 'round: starting from an empty tip, what do we do until we get a delim?


if tip is empty then
  if EOF - tok_eof
  if newline - tok_newline
  if starts an operator - start an op
    which then is as many characters as will keep making an op
  if blank - drop it and cycle
  if # - drop upto next newline, consume that, return tok_newline
  else set tip to c and append based on:
    if EOF - stop
    if \, ', or " - slurp quoted text onto tip
    if $ or ` - slurp parsed text onto tip
    if starts an operator - stop
    if newline - stop w/o using it
    if blank - stop, discarding it
    otherwise - appned to tip

for WORD:
c can't be EOF, newline, operator starts
continues so long as not EOF, operator starts, newline, blank
    note that \ ' " $ ` are all processed specially



§2.12 Shell Execution Environment
Shell (and special built ins) have:
    open files (numbered handles)
    working directory
    file creation mask
    traps
    variables (name -> (extern?, readonly?, value)
    functions
    set options
    async processes
    aliases

Utilities have:
    open files (numbered handles)
    working directory
    file creation mask
    traps (if a shell script?!?!?!)
    env. variables (name -> value)
    + system interfaces



c = coded, partial
C = coded, full
D = doctests

Special Built-In Utilities -- affect shell state, var assignments affect shell
    break continue
    exit return
    colon .(dot) eval exec
    export readonly shift unset
CD  set
    times
    trap

Required Built-In Utilities -- "found" before path search -- affect shell state
    alias read unalias
    bg fg jobs kill wait
c   cd fc pwd
    command getopts
CD  false true
    newgrp umask

Likely to implement Built-Ins -- don't affect shell state
    basename
CD  cat
    cmp
    cp
    date
    diff (partial)
    dirname
CD  echo
    env
    find (partial)
cd  grep (partial)
    head
    ls
c   mkdir
    mv
c   rm
    rmdir
    sed (partial)
    sh
    sleep
    sort (partial)
    tail
    tee
    test
    time
c   touch
    tr
    wc
    xargs




== Execution ==
six cases:
    special built-in
    function
    affecting built-in
    regular built-in
    executable
    script
    

== Completion ==
Things that can be completed:
    command name (first word)
    args, generically as file paths (2-n words)
    args, as options (if word starts with '-')
    words in assignment right hand sides
    words in redirection right hand sides (for some redir types)
    variable names in parameter words
    
    word as expanded or word as entered?
    command specific completions?
    
    
    bash completes:
        $xxx as a variable
        ~xxx as a user name
        @xxx as a host name
        command name (if first word?)
        file name
        
        bash basically runs EITHER command driven completion - OR default
        never both!
        
        plenty of corner cases!!!
    
    Annotations / Complettion    
    type=option
        description=
    
    type=file/dir/path
        status={...}
    
    type=string
    
    type=integer
        min=
        max=
    
    type=oneof
        choices=[...]
    
    type=someof
        choices=[...]
        separator=
    
    Annotation = Option { description :: Maybe Text }
               | Path { description :: Maybe Text, status :: Stat }
               | String { descirption :: Maybe Text }
               | Integer { description :: Maybe Text }
    
    Completion = OneOf { choices :: [(String,Text)] }
               | SomeOf { choices :: [(String,Text)], separator: String }
               | Path { namePattern :: Maybe String,
                        disposition :: Disposition,
                        pathType :: PathType }
    
    [String] -> [(Annotation, m Completion)]
    
    DescriptionAnno Text
    PosixLikeFilestatus s => PathInfoAnno s