all versions |
Warning: Work in progress! Leave feedback on Zulip or Github if you'd like
this doc to be updated.
Notes on Oil's Architecture
This doc is for contributors or users who want to understand the Oil codebase.
These internal details are subject to change.
- Essential: libc
- Optional: GNU readline (TODO: other line editing libraries).
- Only in the OVM build (as of March 2020): yajl
- ASDL front end from CPython (heavily
- frontend/tdop.py: Adapted from tinypy, but almost no original code
- All of OPy (will be obsolete)
- compiler2 from stdlib
- Build Dependency: MyPy
Metaprogramming / Generated Code
ls */*_def.py */*_gen.py
def.py files are abstract definitions. They're not translated by
gen.py files generate source code in Python and C++ from these
- For example, we define the core
Id type and the lexing rules abstractly.
- TODO: Details on each
- See build/dev.sh and build/codegen.sh
Other Cross-Cutting Observations
Where $IFS is Used
- Splitting of unquoted substitutions
- The read builtin
- To split words in
compgen -W (bash only)
Shell Function Callbacks
- Completion hooks registered by
complete -F ls_complete_func ls
- bash has a
command_not_found hook; OSH doesn't yet
Where Unicode is Respected
See the doc on Unicode.
Parse-time and Runtime Pairs
echo -e '\x00\n' and
echo $'\x00\n' (OSH shares lexer rules between them)
[[ (OSH shares the parser and evaluator)
- Static vs. Dynamic Assignment.
local x=$y vs.
s='x=$y'; local $s.
- All shells have both notions!
$(( )) (
expr not in shell)
- printf can have a static variant like
find and our own language (although this may be done with blocks)
$IFS splitting in
- compadjust needs to split partial
argv by user-defined delimiters,
The point of a state machine is to make sure all cases are handled!
Generated on Sat Feb 19 18:43:17 EST 2022