Skip to content

Commit

Permalink
Merge branch 'develop'
Browse files Browse the repository at this point in the history
  • Loading branch information
@cvigilv
cvigilv committed Dec 23, 2022
2 parents b188763 + 44ea715 commit f202bd5
Show file tree
Hide file tree
Showing 17 changed files with 147 additions and 209 deletions.
12 changes: 5 additions & 7 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Reduce your boilerplate code the lazy-bones way.

## What is `esqueleto`?

![Preview](https://i.imgur.com/kby322l.gif)
![Preview](https://i.imgur.com/MBMkSF7.gif)

`esqueleto.nvim` is a minimal plugin that intends to make the use of templates
or "skeletons" as easy and straightfoward as possible. This package adds a prompt
Expand Down Expand Up @@ -43,12 +43,12 @@ your `init.lua`:
require("esqueleto").setup(
{
-- Directory where templates are stored
directory = "~/.config/nvim/skeletons/", --default template directory
directory = "~/.config/nvim/skeletons/",

-- Patterns to match when creating new file
-- Can be either (i) file names or (ii) extension globs.
-- Can be either (i) file names or (ii) file types.
-- Exact file name match have priority
patterns = { "README.md", "*.py" }
patterns = { "README.md", "python" }
}
)
```
Expand All @@ -61,9 +61,6 @@ For more information, refer to docs (`:h esqueleto`). For example skeleton files
I intend on extending this plugin with some functionality I would like for a template
manager. At some point `esqueleto.nvim` should have the following (ordered by priority):

- Cleaner template storage using Vim `ftplugin` directory style
- Template insertion in empty files
- On-demand template insertion
- Template creation interface
- Handle multiple template folders
- Proyect specific templates
Expand All @@ -79,3 +76,4 @@ Create a branch, add commits, and

Please [open an issue](https://github.com/cvigilv/esqueleto.nvim/issues/new) for
support.
upport.
203 changes: 83 additions & 120 deletions doc/esqueleto.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,149 +8,102 @@ various styles or forms depending on it's intended use.
|esqueleto.nvim| intends to make the use of templates or "skeletons" as easy
and straightfoward as possible. This package adds a prompt for inserting an
specific template when creating a new file that matches an specific file name
or pattern.
or type.


==============================================================================
*premise*

|esqueleto| intends to provide a minimal, modular package that implements two
main functionalities for easier use of skeleton files: (1) detection and
prioritization of patterns and (2) managing multiple templates per pattern
through a simple template file type (refer to |template-format| for more
information in how to setup templates).
prioritization of file patterns and (2) managing multiple templates per
pattern through a simple template file type (refer to |setup| for more
information in how to setup the plugin).

First, |esqueleto| prioritizes matching complete file names, e.g. for template
README.md or LICENSE.md, to later match smaller patterns like file extensions,
e.g. adding an specific shebang or header to all Python files.
README.md or LICENSE, to later match over filetypes, e.g. adding an specific
shebang or header to all Python files.

Second, |esqueleto| allows the user to have different templates for an specific
pattern, e.g. having multiple shebang templates for Python files.
pattern, e.g. having multiple licenses for `LICENSE` file type.

Note In the |examples| section some use cases are shown in order to kick-start
your use of |esqueleto|. Please refer to this in order to understand how the
package works and how to make the most out of it.


==============================================================================
*template-format*

In order for |esqueleto| to detect your templates, this have to comply with 2
requisites:
1. Template files must be inside an specific templates directory
(`~/.config/nvim/skeletons/` by default).
2. Template file names must adhere to the following naming convention:
For file name matching: ~
<exact file name>
e.g. README.md, LICENSE.md, .bashrc

For pattern matching: ~
skeleton.<pattern to match>
or
skeleton.<template type>.<pattern to match>

e.g. skeleton.sh (for default templates); skeleton.cli.sh (for CLI
bash templates)


Note File name matching patterns are assigned the type `<exact file name>`,
while pattern matching templates are assigned the type `default` if the
template file name doesn't contain the template type or `<template type>`
if the template file name contains the template type.
your use of |esqueleto|. Please refer to this in order to understand how
the package works and how to make the most out of it.

Note We recommend against using the template type `default` due to the
behaviour described above.

==============================================================================
*examples*

In order to showcase the usecase of |esqueleto|, here we showcase 3 possible,
common use cases for templating: shebangs and README files.

Shebags: ~
A usecase for |esqueleto| is adding the correct shebang depending in the
version of Python the file uses. Here we could have 3 different templates:

`skeleton.python3lastest.py:`
>python
#!/usr/bin/env python3
*setup*

To setup |esqueleto|, tow things must be done:
1. Setup plugin through `init.lua`
2. Setup template directory

First, |esqueleto| setup in the `init.lua` file is as follows: >
require('esqueleto').setup({
-- Default templates directory
directory = '~/.config/nvim/skeleton/'
-- Patterns to detect for template insetion (empty by default,
-- adding as an example)
patterns = {
-- File specific
'README.md',
'LICENSE',
-- File type
'python',
},
})
<

`skeleton.python36.py:`
>python
#!/usr/bin/env python3.6
Second (and based in the setup showcased above), the following step involves
creating the templates directory file structure. For this, one must follow this
steps:
1. Create a templates directory where all templates will be stored
(`~/.config/nvim/skeletons/` based in the setup showcased above).
2. Inside the main template folder, create a subdirectory for each pattern
detected by |esqueleto| (`README.md`, `LICENSE` and `python` based
in the setup showcased above).
3. Add the template files for each pattern to the corresponding
subdirectories we just created.

Based in the example seen above, the tree structure of our template directory
should be: >
~/.config/nvim/skeleton/
├── LICENSE
├── README.md
└── python
<

`skeleton.python2lastest.py:`
>python
#!/usr/bin/env python2
Note In order to see what `filetype` is a specific file, one can use the
following ex-command: >
:lua print(vim.bo.filetype)
<

Adding the pattern `*.py` to |esqueleto| will enable the insertion of any
of this 3 templates when creating a new `*.py` file:
>
Select skeleton to use:
1. python36
2. python3lastest
3. python2lastest
Type number and <Enter> or click with mouse (q or empty to cancel):
>
README: ~
|esqueleto| reduces boilerplate code for files that contain a standard
structure, like a `README.md` file. Here we can automatically detect the
creation of this specific file type and prompt the insertion of the
template. Suppose we have the following `README.md` template in our
`skeletons` directory:

`README.md`
>markdown
# README

Small description of proyect.

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
- [Support](#support)
- [Contributing](#contributing)

## Installation

Instalation instructions.

```sh
git clone https://github.com/user/repo
make install
```

## Usage

Usage instructions and intention.

## Support
==============================================================================
*examples*

Please [open an issue](https://github.com/user/repo/issues/new) for
support.
In order to showcase the usecase of |esqueleto|, here we showcase N possible,
common use cases for templating, based in the setup showcased in the |setup|
section:

## Contributing
LICENSE:~
Different type of licenses for different projects, add all licenses to its
template directory and insert easily this templates without much work

Please contribute using [Github Flow]
(https://guides.github.com/introduction/flow/). Create a branch, add
commits, and [open a pull request](https://github.com/user/repo/compare/).
README.md:~
Theirs multiple styles of README files, some better for some project than
others. Therefore having a collection of this files can enable a faster
creation and launch of a project.

## License
python:~
Python files can be run (in Unix-like systems) as an executable. This
executable knows what version of Python to use thanks to the use of a
shebang in the first line. Templates for commonly used or project specific
shebangs can be created and added for insertion when creating a new file.

License information.
<
Other use case is creating template for common usecases of this filetype,
like CLI applications, Python modules, test cases, etc.

Adding the pattern `README.md` to |esqueleto| will enable the insertion of
any of this templates when creating a new `README.md` file:
>
Select skeleton to use:
1. default
Type number and <Enter> or click with mouse (q or empty to cancel):
<

==============================================================================
*functions*
Expand All @@ -164,8 +117,8 @@ setup({patterns}, {directory})
Example: >
esqueleto.setup(
{
patterns = { "*.jl", "README.md" },
directory = "~/.config/nvim/skeleton/"
patterns = { 'README.md', 'python' },
directory = '~/.config/nvim/skeleton/'
}
)
<
Expand All @@ -175,6 +128,16 @@ setup({patterns}, {directory})
• {directory} (string) An absolute or relative path to the directory
with templates.

==============================================================================
*ex-commands*

*Esqueleto*
Esqueleto

Prompt template insertion for current file, prioritizing patterns matching
over file name then over file type.


==============================================================================
*changelog*

Expand Down
Loading

0 comments on commit f202bd5

Please sign in to comment.