Skip to main content

module IO

rascal-0.40.16

Library functions for input/output.

Usage​

import IO;

Dependencies​

import Exception;

Description​

The following input/output functions are defined:

function registerLocations​

Register a logical file scheme including the resolution method via a table.

void registerLocations(str scheme, str authority, map[loc logical, loc physical] m)

Logical source location schemes, such as |java+interface://JRE/java/util/List| are used for precise qualified names of artifacts while abstracting from their physical location in a specific part of a file on disk or from some webserver or source repository location.

Using this function you can create your own schemes. The authority field is used for scoping the names you wish to resolve to certain projects. This way one name can resolve to different locations in different projects.

Benefits​

  • Logical source locations are supported by IDE features such as hyperlinks
  • Logical source locations are supported by all IO functions as well

Pitfalls​

  • Repeated calls to registerLocations for the same scheme and authority will overwrite the m map.
  • The registry is an intentional memory leak; so make sure you use it wisely. See also Unregister Locations.
  • When the files references by the physical locations are being written to (edited, removed), then you may expect problems. The registry is not automatically invalidated.

function unregisterLocations​

Undo the effect of Register Locations.

void unregisterLocations(str scheme, str authority)

For debugging or for memory management you may wish to remove a lookup table.

function resolveLocation​

loc resolveLocation(loc l)

function findResources​

Finds files in the deployment locations of the configuration of the current runtime.

set[loc] findResources(str fileName)

set[loc] findResources(loc path)
  • For the interpreter this looks at the source path and finds any file in there.
  • For the compiler this looks at the classpath and finds resources in there.

The goal of findResources is to access additional files that are distributed with a Rascal program. For example, the index.html file that comes with a server implemented using Webserver would be located using this function. Such an additional file is essential to the functioning of the given Rascal code.

There is a difference between Rascal programs under development and Rascal programs deployed (in a jar file). The idea is that calls to this function behave the same regardless of this mode. To make this true, the implementation of findResources makes the following assumptions:

  • In interpreter mode, the additional files are stored relative to the source roots of the current project. This means that all source roots are searched as configured for the current interpreter. It is possible that multiple files match the query, hence the result set. Because jar files and target folders are typically added to the source roots by the configuration code for Rascal's IDEs, this works out smoothly also for deployed projects.
  • In compiled mode, the additional files are stored relative to the roots of the classpath. This means they are jar files and target folders of active projects. Your Maven project configuration should take care to copy all relevant resources from source folders to target folders and to package those relative to the root of the jar for this to work in development mode. For deployment mode, the setup works through the resources API of the JVM that uses the Java ClassLoader API.

Benefits​

By satisfying the above two assumptions it is possible to write Rascal code that uses findResources that is portable between interpreter and compiled mode, and does not change between development and deployed mode either.

Pitfalls​

  • Avoid nesting resources in sub-folders in jar files (see Maven resources plugin) since nested files will not be found.
  • Inside jar files the root for module names should be the same as for resources
  • Inside source folders, the names of resources should be relative to the same root as the Rascal module names
  • findResources searches exhaustively for all files with the given name; which may come at an expensive for projects with large search paths. It makes sense to keep this in a constant module variable that is initialized only once.
  • Name clashes are bound to happen. Prepare to, at least, throw a meaningful error message in the case of name clashes. E.g. findResources("index.html") is very likely to produce more than one result. Either choose more unique names, or filter the result in a meaningful manner, or throw an exception that explains the situation to the user of your code. Specifically library project maintainers have to consider this happenstance. The recommendation is to nest resources next to qualified module names, like so: if lang/x/myLanguage/Syntax.rsc is a module name, then lang/x/myLanguage/examples/myExampleFile.mL is an example resource location.

function getResource​

Search for a single resource instance, and fail if no or multiple instances are found.

loc getResource(str fileName) throws IO

