FileHandler Library

This library is used in nearly every experiment. It has handlers to control setting the filepaths PsyScript uses to find image resources, creating a new subject ID, writing results to disk, shuffling lists, creating lists according to certain criteria, etc.

(note: you can get quick acess to all of these handlers by installing the authoring helper in your Script Editor's Scripts Folder)

The Handlers

checkLibraryVersion(minimumVersion)

Checks the version number for the version of fileHandler.lib you are using. If the version is less than the minimum you require, it will throw a dialog asking you to update the library.

e.g checkLibraryVersion(2)

initialize()

Call this first in EVERY experiment to set the filepaths to your experiment , resource and results folders.

setContainer(pathToFolderContainingTheExperimentScript)

If you use Apple's Script Editor, call this before initialize to set the path to your script. (Don't use Apple's Editor - use SMILE if you can;t afford Script Debugger.

setSubjectFileParameters({prefix:"", suffix:""})

Your data files will use the prefix and suffix set here. By default these are empty.
e.g. setSubjectFileParameters({prefix:"egly", suffix:".txt"})
nb: you can run this at any time and a new data file will be generated appropriately

createNewSubjectID()

Requests a subject ID via dialog. This is the name that will be used as the base name of your data files. Any value set using setSubjectFileParameters will be prepended and suffixed.

writespreadsheet(theData)

You can pass this a string, a list of strings, a record, or a list of lists! all of them work.You need to have run initialize() and createNewSubjectID() before using this to write to a file of your choice,  use writespreadsheettoFile(theData, thefile)

more help

writespreadsheettoFile(theData, thefile)

You can pass this a string, a list of strings, a record, or a list of lists! all of them work.more help

writeToCompanionFile(theData, fileSuffix)

Just a convenience function to create and write to files with the same base name as pPathToResultsFile

readSpreadsheet(thefile)

Takes a file path, returns a 2D array. If you just pass a fileName, i.e., "myData" it will look for this file in the pResources folder (set this using initialize()) If you pass a valid path, it will open the file specified by the full path. It returns the spreadsheet as a list of lists, where each line is an item in a  list of lines more help

readSpreadsheet1D(thefile)

Same as readSpreadsheet ,but returns a 1D array. more help

FileExists(thePath)

returns true is thePath is valid, and false otherwise.

getFileNameFromPath(thePath)

Given a full path, this returns the name of the file from a path. ie..getFileNameFromPath("disk:folder:folder2:myfile")
      --> "myfile"

getFileContainerFromPath(thePath)

Returns the container of a file from a path.

 LIST HANDLERS

initializeList(theCount, theContents)

Use this function to quickly create a list of a certain length.
e.g. initializeList(5, "0")
-->{"0", "0", "0", "0", "0"}

getOffset(what, theList)

Finds the offset of "what" in theList returns -1 if not found
e.g. getOffset("cat", {1,2,"cat",4,5,6})
   --> 3
getOffset(6, {1, 2, 3})
   -->-1

sort(theList)

will quickly sort a list of numbers

e.g. set sortedList to filehelper's sort({3,4,1,2})
sortedList --> {1,2,3,4}

randomize(theList)

itemsContaining(theList, includeString, excludeString)

distinct(theList)

returns the unique elements of a list
distinct({1,1,2,3,4,4})
-->{1,2,3,4} *)

union(listA, listB)

e.g. union({1,2,3,4},{4,5,6})
-->{1,2,3,4,5,6}
nb: only one instance of each value is returned

intersection(listA, listB)

e.g. intersection({1,2,3,4},{4,5,6})
-->{4}

difference(listA, listB)

e.g. intersection({1,2,3,4},{4,5,6})
-->{1,2,3,5,6}

replaceItems(itemIndices, NewItems, originalList)

replaceItems({1, -1}, {"a", "b"}, {1, 2, 3, 4})
-->{"a", 2, 3, "b"}

This handler replaces items replaceItems({1, -1}, {"a", "b"}, {1, 2, 3, 4})
-->{"a", 2, 3, "b"}

insert(insertionAt, addingTheseItems, toThisList)

insertion item must come in reverse order!! This function will insert items into a list passed in as "toThisList" If inserts each item in the "addingTheseItems" list at an index given in the list of indices. If using a list, the length of the insertion items and insertion indices lists must match

It can insert a single item:

e.g. return insert(3, "hello", {1, 2, 3, 4})

{1, 2, 3, "hello", 4}

return insert({3, 2}, {"after 3", "after 2"}, {1, 2, 3, 4})

{1, 2, "after 2", 3, "after 3", 4}

parsetostring(theList, theDelimiters)

