ZyX_I avatar ZyX_I committed 240b945

Added readme, some doc fixes

Comments (0)

Files changed (2)

+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)
+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:
+
+        " Define a leader for group `Foo'. Replace with 0 to disable group
+        let g:frawormap_Foo=','
+
+        let g:frawormap_Foo_bar='t'
+        let g:frawormap_Foo_baz=0
+
+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'],})
+
+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
+
+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.
         digits and underscores) as keys and |frawor-t-mapping| as values.
         {mgid} is one of the following:
         1. Unique string that starts with an uppercase latin letter and 
-           contains only latin letters, digits and underscores.
+           contains only latin letters and digits.
         2. Zero. In this case unique {mgid} will be generated and then 
            returned by function, you will have to use it to map/unmap/delete 
            mapping group. Note that {mgid}=0 enables `nouser' option (see 
                    |frawor-mo-mgid_mapname| unless `nouser' key was specified 
                    when mapping group was defined.
                                                                *frawor-mk-rhs*
-        rhs        String, List or Dictionary. Depending of the type may have 
-                   the following meanings:
+        rhs        String, List, Function reference or Dictionary. Depending 
+                   of the type may have the following meanings:
                    1. String: {rhs} of the mapping. If |frawor-mk-strfunc| is 
                       present then all occurences of "%str" will be replaced 
                       with call to a function that will return requested 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.