This is a utility wrapper around Find Resources. It processes the result set of Find Resources to:

  • return a singleton location if the `fileName`` was found.
  • throw an IO exception if no instances of fileName was found.
  • throw an IO exception if multiple instances of fileName were found.

Benefits​

Pitfalls​

  • Get Resource searches for all instances in the entire run-time context of the current module. So if the search path (classpath) grows, new similar files may be added that match and this function will start throwing IO exceptions. If you can influence the fileName, then make sure to pick a name that is always going to be unique for the current project.

function appendToFile​

Append a value to a file.

void appendToFile(loc file, value V..., str charset=DEFAULT_CHARSET, bool inferCharset=!(charset?))
throws PathNotFound, IO

Append a textual representation of some values to an existing or a newly created file:

  • If a value is a simple string, the quotes are removed and the contents are de-escaped.
  • If a value has a non-terminal type, the parse tree is unparsed to produce a value.
  • All other values are printed as-is.
  • Each value is terminated by a newline character.

The existing file can be stored using any character set possible, if you know the character set, please use Append To File Enc. Else the same method of deciding the character set is used as in Read File.

Pitfalls​

  • The same encoding pitfalls as the Read File function.

function appendToFileEnc​

Append a value to a file.

danger

deprecated: marked for future deletion Use appendToFile(file, V, charset=DEFAULT_CHARSET) instead.

void appendToFileEnc(loc file, str charset, value V...) throws PathNotFound, IO

Append a textual representation of some values to an existing or a newly created file:

  • If a value is a simple string, the quotes are removed and the contents are de-escaped.
  • If a value has a non-terminal type, the parse tree is unparsed to produce a value.
  • All other values are printed as-is.
  • Each value is terminated by a newline character.

Files are encoded using the charset provided.

function charsets​

Returns all available character sets.

set[str] charsets()

function canEncode​

Returns whether this charset can be used for encoding (use with Write File).

set[str] canEncode(str charset)

function bprintln​

Print a value and return true.

bool bprintln(value arg)

Print a value and return true. This is useful for debugging complex Boolean expressions or comprehensions. The only difference between this function and Println is that its return type is bool rather than void.

Examples​

rascal>import IO;
ok
rascal>bprintln("Hello World");
Hello World
bool: true

function exists​

Check whether a given location exists.

bool exists(loc file)

Check whether a certain location exists, i.e., whether an actual file is associated with it.

Examples​

rascal>import IO;
ok

Does the library file IO.rsc exist?

rascal>exists(|std:///IO.rsc|);
bool: true

function find​

Find a named file in a list of locations.

loc find(str name, list[loc] path) throws PathNotFound

Examples​

rascal>import IO;
ok

Find the file IO.rsc in the standard library:

rascal>find("IO.rsc", [|std:///|]);
loc: |std:///IO.rsc|

function isDirectory​

Check whether a given location is a directory.

bool isDirectory(loc file)

Check whether the location file is a directory.

function iprint​

Print an indented representation of a value.

void iprint(value arg, int lineLimit = 1000)

See IprintExp for a version that returns its argument as result and Iprintln for a version that adds a newline and IprintToFile for a version that prints to a file.

Examples​

rascal>import IO;
ok
rascal>iprint(["fruits", ("spider" : 8, "snake" : 0), [10, 20, 30]]);
[
  "fruits",
  ("snake":0,"spider":8),
  [10,20,30]
]
ok

function iprintToFile​

Print an indented representation of a value to the specified location.

void iprintToFile(loc file, value arg, str charset=DEFAULT_CHARSET)

See Iprint for a version that displays the result on the console and IprintExp for a version that returns its argument as result and Iprintln for a version that adds a newline.

Examples​

rascal>import IO;
ok
rascal>iprintToFile(|file:///tmp/fruits.txt|, ["fruits", ("spider" : 8, "snake" : 0), [10, 20, 30]]);
ok

function iprintToString​

str iprintToString(value arg)

function iprintExp​

Print an indented representation of a value and returns the value as result.

&T iprintExp(&T v)

See IprintlnExp for a version that adds a newline.

Examples​

rascal>import IO;
ok
rascal>iprintExp(["fruits", ("spider" : 8, "snake" : 0), [10, 20, 30]]);
[
  "fruits",
  ("snake":0,"spider":8),
  [10,20,30]
]
list[value]: [
  "fruits",
  ("snake":0,"spider":8),
  [10,20,30]
]

function iprintlnExp​

Print an indented representation of a value followed by a newline and returns the value as result.

&T iprintlnExp(&T v)

See IprintExp for a version that does not add a newline.

Examples​

rascal>import IO;
ok
rascal>iprintlnExp(["fruits", ("spider" : 8, "snake" : 0), [10, 20, 30]]);
[
  "fruits",
  ("snake":0,"spider":8),
  [10,20,30]
]
list[value]: [
  "fruits",
  ("snake":0,"spider":8),
  [10,20,30]
]

function iprintln​

Print a indented representation of a value and add a newline at the end.

void iprintln(value arg, int lineLimit = 1000)

See IprintlnExp for a version that returns its argument as result and Iprint for a version that does not add a newline.

By default we only print the first 1000 lines, if you want to print larger values, either use WriteTextValueFile or change the limit with the lineLimit parameter.

Examples​

rascal>import IO;
ok
rascal>iprintln(["fruits", ("spider" : 8, "snake" : 0), [10, 20, 30]]);
[
  "fruits",
  ("snake":0,"spider":8),
  [10,20,30]
]
ok
rascal>iprintln([ {"hi"} | i <- [0..1000]], lineLimit = 10);
[
  {"hi"},
  {"hi"},
  {"hi"},
  {"hi"},
  {"hi"},
  {"hi"},
  {"hi"},
  {"hi"},
  {"hi"},
...
ok

function isFile​

Check whether a given location is actually a file (and not a directory).

bool isFile(loc file)

Check whether location file is actually a file.

function lastModified​

Last modification date of a location.

datetime lastModified(loc file)

Returns last modification time of the file at location file.

Examples​

rascal>import IO;
ok

Determine the last modification date of the Rascal standard library:

rascal>lastModified(|std:///IO.rsc|);
datetime: $2024-11-05T18:51:04.000+00:00$

function created​

Creation datetime of a location.

datetime created(loc file)

Returns the creation time of the file at location file.

Examples​

rascal>import IO;
ok

Determine the last modification date of the Rascal standard library:

rascal>created(|std:///IO.rsc|);
datetime: $2024-11-05T18:51:04.000+00:00$

function touch​

Set the modification date of a file to now or create the file if it did not exist yet.

void touch(loc file)

function setLastModified​

Set the modification date of a file to the timestamp.

void setLastModified(loc file, datetime timestamp)

function listEntries​

List the entries in a directory.

list[str] listEntries(loc file)

List the entries in directory file.

Examples​

rascal>import IO;
ok

List all entries in the standard library:

rascal>listEntries(|std:///|);
list[str]: ["Boolean.rsc","Content.rsc","DateTime.rsc","Exception.rsc","Grammar.rsc","IO.rsc","List.rsc","ListRelation.rsc","Location.rsc","Map.rsc","Message.rsc","Node.rsc","ParseTree.rsc","Prelude$1.class","Prelude$2.class","Prelude$3.class","Prelude$4.class","Prelude$Backtrack.class","Prelude$ByteBufferBackedInputStream.class","Prelude$Distance.class","Prelude$Less.class","Prelude$NodeComparator.class","Prelude$ReleasableCallback.class","Prelude$Sorting.class","Prelude.class","Prelude.rsc","Relation.rsc","Set.rsc","String.rsc","Type.class","Type.rsc","ValueIO.rsc","analysis","index.md","lang","resource","util","vis"]

function mkDirectory​

Create a new directory.

void mkDirectory(loc file)
throws PathNotFound, IO

Create a directory at location file.

function print​

Print a value without subsequent newline.

void print(value arg)

Print a value on the output stream. See Println for a version that adds a newline and PrintExp for a version that returns its argument as value.

Examples​

Note that the only difference with Println is that no newline is added after the value is printed

rascal>import IO;
ok
rascal>print("Hello World");
Hello World
ok

NOTE: Since print does not add a newline, the prompt ok appears at a weird place, i.e., glued to the output of print.

function printExp​

Print a value and return it as result.

&T printExp(&T v)

&T printExp(str msg, &T v)

Examples​

rascal>import IO;
ok
rascal>printExp(3.14);
3.14
real: 3.14
rascal>printExp("The value of PI is approximately ", 3.14);
The value of PI is approximately 3.14
real: 3.14

function println​

Print a value to the output stream and add a newline.

void println(value arg)

void println()

Print a value on the output stream followed by a newline. See Print for a version that does not add a newline and PrintlnExp for a version that returns its argument as value.

Examples​

rascal>import IO;
ok
rascal>println("Hello World");
Hello World
ok

Introduce variable S and print it:

rascal>S = "Hello World";
str: "Hello World"
---
Hello World
---
rascal>println(S);
Hello World
ok

Introduce variable L and print it:

rascal>L = ["a", "b", "c"];
list[str]: ["a","b","c"]
rascal>println(L);
["a","b","c"]
ok

Use a string template to print several values:

rascal>println("<S>: <L>");
Hello World: ["a","b","c"]
ok

Just print a newline

rascal>println();
ok

function printlnExp​

Print a value followed by a newline and return it as result.

&T printlnExp(&T v)

&T printlnExp(str msg, &T v)

Examples​

rascal>import IO;
ok
rascal>printlnExp(3.14);
3.14
real: 3.14
rascal>printlnExp("The value of PI is approximately ", 3.14);
The value of PI is approximately 3.14
real: 3.14

NOTE: Since printExp does no produce a newline after its output, the result prompt real: 3.14 is glued to the output of printExp.

function rprint​

Raw print of a value.

void rprint(value arg)

Pitfalls​

This function is only available for internal use in the Rascal development team.

function rprintln​

Raw print of a value followed by newline.

void rprintln(value arg)

Pitfalls​

This function is only available for internal use in the Rascal development team.

function readFile​

Read the contents of a location and return it as string value.

str readFile(loc file, str charset=DEFAULT_CHARSET, bool inferCharset=!(charset?))
throws PathNotFound, IO

Return the contents of a file location as a single string. Also see Read File Lines.

Pitfalls​

  • In case encoding is not known, we try to estimate as best as we can.
  • We default to UTF-8, if the file was not encoded in UTF-8 but the first characters were valid UTF-8, you might get an decoding error or just strange looking characters.

function readFileEnc​

Read the contents of a location and return it as string value.

danger

deprecated: marked for future deletion Use readFile(file, inferCharset=false, charset=DEFAULT_CHARSET) instead.

str readFileEnc(loc file, str charset) throws PathNotFound, IO

Return the contents (decoded using the Character set supplied) of a file location as a single string. Also see Read File Lines Enc.

function readBase64​

Read the content of a file and return it as a base-64 encoded string.

str readBase64(loc file, bool includePadding=true)
throws PathNotFound, IO

function uuencode​

str uuencode(loc file)

function writeBase64​

Decode a base-64 encoded string and write the resulting bytes to a file.

void writeBase64(loc file, str content)
throws PathNotFound, IO

function uudecode​

void uudecode(loc file, str content)

function readBase32​

Read the content of a file and return it as a base-32 encoded string.

str readBase32(loc file, bool includePadding=true)
throws PathNotFound, IO

function writeBase32​

Decode a base-32 encoded string and write the resulting bytes to a file.

void writeBase32(loc file, str content)
throws PathNotFound, IO

function readFileBytes​

Read the contents of a file and return it as a list of bytes.

list[int] readFileBytes(loc file)
throws PathNotFound, IO

function readFileLines​

Read the contents of a file location and return it as a list of strings.

list[str] readFileLines(loc file, str charset=DEFAULT_CHARSET)
throws PathNotFound, IO

Return the contents of a file location as a list of lines. Also see Read File.

Pitfalls​

  • In case encoding is not known, we try to estimate as best as we can (see [readFile]).
  • We default to UTF-8, if the file was not encoded in UTF-8 but the first characters were valid UTF-8, you might get an decoding error or just strange looking characters (see Read File).

function writeFileLines​

Writes a list of strings to a file, where each separate string is ended with a newline.

void writeFileLines(loc file, list[str] lines, str charset=DEFAULT_CHARSET)

Benefits​

Pitfalls​

  • if the individual elements of the list also contain newlines, the output may have more lines than list elements

function readFileLinesEnc​

Read the contents of a file location and return it as a list of strings.

danger

deprecated: marked for future deletion Use readFileLines(file, charset=DEFAULT_CHARSET) instead.

list[str] readFileLinesEnc(loc file, str charset)
throws PathNotFound, IO

Return the contents (decoded using the Character set supplied) of a file location as a list of lines. Also see Read File Lines.

function remove​

void remove(loc file, bool recursive=true) throws IO

function writeFile​

Write values to a file.

void writeFile(loc file, value V..., str charset=DEFAULT_CHARSET)
throws PathNotFound, IO

Write a textual representation of some values to a file:

  • If a value is a simple string, the quotes are removed and the contents are de-escaped.
  • If a value has a non-terminal type, the parse tree is unparsed to produce a value.
  • All other values are printed as-is.
  • Each value is terminated by a newline character.

Files are encoded in UTF-8, in case this is not desired, use Write File Enc.

function writeFileBytes​

Write a list of bytes to a file.

void writeFileBytes(loc file, list[int] bytes)
throws PathNotFound, IO

function writeFileEnc​

Write values to a file.

danger

deprecated: marked for future deletion Use writeFile(file, charset=...) instead.

void writeFileEnc(loc file, str charset, value V...) throws PathNotFound, IO

Write a textual representation of some values to a file:

  • If a value is a simple string, the quotes are removed and the contents are de-escaped.
  • If a value has a non-terminal type, the parse tree is unparsed to produce a value.
  • All other values are printed as-is.
  • Each value is terminated by a newline character.

Files are encoded using the charset provided.

function md5HashFile​

Read the contents of a location and return its MD5 hash.

str md5HashFile(loc file)
throws PathNotFound, IO

MD5 hash the contents of a file location.

function md5Hash​

str md5Hash(value v)
str createLink(str title, str target)

function toBase64​

str toBase64(loc file, bool includePadding=true)
throws PathNotFound, IO

function copy​

void copy(loc source, loc target, bool recursive=false, bool overwrite=true) throws IO

function copyFile​

void copyFile(loc source, loc target)

function copyDirectory​

void copyDirectory(loc source, loc target)

function move​

void move(loc source, loc target, bool overwrite=true) throws IO

function arbLoc​

loc arbLoc()

data LocationChangeEvent​

data LocationChangeEvent  
     = changeEvent(loc src, LocationChangeType changeType, LocationType \type)
     ;

data LocationChangeType​

data LocationChangeType  
     = created()
     | deleted()
     | modified()
     ;

data LocationType​

data LocationType  
     = file()
     | directory()
     ;

function watch​

void watch(loc src, bool recursive, void (LocationChangeEvent event) watcher)

function unwatch​

void unwatch(loc src, bool recursive, void (LocationChangeEvent event) watcher)