[ Impressum ]

LiveCode FileSpecValidatorLib

www.Rozek.de > LiveCode > FileSpecValidatorLib
The "FileSpecValidatorLib" is a small LiveCode [1] "Library Stack" with a series of commands and functions for the validation of file and folder names and specifiers for various file systems.

Validating the syntax of file and folder names is a surprisingly difficult task (at least, under those horrible Windows operating systems) - and, thus, frequently left to the operating system by the programmer rather than done within an application itself. Nevertheless, it is often desirable to know about the validity of a given file name well in advance to actually accessing the corresponding file - or to get a more meaningful error message. This little library stack addresses these situations.

The "FileSpecValidatorLib" supports FAT, VFAT, FAT32, NTFS, HFS+ (Mac OS X), common UNIX file systems and the "Unified Naming Convention" UNC. The actual file system to check against is either chosen automatically (depending on the underlying operating system) or may be specified explicitly. The validators for Microsoft file systems (FAT, VFAT, FAT32 and NTFS) all support "\" as well as "/" as folder separators but cannot handle "\\?\" or "\\.\" prefixes (which would otherwise explicitly address Win32 file or device namespaces, resp.), except when used in conjunction with an UNC (i.e., as a "\\?\UNC\" prefix) - in that case, the leading "\\?\UNC\" is simply ignored.

Download and Installation

The "FileSpecValidatorLib" is available as an unencrypted LiveCode stack and can be downloaded from here:
After downloading, just place the "FileSpecValidatorLib" in a directory of your choice - an explicit installation is not required.

Usage Instructions

The "FileSpecValidatorLib" has been implemented as a LiveCode "library stack" and must therefore be attached to a "MainStack" prior to its use using

start using stack "FileSpecValidatorLib"

Appropriately, this statement is executed in the context of a preOpenStack procedure of a MainStack.

Should the MainStack later be converted into a standalone application, the "FileSpecValidatorLib" must also become part of the list of "Stack Files" in this MainStack (this is easiest done by using the "Standalone Application Settings" from the LiveCode development environment).

Usage Instructions for mobile Applications

The "FileSpecValidatorLib" can also be used in mobile applications. However - and unlike for standalone desktop applications - it must then be included in the list of "non-stack files" and attached to the MainStack using

start using stack (specialFolderPath("engine") & "/FileSpecValidatorLib.livecode")

The list of "non-stack files" can likewise be found on the "Copy Files" page in the "Standalone Application Settings" of the LiveCode development environment.

Command Overview

The "FileSpecValidatorLib" contains four groups of commands and functions:
  • commands for the validation of file and folder names and specifiers
    check the given values for syntactical correctness and throw an exception in the case of an error;
     
  • functions for validation of file and folder names and specifiers
    check the given values for syntactical correctness and return true on success or false on failure;
     
  • commands for the validation of optional arguments (allowXXX)
    check the given arguments (if any) for formal correctness and throw an exception in the case of an error;
     
  • commands to validate required arguments (expectXXX)
    check for the presence of any expected arguments and their contents for formal correctness - in case of an error, an exception is thrown.
The former group contains the actual functionality - all other commands and functions just simplify their use only.

Commands for Validation of File and Folder Specifiers

The names of the commands in this group all begin with validate. If the given argument Candidate complies to the verified syntax, the procedure finishes without further incident and the calling script may be continued. Otherwise, an appropriate exception is thrown which may be caught an processed by the calling script.

The commands are (in alphabetic order):

validateFileName <Candidate> [, FileSystem]


validateFileName ensures that the given Candidate contains a syntactically(!) valid file name. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

validateFileSpec <Candidate> [, FileSystem]


validateFileSpec ensures that the given Candidate contains a syntactically(!) valid file specifier. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

validateFolderName <Candidate> [, FileSystem]


validateFolderName ensures that the given Candidate contains a syntactically(!) valid folder name. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

validateFolderSpec <Candidate> [, FileSystem]


validateFolderSpec ensures that the given Candidate contains a syntactically(!) valid folder specifier. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

Functions for Validation of File and Folder Specifiers

The names of the functions in this group all begin with valid. If the given argument Candidate complies to the verified syntax, the function finishes and returns true. Otherwise, false is returned (but no exception thrown!).

The functions are (in alphabetic order):

validFileName <Candidate> [, FileSystem]


