{"@attributes":{"title":"Google Vimscript Style Guide"},"p":["\n\n    Revision 1.1\n  ","\n    Revision 1.1\n  "],"address":["\n    Nate Soares\n    Artemis Sparks\n    David Barnett\n  ","\n    Nate Soares\n    Artemis Sparks\n    David Barnett\n  "],"OVERVIEW":{"CATEGORY":{"@attributes":{"title":"Background"},"p":"\n        This is a casual version of the vimscript style guide, because\n        vimscript is a casual language. When submitting vim plugin code, you\n        must adhere to these rules. For clarifications, justifications, and\n        explanations about the finer points of vimscript, please refer to the\n        .\n      "}},"CATEGORY":[{"@attributes":{"title":"Portability"},"p":"\n      It's hard to get vimscript right. Many commands depend upon the user's\n      settings. By following these guidelines, you can hope to make your\n      scripts portable.\n    ","STYLEPOINT":[{"@attributes":{"title":"Strings"},"SUMMARY":"Prefer single quoted strings","BODY":{"p":["\n          Double quoted strings are semantically different in vimscript, and\n          you probably don't want them (they break regexes).\n        ","\n          Use double quoted strings when you need an escape sequence (such as\n          ) or if you know it doesn't matter and you need to\n          embed single quotes.\n        "]}},{"@attributes":{"title":"Matching Strings"},"SUMMARY":"\n        Use the  or  operator families over the\n         family.\n      ","BODY":{"p":"\n          The matching behavior depends upon the user's ignorecase and smartcase\n          settings and on whether you compare them with the ,\n          , or  family of operators. Use the\n           and  operator families explicitly\n          when comparing strings unless you explicitly need to honor the user's\n          case sensitivity settings.\n        "}},{"@attributes":{"title":"Regular Expressions"},"SUMMARY":"Prefix all regexes with .","BODY":{"p":["\n          In addition to the case sensitivity settings, regex behavior depends\n          upon the user's nomagic setting. To make regexes act like nomagic and\n          noignorecase are set, prepend all regexes with .\n        ","\n          You are welcome to use other magic levels () and case\n          sensitivities () so long as they are intentional and\n          explicit.\n        "]}},{"@attributes":{"title":"Dangerous commands"},"SUMMARY":"Avoid commands with unintended side effects.","BODY":{"p":["\n          Avoid using  as it moves the cursor and\n          prints error messages. Prefer functions (such as\n          ) better suited to scripts.\n        ","\n          For many vim commands, functions exist that do the same thing with\n          fewer side effects. See  for a list of\n          built-in functions.\n        "]}},{"@attributes":{"title":"Fragile commands"},"SUMMARY":"Avoid commands that rely on user settings.","BODY":{"p":["\n          Always use  instead of . The\n          latter depends upon the user's key mappings and could do anything.\n        ","\n          Avoid , as its behavior depends upon a\n          number of local settings.\n        ","\n          The same applies to other commands not listed here.\n        "]}},{"@attributes":{"title":"Catching Exceptions"},"SUMMARY":"Match error codes, not error text.","BODY":{"p":"Error text may be locale dependent."}}]},{"@attributes":{"title":"General Guidelines"},"STYLEPOINT":[{"@attributes":{"title":"Messaging"},"SUMMARY":"Message the user infrequently.","BODY":{"p":"\n          Loud scripts are annoying. Message the user only when:\n          \n        "}},{"@attributes":{"title":"Type checking"},"SUMMARY":"Use strict and explicit checks where possible.","BODY":{"p":["\n          Vimscript has unsafe, unintuitive behavior when dealing with some\n          types. For instance,  evaluates to true.\n        ","\n          Use strict comparison operators where possible. When comparing against\n          a string literal, use the  operator. Otherwise, prefer\n           or check \n          explicitly.\n        ","\n          Check variable types explicitly before using them. Use functions from\n          , or check  or\n           and throw your own errors.\n        ","\n          Use  for variables that may change types,\n          particularly those assigned inside loops.\n        "]}},{"@attributes":{"title":"Python"},"SUMMARY":"Use sparingly.","BODY":{"p":"\n          Use python only when it provides critical functionality, for example\n          when writing threaded code.\n        "}},{"@attributes":{"title":"Other Languages"},"SUMMARY":"Use vimscript instead.","BODY":{"p":"\n          Avoid using other scripting languages such as ruby and lua. We can\n          not guarantee that the end user's vim has been compiled with support\n          for non-vimscript languages.\n        "}},{"@attributes":{"title":"Boilerplate"},"SUMMARY":"\n        Use .\n      ","BODY":{"p":"\n          maktaba removes boilerplate, including:\n          \n        "}},{"@attributes":{"title":"Plugin layout"},"SUMMARY":"Organize functionality into modular plugins","BODY":{"p":"\n          Group your functionality as a plugin, unified in one directory (or\n          code repository) which shares your plugin's name (with a \"vim-\" prefix\n          or \".vim\" suffix if desired). It should be split into plugin\/,\n          autoload\/, etc. subdirectories as necessary, and it should declare\n          metadata in the addon-info.json format (see the\n           for details).\n        "}},{"@attributes":{"title":"Functions"},"SUMMARY":"\n        In the autoload\/ directory, defined with  and\n        .\n      ","BODY":{"p":["\n          Autoloading allows functions to be loaded on demand, which makes\n          startuptime faster and enforces function namespacing.\n        ","\n          Script-local functions are welcome, but should also live in autoload\/\n          and be called by autoloaded functions.\n        ","\n          Non-library plugins should expose commands instead of functions.\n          Command logic should be extracted into functions and autoloaded.\n        ",{"code":"[!]"},{"code":"[abort]"}]}},{"@attributes":{"title":"Commands"},"SUMMARY":"\n        In the plugin\/commands.vim or under the ftplugin\/ directory, defined\n        without .\n      ","BODY":{"p":["\n          General commands go in .\n          Filetype-specific commands go in .\n        ","\n          Excluding  prevents your plugin from silently\n          clobbering existing commands.  Command conflicts should be resolved by\n          the user.\n        "]}},{"@attributes":{"title":"Autocommands"},"SUMMARY":"\n        Place them in plugin\/autocmds.vim, within augroups.\n      ","BODY":{"p":["\n          Place all autocommands in augroups.\n        ","\n          The augroup name should be unique. It should either be, or be prefixed\n          with, the plugin name.\n        ","\n          Clear the augroup with  before defining new\n          autocommands in the augroup. This makes your plugin re-entrable.\n        "]}},{"@attributes":{"title":"Mappings"},"SUMMARY":"\n        Place them in , using\n         to get a prefix.\n      ","BODY":{"p":["\n          All key mappings should be defined in\n          .\n        ","\n          Partial mappings (see :help using-<Plug>.) should be defined in\n          .\n        "]}},{"@attributes":{"title":"Settings"},"SUMMARY":"Change settings locally","BODY":{"p":"\n          Use  and  instead of\n           and  unless you have explicit\n          reason to do otherwise.\n        "}}]},{"@attributes":{"title":"Style"},"p":"\n      Follow google style conventions. When in doubt, treat vimscript style\n      like python style.\n    ","STYLEPOINT":[{"@attributes":{"title":"Whitespace"},"SUMMARY":"\n        Similar to python.\n        \n        \n        \n      ","BODY":{"ul":{"li":["Use two spaces for indents","Do not use tabs","Use spaces around operators\n            \n            \n          ","Do not introduce trailing whitespace\n            \n            \n          ","Restrict lines to 80 columns wide","Indent continued lines by four spaces","Do not align arguments of commands\n            \n            \n          "]}}},{"@attributes":{"title":"Naming"},"SUMMARY":{"p":["\n          In general, use\n          ,\n          ,\n          ,\n          ,\n          .\n        ","Always prefix variables with their scope."]},"BODY":{"SUBSECTION":[{"@attributes":{"title":"plugin-names-like-this"},"p":"Keep them short and sweet."},{"@attributes":{"title":"FunctionNamesLikeThis"},"p":["Prefix script-local functions with ","Autoloaded functions may not have a scope prefix.","\n            Do not create global functions. Use autoloaded functions\n            instead.\n          "]},{"@attributes":{"title":"CommandNamesLikeThis"},"p":"Prefer succinct command names over common command prefixes."},{"@attributes":{"title":"variable_names_like_this"},"p":"Augroup names count as variables for naming purposes."},{"@attributes":{"title":"Prefix all variables with their scope."},"ul":{"li":["Global variables with ","Script-local variables with ","Function arguments with ","Function-local variables with ","Vim-predefined variables with ","Buffer-local variables with "]},"p":[{"code":["g:","s:","a:"]},{"code":"b:"},{"code":["l:","v:"]}]}]}}]}]}