Metadata-Version: 2.1
Name: vimbuffer
Version: 0.1.2
Summary: Edit files, and strings in temporary vim (or some other console editor) buffers.
Home-page: https://gitlab.com/seanbreckenridge/vimbuffer
Author: Sean Breckenridge
Author-email: seanbrecke@gmail.com
License: MIT
Description: vimbuffer
        ======
        
        Edit files and strings in temporary vim (or some other console editor) buffers.
        
        Installation
        ------------
        
        #### Requires:
        
        - python3.6+
        
        ```
        pip3 install vimbuffer
        ```
        
        Usage
        ------------
        
        There's just the one function, `buffer`:
        
        ```
        vimbuffer.buffer(string: Union[str, NoneType] = None,
                         file: Union[str, NoneType] = None,
                         editor: Union[str, NoneType] = None,
                         fallbacks: Union[List[str], NoneType] = None,
                         name_prefix: Union[str, NoneType] = None) -> str
            Provide one of:
                string: A string to edit in a vimbuffer
                filepath: A file to edit in a vimbuffer
            If neither is provided, uses an empty string
            editor: editor to override the passed fallbacks/environment variable
            fallbacks: A list of fallbacks for alternate editors (e.g. ['vim', 'vi', 'nano'])
            name_prefix: string prefix for the filename when opening in an editor
        
            If string is provided, opens the file in an editor, lets the user edit it,
            and returns the string.
            If a file is, it reads the file, lets the user modify the contents, and writes
            back to the file. It also returns the edited file contents.
        ```
        
        The editor can be overwritten by specifying environment variables, see below for resolution order.
        
        ##### Examples 
        
        ```
        import vimbuffer
        
        # edit a string
        prompt_string = "Edit this and put what you want here!"
        edited_text = vimbuffer.buffer(string=prompt_string)  # opens vim
        
        # edit a file
        vimbuffer.buffer(file=os.path.expanduser("~/.bashrc"), name_prefix="bashrc-")
        ```
        
        This uses [`tempfile`](https://docs.python.org/3.8/library/tempfile.html) to create temporary files on the system, and launches vim against them. If the environment variable `$EDITOR` is set to a graphical text editor, the process (which in this case would just launch the graphical editor) would end before the user had a chance to edit it. I recommend using terminal text editors instead.
        
        You can specify a list of fallback editors;  one you'd like to use instead of `$EDITOR`:
        
        ```
        project_description="""
        ## <my-project>
        
        By <your-name>
        """
        
        edited_desc = vimbuffer.buffer(project_description, fallbacks=["nvim", "vim", "vi", "nano"])
        ```
        
        Alternatively, if you want to leave your `$EDITOR` as a graphical text editor, you can set the `$VIMBUFFER_EDITOR` environment variable, which trumps all other choices. Specifically, the resolution order is:
        
        - `$VIMBUFFER_EDITOR`
        - `editor`
        - `fallbacks`(s) passed as keyword arguments in python
        - `$EDITOR`
        - `vim`
        - `vi`
        
        The `name_prefix` exists as a kwarg since temporary files have names that are randomly generated. By passing a prefix, the name becomes something like `/tmp/bashrc-sd43Jds`, so it may give a hint as to which file/what you're editing
        
        Tests
        ----------
        
        ```
        pytest
        ```
        
Keywords: vim editor stream
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Description-Content-Type: text/markdown
