YAML dumper/emitter in pure vimscript
Vim script
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
autoload
doc
plugin
templates
README
README.markdown

README.markdown

Frawor is a modular vim framework designed to collect some commonly needed functions.

To start using the only thing you should do is to add

execute frawor#Setup('0.0', {})

where '0.0' is your plugin version and {} is a dictionary containing plugin dependencies (the core frawor module is added to dependencies automatically). There are additional rules you should follow:

  1. All script-local functions should be anonymous functions:

     function s:F.somefunc(args)
    

    In some plugins you may even end with having no non-anonymous function definitions.

  2. If function cannot be anonymous (because it is is to be used by sort(), for example), then its name should be added to s:_functions list.

  3. If you define a command, its name should go to s:_commands list, same for autocommand groups (s:_augroups).

  4. All script-local variables whose name starts with s:_ are reserved and should be used only in a way described in documentation.

Advantages

  1. Plugin reloading for easier development and updates without vim restart:

     call frawor#Reload('plugin/frawor')
    

    to reload all plugins (as they all depend on core frawor module).

  2. Frawor provides an easier way to mappings customization:

     execute frawor#Setup('0.0', {'@/mappings': '0.0'})
     <...>
     call s:_f.mapgroup.add('Foo',
             \{'bar': {'lhs': 't', 'rhs': ':Bar<CR>'},
             \ 'baz': {'lhs': 'T', 'rhs': s:F.baz}},
         \{'leader': '<leader>', 'silent': 1})
    

    will define two mappings: <leader>t which will call command :Bar and <leader>T which will run s:F.baz function. Both mappings are silent. Now pretend that you are the user who does not need to run s:F.baz and wants to launch :Bar using ,t. In this case all he needs is to add the following lines to the vimrc:

     let g:frawormap_Foo=','
    
     let g:frawormap_Foo_bar='t'
     let g:frawormap_Foo_baz=0
    

    Replacing ',' with 0 here will lead to disabling the whole mapping group.

  3. Options:

     "plugin/foo.vim:
     execute frawor#Setup('0.0', {'@/options': '0.0'})
     let s:_options={'columns': {'default': 80, 'checker': 'range 0 inf'}}
     <...>
                 let columns=s:_f.getoption('columns')
     <...>
    
     "vimrc:
     let g:foo_columns=78
     autocmd FileType vim  let b:foo_columns=78
    

    If you don't want to prefix your options with foo (second component after runtimepath of a path to your plugin), define s:_oprefix. Note the checker key: it saves you from writing code for checking user input (but will instead generate an exception for invalid value).

  4. Function argument checks:

     execute frawor#Setup('0.0', {'@/functions': '0.0'})
     let s:formats={'html': ...,
                   \'markdown': ...}
     function s:F.checkedfunc(format, columns)
         <...>
     endfunction
     let s:F.checkedfunc=s:_f.wrapfunc({'function': s:F.checkedfunc,
                                       \'@FWC': ['key formats  '.
                                       \         'range 0 inf', 'check'],})
    

    Here you can see FWC decorator which uses FWC-to-vimscript compiler where FWC is a name of the domain-specific language written exclusively for frawor.

  5. Complicated command-line arguments handling:

     execute frawor#Setup('0.0', {'@/commands': '0.0'})
     let s:formats={'html': ...,
                   \'markdown': ...,}
     function s:F.run_foo(options)
         " Here a:options is dictionary containing all prefixed options user
         " have given on the command-line
         let format=a:options.format
         let columns=a:options.columns
         if a:options.beatify
             <...>
         endif
     endfunction
     "                Prefix  default  Description of
     "                         value   the prefix argument
     let s:foo_args='{columns :=(80)   |earg range 0 inf '.
                   \'  format          key formats '.
                   \'!beatify :=(0)'}'
     " Define a :Foo command
     call s:_f.command.add('Foo', {'function': s:F.run_foo,
                                  \    '@FWC': [s:foo_args, 'filter'],}
                          \{'complete': [s:foo_args], 'nargs': '+'})
     " " Example usage:
     " Foo col 78 f markdown
     " Foo nobeatify f html
     " Foo format html beatify c 78
    

    Note that while command accepts short versions of prefixes, s:F.run_foo function will get dictionary with only full names.

  6. Portable versions of OS-specific functions: vimscript implementation of some functions from python os module.

  7. Vimscript base64 encoder/decoder, fancy table echoing, maparg that returns dictionary for old vim's and more.