en-GB/Elizium.Loopz-help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-ForeachFsItem</command:name> <command:verb>Invoke</command:verb> <command:noun>ForeachFsItem</command:noun> <maml:description> <maml:para>Allows a custom defined script-block or function to be invoked for all file system objects delivered through the pipeline.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>2 parameters sets are defined, one for invoking a named function (InvokeFunction) and the other (InvokeScriptBlock, the default) for invoking a script-block. An optional Summary script block can be specified which will be invoked at the end of the pipeline batch. The user should assemble the candidate items from the file system, be they files or directories typically using Get-ChildItem, or can be any other function that delivers file systems items via the PowerShell pipeline. For each item in the pipeline, Invoke-ForeachFsItem will invoke the script-block/function specified. Invoke-ForeachFsItem will deliver what ever is returned from the script-block/function, so the result of Invoke-ForeachFsItem can be piped to another command.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-ForeachFsItem</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Block</maml:name> <maml:Description> <maml:para>The script block to be invoked. The script block is invoked for each item in the pipeline that satisfy the Condition with the following positional parameters:</maml:para> <maml:para>* pipelineItem: the item from the pipeline</maml:para> <maml:para>* index: the 0 based index representing current pipeline item</maml:para> <maml:para>* PassThru: a hash table containing miscellaneous information gathered internally</maml:para> <maml:para>throughout the pipeline batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic. * trigger: a boolean value, useful for state changing idempotent operations. At the end of the batch, the state of the trigger indicates whether any of the items were actioned. When the script block is invoked, the trigger should indicate if the trigger was pulled for any of the items so far processed in the pipeline. This is the responsibility of the client's block implementation.</maml:para> <maml:para>In addition to these fixed positional parameters, if the invoked script-block is defined with additional parameters, then these will also be passed in. In order to achieve this, the client has to provide excess parameters in BlockParam and these parameters must be defined as the same type and in the same order as the additional parameters in the script-block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BlockParams</maml:name> <maml:Description> <maml:para>Optional array containing the excess parameters to pass into the script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Condition</maml:name> <maml:Description> <maml:para>This is a predicate script-block, which is invoked with either a DirectoryInfo or FileInfo object presented as a result of invoking Get-ChildItem. It provides a filtering mechanism that is defined by the user to define which file system objects are selected for function/script-block invocation.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Directory</maml:name> <maml:Description> <maml:para>Switch to indicate that the invoked function/script-block (invokee) is to handle Directory objects.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>File</maml:name> <maml:Description> <maml:para>Switch to indicate that the invoked function/script-block (invokee) is to handle FileInfo objects. Is mutually exclusive with the Directory switch. If neither switch is specified, then the invokee must be able to handle both therefore the Underscore parameter it defines must be declared as FileSystemInfo.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the start of the pipeline batch. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* PassThru: (see PassThru previously described)</maml:para> <maml:para> The Header can be customised with the following PassThru entries:</maml:para> <maml:para>* 'LOOPZ.KRAYOLA-THEME': Krayola Theme generally in use</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.MESSAGE': message displayed as part of the header</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.CRUMB': Lead text displayed in header, default: '[+] '</maml:para> <maml:para>* 'LOOPZ.HEADER.PROPERTIES': An array of Key/Value pairs of items to be displayed</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.LINE': A string denoting the line to be displayed. (There are</maml:para> <maml:para>predefined lines available to use in $LoopzUI, or a custom one can be used instead)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:Description> <maml:para>A hash table containing miscellaneous information gathered internally throughout the pipeline batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Summary</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the end of the pipeline batch. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* count: the number of items processed in the pipeline batch.</maml:para> <maml:para>* skipped: the number of items skipped in the pipeline batch. An item is skipped if</maml:para> <maml:para>it fails the defined condition or is not of the correct type (eg if its a directory but we have specified the -File flag). Also note that, if the script-block/function sets the Break flag causing further iteration to stop, then those subsequent items in the pipeline which have not been processed are not reflected in the skip count. * trigger: Flag set by the script-block/function, but should typically be used to indicate whether any of the items processed were actively updated/written in this batch. This helps in written idempotent operations that can be re-run without adverse consequences. * PassThru: (see PassThru previously described)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>pipelineItem</maml:name> <maml:Description> <maml:para>This is the pipeline object, so should not be specified explicitly and can represent a file object (System.IO.FileInfo) or a directory object (System.IO.DirectoryInfo).</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">FileSystemInfo</command:parameterValue> <dev:type> <maml:name>FileSystemInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Invoke-ForeachFsItem</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Condition</maml:name> <maml:Description> <maml:para>This is a predicate script-block, which is invoked with either a DirectoryInfo or FileInfo object presented as a result of invoking Get-ChildItem. It provides a filtering mechanism that is defined by the user to define which file system objects are selected for function/script-block invocation.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Directory</maml:name> <maml:Description> <maml:para>Switch to indicate that the invoked function/script-block (invokee) is to handle Directory objects.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>File</maml:name> <maml:Description> <maml:para>Switch to indicate that the invoked function/script-block (invokee) is to handle FileInfo objects. Is mutually exclusive with the Directory switch. If neither switch is specified, then the invokee must be able to handle both therefore the Underscore parameter it defines must be declared as FileSystemInfo.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Functee</maml:name> <maml:Description> <maml:para>String defining the function to be invoked. Works in a similar way to the Block parameter for script-blocks. The Function's base signature is as follows:</maml:para> <maml:para>* "Underscore": (See pipelineItem described in Block parameter)</maml:para> <maml:para>* "Index": (See index described in Block parameter)</maml:para> <maml:para>* "PassThru": (See PathThru described in Block parameter)</maml:para> <maml:para>* "Trigger": (See trigger described in Block parameter)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FuncteeParams</maml:name> <maml:Description> <maml:para>Optional hash-table containing the named parameters which are splatted into the Functee function invoke. As it's a hash table, order is not significant.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the start of the pipeline batch. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* PassThru: (see PassThru previously described)</maml:para> <maml:para> The Header can be customised with the following PassThru entries:</maml:para> <maml:para>* 'LOOPZ.KRAYOLA-THEME': Krayola Theme generally in use</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.MESSAGE': message displayed as part of the header</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.CRUMB': Lead text displayed in header, default: '[+] '</maml:para> <maml:para>* 'LOOPZ.HEADER.PROPERTIES': An array of Key/Value pairs of items to be displayed</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.LINE': A string denoting the line to be displayed. (There are</maml:para> <maml:para>predefined lines available to use in $LoopzUI, or a custom one can be used instead)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:Description> <maml:para>A hash table containing miscellaneous information gathered internally throughout the pipeline batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Summary</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the end of the pipeline batch. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* count: the number of items processed in the pipeline batch.</maml:para> <maml:para>* skipped: the number of items skipped in the pipeline batch. An item is skipped if</maml:para> <maml:para>it fails the defined condition or is not of the correct type (eg if its a directory but we have specified the -File flag). Also note that, if the script-block/function sets the Break flag causing further iteration to stop, then those subsequent items in the pipeline which have not been processed are not reflected in the skip count. * trigger: Flag set by the script-block/function, but should typically be used to indicate whether any of the items processed were actively updated/written in this batch. This helps in written idempotent operations that can be re-run without adverse consequences. * PassThru: (see PassThru previously described)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>pipelineItem</maml:name> <maml:Description> <maml:para>This is the pipeline object, so should not be specified explicitly and can represent a file object (System.IO.FileInfo) or a directory object (System.IO.DirectoryInfo).</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">FileSystemInfo</command:parameterValue> <dev:type> <maml:name>FileSystemInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Block</maml:name> <maml:Description> <maml:para>The script block to be invoked. The script block is invoked for each item in the pipeline that satisfy the Condition with the following positional parameters:</maml:para> <maml:para>* pipelineItem: the item from the pipeline</maml:para> <maml:para>* index: the 0 based index representing current pipeline item</maml:para> <maml:para>* PassThru: a hash table containing miscellaneous information gathered internally</maml:para> <maml:para>throughout the pipeline batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic. * trigger: a boolean value, useful for state changing idempotent operations. At the end of the batch, the state of the trigger indicates whether any of the items were actioned. When the script block is invoked, the trigger should indicate if the trigger was pulled for any of the items so far processed in the pipeline. This is the responsibility of the client's block implementation.</maml:para> <maml:para>In addition to these fixed positional parameters, if the invoked script-block is defined with additional parameters, then these will also be passed in. In order to achieve this, the client has to provide excess parameters in BlockParam and these parameters must be defined as the same type and in the same order as the additional parameters in the script-block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BlockParams</maml:name> <maml:Description> <maml:para>Optional array containing the excess parameters to pass into the script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Condition</maml:name> <maml:Description> <maml:para>This is a predicate script-block, which is invoked with either a DirectoryInfo or FileInfo object presented as a result of invoking Get-ChildItem. It provides a filtering mechanism that is defined by the user to define which file system objects are selected for function/script-block invocation.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Directory</maml:name> <maml:Description> <maml:para>Switch to indicate that the invoked function/script-block (invokee) is to handle Directory objects.</maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>File</maml:name> <maml:Description> <maml:para>Switch to indicate that the invoked function/script-block (invokee) is to handle FileInfo objects. Is mutually exclusive with the Directory switch. If neither switch is specified, then the invokee must be able to handle both therefore the Underscore parameter it defines must be declared as FileSystemInfo.</maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Functee</maml:name> <maml:Description> <maml:para>String defining the function to be invoked. Works in a similar way to the Block parameter for script-blocks. The Function's base signature is as follows:</maml:para> <maml:para>* "Underscore": (See pipelineItem described in Block parameter)</maml:para> <maml:para>* "Index": (See index described in Block parameter)</maml:para> <maml:para>* "PassThru": (See PathThru described in Block parameter)</maml:para> <maml:para>* "Trigger": (See trigger described in Block parameter)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FuncteeParams</maml:name> <maml:Description> <maml:para>Optional hash-table containing the named parameters which are splatted into the Functee function invoke. As it's a hash table, order is not significant.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the start of the pipeline batch. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* PassThru: (see PassThru previously described)</maml:para> <maml:para> The Header can be customised with the following PassThru entries:</maml:para> <maml:para>* 'LOOPZ.KRAYOLA-THEME': Krayola Theme generally in use</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.MESSAGE': message displayed as part of the header</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.CRUMB': Lead text displayed in header, default: '[+] '</maml:para> <maml:para>* 'LOOPZ.HEADER.PROPERTIES': An array of Key/Value pairs of items to be displayed</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.LINE': A string denoting the line to be displayed. (There are</maml:para> <maml:para>predefined lines available to use in $LoopzUI, or a custom one can be used instead)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:Description> <maml:para>A hash table containing miscellaneous information gathered internally throughout the pipeline batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Summary</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the end of the pipeline batch. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* count: the number of items processed in the pipeline batch.</maml:para> <maml:para>* skipped: the number of items skipped in the pipeline batch. An item is skipped if</maml:para> <maml:para>it fails the defined condition or is not of the correct type (eg if its a directory but we have specified the -File flag). Also note that, if the script-block/function sets the Break flag causing further iteration to stop, then those subsequent items in the pipeline which have not been processed are not reflected in the skip count. * trigger: Flag set by the script-block/function, but should typically be used to indicate whether any of the items processed were actively updated/written in this batch. This helps in written idempotent operations that can be re-run without adverse consequences. * PassThru: (see PassThru previously described)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>pipelineItem</maml:name> <maml:Description> <maml:para>This is the pipeline object, so should not be specified explicitly and can represent a file object (System.IO.FileInfo) or a directory object (System.IO.DirectoryInfo).</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">FileSystemInfo</command:parameterValue> <dev:type> <maml:name>FileSystemInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.IO.FileSystemInfo</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Object</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>[scriptblock]$block = { param( [System.IO.FileInfo]$FileInfo, [int]$Index, [System.Collections.Hashtable]$PassThru, [boolean]$Trigger ) ... } Get-ChildItem './Tests/Data/fefsi' -Recurse -Filter '*.txt' -File | ` Invoke-ForeachFsItem -File -Block $block;</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 2 --------------------------</maml:title> <dev:code>function invoke-Target { param( [System.IO.DirectoryInfo]$Underscore, [int]$Index, [System.Collections.Hashtable]$PassThru, [boolean]$Trigger, [string]$Format ) ... } [System.Collections.Hashtable]$parameters = @{ 'Format' } Get-ChildItem './Tests/Data/fefsi' -Recurse -Directory | ` Invoke-ForeachFsItem -Directory -Functee 'invoke-Target' -FuncteeParams $parameters</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 3 --------------------------</maml:title> <dev:code>[scriptblock]$block = { param( [System.IO.FileInfo]$FileInfo, [int]$Index, [System.Collections.Hashtable]$PassThru, [boolean]$Trigger ) ... } [scriptblock]$fileIsEmpty = { param( [System.IO.FileInfo]$FileInfo ) return (0 -eq $FileInfo.Length) } Get-ChildItem './Tests/Data/fefsi' -Recurse -Filter '*.txt' -File | Invoke-ForeachFsItem ` -Block $block -File -condition $fileIsEmpty;</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 4 --------------------------</maml:title> <dev:code>[scriptblock]$block = { param( [System.IO.FileInfo]$FileInfo, [int]$Index, [System.Collections.Hashtable]$PassThru, [boolean]$Trigger ) ... } [scriptblock]$filterDirectories = { [OutputType([boolean])] param( [System.IO.DirectoryInfo]$directoryInfo ) Select-FsItem -Name $directoryInfo.Name -Includes 'A*'; } Get-ChildItem './Tests/Data/fefsi' -Directory | Invoke-ForeachFsItem ` -Block $block -Directory -DirectoryIncludes $filterDirectories;</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-MirrorDirectoryTree</command:name> <command:verb>Invoke</command:verb> <command:noun>MirrorDirectoryTree</command:noun> <maml:description> <maml:para>Mirrors a directory tree to a new location, invoking a custom defined script-block or function as it goes.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Copies a source directory tree to a new location applying custom functionality for each directory. File and directory filters can be applied. 2 parameters set are defined, one for invoking a named function (InvokeFunction) and the other (InvokeScriptBlock, the default) for invoking a script-block. An optional Summary script block can be specified which will be invoked at the end of the mirroring batch.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-MirrorDirectoryTree</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Block</maml:name> <maml:Description> <maml:para>The script block to be invoked. The script block is invoked for each directory in the source directory tree that satisfy the specified Directory Include/Exclude filters with the following positional parameters:</maml:para> <maml:para>* underscore: the DirectoryInfo object representing the directory in the source tree</maml:para> <maml:para>* index: the 0 based index representing current directory in the source tree</maml:para> <maml:para>* PassThru object: a hash table containing miscellaneous information gathered internally</maml:para> <maml:para>throughout the mirroring batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic. * trigger: a boolean value, useful for state changing idempotent operations. At the end of the batch, the state of the trigger indicates whether any of the items were actioned. When the script block is invoked, the trigger should indicate if the trigger was pulled for any of the items so far processed in the batch. This is the responsibility of the client's script-block/function implementation. In addition to these fixed positional parameters, if the invoked script-block is defined with additional parameters, then these will also be passed in. In order to achieve this, the client has to provide excess parameters in BlockParams and these parameters must be defined as the same type and in the same order as the additional parameters in the script-block.</maml:para> <maml:para>The destination DirectoryInfo object can be accessed via the PassThru denoted by the 'LOOPZ.MIRROR.DESTINATION' entry.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BlockParams</maml:name> <maml:Description> <maml:para>Optional array containing the excess parameters to pass into the script-block/function.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:Description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CopyFiles</maml:name> <maml:Description> <maml:para>Switch parameter that indicates that files matching the specified filters should be copied</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CreateDirs</maml:name> <maml:Description> <maml:para>Switch parameter indicates that directories should be created in the destination tree. If not set, then Invoke-MirrorDirectoryTree turns into a function that traverses the source directory invoking the function/script-block for matching directories.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DestinationPath</maml:name> <maml:Description> <maml:para>The destination Path denoting the root of the directory tree where the source tree will be mirrored to.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DirectoryExcludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each must contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be ignored. If the directory matches any of the filters in the list, it will NOT be mirrored in the destination tree. Any match in the DirectoryExcludes overrides a match in DirectoryIncludes, so a directory that is matched in Include, can be excluded by the Exclude.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DirectoryIncludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each must contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be ignored. If the directory matches any of the filters in the list, it will be mirrored in the destination tree. If DirectoryIncludes contains just a single element which is the empty string, this means that nothing is included (rather than everything being included).</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FileExcludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each may contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be treated as a file suffix. If the file in the source tree matches any of the filters in the list, it will NOT be mirrored in the destination tree. Any match in the FileExcludes overrides a match in FileIncludes, so a file that is matched in Include, can be excluded by the Exclude.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FileIncludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each may contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be treated as a file suffix. If the file in the source tree matches any of the filters in the list, it will be mirrored in the destination tree. If FileIncludes contains just a single element which is the empty string, this means that nothing is included (rather than everything being included).</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:Description> <maml:para>A script-block that is invoked for each directory that also contains child directories. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* PassThru: (see PassThru previously described)</maml:para> <maml:para> The Header can be customised with the following PassThru entries:</maml:para> <maml:para>* 'LOOPZ.KRAYOLA-THEME': Krayola Theme generally in use</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.MESSAGE': message displayed as part of the header</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.CRUMB': Lead text displayed in header, default: '[+] '</maml:para> <maml:para>* 'LOOPZ.HEADER.PROPERTIES': An array of Key/Value pairs of items to be displayed</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.LINE': A string denoting the line to be displayed. (There are</maml:para> <maml:para>predefined lines available to use in $LoopzUI, or a custom one can be used instead)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Hoist</maml:name> <maml:Description> <maml:para>Switch parameter. Without Hoist being specified, the filters can prove to be too restrictive on matching against directories. If a directory does not match the filters then none of its descendants will be considered to be mirrored in the destination tree. When Hoist is specified then a descendant directory that does match the filters will be mirrored even though any of its ancestors may not match the filters.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:Description> <maml:para>A hash table containing miscellaneous information gathered internally throughout the pipeline batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Path</maml:name> <maml:Description> <maml:para>The source Path denoting the root of the directory tree to be mirrored.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Summary</maml:name> <maml:Description> <maml:para>A script-block that is invoked foreach directory that also contains child directories, after all its descendants have been processed and serves as a sub-total for the current directory. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* count: the number of items processed in the mirroring batch.</maml:para> <maml:para>* skipped: the number of items skipped in the mirroring batch. An item is skipped if</maml:para> <maml:para>it fails the defined condition or is not of the correct type (eg if its a directory but we have specified the -File flag). * trigger: Flag set by the script-block/function, but should typically be used to indicate whether any of the items processed were actively updated/written in this batch. This helps in written idempotent operations that can be re-run without adverse consequences. * PassThru: (see PassThru previously described)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:Description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionHeader</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the start of the mirroring batch. The script-block has the same signature as the Header script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionSummary</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the end of the mirroring batch. The script-block has the same signature as the Summary script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Invoke-MirrorDirectoryTree</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:Description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CopyFiles</maml:name> <maml:Description> <maml:para>Switch parameter that indicates that files matching the specified filters should be copied</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CreateDirs</maml:name> <maml:Description> <maml:para>Switch parameter indicates that directories should be created in the destination tree. If not set, then Invoke-MirrorDirectoryTree turns into a function that traverses the source directory invoking the function/script-block for matching directories.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DestinationPath</maml:name> <maml:Description> <maml:para>The destination Path denoting the root of the directory tree where the source tree will be mirrored to.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DirectoryExcludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each must contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be ignored. If the directory matches any of the filters in the list, it will NOT be mirrored in the destination tree. Any match in the DirectoryExcludes overrides a match in DirectoryIncludes, so a directory that is matched in Include, can be excluded by the Exclude.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DirectoryIncludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each must contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be ignored. If the directory matches any of the filters in the list, it will be mirrored in the destination tree. If DirectoryIncludes contains just a single element which is the empty string, this means that nothing is included (rather than everything being included).</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FileExcludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each may contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be treated as a file suffix. If the file in the source tree matches any of the filters in the list, it will NOT be mirrored in the destination tree. Any match in the FileExcludes overrides a match in FileIncludes, so a file that is matched in Include, can be excluded by the Exclude.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FileIncludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each may contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be treated as a file suffix. If the file in the source tree matches any of the filters in the list, it will be mirrored in the destination tree. If FileIncludes contains just a single element which is the empty string, this means that nothing is included (rather than everything being included).</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Functee</maml:name> <maml:Description> <maml:para>String defining the function to be invoked. Works in a similar way to the Block parameter for script-blocks. The Function's base signature is as follows:</maml:para> <maml:para>* "Underscore": (See underscore described in Block parameter)</maml:para> <maml:para>* "Index": (See index described in Block parameter)</maml:para> <maml:para>* "PassThru": (See PathThru described in Block parameter)</maml:para> <maml:para>* "Trigger": (See trigger described in Block parameter)</maml:para> <maml:para></maml:para> <maml:para>The destination DirectoryInfo object can be accessed via the PassThru denoted by the 'LOOPZ.MIRROR.DESTINATION' entry.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FuncteeParams</maml:name> <maml:Description> <maml:para>Optional hash-table containing the named parameters which are splatted into the Functee function invoke. As it's a hash table, order is not significant.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:Description> <maml:para>A script-block that is invoked for each directory that also contains child directories. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* PassThru: (see PassThru previously described)</maml:para> <maml:para> The Header can be customised with the following PassThru entries:</maml:para> <maml:para>* 'LOOPZ.KRAYOLA-THEME': Krayola Theme generally in use</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.MESSAGE': message displayed as part of the header</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.CRUMB': Lead text displayed in header, default: '[+] '</maml:para> <maml:para>* 'LOOPZ.HEADER.PROPERTIES': An array of Key/Value pairs of items to be displayed</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.LINE': A string denoting the line to be displayed. (There are</maml:para> <maml:para>predefined lines available to use in $LoopzUI, or a custom one can be used instead)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Hoist</maml:name> <maml:Description> <maml:para>Switch parameter. Without Hoist being specified, the filters can prove to be too restrictive on matching against directories. If a directory does not match the filters then none of its descendants will be considered to be mirrored in the destination tree. When Hoist is specified then a descendant directory that does match the filters will be mirrored even though any of its ancestors may not match the filters.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:Description> <maml:para>A hash table containing miscellaneous information gathered internally throughout the pipeline batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Path</maml:name> <maml:Description> <maml:para>The source Path denoting the root of the directory tree to be mirrored.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Summary</maml:name> <maml:Description> <maml:para>A script-block that is invoked foreach directory that also contains child directories, after all its descendants have been processed and serves as a sub-total for the current directory. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* count: the number of items processed in the mirroring batch.</maml:para> <maml:para>* skipped: the number of items skipped in the mirroring batch. An item is skipped if</maml:para> <maml:para>it fails the defined condition or is not of the correct type (eg if its a directory but we have specified the -File flag). * trigger: Flag set by the script-block/function, but should typically be used to indicate whether any of the items processed were actively updated/written in this batch. This helps in written idempotent operations that can be re-run without adverse consequences. * PassThru: (see PassThru previously described)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:Description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionHeader</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the start of the mirroring batch. The script-block has the same signature as the Header script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionSummary</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the end of the mirroring batch. The script-block has the same signature as the Summary script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Block</maml:name> <maml:Description> <maml:para>The script block to be invoked. The script block is invoked for each directory in the source directory tree that satisfy the specified Directory Include/Exclude filters with the following positional parameters:</maml:para> <maml:para>* underscore: the DirectoryInfo object representing the directory in the source tree</maml:para> <maml:para>* index: the 0 based index representing current directory in the source tree</maml:para> <maml:para>* PassThru object: a hash table containing miscellaneous information gathered internally</maml:para> <maml:para>throughout the mirroring batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic. * trigger: a boolean value, useful for state changing idempotent operations. At the end of the batch, the state of the trigger indicates whether any of the items were actioned. When the script block is invoked, the trigger should indicate if the trigger was pulled for any of the items so far processed in the batch. This is the responsibility of the client's script-block/function implementation. In addition to these fixed positional parameters, if the invoked script-block is defined with additional parameters, then these will also be passed in. In order to achieve this, the client has to provide excess parameters in BlockParams and these parameters must be defined as the same type and in the same order as the additional parameters in the script-block.</maml:para> <maml:para>The destination DirectoryInfo object can be accessed via the PassThru denoted by the 'LOOPZ.MIRROR.DESTINATION' entry.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BlockParams</maml:name> <maml:Description> <maml:para>Optional array containing the excess parameters to pass into the script-block/function.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:Description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CopyFiles</maml:name> <maml:Description> <maml:para>Switch parameter that indicates that files matching the specified filters should be copied</maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CreateDirs</maml:name> <maml:Description> <maml:para>Switch parameter indicates that directories should be created in the destination tree. If not set, then Invoke-MirrorDirectoryTree turns into a function that traverses the source directory invoking the function/script-block for matching directories.</maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DestinationPath</maml:name> <maml:Description> <maml:para>The destination Path denoting the root of the directory tree where the source tree will be mirrored to.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DirectoryExcludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each must contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be ignored. If the directory matches any of the filters in the list, it will NOT be mirrored in the destination tree. Any match in the DirectoryExcludes overrides a match in DirectoryIncludes, so a directory that is matched in Include, can be excluded by the Exclude.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DirectoryIncludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each must contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be ignored. If the directory matches any of the filters in the list, it will be mirrored in the destination tree. If DirectoryIncludes contains just a single element which is the empty string, this means that nothing is included (rather than everything being included).</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FileExcludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each may contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be treated as a file suffix. If the file in the source tree matches any of the filters in the list, it will NOT be mirrored in the destination tree. Any match in the FileExcludes overrides a match in FileIncludes, so a file that is matched in Include, can be excluded by the Exclude.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FileIncludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each may contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be treated as a file suffix. If the file in the source tree matches any of the filters in the list, it will be mirrored in the destination tree. If FileIncludes contains just a single element which is the empty string, this means that nothing is included (rather than everything being included).</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Functee</maml:name> <maml:Description> <maml:para>String defining the function to be invoked. Works in a similar way to the Block parameter for script-blocks. The Function's base signature is as follows:</maml:para> <maml:para>* "Underscore": (See underscore described in Block parameter)</maml:para> <maml:para>* "Index": (See index described in Block parameter)</maml:para> <maml:para>* "PassThru": (See PathThru described in Block parameter)</maml:para> <maml:para>* "Trigger": (See trigger described in Block parameter)</maml:para> <maml:para></maml:para> <maml:para>The destination DirectoryInfo object can be accessed via the PassThru denoted by the 'LOOPZ.MIRROR.DESTINATION' entry.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FuncteeParams</maml:name> <maml:Description> <maml:para>Optional hash-table containing the named parameters which are splatted into the Functee function invoke. As it's a hash table, order is not significant.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:Description> <maml:para>A script-block that is invoked for each directory that also contains child directories. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* PassThru: (see PassThru previously described)</maml:para> <maml:para> The Header can be customised with the following PassThru entries:</maml:para> <maml:para>* 'LOOPZ.KRAYOLA-THEME': Krayola Theme generally in use</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.MESSAGE': message displayed as part of the header</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.CRUMB': Lead text displayed in header, default: '[+] '</maml:para> <maml:para>* 'LOOPZ.HEADER.PROPERTIES': An array of Key/Value pairs of items to be displayed</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.LINE': A string denoting the line to be displayed. (There are</maml:para> <maml:para>predefined lines available to use in $LoopzUI, or a custom one can be used instead)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Hoist</maml:name> <maml:Description> <maml:para>Switch parameter. Without Hoist being specified, the filters can prove to be too restrictive on matching against directories. If a directory does not match the filters then none of its descendants will be considered to be mirrored in the destination tree. When Hoist is specified then a descendant directory that does match the filters will be mirrored even though any of its ancestors may not match the filters.</maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:Description> <maml:para>A hash table containing miscellaneous information gathered internally throughout the pipeline batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Path</maml:name> <maml:Description> <maml:para>The source Path denoting the root of the directory tree to be mirrored.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Summary</maml:name> <maml:Description> <maml:para>A script-block that is invoked foreach directory that also contains child directories, after all its descendants have been processed and serves as a sub-total for the current directory. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* count: the number of items processed in the mirroring batch.</maml:para> <maml:para>* skipped: the number of items skipped in the mirroring batch. An item is skipped if</maml:para> <maml:para>it fails the defined condition or is not of the correct type (eg if its a directory but we have specified the -File flag). * trigger: Flag set by the script-block/function, but should typically be used to indicate whether any of the items processed were actively updated/written in this batch. This helps in written idempotent operations that can be re-run without adverse consequences. * PassThru: (see PassThru previously described)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:Description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionHeader</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the start of the mirroring batch. The script-block has the same signature as the Header script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionSummary</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the end of the mirroring batch. The script-block has the same signature as the Summary script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Object</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>function Test-Mirror { param( [System.IO.DirectoryInfo]$Underscore, [int]$Index, [System.Collections.Hashtable]$PassThru, [boolean]$Trigger, [string]$Format ) ... } [System.Collections.Hashtable]$parameters = @{ 'Format' = '---- {0} ----'; } Invoke-MirrorDirectoryTree -Path './Tests/Data/fefsi' ` -DestinationPath './Tests/Data/mirror' -CreateDirs ` -Functee 'Test-Mirror' -FuncteeParams $parameters;</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 2 --------------------------</maml:title> <dev:code>Invoke-MirrorDirectoryTree -Path './Tests/Data/fefsi' ` -DestinationPath './Tests/Data/mirror' -CreateDirs -CopyFiles -block { param( [System.IO.DirectoryInfo]$Underscore, [int]$Index, [System.Collections.Hashtable]$PassThru, [boolean]$Trigger ) ... };</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 3 --------------------------</maml:title> <dev:code>Invoke-MirrorDirectoryTree -Path './Tests/Data/fefsi' -DestinationPath './Tests/Data/mirror' ` -DirectoryIncludes @('A*')</dev:code> <dev:remarks> <maml:para>Note the possible issue with this example is that any descendants named A... which are located under an ancestor which is not named A..., will not be mirrored;</maml:para> <maml:para>eg './Tests/Data/fefsi/Audio/mp3/A/Amorphous Androgynous', even though "Audio", "A" and "Amorphous Androgynous" clearly match the A* filter, they will not be mirrored because the "mp3" directory, would be filtered out. See the following example for a resolution.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 4 --------------------------</maml:title> <dev:code>Invoke-MirrorDirectoryTree -Path './Tests/Data/fefsi' -DestinationPath './Tests/Data/mirror' ` -DirectoryIncludes @('A*') -CreateDirs -CopyFiles -Hoist</dev:code> <dev:remarks> <maml:para>Note that the directory filter must include a wild-card, otherwise it will be ignored. So a directory include of @('A'), is problematic, because A is not a valid directory filter so its ignored and there are no remaining filters that are able to include any directory, so no directory passes the filter.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 5 --------------------------</maml:title> <dev:code>Invoke-MirrorDirectoryTree -Path './Tests/Data/fefsi' -DestinationPath './Tests/Data/mirror' ` -FileIncludes @('flac', '*.wav') -CreateDirs -CopyFiles -Hoist</dev:code> <dev:remarks> <maml:para>Note that for files, a filter may or may not contain a wild-card. If the wild-card is missing then it is automatically treated as a file suffix; so 'flac' means '*.flac'.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 6 --------------------------</maml:title> <dev:code>[scriptblock]$summary = { param( [int]$_count, [int]$_skipped, [boolean]$_triggered, [System.Collections.Hashtable]$_passThru ) ... } Invoke-MirrorDirectoryTree -Path './Tests/Data/fefsi' -DestinationPath './Tests/Data/mirror' ` -FileIncludes @('flac') -CopyFiles -Hoist -Summary $summary</dev:code> <dev:remarks> <maml:para>Note that -CreateDirs is missing which means directories will not be mirrored by default. They are only mirrored as part of the process of copying over flac files, so in the end the resultant mirror directory tree will contain directories that include flac files.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 7 --------------------------</maml:title> <dev:code></dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-TraverseDirectory</command:name> <command:verb>Invoke</command:verb> <command:noun>TraverseDirectory</command:noun> <maml:description> <maml:para>Traverses a directory tree invoking a custom defined script-block or named function as it goes.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Navigates a directory tree applying custom functionality for each directory. A Condition script-block can be applied for conditional functionality. 2 parameters set are defined, one for invoking a named function (InvokeFunction) and the other (InvokeScriptBlock, the default) for invoking a script-block. An optional Summary script block can be specified which will be invoked at the end of the traversal batch.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-TraverseDirectory</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Block</maml:name> <maml:Description> <maml:para>The script block to be invoked. The script block is invoked for each directory in the source directory tree that satisfy the specified Condition predicate with the following positional parameters:</maml:para> <maml:para>* underscore: the DirectoryInfo object representing the directory in the source tree</maml:para> <maml:para>* index: the 0 based index representing current directory in the source tree</maml:para> <maml:para>* PassThru object: a hash table containing miscellaneous information gathered internally</maml:para> <maml:para>throughout the mirroring batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic. * trigger: a boolean value, useful for state changing idempotent operations. At the end of the batch, the state of the trigger indicates whether any of the items were actioned. When the script block is invoked, the trigger should indicate if the trigger was pulled for any of the items so far processed in the batch. This is the responsibility of the client's script-block/function implementation.</maml:para> <maml:para>In addition to these fixed positional parameters, if the invoked script-block is defined with additional parameters, then these will also be passed in. In order to achieve this, the client has to provide excess parameters in BlockParams and these parameters must be defined as the same type and in the same order as the additional parameters in the script-block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BlockParams</maml:name> <maml:Description> <maml:para>Optional array containing the excess parameters to pass into the script-block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Condition</maml:name> <maml:Description> <maml:para>This is a predicate scriptblock, which is invoked with a DirectoryInfo object presented as a result of invoking Get-ChildItem. It provides a filtering mechanism that is defined by the user to define which directories are selected for function/scriptblock invocation.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:Description> <maml:para>A script-block that is invoked for each directory that also contains child directories. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* PassThru: (see PassThru previously described)</maml:para> <maml:para> The Header can be customised with the following PassThru entries:</maml:para> <maml:para>* 'LOOPZ.KRAYOLA-THEME': Krayola Theme generally in use</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.MESSAGE': message displayed as part of the header</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.CRUMB': Lead text displayed in header, default: '[+] '</maml:para> <maml:para>* 'LOOPZ.HEADER.PROPERTIES': An array of Key/Value pairs of items to be displayed</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.LINE': A string denoting the line to be displayed. (There are</maml:para> <maml:para>predefined lines available to use in $LoopzUI, or a custom one can be used instead)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Hoist</maml:name> <maml:Description> <maml:para>Switch parameter. Without Hoist being specified, the Condition can prove to be too restrictive on matching against directories. If a directory does not match the Condition then none of its descendants will be considered to be traversed. When Hoist is specified then a descendant directory that does match the Condition will be traversed even though any of its ancestors may not match the same Condition.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:Description> <maml:para>A hash table containing miscellaneous information gathered internally throughout the traversal batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Path</maml:name> <maml:Description> <maml:para>The source Path denoting the root of the directory tree to be traversed.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Summary</maml:name> <maml:Description> <maml:para>A script-block that is invoked foreach directory that also contains child directories, after all its descendants have been processed and serves as a sub-total for the current directory. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* count: the number of items processed in the mirroring batch.</maml:para> <maml:para>* skipped: the number of items skipped in the mirroring batch. An item is skipped if</maml:para> <maml:para>it fails the defined condition or is not of the correct type (eg if its a directory but we have specified the -File flag). * trigger: Flag set by the script-block/function, but should typically be used to indicate whether any of the items processed were actively updated/written in this batch. This helps in written idempotent operations that can be re-run without adverse consequences. * PassThru: (see PassThru previously described)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionHeader</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the start of the traversal batch. The script-block has the same signature as the Header script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionSummary</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the start of the traversal batch. The script-block has the same signature as the Header script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Invoke-TraverseDirectory</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Condition</maml:name> <maml:Description> <maml:para>This is a predicate scriptblock, which is invoked with a DirectoryInfo object presented as a result of invoking Get-ChildItem. It provides a filtering mechanism that is defined by the user to define which directories are selected for function/scriptblock invocation.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Functee</maml:name> <maml:Description> <maml:para>String defining the function to be invoked. Works in a similar way to the Block parameter for script-blocks. The Function's base signature is as follows:</maml:para> <maml:para>* "Underscore": (See underscore described above)</maml:para> <maml:para>* "Index": (See index described above)</maml:para> <maml:para>* "PassThru": (See PathThru described above)</maml:para> <maml:para>* "Trigger": (See trigger described above)</maml:para> <maml:para></maml:para> <maml:para>The destination DirectoryInfo object can be accessed via the PassThru denoted by the 'LOOPZ.MIRROR.DESTINATION' entry.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FuncteeParams</maml:name> <maml:Description> <maml:para>Optional hash-table containing the named parameters which are splatted into the Functee function invoke. As it's a hash table, order is not significant.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:Description> <maml:para>A script-block that is invoked for each directory that also contains child directories. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* PassThru: (see PassThru previously described)</maml:para> <maml:para> The Header can be customised with the following PassThru entries:</maml:para> <maml:para>* 'LOOPZ.KRAYOLA-THEME': Krayola Theme generally in use</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.MESSAGE': message displayed as part of the header</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.CRUMB': Lead text displayed in header, default: '[+] '</maml:para> <maml:para>* 'LOOPZ.HEADER.PROPERTIES': An array of Key/Value pairs of items to be displayed</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.LINE': A string denoting the line to be displayed. (There are</maml:para> <maml:para>predefined lines available to use in $LoopzUI, or a custom one can be used instead)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Hoist</maml:name> <maml:Description> <maml:para>Switch parameter. Without Hoist being specified, the Condition can prove to be too restrictive on matching against directories. If a directory does not match the Condition then none of its descendants will be considered to be traversed. When Hoist is specified then a descendant directory that does match the Condition will be traversed even though any of its ancestors may not match the same Condition.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:Description> <maml:para>A hash table containing miscellaneous information gathered internally throughout the traversal batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Path</maml:name> <maml:Description> <maml:para>The source Path denoting the root of the directory tree to be traversed.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Summary</maml:name> <maml:Description> <maml:para>A script-block that is invoked foreach directory that also contains child directories, after all its descendants have been processed and serves as a sub-total for the current directory. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* count: the number of items processed in the mirroring batch.</maml:para> <maml:para>* skipped: the number of items skipped in the mirroring batch. An item is skipped if</maml:para> <maml:para>it fails the defined condition or is not of the correct type (eg if its a directory but we have specified the -File flag). * trigger: Flag set by the script-block/function, but should typically be used to indicate whether any of the items processed were actively updated/written in this batch. This helps in written idempotent operations that can be re-run without adverse consequences. * PassThru: (see PassThru previously described)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionHeader</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the start of the traversal batch. The script-block has the same signature as the Header script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionSummary</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the start of the traversal batch. The script-block has the same signature as the Header script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Block</maml:name> <maml:Description> <maml:para>The script block to be invoked. The script block is invoked for each directory in the source directory tree that satisfy the specified Condition predicate with the following positional parameters:</maml:para> <maml:para>* underscore: the DirectoryInfo object representing the directory in the source tree</maml:para> <maml:para>* index: the 0 based index representing current directory in the source tree</maml:para> <maml:para>* PassThru object: a hash table containing miscellaneous information gathered internally</maml:para> <maml:para>throughout the mirroring batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic. * trigger: a boolean value, useful for state changing idempotent operations. At the end of the batch, the state of the trigger indicates whether any of the items were actioned. When the script block is invoked, the trigger should indicate if the trigger was pulled for any of the items so far processed in the batch. This is the responsibility of the client's script-block/function implementation.</maml:para> <maml:para>In addition to these fixed positional parameters, if the invoked script-block is defined with additional parameters, then these will also be passed in. In order to achieve this, the client has to provide excess parameters in BlockParams and these parameters must be defined as the same type and in the same order as the additional parameters in the script-block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BlockParams</maml:name> <maml:Description> <maml:para>Optional array containing the excess parameters to pass into the script-block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Condition</maml:name> <maml:Description> <maml:para>This is a predicate scriptblock, which is invoked with a DirectoryInfo object presented as a result of invoking Get-ChildItem. It provides a filtering mechanism that is defined by the user to define which directories are selected for function/scriptblock invocation.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Functee</maml:name> <maml:Description> <maml:para>String defining the function to be invoked. Works in a similar way to the Block parameter for script-blocks. The Function's base signature is as follows:</maml:para> <maml:para>* "Underscore": (See underscore described above)</maml:para> <maml:para>* "Index": (See index described above)</maml:para> <maml:para>* "PassThru": (See PathThru described above)</maml:para> <maml:para>* "Trigger": (See trigger described above)</maml:para> <maml:para></maml:para> <maml:para>The destination DirectoryInfo object can be accessed via the PassThru denoted by the 'LOOPZ.MIRROR.DESTINATION' entry.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FuncteeParams</maml:name> <maml:Description> <maml:para>Optional hash-table containing the named parameters which are splatted into the Functee function invoke. As it's a hash table, order is not significant.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:Description> <maml:para>A script-block that is invoked for each directory that also contains child directories. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* PassThru: (see PassThru previously described)</maml:para> <maml:para> The Header can be customised with the following PassThru entries:</maml:para> <maml:para>* 'LOOPZ.KRAYOLA-THEME': Krayola Theme generally in use</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.MESSAGE': message displayed as part of the header</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.CRUMB': Lead text displayed in header, default: '[+] '</maml:para> <maml:para>* 'LOOPZ.HEADER.PROPERTIES': An array of Key/Value pairs of items to be displayed</maml:para> <maml:para>* 'LOOPZ.HEADER-BLOCK.LINE': A string denoting the line to be displayed. (There are</maml:para> <maml:para>predefined lines available to use in $LoopzUI, or a custom one can be used instead)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Hoist</maml:name> <maml:Description> <maml:para>Switch parameter. Without Hoist being specified, the Condition can prove to be too restrictive on matching against directories. If a directory does not match the Condition then none of its descendants will be considered to be traversed. When Hoist is specified then a descendant directory that does match the Condition will be traversed even though any of its ancestors may not match the same Condition.</maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:Description> <maml:para>A hash table containing miscellaneous information gathered internally throughout the traversal batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Path</maml:name> <maml:Description> <maml:para>The source Path denoting the root of the directory tree to be traversed.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Summary</maml:name> <maml:Description> <maml:para>A script-block that is invoked foreach directory that also contains child directories, after all its descendants have been processed and serves as a sub-total for the current directory. The script-block is invoked with the following positional parameters:</maml:para> <maml:para>* count: the number of items processed in the mirroring batch.</maml:para> <maml:para>* skipped: the number of items skipped in the mirroring batch. An item is skipped if</maml:para> <maml:para>it fails the defined condition or is not of the correct type (eg if its a directory but we have specified the -File flag). * trigger: Flag set by the script-block/function, but should typically be used to indicate whether any of the items processed were actively updated/written in this batch. This helps in written idempotent operations that can be re-run without adverse consequences. * PassThru: (see PassThru previously described)</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionHeader</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the start of the traversal batch. The script-block has the same signature as the Header script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionSummary</maml:name> <maml:Description> <maml:para>A script-block that is invoked at the start of the traversal batch. The script-block has the same signature as the Header script block.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Object</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>[scriptblock]$block = { param( $underscore, [int]$index, [System.Collections.Hashtable]$passThru, [boolean]$trigger ) ... } Invoke-TraverseDirectory -Path './Tests/Data/fefsi' -Block $block</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 2 --------------------------</maml:title> <dev:code>function Test-Traverse { param( [System.IO.DirectoryInfo]$Underscore, [int]$Index, [System.Collections.Hashtable]$PassThru, [boolean]$Trigger, [string]$Format ) ... } [System.Collections.Hashtable]$parameters = @{ 'Format' = "=== {0} ==="; } Invoke-TraverseDirectory -Path './Tests/Data/fefsi' ` -Functee 'Test-Traverse' -FuncteeParams $parameters;</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 3 --------------------------</maml:title> <dev:code>function Test-Traverse { param( [System.IO.DirectoryInfo]$Underscore, [int]$Index, [System.Collections.Hashtable]$PassThru, [boolean]$Trigger ) ... } [scriptblock]$filterDirectories = { [OutputType([boolean])] param( [System.IO.DirectoryInfo]$directoryInfo ) Select-FsItem -Name $directoryInfo.Name -Includes @('A*'); } Invoke-TraverseDirectory -Path './Tests/Data/fefsi' -Functee 'Test-Traverse' ` -Condition $filterDirectories;</dev:code> <dev:remarks> <maml:para>Note the possible issue with this example is that any descendants named A... which are located under an ancestor which is not named A..., will not be processed by the provided function</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 4 --------------------------</maml:title> <dev:code>function Test-Traverse { param( [System.IO.DirectoryInfo]$Underscore, [int]$Index, [System.Collections.Hashtable]$PassThru, [boolean]$Trigger ) ... } [scriptblock]$filterDirectories = { [OutputType([boolean])] param( [System.IO.DirectoryInfo]$directoryInfo ) Select-FsItem -Name $directoryInfo.Name -Includes @('A*'); } Invoke-TraverseDirectory -Path './Tests/Data/fefsi' -Functee 'Test-Traverse' ` -Condition $filterDirectories -Hoist;</dev:code> <dev:remarks> <maml:para>Note that the directory filter must include a wild-card, otherwise it will be ignored. So a directory include of @('A'), is problematic, because A is not a valid directory filter so its ignored and there are no remaining filters that are able to include any directory, so no directory passes the filter.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- Example 5 --------------------------</maml:title> <dev:code></dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Select-FsItem</command:name> <command:verb>Select</command:verb> <command:noun>FsItem</command:noun> <maml:description> <maml:para>A predicate function that indicates whether an item identified by the Name matches the include/exclude filters specified.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Use this utility function to help specify a Condition for Invoke-TraverseDirectory. This function is partly required because the Include/Exclude parameters on functions such as Get-ChildItems/Copy-Item/Get-Item etc only work on files not directories.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Select-FsItem</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>Name</maml:name> <maml:Description> <maml:para>A string to be matched against the filters.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Includes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each must contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be ignored. If Name matches any of the filters in Includes, and are not Excluded, the result will be true.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Excludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each must contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be ignored. If the Name matches any of the filters in the list, will cause the end result to be false. Any match in the Excludes overrides a match in Includes, so an item that is matched in Include, can be excluded by the Exclude.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Case</maml:name> <maml:Description> <maml:para>Switch parameter which controls case sensitivity of inclusion/exclusion. By default filtering is case insensitive. When The Case switch is specified, filtering is case sensitive.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Case</maml:name> <maml:Description> <maml:para>Switch parameter which controls case sensitivity of inclusion/exclusion. By default filtering is case insensitive. When The Case switch is specified, filtering is case sensitive.</maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Excludes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each must contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be ignored. If the Name matches any of the filters in the list, will cause the end result to be false. Any match in the Excludes overrides a match in Includes, so an item that is matched in Include, can be excluded by the Exclude.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Includes</maml:name> <maml:Description> <maml:para>An array containing a list of filters, each must contain a wild-card ('*'). If a particular filter does not contain a wild-card, then it will be ignored. If Name matches any of the filters in Includes, and are not Excluded, the result will be true.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>Name</maml:name> <maml:Description> <maml:para>A string to be matched against the filters.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Boolean</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>[scriptblock]$filterDirectories = { [OutputType([boolean])] param( [System.IO.DirectoryInfo]$directoryInfo ) [string[]]$directoryIncludes = @('A*'); [string[]]$directoryExcludes = @('*_*', '*-*'); Select-FsItem -Name $directoryInfo.Name ` -Includes $directoryIncludes -Excludes $directoryExcludes; Invoke-TraverseDirectory -Path <path> -Block <block> -Condition $filterDirectories; }</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Write-HostFeItemDecorator</command:name> <command:verb>Write</command:verb> <command:noun>HostFeItemDecorator</command:noun> <maml:description> <maml:para>Wraps a function or script-block as a decorator writing appropriate user interface info to the host for each entry in the pipeline.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The script-block/function (invokee) being decorated may or may not Support ShouldProcess. If it does, then the client should add 'WHAT-IF' to the pass through, set to the current value of WhatIf; or more accurately the existence of 'WhatIf' in PSBoundParameters. Or another way of putting it is, the presence of WHAT-IF indicates SupportsShouldProcess, and the value of 'WHAT-IF' dictates the value of WhatIf. This way, we only need a single value in the PassThru, rather than having to represent SupportShouldProcess explicitly with another value.</maml:para> <maml:para> The PastThru must contain either a 'LOOPZ.WH-FOREACH-DECORATOR.FUNCTION-NAME' entry meaning a named function is being decorated or 'LOOPZ.WH-FOREACH-DECORATOR.BLOCK' meaning a script block is being decorated, but not both.</maml:para> <maml:para> By default, Write-HostFeItemDecorator will display an item no for each object in the pipeline and a property representing the Product. The Product is a property that the invokee can set on the PSCustomObject it returns. However, additional properties can be displayed. This can be achieved by the invokee populating another property Pairs, which is an array of string based key/value pairs. All properties found in Pairs will be written out by Write-HostFeItemDecorator.</maml:para> <maml:para>By default, to render the value displayed (ie the 'Product' property item on the PSCustomObject returned by the invokee), ToString() is called. However, the 'Product' property may not have a ToString() method, in this case (you will see an error indicating ToString method not being available), the user should provide a custom script-block to determine how the value is constructed. This can be done by assigning a custom script-block to the 'LOOPZ.WH-FOREACH-DECORATOR.GET-RESULT' entry in PassThru.</maml:para> <maml:para> This function is designed to be used with Invoke-ForeachFsItem and as such, it's signature needs to match that required by Invoke-ForeachFsItem. Any additional parameters can be passed in via the PassThru (create a new namespaced key eg 'YOUR-MODULE-NAME.CMD-NAME.PARAMS' assigned to the extra parameters collection, and then in the function/script-block, read the extra parameters from the same key you assign).</maml:para> <maml:para> The rationale behind Write-HostFeItemDecorator is to maintain separation of concerns that allows development of functions that could be used with Invoke-ForeachFsItem which do not contain any UI related code. This strategy also helps for the development of different commands that produce output to the terminal in a consistent manner.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Write-HostFeItemDecorator</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>Underscore</maml:name> <maml:Description> <maml:para>The current pipeline object.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Index</maml:name> <maml:Description> <maml:para>The 0 based index representing current item in the pipeline.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>PassThru</maml:name> <maml:Description> <maml:para>A hash table containing miscellaneous information gathered internally throughout the iteration batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Trigger</maml:name> <maml:Description> <maml:para>A boolean value, useful for state changing idempotent operations. At the end of the batch, the state of the trigger indicates whether any of the items were actioned. When the script block is invoked, the trigger should indicate if the trigger was pulled for any of the items so far processed in the batch. This is the responsibility of the client's script-block/function implementation.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue> <dev:type> <maml:name>Boolean</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Index</maml:name> <maml:Description> <maml:para>The 0 based index representing current item in the pipeline.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>PassThru</maml:name> <maml:Description> <maml:para>A hash table containing miscellaneous information gathered internally throughout the iteration batch. This can be of use to the user, because it is the way the user can perform bi-directional communication between the invoked custom script block and client side logic.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Trigger</maml:name> <maml:Description> <maml:para>A boolean value, useful for state changing idempotent operations. At the end of the batch, the state of the trigger indicates whether any of the items were actioned. When the script block is invoked, the trigger should indicate if the trigger was pulled for any of the items so far processed in the batch. This is the responsibility of the client's script-block/function implementation.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue> <dev:type> <maml:name>Boolean</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>Underscore</maml:name> <maml:Description> <maml:para>The current pipeline object.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>function Test-FN { param( [System.IO.DirectoryInfo]$Underscore, [int]$Index, [System.Collections.Hashtable]$PassThru, [boolean]$Trigger, ) $format = $PassThru['CLIENT.FORMAT']; @{ Product = $format -f $Underscore.Name, $Underscore.Exists } ... } [Systems.Collection.Hashtable]$passThru = @{ 'LOOPZ.WH-FOREACH-DECORATOR.FUNCTION-NAME' = 'Test-FN'; 'CLIENT.FORMAT' = '=== [{0}] -- [{1}] ===' } Get-ChildItem ... | Invoke-ForeachFsItem -Path <path> -PassThru $passThru -Functee 'Write-HostFeItemDecorator'</dev:code> <dev:remarks> <maml:para>So, Test-FN is not concerned about writing any output to the console, it simply does what it does silently and Write-HostFeItemDecorator handles generation of output. It invokes the function defined in 'LOOPZ.WH-FOREACH-DECORATOR.FUNCTION-NAME' and generates corresponding output. It happens to use the console colouring facility provided by a dependency Elizium.Krayola to create colourful output in a predefined format via the Krayola Theme.</maml:para> <maml:para>Note, Write-HostFeItemDecorator does not forward additional parameters to the decorated function (Test-FN), but this can be circumvented via the PassThru as illustrated by the 'CLIENT.FORMAT' parameter in this example.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> </helpItems> |