Metadata-Version: 2.1
Name: fictus
Version: 0.3.0
Summary: Generate a fake file system to create documentation examples.
Author-email: Jason Brackman <brackman+fictus@gmail.com>
Project-URL: Homepage, https://github.com/jasonbrackman/arborator
Project-URL: Source, https://github.com/jasonbrackman/arborator
Keywords: documentation,fake,directory,filesystem
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.md

## Fictus

Use `Fictus` to create and output a fictitious file system for sharing in a text driven format.

```Text
🏡kitchen
└─ 📁drawer
   ├─ 📁forks
   │  ├─ 📁old
   │  │  └─ 📄pitchfork.bak
   │  ├─ 📄dinner.mp3
   │  └─ 📄salad.mov
   └─ 📁spoons
      └─ 📄ladle.psd
```

Use cases include creating output for a wiki page, communicating a folder structure to a colleague over chat, or
mocking a file/folder structure layout before committing to actual creation on disk.  Since Fictus mimics a File System,
calling code can create complex loops to build up as little or as much as required to get an idea across.

<HR>

### FictusFileSystem
A Fictus File System starts with instantiating a FicutsFileSystem object and, optionally, providing
a root drive name.  If one is not provided, a single slash ('/') will be used.

```Python
from fictus import FictusFileSystem

# Create a FictusFileSystem.
ffs = FictusFileSystem("c")
```

The object can then be built up using creation methods, such as `mdir` and `mkfile` and folder traversal can occur
using `cd`.


```Python
# create some directories
ffs.mkdir("/files/docs")
ffs.mkdir("/files/music/folk")

# Create some files in the current working directory (happens to be root).
ffs.mkfile("README.md", "LICENSE.md", ".ignore")

# Change directory to the `docs` and make more files. Start with `/` to traver from root.
ffs.cd("/files/docs")
ffs.mkfile("resume.txt", "recipe.wrd")

# Change directory to `music/folk`.  Note the relative cd from the `docs` folder. 
ffs.cd("../music/folk")
ffs.mkfile("bing.mp3", "bang.mp3", "bop.wav")
```

<HR>

### FictusDisplay
A FictusDisplay outputs the FFS.

```Python

from fictus import FictusDisplay

ffs.cd("/")  # for this example, ensure the cwd is the root of the file system

# Generate a ffs structure to be printed to stdout as text.
display = FictusDisplay(ffs)
display.pprint()
```

Produces:

```Text
c:\
├─ files\
│  ├─ docs\
│  │  ├─ recipe.wrd
│  │  └─ resume.txt
│  └─ music\
│     └─ folk\
│        ├─ bang.mp3
│        ├─ bing.mp3
│        └─ bop.wav
├─ .ignore
├─ LICENSE.md
└─ README.md
```

The display can also be generated in place:

```Python
FictusDisplay(ffs).pprint()
```

The tree displayed starts at current working directory. The same example
above with the current directory set to `c:/files/music` produces:

```Text
music\
└─ folk\
   ├─ bang.mp3
   ├─ bing.mp3
   └─ bop.wav
```

<HR>

### Renderer
A FictusDisplay allows customization of the `DOC`, `ROOT`, `FOLDER`, and `FILE` types.
The Renderer can be permanently reassigned using the `renderer` property. Here is an
example that takes advantage of the built-in `emojiRenderer`.  

```Python
from fictus.renderer import emojiRenderer
...
# FictusDisplay the ffs structure after a relative change of directory to files/music
ffs.cd("files/music")

# assign a new Renderer to the display - already instantiated in a previous example.
display.renderer = emojiRenderer

# ouptut with the new Renderer applied
display.pprint()
```

This produces:

```Text
📁music
└─ 📁folk
   ├─ 📄bang.mp3
   ├─ 📄bing.mp3
   └─ 📄bop.wav
```

Previously, the `renderer` was updated so that each call to `pprint` will use
the `emojiRenderer`. If the main renderer is not required to be updated permanently, 
use the `pprint` optional argument - `renderer`.

```Python
from fictus.renderer import defaultRenderer
# current renderer is the emojiRenderer

# uses defaultRenderer just this one time
display.pprint(renderer=defaultRenderer)  

# use the emojiRenderer that was setup in the previous example set.
display.pprint() 
```

<HR>

### RenderTag Customization
Customization may be useful for creating HTML, Markdown, or other custom tags that are
not already provided. A `Renderer` can register valid `RenderTagEnum` types with 
`RenderTag` objects.   By default, all `RenderTags` contain empty strings. The user
can choose to override any number of tags as required.

You can create a new `Renderer` from scratch and customize the `RenderTag`s that are 
appropriate. For example:

```Python
from fictus.renderer import RenderTagEnum, RenderTag

# A customRenderer is created: adds special characters before a File or Folder.
customRenderer = Renderer()
customRenderer.register(RenderTagEnum.FILE, RenderTag("· ", ""))
customRenderer.register(RenderTagEnum.FOLDER, RenderTag("+ ", "\\"))

# Update display_model to the customRenderer
display.renderer = customRenderer
display.pprint()
```

Produces:

```Text
+ music\
└─ + folk\
   ├─ · bang.mp3
   ├─ · bing.mp3
   └─ · bop.wav
```

One can also create a new `Renderer` object starting with an already applied object and 
updating only the Enum value of interest.

```Python
new_renderer = (
    display.renderer
)  # from previous examples -- this will return customRenderer
new_renderer.register(RenderTagEnum.FOLDER, RenderTag("✓ ", ""))
display.pprint(renderer=new_renderer)
```

And this will, as expected, generate the following:
```
✓ music
└─ ✓ folk
   ├─ · bang.mp3
   ├─ · bing.mp3
   └─ · bop.wav
```

<hr>

### Install Using Pip
>pip install fictus

### Building/installing the Wheel locally:
To build the package requires setuptools and build.
>python3 -m build

Once built:
>pip install dist/fictus-*.whl --force-reinstall
