# Module Resources

## Constants

APPEND | Access modifier for append mode.
READ | Access modifier for read mode.
WRITE | Access modifier for write mode.

## Function Overview

closeFile | Close a file. Releases system resources bound by an open file.
createFile | Create a new file in the workspace or the file system.
createFolder | Create a new folder in the workspace or the file system.
createProject | Create a new workspace project. Will create a new project if it now already exists. If creation fails, `null` is returned.
findFiles | Return files matching a certain pattern.
getFile | Get a workspace or file system file. Resolves relative and absolute file locations. Relative files are resolved against the current script file. If exists is `false` this method also returns files that do not exist yet. If `true` only existing instances are returned
getProject | Get a project instance.
getWorkspace | Get the workspace root.
openFile | Opens a file from the workspace or the file system. If the file does not exist and we open it for writing, the file is created automatically.
readFile | Read data from a file. To repeatedly read from a file retrieve a {@link IFileHandle} first using {@link #openFile(String, int)} and use the handle for location.
readLine | Read a single line from a file. To repeatedly read from a file retrieve a {@link IFileHandle} first using {@link #openFile(String, int)} and use the handle for location.
showFileSelectionDialog | Opens a file dialog. Depending on the rootFolder a workspace dialog or a file system dialog will be used. If the folder cannot be located, the workspace root folder is used by default. When type is set to WRITE or APPEND a save dialog will be shown instead of the default open dialog.
showFolderSelectionDialog | Opens a dialog box which allows the user to select a container (project or folder). Workspace paths will always display the workspace as root object.
writeFile | Write data to a file. When not using an {@link IFileHandle}, previous file content will be overridden. Files that do not exist yet will be automatically created.
writeLine | Write a line of data to a file. When not using an {@link IFileHandle}, previous file content will be overridden. Files that do not exist yet will be automatically created.

## Functions

### getWorkspace

org.eclipse.core.resources.IWorkspaceRoot getWorkspace()

Get the workspace root.

org.eclipse.core.resources.IWorkspaceRoot ... workspace root

### getProject

org.eclipse.core.resources.IProject getProject(java.lang.String name)

Get a project instance.

Parameter | Type | Description
--- | --- | ---
name | java.lang.String | project name

org.eclipse.core.resources.IProject ... project or `null`

### getFile

java.lang.Object getFile(java.lang.String location, boolean exists)

Get a workspace or file system file. Resolves relative and absolute file locations. Relative files are resolved against the current script file. If exists is `false` this method also returns files that do not exist yet. If `true` only existing instances are returned

Parameter | Type | Description
--- | --- | ---
location | java.lang.String | file location/path to resolve
exists | boolean | whether the resolved file needs to exist

java.lang.Object ... resolved {@link IFile} or {@link File} instance

### createProject

org.eclipse.core.resources.IProject createProject(java.lang.String name)

Create a new workspace project. Will create a new project if it now already exists. If creation fails, `null` is returned.

Parameter | Type | Description
--- | --- | ---
name | java.lang.String | name or project to create

org.eclipse.core.resources.IProject ... `null` or project

### createFolder

java.lang.Object createFolder(java.lang.Object location)

Create a new folder in the workspace or the file system.

Parameter | Type | Description
--- | --- | ---
location | java.lang.Object | folder location

java.lang.Object ... {@link IFolder}, {@link File} or `null` in case of error

### createFile

java.lang.Object createFile(java.lang.Object location)

Create a new file in the workspace or the file system.

Parameter | Type | Description
--- | --- | ---
location | java.lang.Object | file location

java.lang.Object ... {@link IFile}, {@link File} or `null` in case of error

### openFile

org.eclipse.ease.modules.platform.IFileHandle openFile(java.lang.Object location, int mode)

Opens a file from the workspace or the file system. If the file does not exist and we open it for writing, the file is created automatically.

Parameter | Type | Description
--- | --- | ---
location | java.lang.Object | file location
mode | int | one of {@value #READ}, {@value #WRITE}, {@value #APPEND}

org.eclipse.ease.modules.platform.IFileHandle ... file handle instance to be used for file modification commands

### closeFile

void closeFile(org.eclipse.ease.modules.platform.IFileHandle handle)

Close a file. Releases system resources bound by an open file.

Parameter | Type | Description
--- | --- | ---
handle | org.eclipse.ease.modules.platform.IFileHandle | handle to be closed

### readFile

java.lang.String readFile(java.lang.Object location, int bytes)

Read data from a file. To repeatedly read from a file retrieve a {@link IFileHandle} first using {@link #openFile(String, int)} and use the handle for location.

Parameter | Type | Description
--- | --- | ---
location | java.lang.Object | file location, file handle or file instance
bytes | int | amount of bytes to read (-1 for whole file)

java.lang.String ... file data or `null` if EOF is reached

### readLine

java.lang.String readLine(java.lang.Object location)

Read a single line from a file. To repeatedly read from a file retrieve a {@link IFileHandle} first using {@link #openFile(String, int)} and use the handle for location.

Parameter | Type | Description
--- | --- | ---
location | java.lang.Object | file location, file handle or file instance

java.lang.String ... line of text or `null` if EOF is reached

### writeFile

org.eclipse.ease.modules.platform.IFileHandle writeFile(java.lang.Object location, java.lang.String data, int mode)

Write data to a file. When not using an {@link IFileHandle}, previous file content will be overridden. Files that do not exist yet will be automatically created.

Parameter | Type | Description
--- | --- | ---
location | java.lang.Object | file location
data | java.lang.String | data to be written
mode | int | write mode (WRITE/APPEND)

org.eclipse.ease.modules.platform.IFileHandle ... file handle to continue write operations

### writeLine

org.eclipse.ease.modules.platform.IFileHandle writeLine(java.lang.Object location, java.lang.String data, int mode)

Write a line of data to a file. When not using an {@link IFileHandle}, previous file content will be overridden. Files that do not exist yet will be automatically created.

Parameter | Type | Description
--- | --- | ---
location | java.lang.Object | file location
data | java.lang.String | data to be written
mode | int | write mode (WRITE/APPEND)

org.eclipse.ease.modules.platform.IFileHandle ... file handle to continue write operations

### showFileSelectionDialog

java.lang.String showFileSelectionDialog(java.lang.Object rootFolder, int type, java.lang.String title, java.lang.String message)

Opens a file dialog. Depending on the rootFolder a workspace dialog or a file system dialog will be used. If the folder cannot be located, the workspace root folder is used by default. When type is set to WRITE or APPEND a save dialog will be shown instead of the default open dialog.

Parameter | Type | Description
--- | --- | ---
rootFolder | java.lang.Object | root folder path to use
type | int | dialog type to use (WRITE|APPEND for save dialog, other for open dialog)
title | java.lang.String | dialog title
message | java.lang.String | dialog message

java.lang.String ... full path to selected file

### showFolderSelectionDialog

java.lang.String showFolderSelectionDialog(java.lang.Object rootFolder, java.lang.String title, java.lang.String message)

Opens a dialog box which allows the user to select a container (project or folder). Workspace paths will always display the workspace as root object.

Parameter | Type | Description
--- | --- | ---
rootFolder | java.lang.Object | root folder to display: for workspace paths this will set the default selection
title | java.lang.String | dialog title
message | java.lang.String | dialog message

java.lang.String ... path to selected folder

### findFiles

java.lang.Object findFiles(java.lang.String pattern, java.lang.Object rootFolder, boolean recursive)

Return files matching a certain pattern.

Parameter | Type | Description
--- | --- | ---
pattern | java.lang.String | search pattern: use * and ? as wildcards. If the pattern starts with '^' then a regular expression can be used.
rootFolder | java.lang.Object | root folder to start your search from. `null` for workspace root
recursive | boolean | searches subfolders when set to `true`

java.lang.Object ... An array of all matching files