 
 --- Snap2HTML for Developers --------------------------------------------------

   Table of Contents

   - Exposed Functions
   - Data Format


 --- Exposed Functions --------------------------------------------------

  In case you want to work with the file data in a generated html listing 
  through the JavaScript console, Snap2HTML exposes some useful data and 
  functions on the "window.snap" object. The raw file listing data is found 
  on "window.dirs". Here are some example snippets:

  Extract all files and folders:

    const folders = [];
    const files = [];
    dirs.forEach((d,i) => {
	    const path = snap.getFullPath(i);
	    folders.push(path);
	    snap.getParsedFiles(i).forEach(file => {
		    files.push(`${path}\\${file.name}`)
	    });
    });


  Get data in a tree-like structure and copy as JSON to the clipboard:

    function treeExport(i) {
      const dir = snap.getParsedDir(i);
	  const result = {
          name: dir.name,
          size: dir.size,
          date: dir.date,
          subdirs: [],
          files: snap.getParsedFiles(i).map(file => {
              return { name: file.name, size: file.size, date: file.date}
          })
      }
      snap.getParsedSubdirs(i).forEach(d => {
          result.subdirs.push(treeExport(d.id));
      });
      return result;
    }
    treeExport(0); // root folder is always index 0
    const tree = treeExport(0); // root folder is always index 0
    copy(JSON.stringify(tree, null, 4))
  

  Get a list of all folders that could not be read:

    dirs.filter((dir,i) => snap.getParsedDir(i).error === true)


  --- Data Format -------------------------------------------------------------
  
  The data format used by Snap2HTML is optimized to be compact and fast to read.
  The format has changed several times. Below is find information on how to parse 
  the data structure from different versions of Snap2HTML.

  Note: Described here is the logical format of the data arrays. In the HTML file 
  the data is written slightly different to make parsing large data sets easier 
  on the JavaScript engine.

  
  Snap2HTML 2.5+

    Data format "V2"
    
    Data is stored in an array:
      - Each slot in the array represents one folder.
      - Format: [
                    folder: string, 
                    parent_folder_id: number, 
                    subfolder_ids: string, 
                    file_1: string, 
                    file_2: string, 
                    ... 
                    file_x: string,
                    snapshot_info: object       /* only if root folder */
                ]
      - There can be 0 or more files.
      - Folder IDs are numbers pointing to other slots in the array.
      - Subfolder IDs are separated by asterisks, e.g. "1*2*3".
      - Root folders have parent folder id -1. First item in the 
        array (0) must be a root folder.
      - There may be more than one root folder. Each root folder 
        resets the folders IDs, starting again at 0.
      - Files and folders are displayed in the order they appear.
      - Root folders have an additional payload as the last entry.
        This is a JSON object with information about the snapshot:    
        {
          title: string,
          timestamp: number,
          sourceDir: string,
          linkRoot: string,
          numFiles: number,
          numDirs: number,
          totBytes: number
        }

    Folder & file items:
      - These are strings with the name, size and modified date.
      - Format: "name*size*date".
      - Date is in UNIX ("epoch") format.
      - Size is in bytes.
      - Dates & sizes are numbers stored in base 36. To parse 
        in JavaScript: var n = parseInt(base36numberAsString, 36)
      - For folders, if the size is -1 it means the folder contents 
        could not be read.

    Thus, a folder with two files and two empty subfolders would have the 
    following structure:
      [
        ["rootdir*size*date",-1,"1*2","file 1*size*date","file 2*size*date", {...}]
        ["subdir1*size*date",0]
        ["subdir2*size*date",0]
      ]
    
    Real example:
      [    
        ["Snap2html Example*J1X*SOY9R9",-1,"1*3*4","File in root folder.txt*3GO*SOY9O7",{"title":"Snap2html Example","sourceDir":"C:\\temp\\Snap2html Example","linkRoot":"file:\/\/\/C:\/temp\/Snap2html%20Example","numDirs":5,"numFiles":5,"timestamp":1766493031,"totBytes":24693}],
        ["Folder 1*X0*SOY9MI",0,"2","File in Folder 1.txt*W0*SOY9NT"],
        ["Subfolder*10*SOY9MX",1,"","File in Subfolder.txt*10*SOY9NB"],
        ["Folder 2*EO9*SOY9P0",0,"","File 1 in Folder 2.txt*TL*SOY9Q3","File 2 in Folder 2.txt*DUO*SOY9Q6"],
        ["Folder that could not be read*-1*SOY9RD",0,""],
      ]


  Snap2HTML 2.0-2.14
  
    Data format "V1"

    Each index in "dirs" array is an array representing a directory:
      - First item in array: "directory path*always 0*directory modified date"
        - Note that forward slashes are used instead of (Windows style) backslashes
      - Then, for each each file in the directory: "filename*size of file*file modified date"
      - Second to last item in array tells the total size of directory content
      - Last item in array references IDs to all subdirectories of this dir (if any).
        - ID is the item index in dirs array.
    Note: dates are in UNIX (epoch) format.


  Snap2HTML 1.x
  
    See template files for data format information