This handler will turn a list into a string, using the items in "delimitters" to separate each item
So, to turn a list of trial results into a spreadsheet, you could say
parsetostring({{"yes", 1, 501, "correct"}, {"no", 2, 408, "incorrect"}}, {tab, return})
"yes      1   501   correct
no      2   408   incorrect"

stringToList(theString, theDelimiters)

This is the inverse of parsetostring
This handler reads a string and returns it as a list, using the items in delimitters to break the string into a list of items. Additional delimitters create nested lists. This will create lists for every delimiter even if the delimiter is not found i.e., the list is packed to a square array
e.g. set theString to "yes      1   501   correct
no      2   408   incorrect"

stringToList(theString, {tab, return})
-->{{"yes", 1, 501, "correct"}, {"no", 2, 408, "incorrect"}}

subset(indices, theList)

This will return the items of TheList as chosen by "indices"
e.g. set someItems to filehelper's subset({1,3}, {"cat","dog","log","bow"})
-->{"cat","log"}

remove(deletionAt, fromThisList)

This function will delete items at the indeces in "fromThisList" note: removals are always done in order last to first
return remove(3, {"one", "two", "three", "four"})
{"one", "two", "four"}
return remove({2, 3}, {"one", "two", "three", "four"})
{"one", "four"}

removeItem(x, theList)

removes  item x from  TheList
   e.g. return filehelper's removeItem(3, {"a","b","c","d"})
      -->{"a","b","d"}

sample(itemCount, theList, replacing)

This handler will grab itemCount items from TheList with/without replacement between samples
e.g. sample (5,{1, 2, 3, 4, 5, 6, 7, 8, 9},true)
-->{3, 7, 7,1,5}
sample (6,{1, 2, 3, 4, 5, 6, 7, 8, 9},false)
-->{3, 2, 7,1,5,9}

sparseRepeat given taking:numberWanted, outof:theList, separatedBy:min

This is useful in Attentional Blink type experiments where you want to sample with replacement, but you don't want items to repeat before a gap

sparseRepeat  taking:9, outof:{1, 2, 3, 4, 5, 6, 7, 8, 9} separatedBy:3
-->{4, 5,1, 8, 4,  6, 3, 8, 5}

create_shuffled_list(listLength)

create_shuffled_list(6)
--> {38, 13, 32, 52, 40, 8}

create_shuffled_sublist(totalNumberSet, listLength)

This handler will return a list of sequential numbers from 1 - totalNumberSet, but shuffled into random order.

create_shuffled_sublist(56, 6)
--> {38, 13, 32, 52, 40, 8}

pickInRangeButNotInList({allowedRange, badList})

AllowedRange = list of min and max i.e., {1,100}. bad list = illegal numbers i.e., {3,42}

KEY FUNCTIONS

saveKeyStates()

restoreKeyStates()

setNoticed of keyName given mapping:theMapping

setNoticed of "K" given mapping:"name you want"

noticeKeyboard(keyList)

keyList of form {{"name","mapping"},{"name","mapping"}}

User Interaction Handlers

showAsInstructions(theText, leftMargin, rightMargin)

Shows theText as instructions within the left and right margins, then waits for a space bar press.

nb: to shows an imagefile as instructions, just say

do trial "@?1 #b !t(0)" given {"AX_instruct.png"}

takeABreak(helpNeeded)

This utility function clears the screen and displays a message. If helpNeeded is true, then the both lines are displayed, otherwise only the second line appears:

If you are happy that you understand the task, press any key to continue. Otherwise ask for assistance now.
You can have a short break now if you wish. Press any response key to continue

takeABreakPlus(helpNeeded, trialNumber, breakEvery)

getInfo(asking, defaultAnswer)

waitForOthers()

This utility function clears the screen and displays the message

Stop. Well done. Please wait quietly for the others to catch up

Press space again (only if we are ready to proceed)

Not used very often

setResultsFile(newPathToResultsFile)

use this only if you do not wish to use createNewSubjectID

changeNameOfResultsFile(newName) 

returns new pPathToResultsFile

storeResults(newResponses, flushtoDisk)

Probably won't use this much - you can just call writespreadsheet() directly. It is useful if you need speed and therefore cannot afford to write the results to disk each trial.

quitAllExcept(appstokeepalive)

Kill all running applications except those passed in as appstokeepalive, and returns a list of the processes which were killed

 

 

MACCS		Documentation	Downloads	FAQ	Mailing List	Last change:
					Advanced Search

Applescript in a Nutshell : A Desktop Quick Reference

AppleScript for Applications: Visual QuickStart Guide

AppleScript For Dummies

Applescript for the Internet Visual Quickstart Guide

Applescript Language Guide; English Dialect

Danny Goodman's Applescript Handbook