Source

slimv-newlisp / doc / slimv.txt

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
*slimv.txt*                    Slimv                 Last Change: 25 Aug 2011

Slimv                                                                  *slimv*
                               Version 0.8.6

The Superior Lisp Interaction Mode for Vim.
This plugin is aimed to help Lisp development by interfacing between Vim and
the Lisp REPL, similarly to Emacs/SLIME.
Slimv works on Windows, Linux, and Mac OS X, however the newly introduced
Paredit mode is operating system independent. Please visit |paredit.txt| for
additional information on Paredit mode.
The current version of Slimv contains a SWANK (TCP server for Emacs) client.
Please visit |swank.txt| for additional information on the SWANK client.

|slimv-installation|         Installation
|slimv-customization|        Customization
|slimv-swank|                SWANK client
|slimv-usage|                Usage
|slimv-repl|                 Lisp REPL inside Vim
|slimv-clojure|              Clojure support
|slimv-scheme|               Scheme support
|slimv-package|              Package and Namespace handling
|slimv-profiling|            Profiling
|slimv-hyperspec|            Hyperspec Lookup and Completion
|slimv-paredit|              Paredit mode
|slimv-external|             External utilities
|slimv-faq|                  Frequently Asked Questions
|slimv-changelog|            Change Log
|slimv-issues|               Known Issues
|slimv-todo|                 Todo
|slimv-credits|              Credits

For Vim version 7.0 and above.
This plugin is only available if 'compatible' is not set.

{Vi does not have any of this}

===============================================================================
INSTALLATION                                               *slimv-installation*

Prerequisites:

  Note: the system requirements are different for the SWANK client, please find
  details in |swank-installation|.

  Required components:
  - Lisp (any console Common Lisp implementation should be OK) or Clojure or
    MIT Scheme (Linux only) installed.
  - Python 2.4 or later installed. When using the SWANK client the same Python
    version is needed that Vim is compiled against.
    When not using the SWANK client then due to a Popen bug in the Cygwin
    Python implementation Cygwin users should install Windows Python,
    which is autodetected by the script.

  Optional components:
  - The interrupt functionality needs the pywin32 extension on Windows, but
    only when not using the SWANK server.
  - "Exuberant ctags" for tags file generation (if not bundled with Vim
    already). See |slimv-ctags|.

