Skip to content

Commit

Permalink
ATK: refactor matrix reading/writing code, update docs
Browse files Browse the repository at this point in the history 
As it says on the tin.
  • Loading branch information
@joslloand
joslloand committed Sep 8, 2016
1 parent b7c463b commit d8d5cbe
Show file tree
Hide file tree
Showing 4 changed files with 202 additions and 53 deletions.
53 changes: 31 additions & 22 deletions source/ATK/sc/Classes/ATK.sc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,10 @@ Atk {
File.mkdir(Atk.userSupportDir);
}

*createSystemSupportDir {
File.mkdir(Atk.systemSupportDir);
}

*openSystemSupportDir {
File.exists(Atk.systemSupportDir).if({
Atk.systemSupportDir.openOS;
Expand Down Expand Up @@ -196,13 +200,13 @@ Atk {
};
}

// which: 'matrices', 'kernels'
*getAtkLibSubPath { arg which, isExtension=false;
// op: 'matrices', 'kernels'
*getAtkOpPath { arg op, isExtension=false;
var str, subPath, kindPath, fullPath, tested;

tested = List();

str = switch (which.asSymbol,
str = switch (op.asSymbol,
'matrices', {"/matrices"},
'kernels', {"/kernels"},
// include singular
Expand Down Expand Up @@ -241,15 +245,15 @@ Atk {
^subPath
}

// set: 'FOA', "HOA1", "HOA2", etc
// type: 'decoders', 'encoders', 'xformers'
// set: 'FOA', 'HOA1', 'HOA2', etc
// type: 'decoder(s)', 'encoder(s)', 'xformer(s)'
// op: 'matrices', 'kernels'
*getExtensionPath { arg set, type, op;
*getExtensionSubPath { arg set, type, op;
var subPath, typePath, fullPath;

Atk.checkSet(set);

subPath = Atk.getAtkLibSubPath(op, isExtension:true);
subPath = Atk.getAtkOpPath(op, isExtension:true);

typePath = PathName.new(
set.asString.toUpper ++ "/" ++ // folder structure is uppercase
Expand All @@ -269,15 +273,15 @@ Atk {
^fullPath
}

// set: 'FOA', "HOA1", "HOA2", etc
// set: 'FOA', 'HOA1', 'HOA2', etc
// type: 'decoder(s)', 'encoder(s)', 'xformer(s)'
// op: 'matrices', 'kernels'
*getBuiltInPath { arg set, type, op;
*getAtkOpSubPath { arg set, type, op;
var subPath, typePath, fullPath;

Atk.checkSet(set);

subPath = Atk.getAtkLibSubPath(op, isExtension:false);
subPath = Atk.getAtkOpPath(op, isExtension:false);

typePath = PathName.new(
set.asString.toUpper ++ "/" ++ // folder structure is uppercase
Expand All @@ -298,19 +302,24 @@ Atk {
}

// shortcuts for matrices and kernels, aka 'ops'
*getMatrixExtensionPath { arg set, type;
*getMatrixExtensionSubPath { arg set, type;
type ?? {Error("Unspecified matrix type. Please specify 'encoder', 'decoder', or 'xformer'.").errorString.postln; ^nil};
^Atk.getExtensionPath(set, type, 'matrices');
^Atk.getExtensionSubPath(set, type, 'matrices');
}

*getKernelExtensionPath { arg set, type;
*getKernelExtensionSubPath { arg set, type;
type ?? {Error("Unspecified kernel type. Please specify 'encoder', 'decoder', or 'xformer'.").errorString.postln; ^nil};
^Atk.getExtensionPath(set, type, 'kernels');
^Atk.getExtensionSubPath(set, type, 'kernels');
}

*getAtkMatrixSubPath { arg set, type;
type ?? {Error("Unspecified matrix type. Please specify 'encoder', 'decoder', or 'xformer'.").errorString.postln; ^nil};
^Atk.getAtkOpSubPath(set, type, 'matrices');
}

*getMatrixBuiltInPath { arg set, type;
*getAtkKernelSubPath { arg set, type;
type ?? {Error("Unspecified matrix type. Please specify 'encoder', 'decoder', or 'xformer'.").errorString.postln; ^nil};
^Atk.getBuiltInPath(set, type, 'matrices');
^Atk.getAtkOpSubPath(set, type, 'kernels');
}

*folderExists { |folderPathName, throwOnFail=true|
Expand Down Expand Up @@ -341,9 +350,9 @@ Atk {
hasRelPath = usrPN.colonIndices.size > 0;

mtxDirPath = if (searchExtensions) {
Atk.getMatrixExtensionPath('FOA', mtxType); // hard coded to 'FOA'..
Atk.getMatrixExtensionSubPath('FOA', mtxType); // hard coded to 'FOA'..
} {
Atk.getMatrixBuiltInPath('FOA', mtxType); // .. for now
Atk.getAtkMatrixSubPath('FOA', mtxType); // .. for now
};

relPath = mtxDirPath +/+ usrPN;
Expand Down Expand Up @@ -436,15 +445,15 @@ Atk {

// NOTE: could be generalized for other user extensions, e.g. kernels, etc.
// type: 'decoders', 'encoders', 'xformers'
*postMyMatrixDir { |set, type|
*postMyMatrices { |set, type|
var postContents;

block { |break|

if (set.isNil) {
// no set provided, show all sets
Atk.sets.do{ |thisSet|
Atk.postMyMatrixDir(thisSet, type)
Atk.postMyMatrices(thisSet, type)
};
break.()
} {
Expand Down Expand Up @@ -473,15 +482,15 @@ Atk {

postContents.(
type.isNil.if(
{ Atk.getAtkLibSubPath('matrices', isExtension:true) +/+ set.asString.toUpper },
{ Atk.getAtkOpPath('matrices', isExtension:true) +/+ set.asString.toUpper },
{
if (
[
'decoders', 'encoders', 'xformers',
'decoder', 'encoder', 'xformer' // include singular
].includes(type.asSymbol)
)
{ Atk.getMatrixExtensionPath(set, type) }
{ Atk.getMatrixExtensionSubPath(set, type) }
{ Error("'type' must be 'decoder', 'encoder', 'xformer', or nil (to see all matrix directories)").throw; };
}
);
Expand Down
4 changes: 2 additions & 2 deletions source/ATK/sc/Classes/ATKMatrix.sc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -306,12 +306,12 @@ AtkMatrix {
case
{ pn.colonIndices.size == 0} {
// only filename provided, write to dir matching 'type'
pn = Atk.getMatrixExtensionPath(argSet, argType) +/+ pn;
pn = Atk.getMatrixExtensionSubPath(argSet, argType) +/+ pn;

} { pn.colonIndices.size > 0} {
// relative path given, look for it
var mtxPath, relPath;
mtxPath = Atk.getMatrixExtensionPath(argSet, argType);
mtxPath = Atk.getMatrixExtensionSubPath(argSet, argType);
relPath = (mtxPath +/+ PathName(pn.parentPath));
if (relPath.isFolder) {
// valid relative path confirmed
Expand Down
133 changes: 126 additions & 7 deletions source/ATK/sc/HelpSource/Classes/Atk.schelp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,25 @@ The Atk class defines variables that may be used by the rest of the ATK library,

CLASSMETHODS::

METHOD:: sets

returns:: an Array listing valid ATK sets. (Currently only code::'FOA':: is
supported, code::'HOAn':: is in development!)

SUBSECTION:: ATK's default asset directories

NOTE:: The following methods have both strong::user:: and
strong::system:: versions. Which version you should use will depend on whether
you have the ATK assets installed at the user level:
code::
Platform.userAppSupportDir
::
or the system level:
code::
Platform.systemAppSupportDir
::
::

METHOD:: userSupportDir
set the user support dir where ATK resources are located

Expand All @@ -24,10 +43,21 @@ METHOD:: userSoundsDir

returns:: a path to the 'sounds' dir inside the ATK support dir

METHOD:: userMatrixDir

returns:: a path to the 'matrices' dir inside the ATK support dir

METHOD:: userKernelDir

returns:: a path to the 'kernel' dir inside the ATK support dir

METHOD:: openUserSupportDir
runs a link::Classes/String#-unixCmd:: to open the userAppSupport dir. Uses
'open' (OS X only)

METHOD:: createUserSupportDir
runs a unix command to create the user support dir for ATK

METHOD:: systemSupportDir

returns::the path to the ATK support dir. Defaults to:
Expand All @@ -37,17 +67,106 @@ METHOD:: systemSoundsDir

returns:: a path to the 'sounds' dir inside the ATK system support dir

METHOD:: systemMatrixDir

returns:: a path to the 'matrices' dir inside the ATK system support dir

METHOD:: systemKernelDir

returns:: a path to the 'kernel' dir inside the ATK system support dir

METHOD:: openUserSupportDir
runs a unixCmd to open the userAppSupport dir. Uses 'open' (OS X only)
METHOD:: openSystemSupportDir
runs a link::Classes/String#-unixCmd:: to open the systemAppSupport dir. Uses
'open' (OS X only)

METHOD:: createSystemSupportDir
runs a unix command to create the system support dir for ATK


SUBSECTION:: User asset /extensions directory

The code::extensions:: directory is where the ATK looks for assets generated or
added by you, such as your own matrices or kernels. It is located in
code::
Atk.userExtensionsDir
::
or if the ATK assets are installed system-wide, in:
code::
Atk.systemExtensionsDir
::
It is strong::not installed by default::. It can be
created by running
code::
Atk.createExtensionsDir
::
You can find out more about the directory structure in the
link::Guides/Guide-to-ATK-Matrix-Files::.

METHOD:: userExtensionsDir

returns:: a path to the 'extensions' dir inside the ATK support dir. This is where
user-generated matrices and kernels are stored to and rerieved from by default.

METHOD:: systemExtensionsDir

returns:: a path to the 'extensions' dir inside the ATK support dir. This is where
user-generated matrices and kernels are stored to and rerieved from by default.

METHOD:: postMyMatrices
Displays a formatted list the matrices stored in your
code::ATK/extensions/matrices:: directory. The strong::set:: and
strong::type:: arguments are optional filters to display only matrices of a the
specified strong::set:: and strong::type::.
NOTE:: This method first searches the code::Atk.userExtensionsDir:: and if no
directory is found, it proceeds to check for a system-wide installation in
code::Atk.systemExtensionsDir::.
::

METHOD:: createExtensionsDir
Creates the code::extensions:: folder, along with numerous subdirectories in a
pre-defined structure, in your ATK assets folder. This is where the ATK looks
for assets generated or added by you, such as your own matrices or kernels.
You can find out more about the directory structure and its use in the
link::Guides/Guide-to-ATK-Matrix-Files::.


SUBSECTION:: Convenience methods for accessing subdirectories

The following methods are used by ATK internally but listed here in the case
you find them useful.

METHOD:: getAtkOpPath
Get the Link::Classes/PathName:: of the strong::op:: directory (code::'kernels':: or
code::'matrices'::), in either the "built-in" ATK support directory or
the user code::extension:: subdirectory (strong::isExtension:: = true).

METHOD:: getAtkOpSubPath

Get the Link::Classes/PathName:: of the subdirectory within the
code::ATK/'op'/'set'/'type':: folder.
NOTE:: This method first searches the code::Atk.userExtensionsDir:: and if no
directory is found, it proceeds to check the code::Atk.systemExtensionsDir::.
::

METHOD:: getAtkMatrixSubPath
A shortcut for code::Atk.getAtkOpSubPath(set, op, 'matrices')::

METHOD:: getAtkKernelSubPath
A shortcut for code::Atk.getAtkOpSubPath(set, op, 'kernels')::

METHOD:: getExtensionSubPath
Get the Link::Classes/PathName:: of the subdirectory within the
code::ATK/extensions/'op'/'set'/'type':: folder.
NOTE:: This method first searches the code::Atk.userExtensionsDir:: and if no
directory is found, it proceeds to check the code::Atk.systemExtensionsDir::.
::

METHOD:: getMatrixExtensionSubPath
A shortcut for code::Atk.getExtensionSubPath(set, op, 'matrices')::

METHOD:: getKernelExtensionSubPath
A shortcut for code::Atk.getExtensionSubPath(set, op, 'kernels')::

METHOD:: createUserSupportDir
runs a unix cmd to create the user support dir for ATK

METHOD:: openSystemSupportDir
runs a unixCmd to open the systemAppSupport dir. Uses 'open' (OS X only)

PRIVATE:: checkSet, sets, getAtkLibSubPath, getExtensionPath, getKernelExtensionPath, getBuiltInPath, getMatrixBuiltInPath, systemExtensionsDir, systemMatrixDir, userMatrixDir, resolveMtxPath, folderExists
PRIVATE:: checkSet, sets, getAtkLibSubPath, getKernelExtensionPath, getBuiltInPath, getMatrixBuiltInPath, resolveMtxPath, folderExists
Loading

0 comments on commit d8d5cbe

Please sign in to comment.