*scratch.txt*   Emacs like scratch buffer

Version 0.1+
Script ID: 2107
Copyright (C) 2007 kana <http://whileimautomaton.net/>
License: MIT license  {{{
    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    "Software"), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject to
    the following conditions:

    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
    OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
}}}

CONTENTS                                        *scratch-contents*

Introduction            |scratch-introduction|
Interface               |scratch-interface|
  Commands                |scratch-commands|
  Functions               |scratch-functions|
  Key Mapings             |scratch-key-mappings|
Customizing             |scratch-customizing|
  Variables               |scratch-variables|
  Autocommands            |scratch-autocommands|
Bugs                    |scratch-bugs|
ChangeLog               |scratch-changelog|




==============================================================================
INTRODUCTION                                    *scratch-introduction*

*scratch* is a Vim plugin to provide Emacs-like scratch buffer.  You can write
anything in it, and you can also evaluate a part of the buffer as Vim script.
It is a temporary buffer and it is not related to a real file, so the content
of the buffer will be discarded when you quit Vim.  This buffer is useful when
you test a bit of script or other use.


Requirements:
- Vim 7.0 or later

Latest version:
http://github.com/kana/config/commits/vim-scratch

Document in HTML format:
http://kana.github.com/config/vim/scratch.html




==============================================================================
INTERFACE                                       *scratch-interface*

------------------------------------------------------------------------------
COMMANDS                                        *scratch-commands*

:ScratchOpen                                    *:ScratchOpen*
        ``Open'' the scratch buffer, i.e., create the buffer if it does not
        exist, show if it is not visible, or move the cursor to the window
        that shows it.

        See |g:scratch_show_command| if you want to change the way to open.

:ScratchClose                                   *:ScratchClose*
        Close a window that shows the scratch buffer if able.

:[range]ScratchEvaluate[!]                      *:ScratchEvaluate*
        Evaluate the [range] as a Vim script.
        The default [range] is the current line.
        Without [!], the cursor will be moved to the next line of the script
        after evaluating.  If there is no line to move, new blank line will be
        appended then the cursor will be moved to the new line.
        With [!], such adjustment will not be done.


------------------------------------------------------------------------------
FUNCTIONS                                       *scratch-functions*

scratch#open()                                  *scratch#open()*
        Function version of |:ScratchOpen|.
        The return value is not defined.

scratch#close()                                 *scratch#close()*
        Function version of |:ScratchClose|.
        The return value is not defined.

                                                *scratch#evaluate_linewise()*
scratch#evaluate_linewise({line1}, {line2}, {adjust-cursorp})
        Function version of |:ScratchEvaluate|.
        If {adjust-cursorp} is true, the cursor position will be adjusted as
        same as |:ScratchEvaluate|.  If {adjust-cursorp} is false, such
        adjustment will not be done.
        The return value is not defined.

scratch#evaluate({pos1}, {pos2}, {adjust-cursorp})      *scratch#evaluate()*
        Same as |scratch#evaluate_linewise()|, but this takes the range of the
        script to be evaluated as {pos1} and {pos2}, which are same as the
        returning value of |getpos()|.
        The return value is not defined.


------------------------------------------------------------------------------
KEY MAPPINGS                                    *scratch-key-mappings*

GLOBAL MAPPINGS ~

<Plug>(scratch-open)                            *<Plug>(scratch-open)*
        Do |:ScratchOpen|.

<Plug>(scratch-close)                           *<Plug>(scratch-close)*
        Do |:ScratchClose|.

<Plug>(scratch-evaluate)                        *<Plug>(scratch-evaluate)*
        Do |:ScratchEvaluate| without [!].

<Plug>(scratch-evaluate!)                       *<Plug>(scratch-evaluate!)*
        Do |:ScratchEvaluate| with [!].

SCRATCH BUFFER-LOCAL MAPPINGS ~

<C-j>   or                                      *<C-j>*
<C-m>   or                                      *<C-m>*
<CR>                                            *<CR>*
        Mapped to |<Plug>scratch-evaluate|.
        Note that these mappings will not be defined when {lhs} is already
        mapped to something.




==============================================================================
CUSTOMIZING                                     *scratch-customizing*

------------------------------------------------------------------------------
VARIABLES                                       *scratch-variables*

                                                *g:scratch_buffer_name*
g:scratch_buffer_name           string (default: "*Scratch*")
        The name of the scratch buffer.
        Note that this value must be set before this plugin is loaded (for
        example, in $MYVIMRC).

                                                *g:scratch_show_command*
g:scratch_show_command          string (default: 'topleft split | hide buffer')
        The command to show the scratch buffer.  When this plugin shows the
        scratch buffer, it will execute the following script: >

        execute g:scratch_show_command the_buffer_number_of_the_scratch_buffer
<
        Examples:
        'topleft split | hide buffer' (default value)
                Create new window at the top and show in it.
        'hide buffer'
                Show in the active window.


------------------------------------------------------------------------------
AUTOCOMMANDS                                    *scratch-autocommands*

When the scratch buffer is created, two events will be triggered to initialize
it.  If you want to add and/or override the default settings, use |autocmd|
like the following: >

        autocmd User PluginScratchInitializeBefore {any-command}
        autocmd User PluginScratchInitializeAfter {any-command}
<
"User PluginScratchInitializeBefore" is triggered before the default
initialization.  "User PluginScratchInitializeAfter" is triggered after the
default initialization.

The default initialization does:
- set 'filetype' as vim.  (if 'filetype' is not set)
- put some informative message.  (if 'filetype' is vim)
- define several buffer-local key mappings.




==============================================================================
BUGS                                            *scratch-bugs*

- Don't do |:edit|, |:bunload| or |:bdelete| on the scratch buffer.  The
  content of the scratch buffer and/or other information (e.g., mappings) will
  be cleared.
  If you did it accidentally, do |:bwipeout| then |:ScratchOpen| to recreate
  the scratch buffer.

- |:ScratchOpen| - To create the scratch buffer, the current buffer will be
  hidden temporary.  This behavior may cause some problems.

- |:ScratchEvaluate| - Is it useful to evaluate any programming language other
  than Vim script?




==============================================================================
CHANGELOG                                       *scratch-changelog*

0.1+    2008-01-13T00:47:42+09:00               *scratch-changelog-0.1+*
        - Modify |:ScratchEvaluate| to accept |line-continuation|.
        - scratch#open(): Modify not to use g:scratch_show_command in some
          cases to avoid showing the scratch buffer in two windows.

0.1     2007-12-25T03:57:18+09:00               *scratch-changelog-0.1*
        - Rewrote.

0.0     2007-xx-xx                              *scratch-changelog-0.0*
        - Initial version.




==============================================================================
vim:tw=78:ts=8:ft=help:norl:fen:fdl=0:fdm=marker: