[RELEASE,v1.0] 'fnc_IBEN_base_ROOTer' : Make your addon portable like

[iben]

Hello guys,

currently busy working on boring real life project always looking forward to rest time with DayZ Epoch.
And because I'm lazy and doing stupid things like moving addons root folder up and down during
my experiments - and always asking why my smart computer do not update path itself :)) -
I decided support my lazy nature and write simple function which helps with paths a little bit.
To be more precise, I wrote two variants - basic and extended. Well, will see if basic version
will be found usefull. So here it is...

===

But first - big Thank you to these guys:

• DayZ Epoch developers, collaborators and contributors (thank you guys for your excellent work!)
• Karel Moricky from Bohemia Interactive for his simple and clever idea how to extract mission root.

===

Changelog:

• [2017-06-19], v1.0 | Initial release

===

Read "Goodbye". Wish you the best guys!

===

How to install:

It's completely up to you. Pick one way to load it to fits your needs:

• as a separate file in your custom compiles;
• in the beginning of your addon compiled init code;
• just #include fnc in header of your addon compiled init code;
• use your custom fnc library (using config);

===

Why could be usefull?

In my opinion, it's in every addon developer best interest to make addon
as much as possible usable for user without extra steps. Not because
you are user's slave :)), just because you save yourself answering questions
leads to well known discovery - user didn't update the path (because he/she/it don't
want to have this addon in mission root, but in customized server pack structure - this is usually my case).
Using this fnc you can make your addon 'portable' like (I mean in mission folder boundaries).

===

How to use it?

• Remember 1 - this function returns first parent folder path relative to mission folder.
• Remember 2 - you can use "zero based" option as second argument, which means, you can decide if you want to include "\" at the end of your path.
• Remember 3 - you can uncomment '__IDEBUG__' and see some usefull info in your RPT logfile.
• Remember 4 - you are developer - so again - choose your way that fills your needs the best.

===

Let's take some practical examples:

= Example 1: service point remake by @salival

//src: service_point.sqf, line 39 - original

// ---------------- CONFIG START ----------------
diag_log "Service Points: loading config...";

// general settings
_folder = "scripts\service_points\"; // folder where the service point scripts are saved, relative to the mission file

// Now you can change it to:
_folder = [__FILE__,true] call fnc_IBEN_base_ROOTer; // this addon needs "\" at the end of path, so we set second argument (zero based option) "true"

= Example 2: your custom addon (or more structured addons uses default Epoch files)

// Create global variable:
MyAddonROOTfolder = call {

  // ... code from fnc - see bellow

};

// ... or
MyAddonROOTfolder = [__FILE__] call fnc_IBEN_base_ROOTer;

// and just use it as a root base for your addon. Good news is it's compiled fnc so you can use it anywhere, right?

===

How it looks like?

// ===========================================================================
// FUNCTIONS LIBRARY >> PATH MANIPULATION >> fnc_base_ROOTer.sqf
// ===========================================================================
// @Function name: fnc_IBEN_base_ROOTer
// ===========================================================================
// @Info:
//  - Created by @iben for DayzEpoch 1.0.6.1+
//  - Version: 1.0, Last Update [2017-06-19]
//  - Credits:
//   * DayZ Epoch developers, collaborators and contributors
//     (thank you guys for your excellent work!)
//   * @Karel Moricky from Bohemia Interactive for his idea how to extract
//     mission root.
// @Remarks:
//  - This is basic version of IBEN_ROOTer, which means, it's able to find
//    first parent folder path related to file calling this function.
//    Output path is relative to mission folder.
//    For more options look for extended version: 'fnc_IBEN_ext_ROOTer'
// @Parameters:
//  - current file (use __FILE__ macro)                              | string
//  - zero based (true == "\", false == "" at the end of path)
//    zero based is optional parameter (default false)               | boolean
// @Prerequisities:
//  - none
// @Example:
//  - #Example01: File in 'mission\a\b\file.sqf'
//    * [__FILE__] call IBEN_fnc_base_ROOTer;
//      output: path: 'a\b'
//  - #Example02:File in 'mission\a\b\file.sqf'
//    * [__FILE__,true] call IBEN_fnc_base_ROOTer;
//      output: path (zero based): 'a\b\'
// @Returns:
//  - string
// ===========================================================================
// @Parameters Legend:
//  * _a = _fil
//  * _b = _cfg
//  * _c = _ext
//  * _d = _zeroBased
//  * _e = _filArrRev
//  * _f = _start1
//  * _g = _end1
//  * _j = _bs
//  * _k = _start2
//  * _l = _end2
//  * _r = _result
// ===========================================================================

// IBEN_fnc_base_ROOTer = {

  // #define __IDEBUG__

  private ["_a","_b","_c"];
  _a = toArray (_this select 0);
  _b = toArray (str missionConfigFile);
  _c = count (toArray "description.ext");

  private "_d";
  // _d = false;
  _d = [false,_this select 1] select ((count _this > 1));

  // Reverse _a array, shorten it for speed by cutting virtual path
  private ["_e","_f","_g"];
  _e = [];
  _f = ((count _b) - _c);
  _g = ((count _a) - 1);

  private "_i";
  for "_i" from _g to _f step -1 do {
    _e set [count _e, (toString [_a select _i])];
  };

  // Find first backlash character position from reversed arr (_e)
  private "_j";
  _j = _e find "\";
  // Manage zero based find by user decision
  _j = [_j + 1,_j] select (_d);

  // Exit script if backslash wasn't found (already in root)
  if (_j < 0) exitWith {
    diag_log format
    [
      "=== [DEBUG] 'IBEN_fnc_base_ROOTer' refused path export! You are loading file [[ %1 ]] from MPMissions root - you don't need to use this function."
      ,__FILE__
    ];
  };

  // While we know last backlash position (or first in reversed file array),
  // export string with clean first parent folder path (relative to MPMission folder)
  private ["_k","_l","_r"];
  _k = _j;
  _l = ((count _e) - 1);
  _r = "";

  private "_y";
  for "_y" from _l to _k step -1 do {
    _r = format ["%1%2",_r,(_e select _y)];
  };

  #ifdef __IDEBUG__
  diag_log format
  [
    "=== [DEBUG] Addon relative root: [[ %1 ]], 'IBEN_fnc_base_ROOTer' output typeName: [[ %2 ]]. [[ File: %3, line %4 ]]"
    ,_r
    ,(typename _r)
    ,__FILE__
    ,__LINE__
  ];
  #endif

  _r

// };

// === :: FUNCTIONS LIBRARY >> PATH MANIPULATION >> fnc_base_ROOTer.sqf :: END

===

That's it... Have Fun, stay cool!
Cheers...

===