Packets

The most core part of mbpm's functionality is in the vectorisation of commands over packets. Almost all commands work over multiple packets at the same time. This page describes the syntax and semantics of the "PacketSpecification" part of the command line of most packets.

1 The pipeline

A packet specification consist of a couple of distinct steps, with the input from the previous step being the input for the next. A step in the pipeline is skipped if no option in the command changes it's default behaviour, which is always to leave the current packet list unchanged.

Note: Any fatal error occuring during this process is guaranteed to terminate the process. If the process is terminated this way so is the command also guaranteed not to have executed on any packets.

Note: Trying to add a packet to the list that doesn't exist is always treated as a fatal error, except for remote packets. These packets are instead verfied to exist during the execution of the command. It is up to the command to determine the course of action if a remote packet doesn't exist. How a packet is determined to exist given a location and packet name is described here.

1.1 Simple packet specification

The first step of a packet specification. This step always identifies individual packtes, which are further processed.

Every packet specification has a list of "arguments", which is every part of the command line that isn't identifying the top command or sub command, and which is not a part of a flag or single argument option. These strings are interpreted as packet names, or packet URI's for local packets.

The location type of these packet names are determined by the default location type for the given command, but is usually interpreted as a installed packet.

Note: A argument begining with . or containing / is always interpeted as the URI for a local packet, as these would otherwise form an invalid packet name.

The default packet location of a command can always be overriden with the following flags:

1.2 Default location flags

1.2.1 local

Interpretes all arguments as directory name identifying a local packet.

1.2.2 installed

Interpretes all arguments as the packet name of a installed packet.

1.2.3 user

Interpretes all arguments as the packet name of a user packet.

1.2.4 remote

Interpretes all arguments as the packet name of a remote packet.

Note: Multiple default location flags being present in a command line is treated as fatal error.

1.3 Direct packet specification

The following single argument options directly adds a packet to the result list without relying on the default packet type.

1.3.1 r

Interpates the argument as the name of a remote packet.

1.3.2 i

Interpates the argument as the name of a installed packet.

1.3.3 u

Interpates the argument as the name of a user packet.

1.3.4 l

Interpates the argument as the directory of a local packet.

Note: The order of which packets are processed by the command may be relevant, and the order of packets specified through the argument list are guaranteed to be added to the packet list in the same order, but packets specified through direct packet specification are always added after the packets specified through the argument list, and with unspecified order.

1.4 Examples

# Specifies that MBUtility and MBParsing should be compiled and because compile
# has as default location type as installed so are the installed packets checked
# for packets named MBUtility and MBParsing
mbpm compile MBUtility MBParsing

# This can be overriden by specifying a default location flag, the following
# command therefore searches for the user packets named MBUtility and MBParsing
mbpm compile MBUtility MBParsing --user

# Specifying a packet with a direct packet specification makes it so that the
# deafult location is ignored, therefor MBCLI is in the following commands
# always interpreted as being the name of a user packet
mbpm compile MBUtility MBParsing -u:MBCLI
mbpm compile MBUtility MBParsing --remote -u:MBCLI

1.5 Total packets specification

This part of the pipeline only adds packets to the process and doesn't modify or remove any packets, and consists of two flags:

1.5.1 allinstalled

Adds all installed packets to the packet list.

The packets added here are guaranteed to be added in dependancy order.

1.5.2 alluser

Adds all user packets to the packet list. The order of how these packets are added to the list is unspecified.

1.5.3 Examples

1.6 Packet modifiers

This part of the pipeline takes the current packet list and creates a new packet list. It currently consists of 2 flags, dependants, and dependancies.

1.6.1 dependancies / dependanciesi

If this flag is specified, the packet list is replaced with a list of packets that contains all of the packets that are a dependancy of any packet in the original list. The new packet list is guaranteed to have no duplicate packages, and is also guaranteed to be in dependancy order.

Dependancies for the packet list are always checked against the installed packets, which means that all of the new packets are always installed packets.

The difference between dependancies and dependanciesi is that dependanciesi is inclusive, that is it also includes the original packets in the newly generated list on the correct dependancy order, and as an installed packet.

1.6.2 dependants / dependantsi

If this flag is specified, the packet list is replaced with a list of packet that contains all of the dependants of every packet in the original list. The new packet list is guaranteed to have no duplicate packages, and is also guaranteed to be in dependancy order.

Dependants for the packet list are always checked against the installed packets, which means that all of the new packets installed packets.

The difference between dependants and dependantsi is that dependantsi is inclusive, that is it also includes the original packets in the newly generated list on the correct dependancy order, and as an installed packet.

1.6.3 Design note

These functions always returning the result based on the installed packet is because all packets on a system is assumed to depend on only the installed packets. While a user packet might be a modified version of a installed packet that is being developed, so is the user packet still assumed to only depend on other installed packets.

1.6.4 Examples

1.7 Packet filters

This part of the pipeline only removes packets from the packet list, based on a predicate. This part of the pipeline consists of 2 single argument options:

1.7.1 a

This filter removes all packets that doesnt't have the packet attribute specified in the argument.

1.7.2 na

This filter removes all packets that has the packet attribute specified in it's argument.

The relative order of the packets remaining are preserved after all of the filters are applied.

1.7.3 Examples

1.8 Location modifers

Location modifies keep all of the packets in the current packet list, but modifies them to refer to a different location. For each packet, the new packet is determined by finding the packet with the same name as the current packet, but in the new location. This part of the pipeline currently consists of one single argument option.

1.8.1 m

The argument can only be "installed" or "user", all other values are treated as a fatal error.

All packets are modified to point to the packet of the same name in the new location.

1.8.2 Design note

This part mostly exists in order to compensate for the fact that "--allinstalled" and "--alldependants" only returns the installed packets. Often times the user packets might want to be specified, especially in conjunction with the create top command.

2 Result

The result of a packet specification is always a list of packets to be processed by the given command. The command is guaranteed to process the packets in the order of the resulting packet list.