treescript-builder 0.1.2__tar.gz → 0.1.4__tar.gz

{treescript_builder-0.1.2/treescript_builder.egg-info → treescript_builder-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treescript-builder
-Version: 0.1.2
+Version: 0.1.4
 Summary: Builds File Trees from TreeScript. If DataLabels are present in TreeScript, a DataDirectory argument is required.
 Home-page: https://github.com/DK96-OS/treescript-builder
 Author: DK96-OS
@@ -34,27 +34,70 @@ Dynamic: summary
 Script for Building File Trees.
  - Makes your dreams come true.
 
-## How To
-1. Prepare Your TreeScript Designs.
-   - Initial and Final TreeScripts.
-   - Build New Project Package/Module.
-2. Logical Order of TreeScript Builder Operations.
-3. Run TreeScript Builder from the CommandLine.
-   - Apply combinations of Operations to build TreeScript Workflows.
-
-# Project Technical Details:
+## How To Make The Most Of TreeScript
+1. Think in File Trees:
+   - Initial and Final Trees.
+   - Tree Templates for New Modules, Packages, Apps.
+   - Data Directory and Data Labels.
+2. Prepare Your TreeScript Designs.
+   - New Project in any language you want.
+   - New Feature in a New Module File Tree.
+3. Plan TreeScript Operations.
+   - Split Larger Trees into multiple TreeScript Files.
+   - Combine Trim and Build Operations in a Sequence to meet Workflow requirements.
+   - Apply other TreeScript Packages to your Workflow:
+     - [TreeScript-Diff] : Difference between two TreeScript files.
+     - [TreeScript-Files] : Convert TreeScript into a list of File Paths.
+     - [TreeScriptify] : Create TreeScript from existing File Trees.
+4. Run TreeScript, as part of your Workflow.
+   - Install; add aliases to your terminal config file, if desired.
+
+## Script Structure
+ - Directory names contain a slash char.
+ - The Indentation is 2 spaces per level.
+
+### Directory Slash Chars
+ - Both directions are accepted: `\`, `/`
+ - Start or End of the Directory Name: `\src` or `src/`
+ - No spaces between Name and char.
+
+### Example
+
+```treescript
+src/
+  __init__.py
+  dir/
+```
+
+# Project Technical Details
 
 ## File Tree Builder
 Execute the File Tree Builder with the `ftb` command.
 - Creates Files and Directories
 - If DataLabels are present, a DataDirectory is required.
 
-### File Tree Trimmer (Remover)
+## File Tree Trimmer (Remover)
 Execute the File Tree Remover by adding the `--trim` argument.
 - Removes Files and Empty Directories.
 - DataLabels require DataDirectory.
   - Files are exported to the DataDirectory. 
 
+### Builder DataLabel
+A `DataLabel` is a link to Text content to be inserted into the file.
+ - DataLabel must be present in the DataDirectory, if present in the TreeScript File.
+ - DataDirectory contents are checked during the Tree Validation phase of program execution.
+
+#### Valid DataLabels
+The range of accepted DataLabel characters has been narrowed to reduce risk.
+ - Letters: A - z
+ - Numbers: 0 - 9
+ - Punctuation: -_.
+
+#### Invalid DataLabels
+The dot directories are invalid.
+ - Current Dir: .
+ - Parent Dir: ..
+
 ## Default Input Reader
 Before the Reader receives TreeScript, the input is filtered so comments and empty lines are not ever seen by the Reader.
 The Default Input Reader processes one line at a time and calculates multiple file tree node properties that it stores in dataclass objects.
@@ -65,23 +108,18 @@ It calculates for each node:
 - Depth in tree
 - (optional) DataArgument
 
-## Builder Data Feature
-The Builder provides one additional feature that goes beyond creation of the File Tree. This feature enables Files to be created with data inserted immediately.
-
 ### Input Data Argument
 The Data Argument specifies what will be inserted into the file that is created. The Data Argument is provided in the Input File, immediately after the File Name (separated by a space). There are two types of Data Arguments:
 - DataLabel
 - InlineContent
 
-### Builder DataLabel Feature
-A `DataLabel` is a link to Text content to be inserted into the file.
- - DataLabel is present in both the DataDirectory, and the TreeScript File.
-
 ## Tree Trim Data Directory Feature
 The Remover provides an additional feature beyond the removal of files in the Tree. This feature enables Files to be saved to a Data Directory when they are removed. Rather than destroying the file data, it is moved to a new directory.
 
-
 ## To-Do Features 
+ - Append/Prepend
+ - Overwrite Prevention
+ - Inline Content
 
 ### Builder File Inline Content (TODO)
 `Inline Content` is written in the Tree Node Structure Input file itself. To distinguish `DataContent` from a `DataLabel`, the Content must begin with a special character.
@@ -94,7 +132,7 @@ This feature is a neat mid-sized improvement that may open up opportunities for
  - Adding a new file late in the process.
    - such as after data directory is already prepared, and you review TS and notice a little thing missing.
    - value-adding option that helps you build files faster, more convenient than the DataDirectory.
- - Workflows that use TreeScript.
+ - Workflows that use TreeScript:
    - Easier To Plan, and Communicate What You Did.
    - Package Restructuring, Migrations.
    - Test Environment Setup

{treescript_builder-0.1.2 → treescript_builder-0.1.4}/README.md

@@ -2,27 +2,70 @@
 Script for Building File Trees.
  - Makes your dreams come true.
 
-## How To
-1. Prepare Your TreeScript Designs.
-   - Initial and Final TreeScripts.
-   - Build New Project Package/Module.
-2. Logical Order of TreeScript Builder Operations.
-3. Run TreeScript Builder from the CommandLine.
-   - Apply combinations of Operations to build TreeScript Workflows.
+## How To Make The Most Of TreeScript
+1. Think in File Trees:
+   - Initial and Final Trees.
+   - Tree Templates for New Modules, Packages, Apps.
+   - Data Directory and Data Labels.
+2. Prepare Your TreeScript Designs.
+   - New Project in any language you want.
+   - New Feature in a New Module File Tree.
+3. Plan TreeScript Operations.
+   - Split Larger Trees into multiple TreeScript Files.
+   - Combine Trim and Build Operations in a Sequence to meet Workflow requirements.
+   - Apply other TreeScript Packages to your Workflow:
+     - [TreeScript-Diff] : Difference between two TreeScript files.
+     - [TreeScript-Files] : Convert TreeScript into a list of File Paths.
+     - [TreeScriptify] : Create TreeScript from existing File Trees.
+4. Run TreeScript, as part of your Workflow.
+   - Install; add aliases to your terminal config file, if desired.
 
-# Project Technical Details:
+## Script Structure
+ - Directory names contain a slash char.
+ - The Indentation is 2 spaces per level.
+
+### Directory Slash Chars
+ - Both directions are accepted: `\`, `/`
+ - Start or End of the Directory Name: `\src` or `src/`
+ - No spaces between Name and char.
+
+### Example
+
+```treescript
+src/
+  __init__.py
+  dir/
+```
+
+# Project Technical Details
 
 ## File Tree Builder
 Execute the File Tree Builder with the `ftb` command.
 - Creates Files and Directories
 - If DataLabels are present, a DataDirectory is required.
 
-### File Tree Trimmer (Remover)
+## File Tree Trimmer (Remover)
 Execute the File Tree Remover by adding the `--trim` argument.
 - Removes Files and Empty Directories.
 - DataLabels require DataDirectory.
   - Files are exported to the DataDirectory. 
 
+### Builder DataLabel
+A `DataLabel` is a link to Text content to be inserted into the file.
+ - DataLabel must be present in the DataDirectory, if present in the TreeScript File.
+ - DataDirectory contents are checked during the Tree Validation phase of program execution.
+
+#### Valid DataLabels
+The range of accepted DataLabel characters has been narrowed to reduce risk.
+ - Letters: A - z
+ - Numbers: 0 - 9
+ - Punctuation: -_.
+
+#### Invalid DataLabels
+The dot directories are invalid.
+ - Current Dir: .
+ - Parent Dir: ..
+
 ## Default Input Reader
 Before the Reader receives TreeScript, the input is filtered so comments and empty lines are not ever seen by the Reader.
 The Default Input Reader processes one line at a time and calculates multiple file tree node properties that it stores in dataclass objects.
@@ -33,23 +76,18 @@ It calculates for each node:
 - Depth in tree
 - (optional) DataArgument
 
-## Builder Data Feature
-The Builder provides one additional feature that goes beyond creation of the File Tree. This feature enables Files to be created with data inserted immediately.
-
 ### Input Data Argument
 The Data Argument specifies what will be inserted into the file that is created. The Data Argument is provided in the Input File, immediately after the File Name (separated by a space). There are two types of Data Arguments:
 - DataLabel
 - InlineContent
 
-### Builder DataLabel Feature
-A `DataLabel` is a link to Text content to be inserted into the file.
- - DataLabel is present in both the DataDirectory, and the TreeScript File.
-
 ## Tree Trim Data Directory Feature
 The Remover provides an additional feature beyond the removal of files in the Tree. This feature enables Files to be saved to a Data Directory when they are removed. Rather than destroying the file data, it is moved to a new directory.
 
-
 ## To-Do Features 
+ - Append/Prepend
+ - Overwrite Prevention
+ - Inline Content
 
 ### Builder File Inline Content (TODO)
 `Inline Content` is written in the Tree Node Structure Input file itself. To distinguish `DataContent` from a `DataLabel`, the Content must begin with a special character.
@@ -62,7 +100,7 @@ This feature is a neat mid-sized improvement that may open up opportunities for
  - Adding a new file late in the process.
    - such as after data directory is already prepared, and you review TS and notice a little thing missing.
    - value-adding option that helps you build files faster, more convenient than the DataDirectory.
- - Workflows that use TreeScript.
+ - Workflows that use TreeScript:
    - Easier To Plan, and Communicate What You Did.
    - Package Restructuring, Migrations.
    - Test Environment Setup

{treescript_builder-0.1.2 → treescript_builder-0.1.4}/setup.py

@@ -5,7 +5,7 @@ from setuptools import find_packages, setup
 
 setup(
     name="treescript-builder",
-    version="0.1.2",
+    version="0.1.4",
     description='Builds File Trees from TreeScript. If DataLabels are present in TreeScript, a DataDirectory argument is required.',
     long_description=open('README.md').read(),
     long_description_content_type='text/markdown',
@@ -13,7 +13,7 @@ setup(
 	url='https://github.com/DK96-OS/treescript-builder',
 	project_urls={
         "Issues": "https://github.com/DK96-OS/treescript-builder/issues",
-        "Source Code": "https://github.com/DK96-OS/treescript-builder"
+        "Source Code": "https://github.com/DK96-OS/treescript-builder",
 	},
     license="GPLv3",
     packages=find_packages(exclude=['test', 'test.*']),

{treescript_builder-0.1.2 → treescript_builder-0.1.4}/treescript_builder/data/data_directory.py

@@ -85,5 +85,5 @@ class DataDirectory:
         data_files = self._data_dir.glob(data_label)
         try:
             return next(data_files)
-        except StopIteration as s:
+        except StopIteration:
             return None

{treescript_builder-0.1.2 → treescript_builder-0.1.4}/treescript_builder/input/__init__.py

@@ -25,4 +25,4 @@ def validate_input_arguments(arguments: list[str]) -> InputData:
         validate_input_file(arg_data.input_file_path_str),
         validate_directory(arg_data.data_dir_path_str),
         arg_data.is_reversed
-    )
+    )

{treescript_builder-0.1.2 → treescript_builder-0.1.4}/treescript_builder/input/argument_parser.py

@@ -25,7 +25,7 @@ def parse_arguments(
         exit("No Arguments given.")
     try: # Initialize the Parser and Parse Immediately
         parsed_args = _define_arguments().parse_args(args)
-    except SystemExit as e:
+    except SystemExit:
         exit("Unable to Parse Arguments.")
     return _validate_arguments(
         parsed_args.tree_file_name,
@@ -55,9 +55,7 @@ def _validate_arguments(
     if not validate_name(tree_file_name):
         exit("The Tree File argument was invalid.")
     # Validate Data Directory Name Syntax if Present
-    if data_dir_name is None:
-        pass
-    elif not validate_name(data_dir_name):
+    if data_dir_name is not None and not validate_name(data_dir_name):
         exit("The Data Directory argument was invalid.")
     return ArgumentData(
         tree_file_name,
@@ -96,4 +94,4 @@ def _define_arguments() -> ArgumentParser:
         default=False,
         help='Flag to reverse the File Tree Operation'
     )
-    return parser
+    return parser

treescript_builder-0.1.4/treescript_builder/input/file_validation.py

@@ -0,0 +1,75 @@
+""" File Validation Methods.
+ - These Methods all raise SystemExit exceptions.
+ Author: DK96-OS 2024 - 2025
+"""
+from pathlib import Path
+from stat import S_ISLNK
+from sys import exit
+
+from treescript_builder.input.string_validation import validate_name
+
+
+_FILE_SIZE_LIMIT = 32 * 1024 # 32 KB
+_FILE_SIZE_LIMIT_ERROR_MSG = "File larger than 32 KB Limit."
+_FILE_SYMLINK_DISABLED_MSG = "Symlink file paths are disabled."
+
+_FILE_DOES_NOT_EXIST_MSG = "The File does not Exist."
+_FILE_READ_OSERROR_MSG = "Failed to Read from File."
+_FILE_VALIDATION_ERROR_MSG = "Invalid Input File Contents."
+
+_NOT_A_DIR_ERROR_MSG = "Not a Directory."
+_DIR_DOES_NOT_EXIST_MSG = "The Directory does not exist."
+
+
+def validate_input_file(file_name: str) -> str | None:
+    """ Read the Input File, Validate (non-blank) data, and return Input str.
+ - Max FileSize is 32 KB.
+ - Symlink type file paths are disabled.
+
+**Parameters:**
+ - file_name (str): The Name of the Input File.
+
+**Returns:**
+ str - The String Contents of the Input File.
+
+**Raises:**
+ SystemExit - If the File does not exist, or is empty, blank, over 32 KB, or if the read or validation operation failed.
+    """
+    file_path = Path(file_name)
+    try:
+        if not file_path.exists():
+            exit(_FILE_DOES_NOT_EXIST_MSG)
+        if S_ISLNK((stat := file_path.lstat()).st_mode):
+            exit(_FILE_SYMLINK_DISABLED_MSG)
+        if stat.st_size > _FILE_SIZE_LIMIT:
+            exit(_FILE_SIZE_LIMIT_ERROR_MSG)
+        if (data := file_path.read_text()) is not None:
+            if validate_name(data):
+                return data
+            exit(_FILE_VALIDATION_ERROR_MSG)
+        # Fallthrough: return None
+    except OSError:
+        exit(_FILE_READ_OSERROR_MSG)
+    return None
+
+
+def validate_directory(dir_path_str: str | None) -> Path | None:
+    """ Ensure that if the Directory argument is present, it Exists.
+ - Allows None to pass through the method.
+
+**Parameters:**
+ - dir_path_str (str?): The String representation of the Path to the Directory.
+
+**Returns:**
+ Path? - The Path to the DataDirectory, or None if given input is None.
+
+**Raises:**
+ SystemExit - If a given path does not exist, or is not a Directory.
+    """
+    if dir_path_str is None:
+        return None
+    if (path := Path(dir_path_str)).exists():
+        if path.is_dir():
+            return path
+        exit(_NOT_A_DIR_ERROR_MSG)
+    exit(_DIR_DOES_NOT_EXIST_MSG)

{treescript_builder-0.1.2 → treescript_builder-0.1.4}/treescript_builder/input/line_reader.py

@@ -108,7 +108,7 @@ def _validate_node_name(node_name: str) -> tuple[bool, str] | None:
         if (dir_name := validate_dir_name(node_name)) is not None:
             return (True, dir_name)
         # Fall-Through to File Node
-    except ValueError as e:
+    except ValueError:
         # An error in the dir name, such that it cannot be a file either
         return None
     # Is a File

treescript_builder-0.1.4/treescript_builder/input/string_validation.py

@@ -0,0 +1,144 @@
+""" String Validation Methods.
+ Author: DK96-OS 2024 - 2025
+"""
+from itertools import permutations, repeat
+from typing import Literal
+
+
+def validate_name(argument) -> bool:
+    """ Determine whether an argument is a non-empty string.
+ - Does not count whitespace.
+ - Uses the strip method to remove empty space.
+
+**Parameters:**
+ - argument (str): The given argument, which needs validation.
+
+**Returns:**
+ bool - True if the argument qualifies as valid.
+    """
+    if argument is None or not isinstance(argument, str):
+        return False
+    elif len(argument.strip()) < 1:
+        return False
+    return True
+
+
+def validate_data_label(data_label: str) -> bool:
+    """ Determine whether a Data Label is Valid.
+ - Allows the approved non-alphanumeric chars.
+ - The exclamation point (!) is a valid DataLabel, if by itself.
+ - If a slash char is found in the string, it is invalid.
+ - Small strings (length <= 2) consisting of only punctuation are invalid.
+
+**Parameters:**
+ - data_label (str): The String to check for validity.
+
+**Returns:**
+ bool - Whether the String is a valid Data Label.
+    """
+    if len(data_label) < 3:
+        if '!' == data_label: # 33
+            return True
+        if data_label == '' or _is_invalid_small_tree_string(data_label):
+            return False
+    elif len(data_label) > 99:
+        return False
+    for ch in data_label:
+        n = ord(ch)
+        # ALLOWED: Special Punctuation (-._) Codes: 45, 46, 95
+        # Numbers: 48 - 57
+        # UpperCase: 65 - 90
+        # LowerCase: 97 - 122
+        if not (n != 47 and 45 <= n <= 57 if n < 65 else n <= 90 or n <= 122 and (n == 95 or 97 <= n)):
+            return False
+    return True
+
+
+def validate_dir_name(dir_name: str) -> str | None:
+    """ Determine that a directory is correctly formatted.
+
+**Parameters:**
+ - dir_name (str): The given input to be validated.
+
+**Returns:**
+ str? - The valid directory name, or none if it may be a file.
+
+**Raises:**
+ ValueError - When the name is not suitable for directories or files.
+    """
+    if (name_length := len(dir_name)) >= 100: # Keep Name Length Reasonable
+        raise ValueError(f'Name too Long!: {name_length}')
+    # Check for slash chars
+    if (name := _filter_slash_chars(dir_name)) is not None: # Is a Dir
+        # Validate chars (parent dir, current dir)
+        if name in ['', '.', '..']:
+            raise ValueError('Invalid Directory')
+        return name
+    else: # Is a File
+        return None
+
+
+def _is_invalid_small_tree_string(tree_string: str) -> bool:
+    """ Checks strings of length 1 or 2 for invalid combinations of chars that are generally valid in larger strings..
+ - The dot strings are not allowed because they may escape the DataDirectory.
+ - The permutations including line characters are not allowed, to help prevent mistakes (typos) and so on.
+ 
+**Parameters:**
+ - data_label (str): The Data Label to check, which should be of length 2 or 1.
+
+**Returns:**
+ bool - True, if the given parameter is invalid, given the specific filtering criteria.
+    """
+    return tree_string in (invalid_chars := ('.', '_', '-')) or \
+        tree_string in (''.join(repeat(x, 2)) for x in invalid_chars) or \
+        tree_string in permutations(invalid_chars, 2)
+
+
+def _validate_slash_char(dir_name: str) -> Literal['\\', '/'] | None:
+    """ Determine which slash char is used by the directory, if it is a directory.
+ - Discourages use of both slash chars, by raising ValueError.
+
+**Parameters:**
+ - dir_name (str): The given input to be validated.
+
+**Returns:**
+ str? - The slash character used, or none if no chars were found.
+
+**Raises:**
+ ValueError - When the name contains both slash characters.
+    """
+    slash: Literal['\\', '/'] | None = None
+    if '/' in dir_name:
+        slash = '/'
+        # Also check for other slash
+    if '\\' in dir_name:
+        if slash is not None:
+            raise ValueError('Invalid character combination: forward and back slash in the same path.')
+        slash = '\\'
+    return slash
+
+
+def _filter_slash_chars(dir_name: str) -> str | None:
+    """ Remove all of the slash characters and return the directory name.
+ - Returns None when there are no slash characters found.
+
+**Parameters:**
+ - dir_name (str): The given input to be validated.
+
+**Returns:**
+ str? - The valid directory Name, or None if it may be a file (there were no slash chars found).
+
+**Raises:**
+ ValueError - When the name is not suitable for directories or files, such as when slash characters are used improperly.
+    """
+    slash: Literal['\\', '/'] | None = _validate_slash_char(dir_name)
+    if slash is None: # No slash chars found.
+        return None
+    if dir_name.endswith(slash) or dir_name.startswith(slash):
+        name: str = dir_name.strip(slash)
+        if slash in name: # Has internal slash characters
+            raise ValueError('Multi-dir line detected')
+    else:
+        # Found slash chars only within the node name (multi-dir line)
+        raise ValueError('Multi-dir line detected')
+    return name

{treescript_builder-0.1.2 → treescript_builder-0.1.4}/treescript_builder/tree/build_validation.py

@@ -13,14 +13,12 @@ from treescript_builder.data.tree_state import TreeState
 def validate_build(
     tree_data: Generator[TreeData, None, None],
     data_dir_path: Path | None = None,
-    verbose: bool = False,
 ) -> tuple[InstructionData, ...]:
     """ Validate the Build Instructions.
 
 **Parameters:**
  - tree_data (Generator[TreeData]): The Generator that provides TreeData.
  - data_dir_path (Path?): The optional Data Directory Path. Default: None.
- - verbose (bool): Whether to print DataDirectory information during validation.
 
 **Returns:**
  tuple[InstructionData] - A generator that yields Instructions.
@@ -29,8 +27,6 @@ def validate_build(
         return tuple(iter(_validate_build_generator(tree_data)))
     else:
         data = DataDirectory(data_dir_path)
-        if verbose:
-            print(f"Validating Build With DataDir: {data_dir_path}")
         return tuple(iter(_validate_build_generator_data(tree_data, data)))
 
 

{treescript_builder-0.1.2 → treescript_builder-0.1.4}/treescript_builder/tree/tree_builder.py

@@ -52,7 +52,7 @@ def _create_file(
     """
     try:
         copy2(data, path)
-    except BaseException as e:
+    except OSError:
         return False
     return True
 
@@ -72,6 +72,6 @@ def _make_dir_exist(
         return True
     try:
         path.mkdir(parents=True, exist_ok=True)
-    except IOError as e:
+    except OSError:
         return False
     return True

{treescript_builder-0.1.2 → treescript_builder-0.1.4}/treescript_builder/tree/tree_trimmer.py

@@ -25,10 +25,9 @@ def _trim(instruct: InstructionData) -> bool:
     if instruct.data_path is None:
         try:
             instruct.path.unlink(missing_ok=True)
-            return True
-        except IOError as e:
-            print("IO File Error")
+        except OSError:
             return False
+        return True
     return _extract_file(instruct.path, instruct.data_path)
 
 
@@ -47,9 +46,9 @@ def _extract_file(
     """
     try:
         move(path, data)
-        return True
-    except:
+    except OSError:
         return False
+    return True
 
 
 def _remove_dir(
@@ -65,6 +64,6 @@ def _remove_dir(
     """
     try:
         path.rmdir()
-    except BaseException as e:
+    except OSError:
         return False
     return True

{treescript_builder-0.1.2 → treescript_builder-0.1.4}/treescript_builder/tree/trim_validation.py

@@ -13,7 +13,6 @@ from treescript_builder.data.tree_state import TreeState
 def validate_trim(
     tree_data: Generator[TreeData, None, None],
     data_dir_path: Path | None = None,
-    verbose: bool = False,
 ) -> tuple[InstructionData, ...]:
     """ Validate the Trim Instructions.
 
@@ -29,8 +28,6 @@ def validate_trim(
         return tuple(iter(_validate_trim_generator(tree_data)))
     else:
         data = DataDirectory(data_dir_path)
-        if verbose:
-            print(f"Validating Trim With DataDir: {data_dir_path}")
         return tuple(iter(_validate_trim_generator_data(tree_data, data)))
 
 

{treescript_builder-0.1.2 → treescript_builder-0.1.4/treescript_builder.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treescript-builder
-Version: 0.1.2
+Version: 0.1.4
 Summary: Builds File Trees from TreeScript. If DataLabels are present in TreeScript, a DataDirectory argument is required.
 Home-page: https://github.com/DK96-OS/treescript-builder
 Author: DK96-OS
@@ -34,27 +34,70 @@ Dynamic: summary
 Script for Building File Trees.
  - Makes your dreams come true.
 
-## How To
-1. Prepare Your TreeScript Designs.
-   - Initial and Final TreeScripts.
-   - Build New Project Package/Module.
-2. Logical Order of TreeScript Builder Operations.
-3. Run TreeScript Builder from the CommandLine.
-   - Apply combinations of Operations to build TreeScript Workflows.
-
-# Project Technical Details:
+## How To Make The Most Of TreeScript
+1. Think in File Trees:
+   - Initial and Final Trees.
+   - Tree Templates for New Modules, Packages, Apps.
+   - Data Directory and Data Labels.
+2. Prepare Your TreeScript Designs.
+   - New Project in any language you want.
+   - New Feature in a New Module File Tree.
+3. Plan TreeScript Operations.
+   - Split Larger Trees into multiple TreeScript Files.
+   - Combine Trim and Build Operations in a Sequence to meet Workflow requirements.
+   - Apply other TreeScript Packages to your Workflow:
+     - [TreeScript-Diff] : Difference between two TreeScript files.
+     - [TreeScript-Files] : Convert TreeScript into a list of File Paths.
+     - [TreeScriptify] : Create TreeScript from existing File Trees.
+4. Run TreeScript, as part of your Workflow.
+   - Install; add aliases to your terminal config file, if desired.
+
+## Script Structure
+ - Directory names contain a slash char.
+ - The Indentation is 2 spaces per level.
+
+### Directory Slash Chars
+ - Both directions are accepted: `\`, `/`
+ - Start or End of the Directory Name: `\src` or `src/`
+ - No spaces between Name and char.
+
+### Example
+
+```treescript
+src/
+  __init__.py
+  dir/
+```
+
+# Project Technical Details
 
 ## File Tree Builder
 Execute the File Tree Builder with the `ftb` command.
 - Creates Files and Directories
 - If DataLabels are present, a DataDirectory is required.
 
-### File Tree Trimmer (Remover)
+## File Tree Trimmer (Remover)
 Execute the File Tree Remover by adding the `--trim` argument.
 - Removes Files and Empty Directories.
 - DataLabels require DataDirectory.
   - Files are exported to the DataDirectory. 
 
+### Builder DataLabel
+A `DataLabel` is a link to Text content to be inserted into the file.
+ - DataLabel must be present in the DataDirectory, if present in the TreeScript File.
+ - DataDirectory contents are checked during the Tree Validation phase of program execution.
+
+#### Valid DataLabels
+The range of accepted DataLabel characters has been narrowed to reduce risk.
+ - Letters: A - z
+ - Numbers: 0 - 9
+ - Punctuation: -_.
+
+#### Invalid DataLabels
+The dot directories are invalid.
+ - Current Dir: .
+ - Parent Dir: ..
+
 ## Default Input Reader
 Before the Reader receives TreeScript, the input is filtered so comments and empty lines are not ever seen by the Reader.
 The Default Input Reader processes one line at a time and calculates multiple file tree node properties that it stores in dataclass objects.
@@ -65,23 +108,18 @@ It calculates for each node:
 - Depth in tree
 - (optional) DataArgument
 
-## Builder Data Feature
-The Builder provides one additional feature that goes beyond creation of the File Tree. This feature enables Files to be created with data inserted immediately.
-
 ### Input Data Argument
 The Data Argument specifies what will be inserted into the file that is created. The Data Argument is provided in the Input File, immediately after the File Name (separated by a space). There are two types of Data Arguments:
 - DataLabel
 - InlineContent
 
-### Builder DataLabel Feature
-A `DataLabel` is a link to Text content to be inserted into the file.
- - DataLabel is present in both the DataDirectory, and the TreeScript File.
-
 ## Tree Trim Data Directory Feature
 The Remover provides an additional feature beyond the removal of files in the Tree. This feature enables Files to be saved to a Data Directory when they are removed. Rather than destroying the file data, it is moved to a new directory.
 
-
 ## To-Do Features 
+ - Append/Prepend
+ - Overwrite Prevention
+ - Inline Content
 
 ### Builder File Inline Content (TODO)
 `Inline Content` is written in the Tree Node Structure Input file itself. To distinguish `DataContent` from a `DataLabel`, the Content must begin with a special character.
@@ -94,7 +132,7 @@ This feature is a neat mid-sized improvement that may open up opportunities for
  - Adding a new file late in the process.
    - such as after data directory is already prepared, and you review TS and notice a little thing missing.
    - value-adding option that helps you build files faster, more convenient than the DataDirectory.
- - Workflows that use TreeScript.
+ - Workflows that use TreeScript:
    - Easier To Plan, and Communicate What You Did.
    - Package Restructuring, Migrations.
    - Test Environment Setup

treescript_builder-0.1.2/treescript_builder/input/file_validation.py

@@ -1,52 +0,0 @@
-""" File Validation Methods.
- - These Methods all raise SystemExit exceptions.
- Author: DK96-OS 2024 - 2025
-"""
-from pathlib import Path
-from sys import exit
-
-from treescript_builder.input.string_validation import validate_name
-
-
-def validate_input_file(file_name: str) -> str | None:
-    """ Read the Input File, Validate (non-blank) data, and return Input str.
-
-**Parameters:**
- - file_name (str): The Name of the Input File.
-
-**Returns:**
- str - The String Contents of the Input File.
-
-**Raises:**
- SystemExit - If the File does not exist, or is empty or blank, or read failed.
-    """
-    file_path = Path(file_name)
-    if not file_path.exists():
-        exit("The Input File does not Exist.")
-    try:
-        if (data := file_path.read_text()) is not None and validate_name(data):
-            return data
-    except OSError as e:
-        exit("Failed to Read from File.")
-    return None
-
-
-def validate_directory(dir_path_str: str | None) -> Path | None:
-    """ Ensure that if the Directory is present, it Exists.
-
-**Parameters:**
-- dir_path_str (str, optional): The String representation of the Path to the Directory.
-
-**Returns:**
- Path? - The , or None if given input is None.
-
-**Raises:**
- SystemExit - If a given path does not exist.
-    """
-    if dir_path_str is None:
-        return None
-    if not validate_name(dir_path_str):
-        exit("Data Directory is invalid")
-    if (path := Path(dir_path_str)).exists():
-        return path
-    exit("The given Directory does not exist!")

treescript_builder-0.1.2/treescript_builder/input/string_validation.py

@@ -1,130 +0,0 @@
-""" String Validation Methods.
- Author: DK96-OS 2024 - 2025
-"""
-from typing import Literal
-
-
-def validate_name(argument) -> bool:
-    """ Determine whether an argument is a non-empty string.
- - Does not count whitespace.
- - Uses the strip method to remove empty space.
-
-**Parameters:**
- - argument (str) : The given argument.
-
-**Returns:**
- bool - True if the argument qualifies as valid.
-    """
-    if argument is None or not isinstance(argument, str):
-        return False
-    elif len(argument.strip()) < 1:
-        return False
-    return True
-
-
-def validate_data_label(data_label: str) -> bool:
-    """ Determine whether a Data Label is Valid.
-
-**Parameters:**
- - data_label (str): The String to check for validity.
-
-**Returns:**
- bool - Whether the String is a valid Data Label.
-    """
-    if not 0 < len(data_label) < 100:
-        return False
-    if '/' in data_label or '\\' in data_label:
-        return False
-    # Remove Dash Characters
-    if '-' in data_label:
-        data_label = data_label.replace('-', '')
-    # Remove Underscore Characters
-    if '_' in data_label:
-        data_label = data_label.replace('_', '')
-    # Remove Dot Characters
-    if '.' in data_label:
-        data_label = data_label.replace('.', '')
-    if '!' == data_label:
-        return True
-    # All Remaining Characters must be alphanumeric
-    return data_label.isalnum()
-
-
-def validate_dir_name(dir_name: str) -> str | None:
-    """ Determine that a directory is correctly formatted.
- - This method should be called once for each slash type.
-
-**Parameters:**
- - dir_name (str): The given input to be validated.
-
-**Returns:**
- str | None - The valid directory name, or none if it may be a file.
-
-**Raises:**
- ValueError - When the name is not suitable for directories or files.
-    """
-    # Keep Name Length Reasonable
-    if (name_length := len(dir_name)) >= 100:
-        raise ValueError(f'Name too Long!: {name_length}')
-    # Check for slash characters
-    if (name := _filter_slash_chars(dir_name)) is not None:
-        # Is a Dir
-        if len(name) == 0:
-            raise ValueError('The name is empty')
-        # Check for invalid characters (parent dir, current dir)
-        if name in ['.', '..']:
-            raise ValueError('Invalid Directory')
-        return name
-    # Is a File
-    return None
-
-
-def _validate_slash_char(dir_name: str) -> Literal['\\', '/'] | None:
-    """ Determine which slash char is used by the directory, if it is a directory.
- - Discourages use of both slash chars, by raising ValueError.
-
-**Parameters:**
- - dir_name (str): The given input to be validated.
-
-**Returns:**
- str | None - The slash character used, or none if no chars were found.
-
-**Raises:**
- ValueError - When the name contains both slash characters.
-    """
-    slash = None
-    if '/' in dir_name:
-        slash = '/'
-    if '\\' in dir_name:
-        if slash is not None:
-            raise ValueError('Invalid Directory slash character combination.')
-        slash = '\\'
-    return slash
-
-
-def _filter_slash_chars(dir_name: str) -> str | None:
-    """ Remove all of the slash characters and return the directory name.
-- Returns None when there are no slash characters found.
-- Raises ValueError when slash characters are used improperly.
-
-**Parameters:**
- - dir_name (str): The given input to be validated.
-
-**Returns:**
- str | None - The valid directory name, or none if it may be a file.
-
-**Raises:**
- ValueError - When the name is not suitable for directories or files.
-    """
-    slash = _validate_slash_char(dir_name)
-    if slash is None:
-        return None
-    if dir_name.endswith(slash) or dir_name.startswith(slash):
-        name = dir_name.strip(slash)
-        # Check for internal slash characters
-        if slash in name:
-            raise ValueError('Multi-dir line detected')
-    else:
-        # Found slash chars only within the node name (multi-dir line)
-        raise ValueError('Multi-dir line detected')
-    return name