docs/config-syntax

   1 Configuration setting at startup and changing at runtime happens through one of these:
   2 - stdin at startup (TODO: see if we can keep listening while running) (write command to it + "\n")
   3 - fifo (write command to it + "\n")
   4 - socket (uzblctrl -s <file> -c <comand>
   5
   6 Lines written to the above starting with '#' or being empty, are ignored.
   7
   8 ** Command syntax:
   9 commands can have no, one or 2 arguments.
  10
  11 <command>[\t<arg1>[\t<arg2>]]
  12
  13 The 'bind' command is a special command, where argument 1 is a keyboard character (combo) and argument 2 is a command as specified above.
  14 You can also use a '_' in the <chars> part to denote where you pass on whatever you want, which will be replaced into the specififed command whereever %s is mentioned
  15
  16 ** commands
  17 Commands where one of the arguments is "parameter" expect this arugment to be a valid variable identifier (eg uzbl.behave.status_format)
  18
  19 set              parameter value # make sure the value complies with the datatype.
  20 toggle           parameter    # expects parameter to be a gboolean. (eg status, insert_mode, ..)
  21 get              parameter
  22 bind             <chars> <command>
  23 script           <JS code to execute>
  24 script_file      <filename containing JS code to execute>
  25 back
  26 forward
  27 scroll_vert      <int>
  28 scroll_horz      <int>
  29 reload
  30 reload_ign_cache
  31 stop
  32 zoom_in
  33 zoom_out
  34 spawn            <filename for process to start asynchronously>
  35 exit
  36 search           <string>
  37
  38 The 'set' command may do more then just set the variable. eg 'set uri' commands will also cause uzbl to navigate to the uri.
  39
  40
  41
  42 Rationale. AKA "why not config files?"
  43 -> unify code to configure uzbl and to accept incoming commands
  44 -> no more code needed for config file parsing/handling
  45 -> runtime changing of configuration
  46
  47 issues
  48 -> new instances (open link etc) need same config/state
  49    solutions?
  50    - serialize all state structs -> some libs available, could work. but:
  51                                     - binary format not very user friendly
  52                                     - not that easy (C has no introspection etc)
  53    - iterate over state structs and generate appropriate commands to bring an instance in this state.
  54      - plaintext :)
  55      - user editable
  56      - also useful for saving state if we need to update/shutdown/..