What is a file path?

A file path is, very simply, the location of a file on a computer. It doesn’t have to actually be to a file, it might be to a folder, it’s still called a path. The path can be a local path, like “C:\Program Files\GoFiler” for example, or a UNC (Universal Naming Convention) path, like “\\Support\Program Files\GoFiler”. A UNC path has a computer name for the first part if it after the double slashes, instead of having a drive letter. This allows you to reference a file path on a different computer on your network. All of these functions will work with both types of path. Paths can also include URLs (Uniform Resource Locators) such as “https://www.novaworkssoftware.com/blog/”. Many of the path functions will work with URLs but some will not. Refer to the documentation of each function for more information. Remember, when working with strings, the back slash character must be escaped. So a “\” becomes “\\”, likewise two backslashes “\\” becomes “\\\\” when using Legato. 

Path Manipulators

First thing first, we need to discuss some of the functions that can be used to manipulate paths. If you need to go up a directory, add paths together, get the file name off a path, or any other operation, the functions discussed below can save a lot of time. For quick reference, the function signatures are listed before the description of what the function does.

string = CatPaths (string path1, string path2)

Probably the most basic function, CatPaths has nothing to do with kittens, but does concatenate two file paths together. The reason you would want to use this function instead of simply adding two paths together is that it removes any extra path delimiters (slashes) to ensure the resultant path is at least syntactically valid. Like most functions, this doesn’t check if the result actually exists or not.

string = AddPaths (string base, string target)

More powerful than CatPaths, AddPaths lets you use the “..” operator to go up a directory level. So if you have a path to a folder, and you want to get to the folder above it in the file tree, you can use the AddPaths function to do it. It also means it can deal with relative paths. It also can do everything CatPaths can do, in just adding a couple of file paths together.

string = PathLevelUp (string path)

This function is the equivalent of using the AddPaths function with the “..\” path as the second parameter. It takes whatever path you pass to it, and just removes the last folder reference from it. So “C:\Program Files\GoFiler” becomes “C:\Program Files”.

string = AddPathDelimiter (string path, [string delimiter])

Sometimes you just want to make sure that your program returns a folder path that ends in a valid delimiter character. AddPathDelimiter does just that, it adds a delimiter of your choice to the end of the file path, if one doesn’t already exist. So if you get a path input, and want to make sure it ends in a delimiter, this is a great function to ensure that. The delimiter parameter is optional, and if you don’t include it it will just use what it thinks the correct delimiter is based on the given path.

boolean = IsPath (string path)

A very basic function, this just tests to make sure your path is syntactically valid. It returns a boolean value of true or false if the path is valid or not.

boolean = DoesPathExist (string path)

Most of what we’ve discussed so far doesn’t actually check if the path exists or not. This one does exactly that, however, and it checks to make sure that the path we’ve given it actually exists. If you’re using a UNC path, a false return value here could mean a network problem or the path doesn’t exist.

boolean = DoesFileExist (string path)

Similar to the DoesPathExist function, this function tests to see if a specific file given to it exists, rather than just a path to a folder.

boolean = CanAccessFile (string path, [int mode])

OK, so this one isn’t really a path function, but it’s still very useful, and it’s a pretty good place to talk about it. Passed a fully qualified path to a file, and an access mode flag (read, write, etc) it will return if the script has the access required to actually modify this file.

Get Path Functions 

In addition to having functions to modify and work with paths, there are several built-in functions that will retrieve common folders that a programmer may want access to. This isn’t a comprehensive list, only some of the more useful functions.

string = GetApplicationDataFolder ([boolean base])

This function will return the Application Data folder for the application running the script. Frequently, this will be the “%AppData%\Roaming\Novaworks” folder. If you don’t want the application’s folder but rather the Application Data folder for the computer set the first parameter to false.

string = GetDesktopFolder ()

A very simple function, this will get the user’s desktop folder from the current computer.

string = GetTempFileFolder ()

This will retrieve the temporary folder for the computer that this script is executing on. Very useful if you need to create temporary files that you don’t really want the user to see.

string = GetSystemFolder ()

This will retrieve the system installation folder, which is usually C:\Windows. If you need to run an installed application, like Python, and it’s installed in your system folder, it’s usually a better idea to use the GetSystemFolder function along with the AddPath function to create a path, instead of a hard-coded path into your script.

string = GetScriptFolder ()

This function will return the path to the folder where your script is currently executing. This is very useful if you need to have support files that your script references, so you can move your script from computer to computer without having to hard code the path to the files.

This list should give you an idea of the types of things you can do with path functions when working in Legato. It’s almost always a good idea to use these functions to create dynamic paths that don’t rely on things being installed in predictable locations, because you can’t always count on everyone having the same computer setup with the same paths (or even drives) for common folders and files.

Steven Horowitz has been working for Novaworks for over five years as a technical expert with a focus on EDGAR HTML and XBRL. Since the creation of the Legato language in 2015, Steven has been developing scripts to improve the GoFiler user experience. He is currently working toward a Bachelor of Sciences in Software Engineering at RIT and MCC.

Additional Resources

Novaworks’ Legato Resources

Legato Script Developers LinkedIn Group

Primer: An Introduction to Legato