Package: zeekscript
A toolchain to parse, analyze, and format Zeek scriptszeekscriptis a Python package that provides tooling to operate onZeekscripts.zeekscriptcomes with command line tools that make common tasks accessible,
but its functionality is just animport zeekscriptaway in your own Python tools.zeekscriptis powered byTree-Sitter,
itsPython bindings, and ourtree-sitter-zeekgrammar.Supported platforms and Python versionszeekscriptsupports Python 3.7+ on Linux, MacOS, and Windows. We recommend
CPython. PyPy looks prone to crashing on Windows and MacOS, and we're not
currently building PyPy wheels on those platforms. (We've not investigated PyPy
in depth and feedback is welcome.)InstallationTo install our ready-made Python wheels, say:pip install zeekscriptFor a full list of available builds, you can check out thePyPI downloadsor take a look at ourCI build matrix.Thezeekscriptpackage includes native code (the compiledtree-sitter Zeek
grammar). We strive to provide wheels
for popular platforms and Python versions. In case your setup isn't covered, the
installation process will build the package locally on your system, for which
some dependencies need to be available. Read on for details, and feel free to
file a ticket detailing your setup.Building from sourceIf our build matrix doesn't cover your platform and Python version, or if you'd
simply like to build and install thezeekscriptpackage yourself, you need to
provide two dependencies:Thetree-sitter Python bindings,
available viapip install tree_sitterA C compiler, such asgccorclang.To obtain the sources, please clone this repository.Note: make sure to
clone recursively (git clone --recurse-submodules), since this pulls in the
needed Zeek grammar. We don't provide source packages on Github, but all
releases are tagged ingit.For installation from local sources, say:pip install .Thezeekscriptpackage doesn't implement the Zeek grammar compilation itself,
it outsources it to thetree-sitterPython bindings, which provide this
ability directly from Python.zeekscriptmerely initiates compilation during
the package build. See oursetup.pyfor details.TestingThe package comes with a testsuite. To run it, saymakefrom the toplevel. For details on the tests, take a look at thetestsdirectory.Usagezeek-formatMost significantly, the package includeszeek-format, a tool that formats Zeek
scripts. Our philosophy is similar togofmtand the opposite ofclang-format: there is only one way to layout Zeek scripts, and this tool
provides it. Accordingly, it features zero options for tweaking the formatting:$zeek-format--helpusage: zeek-format [-h] [--version] [--inplace] [--recursive] [FILES ...]A Zeek script formatterpositional arguments:FILES            Zeek script(s) to process. Use "-" to specify stdin as a filename. Omitting filenames entirely impliesreading from stdin.options:-h, --help       show this help message and exit--version, -v    show version and exit--inplace, -i    change provided files instead of writing to stdout--recursive, -r  process *.zeek files recursively when provided directories instead of files. Requires --inplace.Parsing errors are not fatal, andzeek-formatdoes its best to continue
formatting in the presence of errors. When it encounters parser errors,zeek-formatexits with a non-zero exit code and reports the trouble it
encountered to stderr.$echo'event  foo( a:count ) {print  "hi" ; }'|zeek-formatevent foo(a: count){print "hi";}To format entire directory trees, combine--inplaceand--recursive, and
point it at a directory:$cdzeek$zeek-format-irscripts430 files processed successfullyzeek-scriptThezeek-scriptcommand is the Swiss army knife in the toolbox: it provides
access to a range of script-processing tools (including formatting) via
subcommands. (Okay, so far "range" == two, but expect that to grow in the future.)$zeek-script--helpusage: zeek-script [-h] [--version] {format,parse} ...A Zeek script analyzeroptions:-h, --help      show this help message and exit--version, -v   show version and exitcommands:{format,parse}  See `zeek-script <command> -h` for per-command usage info.format        Format/indent Zeek scriptsparse         Show Zeek script parse tree with parser metadata.Theparsecommand renders its script input as a parse tree. It resemblestree-sitter parse, but shows more context about the relevant snippets of
content, including parsing errors.$echo'event zeek_init() { }'|zeek-scriptparsesource_file (0.0,1.0) 'event zeek_init() { }\n'decl (0.0,0.21) 'event zeek_init() { }'func_decl (0.0,0.21) 'event zeek_init() { }'func_hdr (0.0,0.17) 'event zeek_init()'event (0.0,0.17) 'event zeek_init()'event (0.0,0.5)id (0.6,0.15) 'zeek_init'func_params (0.15,0.17) '()'( (0.15,0.16)) (0.16,0.17)func_body (0.18,0.21) '{ }'{ (0.18,0.19)} (0.20,0.21)Here's a syntax error:$echo'event zeek_init)() { }'|zeek-scriptparsesource_file (0.0,1.0) [error] 'event zeek_init)() { }\n'decl (0.0,0.22) [error] 'event zeek_init)() { }'func_decl (0.0,0.22) [error] 'event zeek_init)() { }'func_hdr (0.0,0.18) [error] 'event zeek_init)()'event (0.0,0.18) [error] 'event zeek_init)()'event (0.0,0.5)id (0.6,0.15) 'zeek_init'ERROR (0.15,0.16) [error] ')') (0.15,0.16)func_params (0.16,0.18) '()'( (0.16,0.17)) (0.17,0.18)func_body (0.19,0.22) '{ }'{ (0.19,0.20)} (0.21,0.22)parse tree has problems: cannot parse line 0, col 15: ")"Seezeek-script parse --helpfor more information.Autocompletezeekscriptfeatures command-line auto-completion for users ofargcomplete.Integration into text editorsYou can integratezeekscriptinto any editor that supports the execution of
shell commands on the currently edited files. The relevantzeekscriptcommands
support reading from stdin or filename.EmacsWe offer anEmacs modewith support
for script formatting and parse tree inspection via keyboard shortcuts.vimThe following snippet hooks upzeek-formatto format the current script:functionRunZeekScript()" Create a new undo block for reverting formatting without changing cursor" position. https://github.com/rhysd/vim-clang-format/pull/55silentexecute"noautocmd normal! ii\<esc>\"_x"letl:save=winsaveview()execute"%!zeek-format"callwinrestview(l:save)endfunctionnnoremap<silent><buffer><leader>cf:callRunZeekScript()<CR>Usingzeek-formatwithpre-commitAdd this to your.pre-commit-config.yaml:-repo:https://github.com/zeek/zeekscriptrev:''# Use the SHA/tag you want to point at.hooks:-id:zeek-format