README

Soar Vim Plugin
Author: Aaron Mininger
Written: Summer 2017

Purpose: This plugin is to integrate the soar debugger within a vim environment.
  It will mimic the soar debugger layout and allow normal debugging operations.
  The big benefit is interleaving editing and testing soar agents, 
	where you can edit and reload soar rules while the agent is running 

  This plugin also has a few features specific to the soargroup Rosie project 


===================================================
PREREQUISITES

The code for editing soar files has no prereqs

DEBUGGER ONLY: 

You need vim compiled with either python2 or python3 support

SOAR with sml_python
	You can pass --python=python3 into scons to compile with python 3:
	$> python2 scons/scons.py sml_python --python=python3

Add $SOAR_HOME to PYTHONPATH


===================================================
INSTALLATION

Suggested directory location is ~/.vim/bundle

* PLAIN (no plugin manager)
Put the following in your vimrc:

set runtimepath^=~/.vim/bundle/vim-soar-plugin

set nocompatible
filetype off
filetype plugin indent on

runtime plugin/vim-soar-plugin.vim


* VUNDLE
This plugin is compatible with vundle, just add the following line to your vimrc
  to the section sourcing plugins (see github.com/VundleVim/Vundle.vim for more info)
Plugin 'amininger/vim-soar-plugin'
    

===================================================
PROJECT ORGANIZATION

autoload  - Contains soar debugger specific code, only loaded when SoarDebugger command is executed
doc       - Contains help for using the debugger
ftdetect  - Tells vim to recognize the .soar file extension
ftplugin  - Sets .soar file specific commands, including editing key mappings
indent    - Code to properly indent soar files
plugin    - Code that defines functions and commands for editing soar files
python    - Python code that creates and runs soar agents for the debugger
templates - Collection of soar templates that can be inserted through the InsertSoarTemplate command (you can add more)


==================================================
EDITING COMMANDS AND FEATURES

Even if you don't run the debugger, this plugin offers useful features for editing .soar files

""" EDITING
;or | Open the soar file defining the current rule name in a new tab [cursor is on rule name]
;op | Open the soar file defining the current production in a new tab [cursor is inside production]
Note: These assume that the global variable g:root_agent_directory is set

""" COPYING
;yp | Yank (to buffer) the current production [cursor is inside production]
;yr | Yank (to buffer) the current rule name [cursor is on rule name]
;cp | Copy (to clipboard) the current production [cursor is inside production]
;cr | Copy (to clipboard) the current rule name [cursor is on rule name]

""" DELETING
;dp | Delete the current production [cursor is inside production]

""" COMMENTING
;#p | Comment the current production [cursor is inside production]
;u#p | Uncomment the current production [cursor is inside production]
(can also use ;3p and ;u3p respectively)


""" Managing Source Files

:AddFileToSoarSource
	Looks for a file in the same directory called <dir_name>_source.soar
	And will append a line 'source <cur_file>'

:SourceSoarDirectory <soar_dir>
	Will add 3 lines to the current file which will source a soar directory of the given name:
		pushd <soar_dir>
		source <soar_dir>_source.soar
		popd
	Autocompletes using current subdirectories


==================================================
RUNNING THE EXAMPLE AGENT (Basic Tutorial)

1. Open vim in the current soar_plugin/example directory
2. Run the command :SoarDebugger example.config
   This will open the debugger window layout and put the agent in a ready state
3. Type # to bring up a soar prompt, then enter 'p s1' to print the top-state
4. Type H. This should run 1 DC and do the init-agent operator
5. Move the cursor to the O1 identifier and type ;p2, this will print O1 to a depth of 2
6. Type ;ma which will run the matches command, showing which rules match
7. Move the cursor to the counting-agent*apply*init-agent rule name and type ;pr
   This will print the production with the rule name under the cursor
8. Move the cursor inside the printed production and type ;mp
   This will show why the production currently matches
9. Type U which will run the agent 10 decision cycles (it should count from 1-10)
10. Type :CloseDebugger to close the debugger


==================================================
DEBUGGER COMMANDS

SoarDebugger <config-file>  # Launch the debugger
							# You can pass an optional <config-file> to use to initialize the agent (details below)
RemoteDebugger              # Will connect to a remote Soar kernel and allow you debug remotely
ResetDebugger               # Complete destroys and restarts the agent from a clean state (discards learned rules)
CloseDebugger               # Closes the debugger and deletes the agent

SourceCurrentFile           # The currently running agent will source the current file
SourceSoarFile <filename>   # The currently running agent will source the specified file

AddFileToSource             # Looks for <dir>_source.soar and appends a source command for the current file
InsertSoarTemplate <template>   # Inserts a soar template of the given template name into the current file

RejectSoarOperator <op-name> #  Will reject all operators with the given name for 1 dc

AddPInterrupt <op-name>    # Will source a rule that interrupts when the given operator is proposed
AddSInterrupt <op-name>    # Will source a rule that interrupts when the given operator is selected
RemoveInterrupt <op-name> # Will excise an interrupt rule for the given operator 
RemoveAllInterrupts       # Will excise all interrupt rules created by the debugger

RemoveWaits               # Will delete lines from the end of the debugger until it hits a non-wait operator

==================================================
DEBUGGER FUNCTIONS

:call FilterChunks("match_str")
# Will print out any chunks with the given string in the rule name

:call FilterRules("match_str")
# Will print out any rules with the given string in the rule name

:call ExtractFiredRules("filename")
# Will write all fired rules to the given file


==================================================
CONFIG FILE OPTIONS
agent-name = <string>     | The name of the agent
agent-source = <filename> | The soar file to source
smem-source = <filename>  | The soar file sourcing any smem code
source-output = full|summary|none  | How much output to print when sourcing files

watch-level = <int>       | The watch level to print information at (default=1)
spawn-debugger = <bool>   | If true, will spawn the soar debugger externally (default=false)
write-to_stdout = <bool>  | If true, will print all output to std out (default=false) 
enable-log = <bool>       | If true, will write all soar output to a file
log-filename = <str>      | The name to give the log file (defaults to agent-log.txt)

==================================================
DEFAULT VIM MAPPINGS
Many commands are ; followed by a shortcode
This does remap the keyboard shortcuts for H U # and Ctrl+P

To disable these shortcuts, define the following global variable in your vimrc
	let g:enable_soar_plugin_mappings = 0

""" Executing Soar Commands