validFileName checks if the given Candidate contains a syntactically(!) valid file name. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.


validFileSpec <Candidate> [, FileSystem]


validFileSpec checks if the given Candidate contains a syntactically(!) valid file specifier. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

validFolderName <Candidate> [, FileSystem]


validFolderName checks if the given Candidate contains a syntactically(!) valid folder name. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

validFolderSpec <Candidate> [, FileSystem]


validFolderSpec checks if the given Candidate contains a syntactically(!) valid folder specifier. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

Validation of optional Arguments

This group of commands (whose names begin with "allow") validates optional arguments - these procedures differ from from those validating required arguments insofar as the given argument may also be empty.

The commands are (in alphabetic order):

allowFileName <ArgName>, <ArgValue> [, FileSystem]


allowFileName ensures that the passed ArgValue is either absent (i.e. empty) or contains a syntactically(!) valid file name. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowFileSpec <ArgName>, <ArgValue> [, FileSystem]


allowFileSpec ensures that the passed ArgValue is either absent (i.e. empty) or contains a syntactically(!) valid file specifier. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowFolderName <ArgName>, <ArgValue> [, FileSystem]


allowFolderName ensures that the passed ArgValue is either absent (i.e. empty) or contains a syntactically(!) valid folder name. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowFolderSpec <ArgName>, <ArgValue> [, FileSystem]


allowFolderSpec ensures that the passed ArgValue is either absent (i.e. empty) or contains a syntactically(!) valid folder specifier. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

Validation of mandatory Arguments

This group of commands (whose names begin with "expect") validates mandatory arguments - these procedures differ from from those validating optional arguments insofar as the given argument may never be empty.

The commands are (in alphabetic order):

expectFileName <ArgName>, <ArgValue> [, FileSystem]


expectFileName ensures that the passed ArgValue exists (i.e., is not empty) and contains a syntactically(!) valid file name. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectFileSpec <ArgName>, <ArgValue> [, FileSystem]


expectFileSpec ensures that the passed ArgValue exists (i.e., is not empty) and contains a syntactically(!) valid file specifier. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectFolderName <ArgName>, <ArgValue> [, FileSystem]


expectFolderName ensures that the passed ArgValue exists (i.e., is not empty) and contains syntactically(!) valid folder name. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectFolderSpec <ArgName>, <ArgValue> [, FileSystem]


expectFolderSpec ensures that the passed ArgValue exists (i.e., is not empty) and contains a syntactically(!) valid folder specifier. If FileSystem is given (and non-empty), it must contain a supported file system (i.e., one of "FAT", "VFAT", "FAT32", "NTFS", "UNC", "UNIX" or "HFS+") and specifies which syntax rules should be used to validate the given Candidate. If FileSystem is missing (or empty), the rules of the underlying platform's default filesystem will be applied.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

System Requirements

The "FileSpecValidatorLib" requires LiveCode 6.x or later, and works regardless of the operating system on both stationary and mobile platforms.

Dependencies

Internally, the "FileSpecValidatorLib" uses my "BasicLib", "ValidatorLib" and "NetValidatorLib" - when using the "FileSpecValidatorLib", these two must therefore also be present.

Automated Tests

There is also a separate stack with automated tests of the "FileSpecValidatorLib":
When this stack is opened, the command performTests is executed, which is responsible for running the actual tests. In the end, the "Message Box" of the LiveCode development environment should appear and display the message

all tests passed

Otherwise, an error message with information about the failed test should be shown instead.

Known Bugs

There are currently no known bugs in the "FileSpecValidatorLib".

License Information

The "FileSpecValidatorLib" and its tests are licensed under a "Creative Commons Attribution 4.0 Unported license", which essentially means that you may both use and modify them (even in a commercial context) - provided that your changes have been marked as such and there is a reference to me as the original author at an appropriate place.

                       
Have fun with LiveCode and my libraries! Creative Commons License

Bibliography

[1]
(RunRev Ltd.)
LiveCode | Create apps for multiple platforms. Quickly. Easily. Free
LiveCode is a development environment for both stationary (Windows, Linux, MacOS X) and mobile (iOS, Android) applications modeled after the legendary Apple HyperCard. A visual editor allows fast design of user interfaces, a programming language inspired by the english language allows even non-professional programmers to develop professional applications and the concept of "modifying a running program" simplifies testing and troubleshooting.