Merge remote-tracking branch 'cpp-lln-lab/master'

Author: CerenB

.gitignore

@@ -6,3 +6,4 @@
 # exclude content of logfiles folders
 *.tsv
 *.mat
+check_my_code_report.txt

.travis.yml

@@ -0,0 +1,31 @@
+# Travis CI (https://travis-ci.org/)
+
+language: c
+dist: bionic
+cache:
+  apt: true # only works with Pro version
+
+env:
+  global:
+    - OCTFLAGS="--no-gui --no-window-system --silent"
+
+before_install:
+  - travis_retry sudo apt-get -y -qq update
+  - travis_retry sudo apt-get -y install octave
+  - travis_retry sudo apt-get -y install liboctave-dev
+  - cd .. && git clone https://github.com/florianschanda/miss_hit.git && export PATH=$PATH:`pwd`/miss_hit && cd CPP_PTB
+
+install:
+  - octave $OCTFLAGS --eval "addpath (pwd); savepath ();"
+
+before_script:
+  # Change current directory
+  - cd tests
+
+jobs:
+  include:
+    - stage: "Tests and linter"
+      name: "Unit Tests" # names the first job
+      script: octave $OCTFLAGS --eval "results = runTests; assert(all(~[results.Failed]))"
+    - script: cd .. && mh_style.py `pwd`
+      name: "miss_hit linter" # names the second job

CPP_getResponseDemo.m

@@ -27,8 +27,11 @@ The exact version required for this to work but it is known to work with:
 ## Code guidestyle
 
 We use the `camelCase` to more easily differentiates our functions from the ones from PTB that use a `PascalCase`.
+We use the following regular expression for function names: `[a-z]+(([A-Z]|[0-9]){1}[a-z]+)*`.
 
