Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jbyuki/ntangle.vim

Literate programming in VIM
https://github.com/jbyuki/ntangle.vim

Last synced: 4 days ago
JSON representation

Literate programming in VIM

Awesome Lists containing this project

README 

        
ntangle

=======



#### Also see [ntangle.nvim](https://github.com/jbyuki/ntangle.nvim) which is the "spirtual successor" to this plugin.



Description

-----------



**ntangle** is a plugin which allows you to program in a literal programming style directly in vim. Its features are:



* Automatic code generation on save

* Syntax highlighting

* Build an index of sections for quick access (requires [ctrlp](https://github.com/ctrlpvim/ctrlp.vim))

* Jump to line



Install

-------



The easiest method is install through plugin manager such as [vim-plug](https://github.com/junegunn/vim-plug).



Add this to your plug-in list:



```

Plug 'jbyuki/ntangle.vim'

```



Basic usage

-----------



Open a \*.tl to start editing a ntangle file.  The plug-in should automatically detect the file. To verify it detected the file, type:



```

set ft

```



and it should return



```

ft=tangle

```



Type a ntangle literal program such as:



```

@test.txt=

Hello ntangle

```



After saving the file, it should automatically create an ntangle folder besides the \*.tl which contains test.txt with the following content:



```

Hello ntangle

```



Syntax

------



The **root sections** are defined using the following syntax:



```

@file=

some text

```



Notice it's an `@` sign followed by the name with no spaces followed by a simple `=` sign. ntangle will automatically generate a file for every root nodes. Roots nodes can also contains dots to put an extension such as:



```

@hello.cpp=

std::cout << "hello world" << std::endl;

```



Or it can even contain slashes to put the file in a subdirectory



```

@src/hello.cpp=

std::cout << "hello world" << std::endl;

```



The plain **sections** are defined using the following syntax:



```

@do_something+=

some text

```



Notice it's same as **root sections** except the `+=` signs at the end. These sections will not be output as a file. These are referenced in other sections and eventually in root sections.



Sections can be referenced with the following syntax:



```

@file=

@do_something

@do_something_else

```



This will include the text contained in the section and recursively. **root sections** can also be referenced.



Finally, there is a special section denotated by the `*` sign which will output a file with the \*.tl filename without the extension.



This means that for **hello.cpp.txt** containing:



```

@*=

some text

```



It will output it in a file named **hello.cpp**.



Caching

-------



ntangle also allows to fuzzy search in all sections on your filesystem. [ctrlp](https://github.com/ctrlpvim/ctrlp.vim) is **required** in order to use this functionality. 



Some additional configurations needs to made in order to work. In your $VIMRC add the following global variables definition:



```

let g:tangle_code_dir = "~/allmycode"

```



This will inform the plugin where all the code resides.

Type the following command the index all the sections:



```

:TangleBuildCache

```



This will search for all the \*.tl files and uniquely index in each file all the sections. By default it will skip, section names which are file names. This behaviour can be changed using the `g:tangle_cache_skip_filenames`. Once done, it will echo a message saying it 



```

Cache saved to ~/tangle_cache.txt

```



The cache path can be changed using the `g:tangle_cache_file` configuration variable.

Once the cache has been generated the ctrlp fuzzy search can be invoked using:



```

:call ctrlp#init(ctrlp#tangle#id())

```



It's a good idea to bind this to a shortcut key with nnoremap for more convinence.



Line jumping

------------



If you encounter some compilation errors during your development process the compiler might say the error is on **line 34** for example.



To jump to the line directly viewing the tangle file is done using:



```

:TangleGoto 34

```



If the tangle file generates multiple files, the filename also needs to specified:



```

:TangleGoto file.cpp:34

```



Examples

--------



* [Game of life](https://gist.github.com/jbyuki/e2d0b9a93f79ed8acd4df330218830aa)

* [This plugin](https://gist.github.com/jbyuki/c3c102037805a963a696358646d97cf8)



Additional notes

----------------



* Section and section references can be escaped with a double `@` sign

* Section text will append at the end using `+=` but with the operator `-=`, it can also be appended at the beginning

* The destination folder can be configured using the `g:tangle_dir` variable

* Use the \* key to quickly navigate to sections

* Use Tab to autocomplete long section names

* Filetype detection for syntax highlighting is done through extension (e.g. hello.cpp.tl will turn on cpp highlighting)