Description

The unpath tool is to expand file paths into their contents.

{unpath | unpath {-i | --invert}}
    [--path-prefix <file_path_prefix>]
    [--path-suffix <file_path_suffix>]
    [--prefix <prefix>]
    [--suffix <prefix>]
    [-d | --document-format <document_format>]
    [-h | --help]
    [-o <class> | --only <class>]
    [-s | --save]
    {<root_directory_path> [<document_path>] | [<document_path>]}

Features

• to be an isomorphism
  (unpath <root_directory_path> <document_path> | unpath --invert = id
  and unpath --invert <document_path> | unpath <root_directory_path> = id)
• to be indempotent
  (unpath <root_directory_path> <document_path> | unpath <root_directory_path> = unpath <root_directory_path> <document_path>)
• to print a <document_path> file with each <file_path_prefix><local_file_path><file_path_suffix> file path marker prepended with a <prefix> prefix and appended with the contents of the file, read from a <root_directory_path> directory by a <local_file_path> path, and a <suffix> suffix

Installation flow

1. Obtain the derivation. (?)
2. Include it into a dependee. (?)

Obtain

Fetch the source code of this tool at an appropriate commit-ish from a repository.

Include

1. Import the source code of this tool to get its derivation.
2. Include the derivation into a buildInputs field of a shell.nix file of a dependee.

Usage flow

1. Mark a <document_path> file. (?)
2. Expand paths. (?)
3. Save output. (?)

Mark

Mark the lines needed to be expanded in a <document_path> file by an appropriate file path markers containing a path of a file whose contents are to be expanded with.

Notes

• Paths inside file path markers must be quoted.

Hints

• In order that only a particular <class> of path markers to expand can be chosen, a <local_file_path> can be prepended with its <class>.

Expand

1. Enter the nix shell running the nix-shell command.
2. Run the unpath <root_directory_path> <document_path> command.

Hints

• In order to expand only a particular <class> of path markers, pass it as a value of the --only (-o) option.

Notes

• The nix-shell command must be run from a root directory of a dependee or with a path to the shell.nix file as its argument.
• A first expanding can be cancelled by passing the --invert (-i) flag.

Hints

• Some custom prefixes and suffixes can be set directly to avoid using a predefined set of them.

Save

If <document_path> file contents with expanded paths are satisfying, then run the command again but passing the --save (-s) flag to save it into a <document_path> file with new contents.

Convention

This tool follows the convention followed by the bem library.

---

Table 1

the predefined document formats

Document format	Inserted file contents prefix	Inserted file contents suffix	Path markers
Markdown	```<<root_directory_path>file_extension>	```	<!-- <?class> "<local_file_path>" -->, <!-- <?class> '<local_file_path>' -->

Table 2

the flag and options descriptions

Flag or option	Default value	Description
--path-prefix	<\!--.*['\"]	a search pattern before a <local_file_path> path inside a file path marker
--path-suffix	['\"].*-->	a search pattern after a <local_file_path> path inside a file path marker
--prefix	```<<root_directory_path>file_extension>	text to prepend to inserted file contents
--suffix	```	text to append to inserted file contents
-d, --document-format	Markdown	a predefined set of prefixes and suffixes to use
-h, --help	0	whether to print the help message and then exit
-o, --only	''	a <class> only of which file path markers are to be expanded
-i, --invert	0	whether to cancel a previous expanding
-s, --save	0	whether to save output into a <document_path> file instead of printing it