-We keep the McCabe complexity as reported by the [check_my_code function](https://github.com/Remi-Gau/matlab_checkcode) below 15.
+We keep the McCabe complexity as reported by the [check_my_code function](https://github.com/Remi-Gau/check_my_code) below 15.
+
+We use the [MISS_HIT linter](https://florianschanda.github.io/miss_hit/style_checker.html) to automatically fix some linting issues.
 
 ## How to install
 
@@ -70,6 +73,30 @@ You can then use the [matlab package manager](https://github.com/mobeets/mpm), t
   end
 ```
 
+## Setting up keyboards
+
+To select a specific keyboard to be used by the experimenter or the participant, you need to know
+the value assigned by PTB to each keyboard device.
+
+To know this copy-paste this on the command window:
+
+``` matlab
+[keyboardNumbers, keyboardNames] = GetKeyboardIndices;
+
+disp(keyboardNumbers);
+disp(keyboardNames);
+```
+
+You can then assign a specific device number to the main keyboard or the response box in the `cfg` structure
+
+-   `cfg.keyboard.responseBox` would be the device number of the device used by the participant to give his/her
+response: like the button box in the scanner or a separate keyboard for a behavioral experiment
+-   `cfg.keyboard.keyboard` would be the device number of the keyboard on which the experimenter will type or
+press the keys necessary to start or abort the experiment.
+
+`cfg.keyboard.responseBox` and `cfg.keyboard.keyboard` can be different or the same.
+
+Using empty vectors (ie `[]`) or a negative value for those means that you will let PTB find and use the default device.
 
 ## Structure and function details
 
@@ -106,23 +133,27 @@ It is wrapper function to use `KbQueue` which is definitely what you should used
 
 You can easily collect responses while running some other code at the same time.
 
-It will only take responses from the `response box` which can simply be the "main keyboard" or
-another keyboard connected to the computer or the response box that the participant is using.
+It will only take responses from one device which can simply be the "main keyboard" 
+(the default device that PTB will find) or another keyboard connected to the computer 
+or the response box that the participant is using.
 
 You can use it in a way so that it only takes responses from certain keys and ignore others (like
 the triggers from an MRI scanner).
 
 If you want to know more on how to use it check its help section and the `CPP_getResponseDemo.m`.
 
-To select a specific keyboard to be used by the experimenter or the participant, you need to know
-the value assigned by PTB to each keyboard device.
+In brief, there are several actions you can execute with this function.
 
-To know this copy-paste this on the command window:
+-   init: initialize the buffer for key presses on a given device (you can also specify the keys of interest that should be listened to).
+-   start: start listening to the key presses (carefully insert into your script - where do you want to start buffering the responses).
+-   check: till that point, it will check the buffer for all key presses. 
+    -   It only reports presses on the keys of interest mentioned at initialization.
+    -   It **can** also check for presses on the escape key and abort if the escape key is part of the keys of interest.
+-   flush: Empties the buffer of key presses in case you want to discard any previous key presses.
+-   stop: Stops buffering key presses. You can still restart by calling "start" again.
+-   release: Closes the buffer for good.
 
-    [keyboardNumbers, keyboardNames] = GetKeyboardIndices;
 
-    keyboardNumbers
-    keyboardNames
 
 ### deg2Pix
 

README.md

@@ -0,0 +1,36 @@
+function checkAbort(cfg, deviceNumber)
+    % Check for experiment abortion from operator
+    % When no deviceNumber is set then it will check the default device
+    % When an abort key s detected this will set a global variable and throw a
+    % specific error that can then be catched.
+    %
+    % Maint script
+    % try
+    %     % Your awesome experiment
+    % catch ME % when something goes wrong
+    %     switch ME.identifier
+    %         case 'checkAbort:abortRequested'
+    %             % stuff to do when an abort is requested (save data...)
+    %         otherwise
+    %             % stuff to do otherwise
+    %             rethrow(ME) % display the error
+    %     end
+    % end
+
+    if nargin < 1 || isempty(cfg)
+        error('I need at least one input.');
+    end
+
+    if nargin < 2 || isempty(deviceNumber)
+        deviceNumber = -1;
+    end
+
+    [keyIsDown, ~, keyCode] = KbCheck(deviceNumber);
+
+    if keyIsDown && keyCode(KbName(cfg.keyboard.escapeKey))
+
+        errorAbort();
+
+    end
+
+end

checkAbort.m

@@ -1,43 +1,42 @@
 function checkDependencies()
-% Checks that the right dependencies are installed.
-
-printCredits()
-
-PTB.major =  3;
-PTB.minor = 0;
-PTB.point =  14;
-
-fprintf('Checking dependencies\n')
-
-% check ptb version
-try
-    
-    [~, versionStruc] = PsychtoolboxVersion;
-    
-    fprintf(' Using PTB %i.%i.%i\n', ...
-        versionStruc.major, ...
-        versionStruc.minor, ...
-        versionStruc.point)
-    
-    if any( [...
-            versionStruc.major < PTB.major, ...
-            versionStruc.minor < PTB.minor, ...
-            versionStruc.point < PTB.point, ...
-            ])
-        
-        str = sprintf('%s %i.%i.%i %s.\n%s', ...
-            'The current version PTB version is not', ...
-            PTB.major, ...
-            PTB.minor, ...
-            PTB.point, ...
-            'In case of problems (e.g json file related) consider updating.');
-        warning(str); %#ok<*SPWRN>
-    end
-catch
-    error('Failed to check the PTB version: Are you sure that PTB is in the matlab path?')
-end
+    % Checks that the right dependencies are installed.
+
+    printCredits();
+
+    PTB.major =  3;
+    PTB.minor = 0;
+    PTB.point =  14;
+
+    fprintf('Checking dependencies\n');
 
+    % check ptb version
+    try
+
+        [~, versionStruc] = PsychtoolboxVersion;
+
+        fprintf(' Using PTB %i.%i.%i\n', ...
+            versionStruc.major, ...
+            versionStruc.minor, ...
+            versionStruc.point);
+
+        if any([ ...
+                versionStruc.major < PTB.major, ...
+                versionStruc.minor < PTB.minor, ...
+                versionStruc.point < PTB.point, ...
+                ])
+
+            str = sprintf('%s %i.%i.%i %s.\n%s', ...
+                'The current version PTB version is not', ...
+                PTB.major, ...
+                PTB.minor, ...
+                PTB.point, ...
+                'In case of problems (e.g json file related) consider updating.');
+            warning(str); %#ok<*SPWRN>
+        end
+    catch
+        error('Failed to check the PTB version: Are you sure that PTB is in the matlab path?');
+    end
 
-fprintf(' We got all we need. Let us get to work.\n')
+    fprintf(' We got all we need. Let us get to work.\n');
 
 end