trun

Script for parsing any output. Yes, it is all it does.
git clone git://gtms.dev/trun
Log | Files | Refs | README | LICENSE

README (4512B)

      1 # Track run [v1.1.5 09.08.2021]
      2   TrackRun listen on stdin and for each line it gets status which is written to
      3   status_file.
      4   Status is taken from handler module via `handle` function.
      5 
      6   ! Lots of thing are explained inside scripts so check them out.
      7 
      8 
      9 # Dependencies
     10 
     11   It is written in lua and used/tested on linux. I have no plan to make it work
     12   for windows. But besides that nothing else is really needed.
     13   - If you want to `trun` to better handle process signals you will want to
     14     install luaposix via loarocks (luarocks install luaposix). So `trun` can
     15     cleanup files on sig{term,kill,int,hup}
     16 
     17 
     18 # Project structure
     19   Inside project you will find number of different files.
     20   - helper_functions.lua - useful functions for handler usage. (send command
     21     to neovim instances and more)
     22   - examples/ - handler examples
     23   - handlers/ - real life handlers i use. (contact me to add more)
     24     - TODO
     25   - tools/ - other tools that uses `trun` to make life easier
     26     - trun-fmt.lua: i use it for show semaphor of cmd (green,orange,red)
     27     - trun-ls.lua: for list of running trun
     28     - trun-status.lua: for status_file content for specific trun
     29     - trun_to_neovim_quickfix.lua: plugin to fill qf-list from cmd
     30 
     31 
     32 # Install
     33   You can install `trun` with:
     34   make install
     35 
     36   Also uninstall via `make uninstall`. 
     37   But you can install it manually. Just take a look at Makefile and see what it
     38   does... It is straightforward.
     39 
     40   Code inside other files are made for you to copy and modify as you need.
     41 
     42 
     43 # Usage
     44 
     45   <cmd> >&1 > >(trun <handler> <name>)
     46   NOTE: this cmd is for zsh.
     47 
     48   _explanation_
     49   `>&1` - copy output of cmd to terminal
     50   `> >(...)` - copy output of cmd to stdin of subprocess
     51   So if you don't need output in terminal you can simply `|`(pipe) to `trun`
     52 
     53 
     54 # Handler
     55   Handler is module that implements specific functions to catch some key
     56   moment of tracking: 
     57   There are these hook functions you can implement:
     58   - handle(userdata, line): returns status for current line
     59   - (optional) on_start(userdata): before first line is passed to handle function
     60   - (optional) on_update(userdata, line, status): when status change
     61   - (optional) on_end(userdata): when script end
     62 
     63   Every handler must implement 'handle' function, others are optional.  
     64   Handlers must have `lua` ext. and be inside specific folder. viz->#Config
     65 
     66 ## Handle function
     67   Returned status can be anything you want to store. Everything is just written
     68   to status_file.  Handle function can return either table or string. When table
     69   is returned, every item inside table will end up on new line in status_file so
     70   it can be easily used by other scripts.
     71 
     72 ## Userdata
     73   userdata has pre filled `name` key with value of `trun` name
     74 
     75 
     76 # Config
     77   There are 2 ENV variables you may want to set:
     78   - TRUN_HANDLERS_DIR: directory where handlers are stored 
     79     (defaults to $XDG_CONFIG_HOME/trun)
     80   - TRUN_STATUS_DIR: directory to store files with statuses 
     81     (defaults to $XDG_CACHE_HOME/trun)
     82 
     83 
     84 # Usage steps
     85 1. create handler
     86    inside $TRUN_HANDLERS_DIR add `your_handler.lua` file.
     87    viz -> examples
     88 
     89 2. Run cmd and pipe output to trun like `<cmd> | trun your_handler my_app`.
     90 
     91    For output also in terminal: `<cmd> >&1 > >(trun your_handler my_app)`
     92    NOTE: this is for zsh!
     93 
     94 3. status file
     95    Inside $TRUN_STATUS_DIR is created `my_app.your_handler` file with current
     96    status in it.
     97 
     98 
     99 # Test
    100   Inside test/ folder is playground. You can edit handler, modify gen.lua for
    101   your specific output and run `run.zsh` to see behaviour.
    102 
    103 # FAQ
    104 
    105   1. What is different between storing status in `status_file` or in `userdata`
    106 
    107     Data inside status_file you can use outside of handler
    108     (viz->tools/print_status.lua). And `userdata` is passed to each hook
    109     function.
    110 
    111   2. I want to contribute.
    112 
    113     Sure thing! Send me an email with suggestion on feature or better with git
    114     patch and we can discuss. viz->#Contact
    115 
    116   3. Why your English so bad?
    117 
    118     Sorry for that, i am trying my best. 
    119 
    120 
    121 # License viz->/LICENSE
    122 
    123  
    124 # Contact - Bugs, Suggestions, Questions...
    125 
    126   Feel free to contact me via mail on: <nemi@skaut.cz>
    127 
    128 
    129 # TODO
    130 
    131 - Make trun.lua multifunctional, so trun-status and trun-ls is not needed.
    132   Something like `trun -list` and `trun -status <name>`
    133 
    134 - Make easier to cache output of cmd, some configuration flag returned from
    135   on_start so trun will start caching every line until status changed.
    136   But status can be anything so, we have to tell that change is determined by
    137   first line?