Loading ...
Sorry, an error occurred while loading the content.
 

[RFC] Some more python and VimL interfaces

Expand Messages
  • ZyX
    This is a description of proposed new python interfaces. ================== New python objects ================== vim.mappings/{buffer}.mappings:
    Message 1 of 42 , May 9, 2013
      This is a description of proposed new python interfaces.

      ==================
      New python objects
      ==================

      vim.mappings/{buffer}.mappings:
      Dictionary-like object mapping mode characters to vim.modemappings objects
      below. Unlike vim.buffers iteration is being done for keys.

      modemappings:
      Dictionary-like object mapping expanded (see vim.special_expand() below)
      strings to vim.Mapping objects. Assigning Mapping objects to some key works
      like :*map. `sid` attribute is ignored when assigning. Unlike vim.buffers
      iteration is being done for keys.

      mapping:
      Namedtuple-like object with the following attributes:
      rhs Rhs of the mapping.
      sid Script ID.
      silent True or False, tells whether mapping is silent.
      expr True or False, tells whether it is <expr> mapping.
      noremap Depends on the numeric constant:
      vim.MAPPING_REMAP False (zero) constant, mapping is
      remappable
      vim.MAPPING_NOREMAP True (non-zero), mapping is
      noremappable
      vim.MAPPING_SCRIPT True (non-zero), mapping is <script>
      one
      No .mode or .buffer attributes: they are expressed in using appropriate
      vim.mappings[mode] (buffer.mappings[mode]) objects.

      vim.commands/{buffer}.commands
      Mapping-like object mapping command names to vim.command objects. Assigning
      vim.Command object to the key acts like :command, `sid` attribute is
      ignored. Unlike vim.buffers iteration is being done for keys.

      command:
      Namedtuple-like object with the following attributes:
      command Command string.
      sid Script ID.
      nargs One of constants:
      vim.COMMAND_ARGS_NO
      vim.COMMAND_ARGS_ONE
      vim.COMMAND_ARGS_ANY
      vim.COMMAND_ARGS_ONE_OR_NO
      vim.COMMAND_ARGS_SOME
      complete String or None.
      range Number or None. Number is either vim.COMMAND_RANGE_CURRENT,
      vim.COMMAND_RANGE_WHOLE or non-negative integer. All
      constants are negative integers. None is used when neither
      range nor count is allowed.
      count True or False. Determines whether .range attribute really
      describes -count argument.
      bang, bar, register
      True or False.

      vim.autocommands:
      Mapping-like object mapping autocommand groups to vim.Augroup objects.
      Iteration is done for keys. Autocommands without groups are autocommands
      with group None.

      augroup:
      Mapping-like object mapping event names to list of vim.Autocommand objects.
      Iteration is done for keys. Methods:
      .append_autocmd(event, autocommand)
      .del_autocmds(event, pattern=None)
      .clear(event=None)
      As usual, `sid` attribute is ignored when using above methods. Item
      assignment works by calling first .clear(event=key) and then a sequence of
      .append_autocmd(event=key, autocmd=item).

      autocommand:
      Namedtuple-like object with the following attributes:
      command Command string.
      sid Script ID.
      nested True or False.
      pattern Glob.

      vim.signs:
      Mapping-like object mapping sign names to vim.Sign attributes. Iterates over
      keys, supports item assignment.

      sign:
      Namedtuple-like object with the following attributes:
      icon None or file name.
      linehl None or string.
      text String.
      texthl None or string.

      {buffer}.signs:
      Mapping-like object mapping place ids to signplace objects (note: they is no
      constructor for this). Iterates over signplace objects in order they are
      shown in the buffer. Methods:
      place(line, name, id=None)
      Place given sign on the given line. Returns id which is equal to id
      argument if it was given or is a new unique id.
      unplace(line=None, id=None)
      Unplace sign from the given line or id or all signs if no arguments
      were given. If both line and id are present then it verifies whether
      sign with given id is placed on the given line and either unplaces
      it or raises ValueError.

      signplace:
      Object with the following attributes:
      id Identifier.
      line Line number.
      name Names of signs: keys in vim.signs.
      . Also has method .jump().

      vim.scripts:
      Sequence-like object that removes the need of parsing :scriptnames. Maps
      script numbers (subtracted by one) to file names.

      vim.jumps:
      Sequence-like object that removes the need of parsing :jumps. Contains jump
      objects.

      {buffer}.changes:
      Like vim.jumps, but for :changes in the given buffer.

      jump:
      Objects with the following attributes:
      line Line number.
      col Column number.
      file None or file name.
      buffer None (file not loaded) or vim.buffer object.
      . Also has method .jump().

      vim.current.jump:
      Index of the current jump in vim.jumps.

      Notes:
      - “Namedtuple-like” means that all attributes are RO and that there are no
      methods.
      - “Ignored when assigning” means “set to sid which is current when assigning”.

      ==================
      New VimL functions
      ==================

      maplist([{mode}[, {bufnr}]])
      Returns a list of strings suitable for maparg().

      cmdarg({cmdname}[, {bufnr}])
      Returns a dictionary with the following keys, works with partial commands:
      name Full {cmdname}.
      command Command string.
      sid Script ID.
      nargs String constant or empty string.
      complete String, possibly empty.
      range String constant or empty string, stands only for -nargs.
      count String constant or empty string, stands only for -count.
      bang, bar, register, buffer
      One or zero.

      cmdlist([{bufnr}])
      Returns a list of command names suitable for cmdarg().

      aulist({event}[, {augroup}[, {pattern}]])
      Returns a list of dictionaries with the following keys:
      event {event}
      augroup Autocmd group.
      patterns List of globs.
      command Command string.
      nested One or zero.
      sid Script ID.

      auglist()
      Returns a list of autocmd groups.

      signarg({name})
      Returns a dictionary with the following keys:
      name {name}
      icon Icon file or empty string.
      linehl String or empty string.
      texthl String or empty string.
      text String.

      signlist()
      Returns a list of sign names suitable for signarg().

      signplacelist({bufnr})
      Returns a list of signs placed in the given buffer: dictionaries with keys
      name Name suitable for signarg().
      id Sign ID.
      line Line number.

      getjumps()
      Returns a list of dictionaries with the following keys:
      line Line number.
      col Column number.
      file File name.

      getchanges({bufnr})
      Returns a list of lists, latter lists are suitable for cursor(): look like
      ([{line}, {col}]).

      Note: {bufnr} is {expr} argument from bufnr() function.

      =======================================
      Python classes that are made accessible
      =======================================

      vim.Mapping(rhs, noremap=vim.MAPPING_NOREMAP, silent=False, expr=False)
      Returns mapping object described above. New mappings that are created using
      vim.Mapping are then to be assigned to appropriate
      `{vim,buffer}.mappings[mode][lhs]` thus there are no attributes like `mode`,
      `buffer` or `lhs`: they are determined by appropriate keys and objects when
      assigning. `sid` attribute is created automatically (though in any case it
      is ignored when assigning).

      vim.Command(command, nargs=vim.COMMAND_ARGS_NO, complete=None, range=None,
      count=False, bang=False, bar=True, register=False)
      Returns command object described above. New commands that are created using
      vim.Command are then to be assigned to `{vim,buffer}.commands[cmd]` thus
      there are no attributes like `name` or `buffer`. `sid` attribute is created
      automatically (though in any case it is ignored when assigning).

      vim.Autocommand(command, pattern, nested=True)
      Returns new autocmd group as described above.

      vim.Sign(text, icon=None, linehl=None, texthl=None)
      Returns new sign as described above.

      vim.Dictionary(dict)
      vim.Dictionary(iterable)
      vim.Dictionary(**kwargs)
      Returns a vim.dictionary object. Is subclassable.

      vim.List(iterable)
      Returns a vim.list object. Is subclassable. Main reason for creating this and
      previous classes is not subclassability (it is highly optional) or ability
      to define new lists without using `vim.bindeval`, but ability to use
      `isinstance(vim.bindeval("var"), vim.Dictionary)`.


      Note: here are different (more convenient) defaults:
      Mapping(noremap=vim.MAPPING_NOREMAP) in place of vim.MAPPING_REMAP
      Command(bar=True) in place of False
      Autocommand(nested=True) in place of False

      =========================
      Auxilary/helper functions
      =========================

      vim.special_expand() + special_expand() :: string -> string
      Expands special characters like `<C-a>` in the string. Currently it is done
      in VimL by using `eval('"'.escape(str, '\<"').'"')` which is rather hacky.

      vim.match_glob() :: glob, string -> boolean
      match_glob() :: string, glob -> boolean
      Match string against glob expression. Order is different in python and VimL:
      in python it is taken from `re.match(pattern, string)`, in VimL from
      `matchstr({expr}, {pat})`.

      vim.find_buffer() :: string -> vim.buffer
      Like vim.buffers[vim.bindeval("bufnr(string)")].

      =================================
      Changes to existing functionality
      =================================

      - Iterators for *.windows and vim.tabpages that allow

      for window in vim.windows:
      window.close()

      like it is allowed for buffer list.

      - {buffer}.wipe(), {window}.close() and {tabpage}.close() methods.
      Alternative: `del vim.buffers[number]`, `del {windowlist}[number]` and
      `del vim.tabpages[number]`.
      - {dictionary}.items(), {dictionary}.values(), {dictionary}.pop() and
      {dictionary}.update() (last is most useful).
      - Doing `item in {dictionary}` without doing `{dictionary}[item]`.
      - `iter({dictionary})` iterating over keys.
      - {function}.sid and {function}.code attributes.
      - {buffer}.valid, {window}.valid, {tabpage}.valid, {windowlist}.valid and
      {function}.valid attributes.
      - {window}.tabpage attribute and {window}.number attribute working for
      non-current tab pages.
      - vim.eval(expr, number_strings=True): sometimes python objects are more desired
      then what vim.bindeval returns, but numbers represented as strings spoil it
      all.

      --
      --
      You received this message from the "vim_dev" maillist.
      Do not top-post! Type your reply below the text you are replying to.
      For more information, visit http://www.vim.org/maillist.php

      ---
      You received this message because you are subscribed to the Google Groups "vim_dev" group.
      To unsubscribe from this group and stop receiving emails from it, send an email to vim_dev+unsubscribe@....
      For more options, visit https://groups.google.com/groups/opt_out.
    • Bram Moolenaar
      ... Yes, this also came up as a side effect of the os.chdir() solution. It s especially useful if a plugin can be distributed as a Python module plus some
      Message 42 of 42 , May 21, 2013
        Marc Weber wrote:

        > Yet another suggestion - what about adding &rtp to sys.path somehow ?
        > (with or without python version site-packages or the like)
        >
        > Then you could
        > - write .py files
        > - use them from python by
        >
        > import module
        > do_stuff()
        >
        > Yes - it can be trivially implemented in tools like vim-addon-manager,
        > but I'd prefer a global solution usable by everyone.

        Yes, this also came up as a side effect of the os.chdir() solution.

        It's especially useful if a plugin can be distributed as a Python module
        plus some lines in the Vim plugin. It would have a similar effect as
        using a Vim script under autoload.

        --
        A M00se once bit my sister ...
        "Monty Python and the Holy Grail" PYTHON (MONTY) PICTURES LTD

        /// Bram Moolenaar -- Bram@... -- http://www.Moolenaar.net \\\
        /// sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
        \\\ an exciting new programming language -- http://www.Zimbu.org ///
        \\\ help me help AIDS victims -- http://ICCF-Holland.org ///

        --
        --
        You received this message from the "vim_dev" maillist.
        Do not top-post! Type your reply below the text you are replying to.
        For more information, visit http://www.vim.org/maillist.php

        ---
        You received this message because you are subscribed to the Google Groups "vim_dev" group.
        To unsubscribe from this group and stop receiving emails from it, send an email to vim_dev+unsubscribe@....
        For more options, visit https://groups.google.com/groups/opt_out.
      Your message has been successfully submitted and would be delivered to recipients shortly.