#      | Execute a custom soar command (will bring up prompt)

""" Running the Agent
;re    | Run 1 elaboration cycle (run 1 -e)
H      | Run 1 decision cycle
U      | Run 10 decision cycles
;ru    | Run 1000 decision cycles
;rsu   | Run 1000 decision cycles 'slowly' (will run at about 100 DC/s instead of full speed)
;rf    | Run forever (until interrupted). Note: This is discouraged, vim will hang forever unless soar stops itself
;rsf   | Run forever slowly (until interrupted). Again, issues if soar never interrupts

;r#    | Run 10^# dc's:  ;r2 will run 100  ;r4 will run 10000
;rs#   | Run 10^# dc's slowly

:RunAgent [n] | Run custom number of dc's 
:RunSlow [n]  | Run custom number of dc's slowly

""" PRINTING
;pr | Prints the full production [cursor is on rule name]
;p# | Print the current identifier to # depth (;p2 ;p4 ...) [cursor is on identifier]
;st | Prints out the current state (bottom of the stack)
;s# | Prints out the current state to # depth (;s2)
;o# | Prints out the current operator to # depth (;o2)
;aa | Does the last print command (a)gain, but with the depth increased by 1
;a# | Does the last print command (a)gain, but with the depth increased by #

""" EDITING
;or | Open the soar file defining the current rule name in a new tab [cursor is on rule name]
;op | Open the soar file defining the current production in a new tab [cursor is inside production]

""" COPYING
;yp | Yank (to buffer) the current production [cursor is inside production]
;yr | Yank (to buffer) the current rule name [cursor is on rule name]
;cp | Copy (to clipboard) the current production [cursor is inside production]
;cr | Copy (to clipboard) the current rule name [cursor is on rule name]

""" DELETING
;dp | Delete the current production [cursor is inside production]

""" COMMENTING
;#p | Comment the current production [cursor is inside production]
;u#p | Uncomment the current production [cursor is inside production]
(can also use ;3p and ;u3p respectively)

""" SOURCING
;sp | Source the current production [cursor is inside production]

""" EXCISING
;ep | Excises the current production [cursor is inside production]
;er | Excises the current rule [cursor is on rule name]

""" MATCHING
;ma | Runs the matches command
;mp | Runs the matches command with the current production [cursor is inside production]
;mr | Runs the matches command with the current rule name [cursor is on rule name]

""" Print firing count
;fcp | Runs the fc command with the current production [cursor is inside production]
;fcr | Runs the fc command with the current rule name [cursor is on rule name]

""" TEMPLATES
Ctrl+P | Goes to the next insertion point in a template (marked by #!#)


================================================
ROSIE SPECIFIC FEATURES

I recommend adding the following to a .vimrc:
	let g:root_agent_directory = $ROSIE_HOME."/agent"
This will allow shortcuts that open soar rules (;op) to find the right files

:RosieDebugger [config_file]
	Will open the rosie-specific debugger with the given rosie config file
	If config_file is not given, vim will prompt for an agent name from rosie/test-agents
	A default can be specified via:  let g:default_rosie_agent = "name"
Similarly, :MobileDebugger :CozmoDebugger :ThorDebugger will setup rosie for the different external environments

:call SendMessageToRosie()
	Will show a prompt to let you send a natural language sentence to rosie

:call PrintRosieWorld("S1") or ;prw
	Prints the top-state world in a nicely-formatted way


================================================
SOAR PARSING HELPER FUNCTION

""" Other useful functions for parsing soar productions

GetSoarProductionBody(line_num)
	Returns the production a the given line (as a string)
	If line_num is not given, this will use the current cursor position

GetSoarProductionName(line_num)
	Returns the name of the production at the given line
	If line_num is not given, this will use the current cursor position

GetSoarWord(row, col)
	Returns the soar word at the given position 
	(considers a word to be alpha-numeric, plus underscore, hypthen, and asterisk)
	If row/col are not given, this will use the current cursor position

GetSoarProductionInfo(line_num, commented)
	Gets information about the soar production at the given line number
 	  (line_num can be anywhere inside the production)
 	  If no line_num is given, uses the current cursor position
 	if commented is given and equals 1, this will look for #'s in front

 	returns a 3-index array if inside a production (empty array otherwise)
 	  prod_info[0] = production start line number
 	  prod_info[1] = production end line number
 	  prod_info[2] = production name