To install the script:

  - Install all required components described above.
  - Download slimv.zip.
  - Extract the zip archive into your vimfiles or runtime directory.
    See Vim help file |usr_05.txt| for details on adding a plugin.
    The archive contains the following files:

       doc/paredit.txt
       doc/slimv.txt
       doc/swank.txt
       ftdetect/clojure.vim
       ftplugin/slimv.py
       ftplugin/slimv.vim
       ftplugin/slimv-clhs.vim
       ftplugin/slimv-cljapi.vim
       ftplugin/slimv-javadoc.vim
       ftplugin/swank.py
       ftplugin/clojure/slimv-clojure.vim
       ftplugin/lisp/slimv-lisp.vim
       ftplugin/scheme/slimv-scheme.vim
       indent/clojure.vim
       indent/lisp.vim
       plugin/paredit.vim
       slime/*
       swank-clojure/*
       syntax/clojure/slimv-syntax-clojure.vim
       syntax/scheme/slimv-syntax-scheme.vim

    You might already have an ftdetect/clojure.vim file if you already use
    another Clojure filetype plugin. In this case just keep the original file.

  - Start Vim or goto an existing instance of Vim.
  - Execute the following command:
>
       :helptags <your runtime directory>/doc

    (e.g :helptags $VIMRUNTIME/doc)
<
    This will generate all the help tags for any file located in the doc
    directory.
  - Enter path definitions into your vimrc (if the default values are not
    valid for your Vim/Python/Lisp installation).
    See |slimv-customization| below on how to do this.
  - On Linux some login shells (like fish) might be incompatible with the Vim
    temporary file generation, which results in getting random E484 errors.
    This is because Vim expects a POSIX-compliant shell and the problem might
    occur in other Vim scripts as well.
    One solution is to add a similar block to the top of .vimrc:

        if $SHELL =~ 'bin/fish'
            set shell=/bin/sh
        endif


Uninstallation:

  - Exit all Vim instances and exit from the REPL server terminal window.
  - Delete the files that were copied to the vimfiles directory during
    installation (see list of files above).


===============================================================================
CUSTOMIZATION                                             *slimv-customization*

|slimv-options|              Options
|slimv-templates|            Templates
|slimv-keyboard|             Keyboard mappings

-------------------------------------------------------------------------------
                                                                *slimv_options*

The list below contains an alphabetical collection of Slimv options.
Below that list follows the detailed explanation on each option.
For the Paredit options please visit |paredit-options|.
For the Swank options plese visit |swank-configuration|.

|g:slimv_browser_cmd|        If nonempty, this command is used to open the
                             Common Lisp Hyperspec. 

|g:slimv_clhs_root|          Base URL for the Common Lisp Hyperspec.

|g:slimv_clhs_user_db|       User defined extension for Slimv's built-in
                             Common Lisp Hyperspec symbol database.

|g:slimv_clhs_user_root|     Base URL for the user defined CLHS extension.

|g:slimv_cljapi_root|        Base URL for the Clojure API.

|g:slimv_cljapi_user_db|     User defined extension for Slimv's built-in
                             Clojure API symbol database.

|g:slimv_cljapi_user_root|   Base URL for the user defined Clojure API
                             extension.

|g:slimv_client|             The whole OS command to start the Slimv client.
                             Used for advanced customization, like changing
                             the terminal emulator to use for the Lisp REPL.

|g:slimv_ctags|              OS command to generate tags file.

|g:slimv_echolines|          Echo only this number of lines from the form
                             being evaluated.

|g:slimv_impl|               The Lisp implementation. Defaults to 'clisp'.

|g:slimv_javadoc_root|       Base URL for the JavaDoc.

|g:slimv_keybindings|        Predefined Slimv keybindings. Possible values:
                             1 = set #1, 2 = set #2, other = no keybindings

|g:slimv_leader|             Custom <Leader> setting for Slimv.

|g:slimv_lisp|               Path for the Lisp interpreter.

|g:slimv_menu|               If nonzero, Slimv menu is added to the Vim menu.

|g:slimv_package|            If nonzero, Slimv package/namespace handling is
                             switched on.

|g:slimv_port|               TCP/IP port number to use in the Slimv client-
                             server communication.

|g:slimv_python|             Path for the Python interpreter.

|g:slimv_repl_dir|           Directory path for the Lisp REPL buffer file.

|g:slimv_repl_file|          Filename without path for the REPL buffer file.

|g:slimv_repl_open|          If nonzero, Slimv opens the Lisp REPL buffer
                             inside Vim when the server is started.

|g:slimv_repl_split|         Open the Lisp REPL buffer in a split window
                             or in a separate buffer.

|g:slimv_repl_syntax|        Enable syntax coloring for the REPL buffer.

|g:slimv_repl_wrap|          Set wrap mode for the REPL buffer.

|g:slimv_swank|              Indicates the usage of the SWANK client.
                             Please find additional SWANK related options
                             in |swank.txt|.

|g:slimv_updatetime|         Alternative value for 'updatetime' during REPL
                             refresh.


Note: Most options require to restart the Vim session when modified.

Slimv tries to autodetect the Python and Lisp installation directories,
however the algorithm is not very sophisticated.
If the installation directories are put in the path, then the autodetection
should find them (this is usually the case on Linux). Otherwise (on Windows)
some frequently used directories are searched under C:\ and C:\Program Files.
For a minimum, Slimv needs to know the path of the existing Python and Lisp
installations, so if autodetection does not work for you, then set the
following global variables in your vimrc.

Note: On Windows use the / (slash) character instead of \ (backslash) as the
      directory separator to avoid any incidental character escaping problems
      while the paths are beeing passed between the Slimv processes.
      On Linux this is not an issue.

                                                               *g:slimv_python*
This is the installation path of the Python interpreter.
Normally the Python path is autodetected, but sometimes autodetection fails
and you need to set up the path in your .vimrc file explicitly.
If the Python path contains space characters then either the spaces should be
escaped (Linux) or the short 8.3 filename format should be used (Windows).
Enclosing the full Python path in double quotes may also work, but this depends
on the command string handling of the console command used (xterm/cmd.exe/etc).
Example:
    let g:slimv_python = 'C:/MyPythonDir/python.exe'

                                                                 *g:slimv_lisp*
This is the installation path of the Lisp interpreter.
Example:
    let g:slimv_lisp = 'C:/MyLispDir/mylisp.exe'

                                                                 *g:slimv_impl*
This is the Lisp implementation used. Slimv tries to autodetect it at script
startup. If the autodetection fails, set this to the actual Lisp
implementation.
Example:
    let g:slimv_impl = 'sbcl'

                                                                 *g:slimv_port*
The default port used by Slimv is 5151. If this port is used by another
program then set this variable to a free port number.
It is also possible to run multiple REPLs from multiple Vim processes, just
set a different port number for each Vim instance.
Example:
    let g:slimv_port = 10101

There is a separate port definition in Slimv which sets the port number to
use for the SWANK server, see |g:swank_port| for details.

                                                               *g:slimv_client*
Note: Used only when SWANK client is not enabled.

You may want to use a shell frontend other then the default one (cmd.exe
on Windows, xterm on Linux) or put additional command line parameters
for starting the server.
In this case you can omit the variables above and use g:slimv_client instead.
This is the complete command that is used to start the client. If not set
by the user, this is automatically built from the variables above.

The command format is the following (items in [] are optional):
    <python> <slimv> [-p <port>] -r "<server_cmd>"
Where:
    <python>       is the command to start the Python interpreter
    <slimv>        is the path of slimv.py
    <port>         is the port number to use (if other than default)
    <server_cmd>   is the command to start the server

The format of <server_cmd> is the following (please remember to enclose the
whole command in double quotes, as this will be passed as one parameter
to the client):
    [<terminal>] <python> <slimv> -l <lisp> -s
Where:
    <terminal>     is the command to open a new terminal window
    <python>       is the command to start the Python interpreter
    <slimv>        is the path of slimv.py
    <lisp>         is the command to start the Lisp REPL
You can also pass the following shortcuts in <server_cmd>:
    @p             equals <python>
    @s             equals <slimv>
    @@             use it if you need to insert an @ character
    \"             use it to insert a " character
So <server_cmd> can be rewritten in this shorter form:
    [<terminal>] @p @s -l <lisp> -s

The reason behind the duplication of the <python> and <slimv> part is that
you may want to start the server/REPL in a shell frontend that needs
special command line options. For example on Windows I highly recommend
to use Console (http://sourceforge.net/projects/console/) which is greatly
configurable and you also get usable select/copy/paste functions.

Note: Remember to escape with a \ all " characters that are supposed to be
      inside a command line argument, otherwise the argument will be split
      by the shell.

Example to start the Slimv server via Console on Windows:

  let g:slimv_client = 
  \ 'python slimv.py -p 5152 -r "console -r \"/k @p @s -l clisp -s\""'

So the server will be started as if we typed at the command line:

  console -r "/k python slimv.py -l clisp -s"

A similar situation is if you want to use a terminal program other than
xterm on Linux (e.g. Konsole). A typical g:slimv_client setup can be on
Linux for xterm:

  let g:slimv_client =
  \ 'python ~/.vim/plugin/slimv.py -r "xterm -T Slimv -e @p @s -l clisp -s"'

And this can be for Konsole:

  let g:slimv_client =
  \ 'python ~/.vim/plugin/slimv.py -r "konsole -T Slimv -e @p @s -l clisp -s"'

                                                                *g:slimv_ctags*
It is possible to generate tags file from within Vim. By default Slimv assumes
that ctags.exe is stored somewhere along with the standard Vim path designated
by $vim or $vimruntime. The command for generating tags file is then
automatically built at script startup.
If ctags.exe is stored somewhere else, or the default ctags options are
unsatisfactory, then override this option with the desired command.
The default ctags command is:
  "ctags.exe -a --language-force=lisp *.lisp *.clj"

                                                          *g:slimv_keybindings*
Defines the keybinding set used by Slimv.
Value 0 means no keybinding at all.
Value 1 defines the short keybinding with one-key bindings (after <Leader>).
        Example: Eval-Defun is mapped to ,d
Value 2 defines the easy keybinding with two-key bindings (after <Leader>).
        Example: Eval-Defun is mapped to ,ed
Other values mean no predefined keybinding is wanted.
<Leader> is set to "," by default in Slimv.

                                                               *g:slimv_leader*
This option allows a custom <Leader> setting for the Slimv keybindings.
By default it has the same value as |mapleader|. If neither g:slimv_leader nor
mapleader are defined then the default <Leader> is "," in Slimv.
Example:
    let g:slimv_leader = '\'
If this is set in the .vimrc then Eval-Defun will be mapped to \d instead of ,d.

There is a separate |g:paredit_leader| option for the Paredit keybindings.

                                                                 *g:slimv_menu*
If nonzero then the Slimv menu is added to the end of the global menu.
Also the Slimv menu can be shown by pressing <Leader>, (defaults to ,,).

                                                          *g:slimv_browser_cmd*
Specifies the command to start the browser in order to display the Common Lisp
Hyperspec or the Clojure API. If the command contains spaces then enclose the
whole string in double quotes or escape the spaces with a backslash.
This option is empty by default, which means that the command associated with
the .html extension (on Windows) or returned by the Python webbrowser package
(on Linux) is used to start the browser.

                                                             *g:slimv_repl_dir*
Directory path for the Lisp REPL buffer file. By default this is a directory
for temporary files, something like /tmp/ on Linux or
"C:\Documents and Settings\Username\Local Settings\Temp\" on Windows.
The directory name must end with the pathname separator (/ or \).
See also |g:slimv_repl_file|.

                                                            *g:slimv_repl_file*
The Lisp REPL output is written to a temporary file by the Slimv server.
|g:slimv_repl_file| defines the filename part of the REPL output file without
the directory path. The complete REPL filename is built from
|g:slimv_repl_dir| and |g:slimv_repl_file|.

                                                            *g:slimv_repl_open*
Slimv opens the Lisp REPL buffer inside Vim by default when the Slimv server
is started, so there exist actually two REPL-s with the same contents:
one inside a Vim buffer and another one as a separate terminal window.
The reason behind this is that the simulation is not perfect, which is caused
by the lack of asynchronous update possibilities in Vim. Sometimes the REPL
buffer is not perfectly updated, this is the case for example when a Lisp
program is running too long and it has infrequent outputs only.
Slimv refreshes the REPL buffer at every keystroke or when the user doesn't
press a key for the time specified with 'updatetime'. It is also possible
to manually refresh the REPL buffer. The default value for 'updatetime' is
4 secs (=4000 ms), in cases when more precise refreshing is needed you can
lower the 'updatetime' option, e.g. to one second (=1000 ms):
    set updatetime=1000
However, it is not recommended to set this to a much lower value.
Optionally one may check the output of the separate REPL window.
The |g:slimv_repl_open| = 0 option can be used to disable the built-in REPL
buffer, so that only the separate REPL window is opened.

                                                           *g:slimv_repl_split*
Open the Lisp REPL buffer in a split window or in a separate buffer in Vim.
Used only when |g:slimv_repl_open| is nonzero.
The default is to use split window. If you prefer having REPL being in a hidden
buffer then set this option to zero. This way the REPL buffer will be opened
at the first evaluation, but any subsequent evaluation will be performed
silently, with the REPL buffer kept hidden.

It is also possible to define the desired split direction. The following
values may be used for |g:slimv_repl_open|:

    0: no split
    1: horizontal split above (default)
    2: horizontal split below
    3: vertical split left
    4: vertical split right

                                                           *g:slimv_updatetime*
The REPL buffer is refreshed at every keystroke or when the user doesn't press
a key for the time specified with 'updatetime'. Slimv alters the value for
'updatetime' to a lower value when the REPL buffer is changed, so that the
update frequency gets higher while there is new REPL output. The original
value for 'updatetime' is restored when there is no REPL output.
The g:slimv_updatetime option defines the alternative (lower) value for
'updatetime' during REPL refresh. If you don't want that Slimv changes
'updatetime', then set g:slimv_updatetime to zero.
The default value is 200 (=0.2 sec).

                                                              *g:slimv_package*
If nonzero then Slimv package/namespace handling is switched on. Please find
details in the |slimv-package| section.

                                                          *g:slimv_repl_syntax*
Enables syntax highlighting for the REPL buffer. Switched off by default for
two reasons:
  1. The REPL buffer also contains the REPL output, which is generally not
     related to s-expressions, therefore may confuse syntax coloring.
  2. REPL output may contain very long lines, which significantly slows down
     syntax coloring in Vim. If you really want to enable syntax highlighting
     for the REPL buffer, then it is recommended to adjust the |synmaxcol|
     parameter to a relatively low value in order to increase syntax coloring
     speed.

                                                            *g:slimv_repl_wrap*
Set wrap mode for the REPL buffer, which means the lines longer than the
window width will not be hidden to the right. Instead they will be continued
in the next display line.
This is the default behaviour as it is how regular REPL windows work. This
mode also enables keybindings for cursor movements, so that an <Up> keypress
will move the cursor one line on the display and not one line in the document.

                                                            *g:slimv_echolines*
If a long form is evaluated then echo only this number of lines from the
beginning of the form. This option prevents filling the REPL buffer with
mostly unnecessary information. Closing parens are added to the end even if
the end of the form is not echoed, so paren balance is kept.
If this option is set to zero then no line is echoed at all, if set to -1
then all lines are always echoed.

                                                            *g:slimv_clhs_root*
                                                          *g:slimv_cljapi_root*
                                                         *g:slimv_javadoc_root*
Base URL for the Common Lisp Hyperspec, Clojure API, and JavaDoc.
If the Hyperspec/API is downloaded to the hard disk, then set these variables
to the base path of the local copy, something like (where file:// specifies
the file protocol):
"file:///c:/doc/HyperSpec/" (Windows).
or
"file:///usr/local/doc/HyperSpec/" (Linux).
It is possible to extend the Hyperspec symbol database with user defined
symbols, see |g:slimv_clhs_user_db| and |g:slimv_cljapi_user_db|.

                                                         *g:slimv_clhs_user_db*
                                                       *g:slimv_cljapi_user_db*
                                                       *g:slimv_clhs_user_root*
                                                     *g:slimv_cljapi_user_root*
If you want to extend Slimv's built-in Hyperspec/API symbol database, define
the list of additional symbols in these variables. The format of this list is
the following: [["symbol1", "url1"], ["symbol2", "url2"], ...].
If the URL contains a ":" character then it is considered to be a fully
qualified URL, otherwise it is a relative address to the Hyperspec root
defined in |g:slimv_clhs_root| or |g:slimv_cljapi_root|.
It is also possible to define a separate base URL for the user extensions via
|g:slimv_clhs_user_root| or |g:slimv_cljapi_user_root|.

Example:
    let g:slimv_clhs_user_root = "http://myhyperspec.com/"
    let g:slimv_clhs_user_db = [
        \["my-cool-function", "mycoolfunc.htm"],
        \["my-super-function", "mysuperfunc.htm"],
        \["my-awesome-function", "myawesomefunc.htm"]] 

Remember to insert a backslash at the beginning of each additional line of a
multi-line Vim command.


-------------------------------------------------------------------------------
                                                              *slimv_templates*

Many Slimv commands are performed by creating a special Lisp form from the
selected symbol (or list) and send it to the REPL for execution.
Slimv defines various templates to build these special Lisp forms.
You can override them to suit your needs. Use %1 for substituting the selected
symbol's name or the selected list.
Here follows a list of the templates defined in Slimv.

                                                      *g:slimv_template_pprint*
Lisp form built when issuing the 'Pprint' command.
Example:
    let g:slimv_template_pprint = '(dolist (o %1)(pprint o))'

                                                    *g:slimv_template_undefine*
Note: Used only when SWANK client is not enabled.

Lisp form built when issuing the 'Undefine' command.
Example:
    let g:slimv_template_undefine = '(fmakunbound (read-from-string "%1"))'

                                                    *g:slimv_template_describe*
Note: Used only when SWANK client is not enabled.

Lisp form built when issuing the 'Describe' command.
Example:
    let g:slimv_template_describe = '(describe (read-from-string "%1"))'

                                                       *g:slimv_template_trace*
Note: Used only when SWANK client is not enabled.

Lisp form built when issuing the 'Trace' command.
Example:
    let g:slimv_template_trace = "(trace %1)"

                                                     *g:slimv_template_untrace*
Note: Used only when SWANK client is not enabled.

Lisp form built when issuing the 'Untrace' command.
Example:
    let g:slimv_template_untrace = "(untrace %1)"

                                                     *g:slimv_template_profile*
Lisp form built when issuing the 'Profile' command.
Example:
    let g:slimv_template_profile = "(mon:monitor %1)"

                                                   *g:slimv_template_unprofile*
Lisp form built when issuing the 'Unprofile' command.
Example:
    let g:slimv_template_unprofile = "(mon:unmonitor %1)"

                                               *g:slimv_template_unprofile_all*
Lisp form built when issuing the 'Unprofile All' command.
Example:
    let g:slimv_template_unprofile_all = "(mon:unmonitor)"

                                               *g:slimv_template_show_profiled*
Lisp form built when issuing the 'Show Profiled' command.
Example:
    let g:slimv_template_show_profiled = "(pprint mon:*monitored-functions*)"

                                              *g:slimv_template_profile_report*
Lisp form built when issuing the 'Profile Report' command.
Example:
    let g:slimv_template_profile_report = "(mon:report-monitoring)"

                                               *g:slimv_template_profile_reset*
Lisp form built when issuing the 'Profile Reset' command.
Example:
    let g:slimv_template_profile_reset = "(mon:reset-all-monitoring)"

                                                 *g:slimv_template_disassemble*
Lisp form built when issuing the 'disassemble' command.
Example:
    let g:slimv_template_disassemble = "(disassemble #'%1)"

                                                     *g:slimv_template_inspect*
Note: Used only when SWANK client is not enabled.

Lisp form built when issuing the 'inspect' command.
Example:
    let g:slimv_template_inspect = "(inspect %1)"

                                                     *g:slimv_template_apropos*
Lisp form built when issuing the 'apropos' command.
Example:
    let g:slimv_template_apropos = '(apropos "%1")'

                                                 *g:slimv_template_macroexpand*
Note: Used only when SWANK client is not enabled.

Lisp form built when issuing the 'macroexpand-1' command, after "defmacro"
string is replaced with "macroexpand-1".
Example:
    let g:slimv_template_macroexpand = '(pprint %1)'

                                             *g:slimv_template_macroexpand_all*
Note: Used only when SWANK client is not enabled.

Lisp form built when issuing the 'macroexpand-all' command, after "defmacro"
string is replaced with "macroexpand".
Example:
    let g:slimv_template_macroexpand_all = '(pprint %1)'

                                                *g:slimv_template_compile_file*
Lisp form built when issuing the 'compile-file' command.
Example:
    let g:slimv_template_compile_file = '(compile-file "%1")'


-------------------------------------------------------------------------------
                                                               *slimv_keyboard*

The default keybindings (|g:slimv_keybindings|=1) and another easy to remember
built-in keybinding set (|g:slimv_keybindings|=2) for Slimv are the following.
Please note that the leading ',' key below refers to <Leader>, which is set
by Slimv to ',' by default (see |g:slimv_leader|).
In the graphical menu the currently active keyboard shortcuts are displayed
beside the menu item names, so one can refer to the GUI menu as a quick
reference for the keymappings.
Vim defines timeout values for mapped key sequences. If you find that Vim does
not allow you enough time between pressing ',' and the last key(s) of the
sequence, then you may want to fine tune these Vim options:
|timeout|, |ttimeout|, |timeoutlen|, |ttimeoutlen|.

    Set#1   Set#2    Command
    ---------------------------------------------------
    ,,      ,,       Slimv Menu

    Edit commands (Insert mode):
    <C-X>0           Close Form
    <Tab>            Complete Symbol
    <Space>          Function Arglist (only when using SWANK client)

    Edit commands (Normal mode):
    ,)      ,tc      Close Form
    ,(      ,(t      Paredit Toggle

    Evaluation commands:
    ,d      ,ed      Eval Defun (current top level form)
    ,e      ,ee      Eval Current Expression (current subform)
    ,r      ,er      Eval Region (visual selection)
    ,b      ,eb      Eval Buffer
    ,v      ,ei      Interactive Eval (evaluates in frame when in SLDB)
    ,u      ,eu      Undefine Function

    Debug commands:
    ,1      ,m1      Macroexpand-1
    ,m      ,ma      Macroexpand All
    ,t      ,dt      Toggle Trace
    ,T      ,du      Untrace All
    ,l      ,dd      Disassemble
    ,i      ,di      Inspect (inspects in frame when in SLDB)
    ,a      ,da      Abort (only when using SWANK client)
    ,q      ,dq      Quit to Toplevel (only when using SWANK client)
    ,n      ,dc      Continue (only when using SWANK client)
    ,H      ,dl      List Threads
    ,K      ,dk      Kill Thread
    ,G      ,dg      Debug Thread

    Compile commands:
    ,D      ,cd      Compile Defun
    ,L      ,cl      Compile and Load File
    ,F      ,cf      Compile File
    ,R      ,cr      Compile Region

    Cross Reference commands (only when using SWANK client):
    ,xc     ,xc      Who Calls
    ,xr     ,xr      Who References
    ,xs     ,xs      Who Sets
    ,xb     ,xb      Who Binds
    ,xm     ,xm      Who Macroexpands
    ,xp     ,xp      Who Specializes
    ,xl     ,xl      List Callers
    ,xe     ,xe      List Callees

    Profile commands:
    ,p      ,pp      Toggle Profile
    ,B      ,pb      Profile by Substring
    ,U      ,pa      Unprofile All
    ,?      ,ps      Show Profiled
    ,o      ,pr      Profile Report
    ,x      ,px      Profile Reset

    Documentation commands:
    ,s      ,ds      Describe Symbol
    ,A      ,da      Apropos
    ,h      ,dh      Hyperspec
    ,]      ,dt      Generate Tags

    Repl commands:
    ,c      ,rc      Connect to Server
    ,y      ,ri      Interrupt Lisp Process


    Set#1   Set#2    Command
    ---------------------------------------------------
    ,\      ,\       REPL Menu (separate menu, valid only for the REPL buffer)

    REPL menu commands:
    ,.      ,rs      Send Input
    ,/      ,ro      Close and Send Input
    ,g      ,rp      Set Package (only when using SWANK client)
    <C-C>   <C-C>    Interrupt Lisp Process
    ,<Up>   ,rp      Previous Input
    ,<Down> ,rn      Next Input
    ,z      ,rr      Refresh REPL Buffer


Also see |slimv-repl| for additional keybindings valid only in the REPL buffer.
Some menu items or Slimv commands may differ in case Slimv uses the SWANK
client, please find details in |swank.txt|.


===============================================================================
USAGE                                                             *slimv-usage*

After proper installation start Vim and load a *.lisp source file into a
buffer. When the first Slimv command is entered (either from the menu or
via keyboard shortcut or entering a :call Slimv...() at the Vim command line)
then Slimv checks if the server/REPL runs and starts it if nedeed.
When the server is running, the Slimv commands send the appropriate Lisp
forms to the server/REPL for processing. That's it.

All you need to know then is the list of possible Slimv commands, how to
enter them and under what conditions.

It is possible to interrupt a running Lisp program by pressing Ctrl-C,
at least in some Lisp implementations, like CLISP (does not work for example
with SBCL).
In Clojure Ctrl-C exits the REPL by default, but it is possible to change this
behaviour via the add-break-thread! function:
    user=> (use 'clojure.contrib.repl-utils)
    nil
    user=> (add-break-thread!)
Then pressing Ctrl-C results in a SIGINT exception in the current thread.
This may however make bad things to your JVM, so use it with caution.

To end the Lisp session press EOF (Ctrl-D on Linux, Ctrl-Z on Windows)
in the Lisp REPL window. After exiting the REPL it is possible to open
a new one from Vim the same way as before.


===============================================================================
LISP REPL                                                          *slimv-repl*

The Lisp REPL is displayed as a separate terminal window and also inside a
Vim buffer. The Lisp REPL buffer is opened when the Slimv server is started.
The REPL buffer is a more or less regular Vim buffer, all Vim keybindings and
commands can be used here as well.

There are however some subtle differences. The main idea is that the last line
in the REPL buffer is a "command line", just like in any REPL. The command
line usually begins with a prompt, something like "[1] > ". The user types the
command after the prompt in Insert mode. When Enter (<CR>) is pressed, the
contents of the command line (which can actually be multiple lines, when
pasted) is sent to the Lisp REPL for evaluation. It is not allowed to
backspace before the end of the command line prompt.
Please remember that this evaluation style is working only in Insert mode,
in Normal mode the function of <CR> is left unchanged.
Other areas of the REPL buffer can be used to eval Lisp forms, just like
from the .lisp source code. So it is possible to move the cursor inside a form
that was previously eval-ed, make some changes, then eval it again.
Please note, that after evaluation the REPL buffer is refreshed, so the
changes made to the form are restored at that location, but the changed form
will be evaluated at the end of the REPL buffer.

Another difference is the command line history, which can be activated by
pressing <Up> or <Down> in the command line (also only in Insert mode).
Outside of the command line the <Up> and <Down> keys move the cursor,
as usual.

The keys with modified meanings in the Lisp REPL buffer are listed below:

Insert Mode:

    <CR>           Sends the command typed in the last line to the Lisp REPL
                   for evaluation.

    <C-CR>         Adds missing closing parentheses at the end of the command,
                   then sends the command to the Lisp REPL for evaluation.

    <BS>           In the last line it deletes characters to the left only
                   until the end of the Lisp prompt reached.

    <Up>           Brings up the previous command typed and sent to the Lisp
                   REPL when in the command line.

    <Down>         Brings up the next command typed and sent to the Lisp REPL
                   when in the command line.


===============================================================================
CLOJURE SUPPORT                                                 *slimv-clojure*

Vim has a built-in support for Lisp, however it has no Clojure support by
default. As Clojure is a Lisp dialect, Slimv simply reuses Vim's Lisp syntax
and indent plugins for Clojure. It this does not suit your needs, then it is
possible to download and install a separate Clojure plugin parallel to Slimv.

In order to launch the Clojure REPL the variable |g:slimv_lisp| must be
properly set up.
The simplest definition is something like this, which assumes that the
directory for clojure.jar is in the PATH. Please note that the whole expression
needs to be enclosed in double quotes, as it will be passed to the server in
one single command line argument:

  let g:slimv_lisp = '"java -cp clojure.jar;clojure-contrib.jar clojure.main"'

Here follows an example, which starts c:\Clojure\clojure.jar on Windows.
Remember to escape the backslashes:

  let g:slimv_lisp =
  \ '"java -cp c:\\Clojure\\clojure.jar;c:\\Clojure\\clojure-contrib.jar clojure.main"'


===============================================================================
SCHEME SUPPORT                                                   *slimv-scheme*

Slimv has a limited support for Scheme: currently only MIT Scheme is supported
via the SWANK client, using a modified version of swank-mit-scheme.scm in the
slime/contrib directory.
The Scheme SWANK server also requires the 'netcat' program to create sockets.
Please read information about the implementation details in the file header of
swank-mit-scheme.scm.
There is no Hyperspec information for Scheme at the moment.


===============================================================================
PACKAGE AND NAMESPACE HANDLING                                  *slimv-package*

Slimv has a basic support for handling Lisp packages and Clojure namespaces.
This means that at every form evaluation Slimv first searches the source file
for any preceding '(in-package ...)' form for Lisp and '(in-ns ...)' form for
Clojure. If found then each time the package/namespace definition is evaluated
first. This way it is possible to randomly re-evaluate forms in a source (or
multiple sources) that use multiple packages/namespaces, each time the correct
package/namespace will be used.
The package/namespace handling can be switched off via the |g:slimv_package|
option.


===============================================================================
PROFILING                                                     *slimv-profiling*

The SWANK client has the same profiler support as SLIME.

If not using the SWANK client, then Slimv is still capable of utilizing SBCL's
built-in profiler, and also the same monitoring/profiling package
(metering.lisp) that is used by SLIME.

SBCL's profiler is ready to use by just starting the Lisp REPL.
In order to use SLIME's profiler with CLISP it first must be compiled and
loaded into a running REPL. Perform this with the 'Load-Profiler' command.
If the compilation was successful then Slimv is ready to profile.

Use the 'Profile' command to select functions for profiling, 'Unprofile' to
deselect specific functions or 'Unprofile All' to deselect all functions.
Obtain a list of profiled functions with 'Show Profiled'.
use 'Profile-Report' to display profiling results.
Reset profiling counters with 'Profile-Reset'.

When the REPL is restarted, the profiler needs to be reloaded (only in case
of CLISP): select the 'Load-Profiler' command again (this re-compiles
metering.lisp).

It is possible to override the default profile commands via the following
templates (see |slimv_templates|):

    |g:slimv_template_profile|
    |g:slimv_template_unprofile|
    |g:slimv_template_unprofile_all|
    |g:slimv_template_show_profiled|
    |g:slimv_template_profile_report|
    |g:slimv_template_profile_reset|


===============================================================================
HYPERSPEC AND COMPLETION                                      *slimv-hyperspec*

Slimv contains Common Lisp Hyperspec, Clojure API and JavaDoc symbol databases.
When you are looking for the definition of a symbol, just place the cursor on
the symbol and select the 'Hyperspec' function. If the symbol is found in the
symbol database then the corresponding web page is displayed in the default
browser. It is also possible to select this function having just the beginning
of the symbol name, then the first match is presented to the user, and he/she
is asked to confirm or edit the symbol name before the hyperspec lookup.

It is possible to use a local copy of the Hyperspec, for this you need to
define its base URL. See |g:slimv_clhs_root|, |g:slimv_cljapi_root| and
|g:slimv_javadoc_root| for details.

It is also possible to add user defined symbols to the Hyperspec database,
see |g:slimv_clhs_user_db| and |g:slimv_cljapi_user_db|.


The SWANK client requests simple or fuzzy completion from the SWANK server,
see |swank-completions| for details.

Without the SWANK client Slimv uses the Hyperspec symbol database for symbol
name completion, via Vim's omni-completion feature (if it is enabled and
'omnifunc' is not defined already to something else).
Start to enter the symbol in Insert mode, then at some point press the
<C-X><C-O> (omni-complete) key combination or select the 'Complete Symbol'
function. The first match in the symbol database is inserted at the cursor
position and a list of matching symbols is displayed in a submenu.
Use <C-N> to select the next match, <C-P> to select the previous match.

See Vim help file |insert.txt| for details on the usage of the various
completion functions built in Vim.


===============================================================================
EXTERNAL UTILITIES                                             *slimv-external*

This section is about utilities, settings, etc., not related strongly to Slimv,
but may be used to aim Lisp development. These are mostly built-in Vim features
or options, and sometimes external Vim plugins.
Slimv does not want to copy these functionalities, if they exist and work well.


1. Syntax highlighting

The syntax highlighting is done via the default lisp.vim syntax plugin.
For Clojure files one has two options:
a. use the Lisp filetype also for Clojure files (that approach is used by Slimv
   for the REPL buffer if no other filetype is set)
b. install a Clojure Vim syntax plugin, like VimClojure.


2. Indentation

The indentation is also done via the default lisp.vim indent plugin, or an
optionally installed Clojure indent plugin, just like for the syntax
highlighting.
When using the SWANK client and it is connected to the server, then indentation
information is fetched from the SWANK server. This allows special indentation
methods, e.g. when the given macro has an &body argument then it is indented
by 2 spaces (instead of indenting the second argument below the first one).

There are some built-in Vim reindentation commands that may come very handy
when editing Lisp files. One can define a custom key mapping for any of them,
such mappings are not defined by Slimv.

    =                       Reindent selection, after a text has been selected.

    ==                      Reindent current line.

    vab=   or    [(v%=      Select current list and reindent it.

    99[(v%=                 Select top level form and reindent it.

    gg=G                    Reindent whole file.


3. Parenthesis handling

First of all there is paredit mode. If you don't like it, Vim still obtains
many tools to aid working with parentheses. This is a very important topic
for a Lisp programmer.

    :inoremap ( ()<Esc>i    Automatically insert closing parenthesis mark when
                            an opening one is inserted.

    :inoremap [ []<Esc>i    Same as above but for square brackets.

    :set showmatch          Briefly jump with the cursor to the matching
                            parenthesis or square bracket when a closing pair
                            is inserted.

    %                       Go to the matching parenthesis or square bracket.

    :source $VIMRUNTIME/macros/matchit.vim
                            Adds extended matching with "%" to Vim.

    vab    or    [(v%       Select current list.
    vib                     Select current list without enclosing parentheses.
    yab                     Yank current list.
    dab                     Delete current list.

    99[(v%                  Select top level form.

    g:lisp_rainbow          Colorize differing levels of parenthesization with
                            different highlighting. Currently works only for
                            the 'lisp' filetype, hopefully it will be added
                            soon to the Clojure plugins as well.


4. Completion

    CTRL-N                  The built-in Vim keyword completion is a very handy
    CTRL-P                  feature. You start typing a word, and when CTRL-P
                            or CTRL-N is pressed, then Vim looks up the keyword
                            starting with the same letters as typed in up or
                            down direction in the current buffer.
                            This is not the same as the omni-completion
                            feature (see |slimv-hyperspec|). Omni-completion is
                            based on a symbol database and not on the contents
                            of the current buffer.

    :set complete           The |'complete'| option controls how keyword
                            completion works.


5. Tag lookup

Also see Slimv option |g:slimv_ctags|.

    |ctags|                 "Exuberant ctags" is a powerful utility for
                            generating tag database for different kind of
			    programming languages, including Lisp. Tag lookup
                            is then done via the CTRL-] (or :tag) command,
                            return to the previous positon with CTRL-T.

    ctags --language-force=lisp *.lisp *.clj
                            This or a similar command may be used to generate
                            tags file from .lisp and .clj files in a directory.


===============================================================================
FAQ                                                                 *slimv-faq*

- Q: Why is this plugin called 'Slimv'?
- A: Because it is trying to mimic the popular Emacs extension 'SLIME'.
     In SLIME 'E' stands for 'Emacs', so here it is replaced with 'V' as Vim.
     The most recent plugin version also contains a SWANK client, so Slimv's
     functionality is getting closer to SLIME.
     To tell the truth, first I gave the name 'Slimvim' to the plugin but
     then I found an (already abandoned) project called 'Slim-Vim' and I did
     not want to interfere with it.

- Q: Why another 'Superior Lisp Mode' if there is already one (for Emacs)?
- A: Because many programmers prefer Vim as a program text editor over Emacs,
     including me. I don't want to start a holy war or whatsoever, I'm just
     happy if someone else finds this plugin useful.

- Q: But there are other similar projects for Vim. Why having yet another
     SLIMxxx for Vim?
- A: To my knowledge, none of the above mentioned Vim scripts/extensions
     contain all the functionalities of SLIME (nor does Slimv, to tell the
     truth). There is definitely room for improvement.
     It would be nice to make Vim as usable as Emacs for Lisp programming.
     In my opinion the main barrier is the lack of asynchronous buffer update
     in Vim, but this may change in the future.

- Q: How does Slimv work?
- A: Slimv consists of three parts by the original concept:
     Vim plugin, client and server.
     The Slimv server is a swank-like server that embeds a console Lisp REPL
     via pipes, catching all REPL input/output.
     The Slimv client interfaces with the server and is responsible
     for sending Lisp commands to the Lisp REPL.
     The Vim plugin is translating editor commands to Lisp commands to be
     sent to the server by the client.
     So the dataflow is like this:
     Vim -> Vim plugin -> Slimv client -> Slimv server -> Lisp REPL
     The plugin resides in 'slimv.vim', the client and the server both
     located in 'slimv.py'.

     Slimv also contains a SWANK client that is able to communicate a
     running SWANK server, just as it is done by Emacs with SLIME.
     The SWANK output is regularly polled via the socket connection.
     The SWANK client is located in 'swank.py'.

- Q: There is no Slimv server opened when I evaluate a form in Vim.
- A: There may be many reasons for that. Try to run the server manually by
     opening a new terminal console window and running this command:
         {python command} {slimv.py path} -l {lisp command} -s
     where
         {python command} is the command to start the Python interpreter,
         {slimv.py} is the path for slimv.py (usually in Vim's ftplugin dir),
         {lisp command} is the command to start Lisp (or Clojure).
     Examples:
         c:\python24\python "c:\Program Files\Vim\vimfiles\ftplugin\slimv.py" -l c:\clisp\clisp.exe -s
         python /home/username/.vim/ftplugin/slimv.py -l sbcl -s
     Please remember to enclose each parameter in double quotes if that
     parameter contains spaces.
     Also check the following Slimv variables in Vim, maybe they are not
     correctly autodetected and you need to override them in your .vimrc:
         :echo g:slimv_python
         :echo g:slimv_lisp
         :echo g:slimv_client         

- Q: The Slimv plugin is not loaded for a .lisp (or .clj, etc) file.
- A: Filetype plugins should be enabled, check it via the :filetype command.
     If needed, put this in your .vimrc file:
         filetype plugin on
         filetype indent on
     You can check the scripts loaded with the :scriptnames command,
     filetype.vim and ftplugin.vim should be listed in order to load other
     filetype plugins.
     The source buffer filetype should be lisp (or clojure, etc), check it via
         :set ft?
     The Slimv files should be in Vim's runtime path, check the path via
         :set rtp?
     slimv.vim should be in the ftplugin directory in the runtimepath,
     there should be an ftplugin/lisp subdirectory containing slimv-lisp.vim.
     Also make sure that no other ftplugin/lisp.vim is loaded that prevents
     loading of the Slimv scripts.

- Q: Why is SLIME functionality XYZ missing from Slimv?
- A: There are two possible reasons:
     1. The dataflow of Slimv is one-directional: from client to server.
        There is no data sent back from the server to the client, so if a
        functionality requires that Slimv reads data from REPL, then
        currently it is not possible to implement it.
     2. It is possible to implement it, but I did not (yet) do it.
        Maybe future releases will contain it. All feature requests are
        welcome.

- Q: Why is the default Slimv port number 5151?
- A: Hint: what roman numerals are 5,1,5,1? Bingo: VI, doubled.

- Q: What is the version numbering concept?
- A: <major version>.<minor version>.<bugfix release>, where:
     major  version: Let's talk about it when it reaches 1...
     minor  version: New functionalities added, that are worth mentioning.
     bugfix release: Only bugfixes or tiny additions.

- Q: Why is the plugin distributed in zip file?
- A: I want that Windows/Linux/Mac users all can easily extract the plugin
     files. For this reason the vimball or zip format seems to be a good
     choice. There is no native .tar, .tar.gz, .tar.bz2 decompressors on
     Windows (however there exist free tools for the job, like 7zip).
     I'm relatively new to vimball and it looks like a good candidate, but
     I have some problems with it:
     1. It is uncompressed, and if I want to compress it then I will end up
        having it zipped.
     2. The .vba extension is also used for Visual Basic scripts on Windows
        and this frequently contains virus, so Windows users may dislike it.
        And remembering the very first time I met a vba file I was thinking
        that someone had created a Visual Basic installer for the script.
     3. Many Vim users don't know vimball but most of them know zip files.

- Q: Are you a Lisp expert?
- A: No, not at all. I'm just learning Lisp. Also just learning Vim
     scripting. And I'm not a Python expert either, however (at the moment)
     I have more experience with Python than with Lisp.

- Q: What about Clojure?
- A: I have even less experience with Clojure than with Lisp.
     But it looks like the Slimv functions can be easily ported for Clojure,
     and as there are not many (yet) Vim scripts written for Clojure, I gave
     it a try.

- Q: Why using Python for the client/server code? Why not Lisp?
- A: It is needed to use one of Vim's embedded languages for maintaining a
     permanent socket connection from within Vim. There aren't too many choices,
     and Lisp is not (yet?) embedded into Vim.

===============================================================================
CHANGE LOG                                                    *slimv-changelog*

0.8.6  - Handle cl:in-package, common-lisp:in-package (thanks to Philipp Marek).
       - Added option g:swank_host to allow connecting to remote Swank server.
       - Autodetection of Cake for Clojure (thanks to Chris Cahoon).
       - Set Paredit mode also for .cl and .rkt files.
       - Recognise domain reversed package names in form com.gigamonkeys.pathnames
         (thanks to has2k1).
       - Added curly braces rainbow parenthesis for Clojure.
       - Added paredit handling of curly braces for Clojure.
       - Use SlimvIndent also for Clojure.
       - Handle line number returned in :compilation-result.
       - Bugfix: removed double newline in :read-string (text input).
       - Bugfix: when editing with cw in paredit mode, keep ending whitespaces
         (thanks to Mats Rauhala).
       - Bugfix: compilation error when Swank does not return file name.
       - Bugfix: skip dot character when Swank returns a dotted pair (a . b).

0.8.5  - Switch on indent plugins.
       - Do not complete empty string on <Tab>.
       - Added Clojure keywords to syntax plugin.
       - Use -i option to load swank-clojure.
       - Implementation specific REPL initialization, for Clojure it imports
         source, apropos, javadoc, etc. (thanks to �mer Sinan Agacan).
       - Print Lisp version at REPL startup.
       - Added List-Threads, Kill-Thread, Debug-Thread (thanks to Philipp Marek).
       - Write prompt after Toggle-Trace.
       - Display list of untraced functions for Untrace-All.
       - When in SLDB, Interactive-Eval evaluates expressions in the frame,
         Inspect inspects objects in the frame.
       - Changed g:slimv_echolines logic: set 0 for no lines, -1 for all lines.
       - Bugfix: removed extra linebreak between chunks of long output.
       - Bugfix: indentation problems for symbols with package specification
         (thanks to Philipp Marek).
       - Bugfix: indentation of Clojure's defn.
       - Bugfix: plist indentation (thanks to Philipp Marek).
       - Bugfix: occasional few seconds delay in swank response.
       - Bugfix: running Swank server on Mac OS X (on behalf of Tobias Pflug).

0.8.4  - Added handling for Unicode characters.
       - Truncate arglist output to fit in the status line.
       - Added debugger keybindings: ,a for abort ,q for quit ,n for continue.
       - Changed keybinding for apropos to ,A
       - Added compiler error messages to quickfix list.
       - Map insert mode <Space> and <Tab> only for lisp (and dialects) buffers.
       - Bugfix: wait for the response to :create-repl before calling
         :swank-require (thanks to Philipp Marek).
       - Bugfix: indentation problems with unbalanced parens in comment.
       - Bugfix: arglist ate the <Space> when virtualedit was off.

0.8.3  - Added top/bottom/left/right directions to g:slimv_repl_split.
       - Added :Lisp (and an equivalent :Eval) command with completion.
       - Added g:slimv_leader and g:paredit_leader options.
       - Added g:slimv_echolines to echo only the first few lines of the
         form being evaluated.
       - Added fuzzy completion and option g:slimv_simple_compl (by Philipp Marek).
       - Indent macros with &body argument by two spaces when connected to swank
         (thanks to Philipp Marek and Andreas Fredriksson).
       - Special indentation for flet, labels, macrolet.
       - Default for Set-Package is current package (thanks to Philipp Marek).
       - Bugfix: REPL output ordering problems.
       - Bugfix: problem with inserting Space into visual block.
       - Bugfix: blinking when g:slimv_repl_syntax is on.
       - Bugfix: entering incomplete form in REPL command line.
       - Bugfix: close form when inside comment, string, or with mixed ([.

0.8.2  - Added Paredit and g:lisp_rainbow support for Scheme files.
       - Added SWANK support for MIT Scheme on Linux.
       - Added frame call information to SLDB (thanks to Philipp Marek).
       - Check for unbalanced form before evaluation.
       - Reconnect SWANK server in Connect-Server if already connected
         (thanks to Philipp Marek).
       - Select current form instead of top level form in Macroexpand.
       - Bugfix: Paredit handling of escaped matched characters, like \" or \(.
       - Bugfix: cursor positioning problems when debugger activated.
       - Bugfix: print prompt after Describe.

0.8.1  - Added action handling to Inspector, fixed Inspector output.
       - Bugfix: read-string mode was stuck.
       - Bugfix: buffer corruption with two source windows
         (thanks to Philipp Marek).
       - Bugfix: eliminate multiple CursorHold autocommands
         (thanks to Philipp Marek).
       - Bugfix: completion with special characters in symbol name
         (thanks to Philipp Marek).
       - Bugfix: sometimes cursor went to the start of line in insert mode.
       - Bugfix: syntax error in Untrace All (thanks to Philipp Marek).
       - Bugfix: removed ' prefix from symbol selection (except for Inspect).
       - Bugfix: keep cursor position in Describe and Compile-Region.

0.8.0  - Major update: added SWANK client (many thanks to Philipp Marek).
       - Split documentation into three parts.
       - Added keymapping hints to GUI menu items.
       - Renamed Eval-Last-Expression to Eval-Current-Expression.
       - REPL buffer is not syntax highlighted anymore.
       - Switch on filetype plugins.
       - Autodetection for Allegro CL, Lisp Cabinet and Leiningen.
       - Ask for save before compiling file.
       - Map <Tab> for symbol name completion.
       - Bugfix: finding start of keyword in completion.
       - Bugfix: deleting escaped " inside string.
       - Bugfix: Up/Down/Enter handling in popup menu.

0.7.7  - Paredit: find next closing paren when using ,< or ,> and not standing
         on a paren.
       - Open REPL buffer upon connecting server.
       - Bugfix: REPL buffer prompt identification was sometimes missing.
       - Bugfix: switch off REPL refresh mode when REPL buffer is not visible
         (thanks to Philipp Marek).
       - Bugfix: convert Python path on Windows to short 8.3 filename format
         if it contains space (thanks to Razvan Rotaru).

0.7.6  - Cursor potision is kept during evaluation.
       - Most Slimv commands made silent.
       - Bugfix: find defun start when cursor is on a comment.
       - Bugfix: keep newlines in Compile-Region.
       - Bugfix: infinite loop when selecting form in empty buffer.
       - Bugfix: error when opening REPL buffer with g:slimv_repl_split=0.
       - Bugfix: REPL blinking in insert mode when visualbell is on.
       - Bugfix: added the comma to the list of macro prefix characters
         (thanks to John Obbele).
       - Bugfix: long/short Windows filename problem for REPL buffer.

0.7.5  - Added Cygwin compatibility using the Windows Python
         (thanks to Jerome Baum).
       - Display client error message when eval was not successful.
       - Form is passed to client via stdin instead of temp file.
       - Bugfix: automatic reconnection when server closed and reopened.
       - Bugfix: delete and yank also via named registers in paredit.vim.
       - Bugfix: handle double quotes in Compile-Defun and Compile-Region.

0.7.4  - Added autodetection for simple 'clojure' command on Linux.
       - Removed duplicates from history of commands entered in REPL buffer
         (those recallable with <Up> and <Down>).
       - Bugfix: infinite loop during eval when 'in-package' or 'in-ns'
         was in comment.
       - Bugfix: Lisp prompt identification problems in REPL buffer.
       - Bugfix: input line duplication in SBCL on Linux
         (assigned "*debug-io*" to stdin).
       - Bugfix: Eval Defun missed last ")" if form contained "'('".

0.7.3  - Added compatibility with Python 3.x.
       - Bugfix: input lines for REPL were doubled on Linux (thanks to
         Andrew Hills), however not yet fixed for SBCL.
       - Bugfix: enclose Slimv path in double quotes if it contains space.
       - Bugfix: select form when standing on prefix character (e.g. ' or `).

0.7.2  - Added autodetection for /usr/local/bin/clojure on Linux.
       - Added special characters to Lisp keyword selection (iskeyword).
       - Run Vim's original ftplugin/lisp.vim for Clojure filetype.
       - Bugfix: PareditWrap error when g:paredit_shortmaps=1 (thanks to
         Jon Thacker).
       - Bugfix: buffer selection problems in case of three of more buffers
         (thanks to Philipp Marek).
       - Bugfix: conflicting keybindings for SlimvGenerateTags.
       - Bugfix: unmap error messages when g:paredit_mode=0.

0.7.1  - Added option g:slimv_browser_cmd for opening hyperspec in a custom
         webbrowser (on behalf of Andreas Salwasser).
       - Added paredit handling for d<motion>, c<motion>, p and P commands:
         keep paren balance when deleting and pasting text.
       - Paredit Toggle function removes and re-adds paredit keybindings.
       - Bugfix: D and C deleted till beginning of line if () or [] found.
       - Bugfix: handle escaped \" characters inside string.

0.7.0  - Added package/namespace support.
       - New way of refreshing the REPL buffer via autocommands, removed
         'RUNNING' mode, cursor stays in the current buffer at evaluation.
       - Added option g:slimv_updatetime.
       - Removed options related to the old way of refreshing:
         g:slimv_repl_return and g:slimv_repl_wait.
       - Removed debug logging.
       - Updated Clojure API to version 1.2.
       - Extended keyword definition when selecting symbols.
       - Bugfix: defmacro detection problem (again).

0.6.3  - Added option g:slimv_repl_return to return cursor to the editor window
         from REPL buffer after evaluating an s-expression.
       - Wrap: if standing on a paren then wrap the whole s-expression.
       - Wrap selection: exit visual mode after command.
       - Bugfix: inserting double quotes in paredit mode (like "\"").
       - Bugfix: dd in paredit mode when unbalanced form is inside comment.
       - Bugfix: reopen REPL buffer after closing it via :q.
       - Bugfix: comment and string detection error with noignorecase setting
         (thanks to Brian Kropf).
       - Bugfix: wrong positioning when moving parenthesis to the right.
       - Bugfix: defmacro detection problem (thanks to Philipp Marek).
       - Bugfix: paredit wrap selection missed last character when 'selection'
         was not "exclusive".

0.6.2  - Added support for Mac OS X via Terminal.app (on behalf of Vlad Hanciuta).
       - Added string "clj" as a detector for Clojure (by Vlad Hanciuta).
       - Bugfix: paredit wrap function missed last character when 'selection'
         was not "exclusive" (thanks to Marcin Fatyga).
       - Bugfix: input was stuck inside SBCL debugger
         (on behalf of Philipp Marek and Dmitry Petukhov).
       - Bugfix: occasional error messages during REPL buffer update.
       - Bugfix: REPL menu was sometimes missing.
       - Bugfix: occasional command line color problems.

0.6.1  - Added Split, Join, Wrap, Splice functions to Paredit Mode.
       - Added g:paredit_shortmaps to select short/long paredit keymaps.
       - Bugfix: delete commands put erased characters into yank buffer.
       - Bugfix: D deletes only characters after the cursor position.

0.6.0  - Added paredit mode.
       - Set wrap mode for REPL buffer with keybindings.

0.5.6  - Improved REPL buffer response time.
       - Added debug log flushing frequency.
       - Bugfix: early exit of REPL refresh mode on some machines.

0.5.5  - Updated Clojure API to 1.1.
       - Expand tilde-prefix to home directory on Linux.
       - Autodetect Clojure in the user home directory on Linux.

0.5.4  - Added autodetection for clojure-contrib.jar.
       - Added autodetection for Clozure CL.
       - Applied lisp_rainbow to Clojure's [].
       - Renamed Clojure indent plugin to clojure.vim
         so that Vim finds and loads it.
       - Switched on lisp mode explicitly for Clojure filetype.

0.5.3  - Added Interrupt-Lisp-Process command.
       - Added mapping for the REPL menu.
       - Added special forms to Clojre API lookup.
       - Bugfix: put cursor after the last character in insert mode when
         continuously refreshing REPL buffer.
       - Fixed some Ctrl-C handling problems.

0.5.2  - Updated Clojure API.
       - Adapted Clojure autodetection to version 1.0 (clojure-1.0.0.jar).
       - Complete-Symbol command moved to separate Edit submenu.
       - Added Close-Form command to the Edit submenu.

0.5.1  - Added symbol name completion based on the Hyperspec database.

0.5.0  - Major project reorganization:
         Slimv is now a Lisp and Clojure filetype plugin.
       - Added Common Lisp Hyperspec, Clojure API, and JavaDoc lookup.
       - Separate menu for REPL buffer, menu items work in every Vim mode.
       - Fixed mark 's usage bug - thanks to Lorenzo Campedelli.

0.4.1  - Added profiler support for SBCL.
       - Added commands/menu items: Profiling: Show Profiled,
         REPL: Send Input, Close and Send Input, Previous Input, Next Input
       - Display Slimv error messages with ErrorMsg highlight.

0.4.0  - Added SLIME's profiling tool with support from Slimv.
       - Added command to generate tags file.
       - Fixed evaluation problems of large buffers on some systems.
       - Fixed Compile And Load filename problems with '\' on Windows.
       - Recycle old REPL temporary file at next server startup.

0.3.0  - Added syntax highlighting and automatic indentation for the REPL
         buffer (needs lisp and/or clojure Vim plugins).
       - It is possible to enter a multi-line command in the REPL buffer,
         until the opening and closing parens match.
       - Insert mode Up and Down keys move cursor when outside of the REPL
         command line.
       - Ctrl-C is working inside the REPL buffer (while waiting for output),
         so Ctrl-X and Ctrl-X Ctrl-X keybindings are removed.
       - REPL window performance enhancement on Linux.

0.2.2  - Fixed REPL input and output mix-up problems.
       - Evaluation performance enhancement.
       - Corrected some more macroexpand problems.

0.2.1  - Added basic Clojure support.
       - Corrected some macroexpand problems.
       - Fixed a REPL buffer refresh bug.

0.2.0  - Major update: Lisp REPL displayed in a Vim buffer.

0.1.4  - Corrected the delayed display of last line in REPL window on Linux.
       - Ctrl-C is propagated to Lisp REPL, so it is possible to interrupt
         a running program. Does not work however with some Lisp
         implementations (like SBCL).

0.1.3  - Handle DOS and Unix style newlines produced by various
         Lisp implementations on Windows.
       - Do not write debug logfile when debug level is zero.
       - Removed unused client command line argument: -c

0.1.2  - Windows users do not need pywin32 anymore.
       - Display buffer is more thread safe.

0.1.1  - Corrected memory fillup problem after a long REPL session.

0.1    - Initial release.

===============================================================================
ISSUES, LIMITATIONS, KNOWN BUGS                                  *slimv-issues*

- Vim register "s is used for all form selections, so its original content is
  destroyed.
- Vim mark 's is used to mark the end of the REPL buffer, i.e. the beginning
  of the "command line".
- Needs Vim version 7.0 or above, because of the intensive use of lists.
- Needs the same Python version that Vim is compiled against
- It is not possible to run separate Lisp and Clojure REPL in the same
  Slimv session.


===============================================================================
TODO                                                               *slimv-todo*

- Add missing SLIME functions to the SWANK client.
- Separate SLDB/Inspector/etc buffers from the REPL buffer.
- Allow connecting remote SWANK server (outside of localhost).

===============================================================================
CREDITS                                                         *slimv-credits*

Author: Tamas Kovacs <kovisoft at gmail dot com>

Please send comments, bug reports, suggestions, etc. to the e-mail address
above.

Slimv is free software, you can redistribute it and/or modify it any way you
like, except the embedded SLIME and Swank Clojure.

SLIME is distributed under the terms of the GNU General Public License as
published by the Free Software Foundation. See the included slime/README file
or http://common-lisp.net/project/slime/ for details.

Swank Clojure is licensed under the Eclipse Public License. See the file
swank-clojure/COPYING or https://github.com/technomancy/swank-clojure for
details.

Credit must go out to Bram Moolenaar and all the Vim developers for making
the world's (one of the) best editor.

Thanks to Eric Marsden, Luke Gorrie, Helmut Eller, Luke Gorrie, Helmut Eller,
Tobias C. Rittweiler and all the Emacs/SLIME developers for making SLIME.
Also special thanks to Erik Naggum, Yuji Minejima and others for making the
Common Lisp Hyperspec lookup packages for SLIME, and thanks to
Taylor R. Campbell for the Emacs paredit.el script.

Thanks to Jeffrey Chu, Phil Hagelberg, Hugo Duncan for making Swank Clojure,
and to Helmut Eller for making Scheme Swank server.

Thanks to the Vim community for testing, commenting and patching the script,
especially to Philipp Marek for his great number of contributions, patches,
ideas, suggestions on the SWANK integration.

Also thanks to Vlad Hanciuta, Marcin Fatyga, Dmitry Petukhov,
Daniel Solano G�mez, Brian Kropf, Len Weincier, Andreas Salwasser,
Jon Thacker, Andrew Hills, Jerome Baum, John Obbele, Andreas Fredriksson,
�mer Sinan Agacan, Tobias Pflug, Chris Cahoon, Mats Rauhala for additional
notes and contributions.

I would also like to say a big thank you to everyone donating to support
development. This is a one-element list at the moment: :)
thanks to Paul Michael Bauer.

Last but not least many thanks to my wife Andrea (for the Italians out there:
hey, this is a female name in Hungary :) for her support and patience.

===============================================================================
vim:tw=80:et:wrap:ft=help:norl: