HFS: scripting commands
Also known as template macros, these are commands with some useful effects, that users can input in HFS to improve a template or to create functionality not otherwise available.
Every command is expressed as a name, and sometimes parameters, separated by pipes "|".
Following, with letters we are denoting parameters, and their meaning is explained immediately after.
Logic and flow
- if | A | B | C
- if A is true, then it expands to B, else it expands to C. When it expands to B, C is just discarded, and the vice versa. C is optional.
- How you tell A is true? A is true if it is not empty and not just a zero. So if A is "hi there!", then it is true.
- Remember to use quoting if you use macros in the body.
- if not | A | B | C
- same as if, but the logic is inverted. When A is true it expands to C and vice versa.
- not | A
- true if A is not true
- and | A | B
- true if both A and B are true. In details: it works as the pythonic and, that is, in the true case it returns B (or the last parameter, in case you specify more than two parameters).
- or | A | B
- true if any of A or B are true. In details: it works as the pythonic or, that is, it returns the first true parameter (yes, it supports any number of parameters). If none of the parameters is true, then it return false.
- xor | A | B
- true if A is true while B is false, or the opposite
- = | A | B
- true if A is the same as B. It's case insensitive. You can use the opposite macro, true if they are different, and it's name is != or <> (use the one you like most, there's no difference).
- > | A | B
- true if A is greater than B. Of course you can also use the related macro <.
- >= | A | B
- true if A is equal or greater than B. Of course you can also use the related macro <=.
- switch | A | B | C | D | E | F ...
- this is rather complex for non-programmers. You can learn how a switch statement is supposed to work from Wikipedia. When you know how a switch works, then you will understand this schema that will make you understand how the parameters of this macro work
switch(A) { case C: return D; case E: return F; ... }
- The B is a separator string for C. Let's be clearer: if you want to specify several cases in C, all of them returning D, then you can specify them separating with B.
- As you can see C and D are paired, as E and F, eventually G and H, and so on. If at the end of this list of pairs, a single unpaired parameter is found, then it is used as the else/default case, when all other pairs have failed.
- Let me translated the first example of Wikipedia using the macro
{.switch|%n%|,| 0|you typed zero| 3,5,7|%n% is a prime number| 4,6,8|%n% is an even number| 2|%n% is a prime and even number| 1,9|%n% is a perfect square| Only single-digit numbers are allowed .}
- for | A | B | C | D | E
- repeats D by replacing variable {.^A.} with every value between B and C (they are meant to be numbers).
- Optionally you can specify a step for the numbers: that is, instead of going 1-by-1, they can go 2-by-2. The optional step is specified at position D; in such case the body is moved from position D to position E.
- Remember to use quoting for the body.
- for each | A | B | C ... | Z
- a (sometimes) handier version of for, that will repeat Z but replacing variable {.^A.} with value B the first time, value C the second time, D etc etc. Remember to quote the body.
- example: {.for each|i|10|100|1000|{:now it's {.^i.} :}.}
- while | A | B
- repeats B for as long as A is true. Both B is automatically dequoted. If A is quoted, then it's expanded, otherwise is considered the a variable name.
- Optional parameter else will be expanded if B is never done.
- Optional parameter timeout let you specify (in seconds) the maximum time the loop can live before it is stopped. It's 1 second by default.
- Optional parameter var saves the output in a variable instead of just expanding to it.
- Example: {.while|#x|{: {.dec|#x.} welcome! :}.} will welcome 10 times if #x is 10.
- after the list | A
- quoted text A is dequoted and executed, but only if the file listing is completed.
- dequote | A
- if A is {:quoted:} then quoting markers are removed (unleashing macro execution of the previously quoted text).
Data getting
- section | A
- A is the name of the [section] you want to include. Note: till build #160 it was case sensitive.
- Optional parameter file to load the section from an external file.
- Optional parameter back=1 will work in diff templates to access the section in the original template. So you can access it even if you overwrote it.
- Example: {.section|names|file=tables.txt.}
- get | A
- where A is the name of a value you are interested in, like to know if an option is enabled or not.
- This is a list of supported values for A:
- can upload
- true if in the current folder the user is allowed to upload files
- can delete
- true if the user is allowed to delete the current item
- can recur
- true if the option Recursive listing is enabled
- can archive
- true if the current item in list is archivable. outside the list it refers to the current folder.
- can access
- true if the current item in list is accessible by the user
- is new
- true if the current item in list is flagged as "new"
- accounts
- semicolon-separated list of username of all accounts.
- By specifying an additional parameter groups you'll get only groups. Respectively, a parameter users will give you only non-group accounts.
- stop spiders
- true if stop spider option is enabled.
- urlvar | A
- url variable. Let's say in the url you see ?sort=s and you want to know that s, just use the macro urlvar|sort.
- postvar | A
- just as urlvar but reads the value from the POST part of the request instead of the URL.
- header | A
- get any value from the HTTP request header. A is the name of the header field. This is something mostly for techies. Don't fret if you don't even know what the header is.
- time | A
- returns current time information. The format is specified by optional parameter A. Refer to this page for format syntax. If A is not supplied, value "c" will be used.
- Optional parameter when to specify a time other than current.
- Optional parameter offset to specify the number of days differing from the current time.
- cookie | A
- expands to the value A passed by the browser.
- With an optional parameter value you will set a new value.
- Every known standard parameter for cookies is accepted, as expires and path. Expires can be expressed in many ways: if it starts with + or - will be the number of days in the future or in the past. If it's a number will be considered as unix time format or HFS format. You can even specify it as a date: 2/4/2013.
- Example: {.cookie|step.} will give you the current value
- Example: {.cookie|step|value=3|expires=+30.} will set step to 3 and the cookie will expire in 30 days.
Data manipulation
- substring | A | B | C
- cut C from A to B, with B not included.
- Example: substring|(|belong|you (are) belong to us.} will be (are).
- If A is not specified, C is taken from the start. If B is not specified, C is taken to the end.
- Optional parameter case=1 to turn on case sensitivity.
- Optional parameter include to say if A and/or B must be included. Values: 0 (none), 1 (only A), 2 (only B), 1+2 (both).
- cut | A | B | C
- cut C from position A, for B characters. The difference with macro substring is that here you specify where to cut by numeric positions.
- Example: cut|2|3|abcdef will expand to bcd
- If you don't specify A, it defaults to 1. If you don't specify B, it defaults to the length of C.
- If A is negative, then you are counting backward from the end of C. If B is negative, then you are considering the length of C minus the amount of B.
- Optional parameter to will let you specify the number of character to cut. B is ignored in this case.
- Optional parameter var specifies the variable name to work on. Use it instead of C.
- You can use named parameter from instead of A, size instead of B, and what instead of C.
- Example: cut|from=3|size=2|abcdef will expand to cd
- repeat | A | B
- repeat B for A times. Example: for A=5 and B=+ the result is +++++
- upper | A
- returns A with all letters uppercased. Example: for A=Hello the result is HELLO
- lower | A
- returns A with all letters lowercased. Example: for A=Hello the result is hello
- trim | A
- returns A with any leading and trailing space removed
- replace | A | B | C
- returns C with every A replaced with B
- calc | A
- return the result of the mathematical expression A. Example: for 1+(5/2) the result is 3.5
- supported operators are + - * / % (as modulus)
- round | A | B
- returns rounded value of A, where A is a non-integer number, and B is the number of digits after the decimal point. B is zero by default if not specified.
- add | A | B
- returns A+B where A and B are numbers
- sub | A | B
- returns A-B where A and B are numbers
- mul | A | B
- returns A*B where A and B are numbers
- div | A | B
- returns A/B where A and B are numbers
- mod | A | B
- returns A modulus B where A and B are numbers
- min | A | B ...
- returns the minimum over all parameters. You can have more than 2 parameters.
- max | A | B ...
- returns the maximum over all parameters. You can have more than 2 parameters.
- count substring | A | B
- tells the number of times A is present in B (case sensitive)
- encodeuri | A
- all characters are encoded in the %XX form used for URLs, expect alphanumerics and #/,&?:$@=+
- decodeuri | A
- all encoded characters in the form %XX are decoded.
- convert | A | B | C
- converts C from charset A to charset B. At the moment only supported charsets are ansi and utf-8.
- force ansi | A
- if template is using UTF-8 charset, then A is converted to ANSI. Otherwise A is left unchanged.
Variables and functions
- set | A | B
- what you actually do is to bind B to the name A. You can later recall B by passing A to the macro call.
- If you are used to programming, you may know what variables and functions are. In such case, consider that set|x|1 is similar to a variable x with value 1. By binding to x something more complex, with parameters, you are creating a function. The first parameter is $1, the second $2, and so on, that you can specify inside the body B.
- Remember to use quoting if you use macros in the body (B).
- Example: {.set|x|1.} or {.set|double|{:{.mul|$1|2.}:}.}
- Optional parameter var will let you copy variables.
- Example: {.set|y|var=x.}
- Optional parameter mode can be append or prepend, to concatenate existing content of the variable to the new content, as AB or BA.
- Example: {.set|x| is a good boy|mode=append.}
- call | A | B | C | ...
- this macro (shortcut by ^) expands to the value bound to A. Such value can be a number or a text, doesn't matter. If the value contains symbols $1 and $2, then they are replaced with the parameters B and C (and so on).
- Example referring to above: {.call|double|15.} will expand to 30
- You can find some examples for set and call on the forum.
- inc | A | B
- if A is a variable with numeric value, then its value is incremented by the number B. If B is omitted, it defaults to 1.
- dec | A | B
- just as the inc above, but the value is decremented
- count | A
- each call returns and increments A, so the sequence will be 0 1 2 3...
- variable A is not actually a variable, you can't access it throught {.^A.} and its value can be retrieved only through another call to count.
- from table | A | B
- A is the table and B is the key. The table is a variable or a section with this form
- key1=value1
- key2=value2
- key3=value3
- Let's say such text is the content of variable foo, then to get value2 you should do {.from table|foo|key2.}. (yes, poetry)
- If it was the content of table [bar] instead, then you should do {.from table|$bar|key2.}.
- set table | A | B
- it's the counterpart of from table. A is the name of the table, while B is in the form key=value.
- If the key already exists, it's replaced, added otherwise.
- Example: set table|foo|key2=new value
- cache | A | B | C
- expands to retrieved value B from cache-table A. If not found, the new value C will be set. You can quote C if you need it.
- This is a very useful tool when C takes too much time and you want to be sure you will do it only once.
- Example: {.cache|%ip%|#countries|{:{.load|http://server/giveMeTheCoutry?ip=%ip% .}:}.}
Localization
Here goes a macro useful for template localization.
Inside the template you can use identifiers (IDs) instead of real text. So you can gather all the text in one place, and ease the work of whom wants to translate to another language.
Lets say that you have a link <a href ='..'>Go up one level</a>. You can replace with <a href ='..'>{.!up.}</a>, moving the text to section [special:strings].
[special:strings] up=Go up one level
You can optionally provide a parameter (like {.!up|Go to parent folder.}) that will be the default text in case up is not found in [special:strings].
If no parameter is provided, then the ID itself will be used as default text.
File manipulation
Consider most of these macros work only with operating system oriented paths, not the ones of the virtual file system.
- load | A
- you'll love this one. You can specify A as a file name, or as a URL. It will load and expand to it. The file or URL you specify must be accessible from the server machine. A can be C:\windows\win.ini or also http://another_hfs_in_lan/the_file_i_want.txt.
- With an optional parameter var you can specify the name of a variable where the whole content of the file will be stored. In such case, the macro will not expand to the content of the file, it's just in the var.
- Optional parameter from to specify an offset from where to start reading.
- Optional parameter size to specify how much to read.
- Optional parameter to to specify the last byte to read, as an offset from the beginning.
- All parameters from, size and to are expressed as number of bytes.
- Example: {.load|document.txt|var=mytext.}
- filesize | A
- tells you the size in bytes of the file A. At the moment URL are not supported, only local filenames.
- save | A | B
- stores B to file path A. The path can be absolute, URI based or relative to HFS folder.
- You can supply an optional parameter var instead of B, and the content of the specified variable will be saved.
- append | A | B
- add B at the end of file A. This may is also useful to keep special logs.
- delete | A
- moves the file A to the recycle bin.
- Optional parameter forced=1 will force deletion in case the bin is not available.
- Optional parameter bin=0 will delete the file permanently instead of moving to the recycled bin.
- rename | A | B
- renames the file A to B.
- md5 file | A
- computes and expands to the MD5 hash for file A.
- copy | A | B
- copies file A to B, where B can be a folder or a full path+filename.
- move | A | B
- as copy, but A is removed when the copy is complete.
- chdir | A
- changes the current working directory of the HFS process.
- mkdir | A
- creates the specified folder. URI is supported in A, but it must refer a real folder.
- exists | A
- checks A for existence, may it be a file or folder.
- is file | A
- checks A for existence as a file.
- filename | A
- returns only the filename part of A, removing eventual path information.
- filepath | A
- returns only the path of A, removing the file name.
Virtual File System manipulation
- add folder | A | B | C
- adds a folder to the virtual file system. A specifies real or virtual, while B is the name of the folder.
- For real folders B should be the path on disk, but if published name is different than the real one, you can specify the path in parameter B, and the name in C.
- Where in place of a simple name, you specify a virtual path, it will be used to place the folder (otherwise it will be place on the root).
- Any existent folder with same name will be overwritten, unless you specify a parameter overwrite=0.
- Example: {.add folder|virtual|/personal/my pictures.}
- a virtual folder "my pictures" will be added under existing folder "personal".
- Example: {.add folder|real|C:\music|my music|overwrite=0.}
- folder on hard disk C:\music is published with public "my music". If a folder with same name is in the VFS, it's left untouched and no new folder is created.
- set item | A
- modifies the item A in the virtual file system by using any of these optional parameters
- hide
- set to 1/0 to decide item visibility
- hide tree
- set to 1/0 to decide item visibility and sub-items
- no log
- set to 1/0 to decide item logging
- not as download
- set 1/0, it's the same as don't consider as a download. For folders, set it to * for all files, or any other file mask you want.
- comment
- set the comment
- Example: {.set item|private files|hide=0|comment=you should never see this!.}
- access / delete / upload
- you can set permissions on the item, by specifying a list of usernames.
- Example: set item|videos|upload=robert will give account robert the ability to upload files in /videos.
- Moreover, you can prefix permission by add or remove. In the previous example you set the upload permission. If mike already had upload permission, it is now lost. To add robert instead of just overwriting, you should {.set item|videos|add upload=robert.}. Now mike is happy too. As well, if you change your mind, and want to revoke your grant, just set item|videos|remove upload=robert.
- You can specify more than one username this way: robert;mike;rupert.
- Special usernames are @anonymous @any account @anyone.
Connections control
- disconnect | A | B
- with no parameters, it disconnects current connection. If A is supplied, it is considered an IP mask, and every connection matching it (instead of the current one) will be disconnected. If also B is supplied, it will select only connections with port number same as B.
- set speed limit for connection | A
- set a speed limit A in KB/s for the current connection
- set speed limit for address | A | B
- set a speed limit B in KB/s for all connections coming from address A (no masks allowed)
- disconnection reason | A
- this reason determines if a download must be aborted. Any value will abort the download, but if the value is empty the download goes on.
- This macro will always return the value of the reason just before its call. So with a single call you are reading and setting the value. If no parameter is specified, then you are only reading.
- add header | A
- adds line A to the HTTP header.
- current downloads
- expands to the number of current downloads.
- Optional named parameter user will count only downloads made by specified user.
- Optional named parameter ip will count only downloads made by the specified address.
- Optional parameter file=this will count only downloads of this current file.
- Example: {.current downloads|user=%user%|file=this.} will tell you how many connections this user is using to download this same file.
- current downloads of file
- number of current downloads of current file.
- If an unnamed optional parameter is specified, it is used as IP mask, and only matching connections will be counted.
- If the parameter is given name user, only connections by such user will be counted.
Account manipulation
- set account | A | ...
- with this command you can change all attributes of the account whose username is specified in first parameter. If the username is left empty, current username is used, given this makes sense in current context.
- Other parameters are the attributes you want to change, in the form set account|username|thing=value|thing2=value2.
- Here is a list of such attributes
- password
- set a new password
- newname
- set a new username
- redirect
- set the homonymous field
- no limits
- set the homonymous field (true/false)
- enabled
- set the homonymous field (true/false)
- is group
- set the homonymous field (true/false)
- member of
- set the member of field (specify more than one group separating by semicolons ";" )
- add member of
- add more groups to the above
- remove member of
- remove some groups to the above
- notes
- set the homonymous field
- notes key
- set the notes as it was a table with {.set table.}
- Example: {.set account|mike|notes key=last time=%timestamp%.}
- new account | A | ...
- creates a new account with username A. After the username, you can also specify all the values available in the set account macro.
- get account | A | B
- expands to the value of property B of account A.
- Supported value for B are redirect, no limits, enabled, is group, member of, notes, notes key. Group names for member of are semicolon-separated. Special case for notes key where you should specify the key to retrieve, while the notes are treated as a table, just as for {.from table.}.
- If A is omitted, current username is used, given this makes sense in current context.
- member of | A
- true if the current user is member of group A (specify more than one group separating by semicolons ";").
- Optional parameter user to check a different user.
- Example member of|administrators|user=rejetto
- If A is omitted, you will get the full membership for current (or specified) user. This is different from {.get account||member of.} because this latter form will consider only direct first-level membership, while {.member of.} will actually consider membership at any level.
Others
- comment | A
- this is just discarded. It's for your convenience, to put a comment in the template. HTML comments are readable by visitors if they use show html source in their browser. Using this macro you will have comments that will never leave your server.
- length | A
- if A is 5 characters length, like abcde, it expands to 5.
- Optional parameter var will work on the specified variable instead of A.
- match | A | B
- it is true if the content B is matched by the mask A.
- match address | A | B
- just like the macro match, but the mask supports ip ranges like 10.0.0.1-10.0.0.25
- random | A | B | C | ...
- it expands to any of the parameters, randomly
- random number | A | B
- if only A is specified then a number between 0 and A is generated. If also B is specified then the number will be between A and B (included).
- pos | A | B
- expands to the position of A in B. Zero if not found.
- Optional parameter from will start searching from specified position.
- Optional parameter case will decide case sensitivity. Default is: insensitive.
- Example pos|the|i'm the alpha and the omega|from=14|case=1 expands to 19
- regexp | A | B
- Try to match pattern A on text B.
- When the pattern doesn't match, it just expands to nothing (then, false).
- When it does, the matched sub-pattern is returned.
- You can provide optional parameter var instead of B, and the text will be the content of the specified variable.
- Optional parameter case will determine case sensitivity. (off by default)
- Optional parameter sub will specify the name of a variable that will be set as a table, where you can retrieve every sub-pattern by numerical index.
- If optional parameter replace=YYY is used, the command returns no more the matched pattern, but the whole text B with every matched pattern replaced by YYY.
- Example: regexp|\d+|var=weWantNumbers
- breadcrumbs | A
- builds a breadcrumbs based on the current folder path. The A is a little html template that is repeated for every piece of the path, for which 3 symbols are provided: %bread-url% , %bread-name% and %bread-idx%.
- Remember to use quoting, especially if you use macros in the parameter.
- Optional parameter from will let you specify how many steps of the path to skip.
- Example: {.breadcrumbs|{:<a href ="%bread-url%">%bread-name%/</a>:}.}
- dialog | A | B | C
- display a server-side message in a dialog box. A is the message itself, and only required parameter. B are options separated by spaces, and C a title for the dialog.
- Possible options are
- okcancel
- offers buttons OK and CANCEL
- yesno
- offers buttons YES and NO
- yesnocancel
- offers buttons YES, NO and CANCEL
- error
- this is an error reporting dialog
- question
- this is a questioning dialog
- warning
- this is a warning dialog
- information
- this is an informational dialog
- mime | A
- the mime-type describing the content sent to the browser. For techies, it's the content of the header field "Content-type".
- any macro marker | A
- it is true if any macro marker is present in A. Macro markers are {.delimiters.} , {:quotings:} and the parameters separator (the pipe, "|").
- play system event | A
- specify the name of the event bound to a sound that you want to play. SystemStart and MailBeep are just examples, for a full list you can open your registry at HKEY_CURRENT_USER\AppEvents\EventLabels .
- exec | A
- ask system to run file A, eventually with parameters. If you need to use the pipe, then use macro quoting.
- Optional parameter out will let you capture the console output of the program to the specified parameter.
- Optional parameter timeout will specify the max number of seconds the app should be left running.
- Example: {.exec|notepad.}
- add to log | A
- add A to the log panel.
- Optional parameter color to specify the color.
- set ini | A
- where A is a text in the same format you can find in hfs.ini (save options -> to file).
- example: {.set ini|speed limit=100.} will turn the global speed limit to 100KB/s.
- focus
- will bring HFS window on front of the user.
Shortcuts
- $A
- is a shortcut for section | A
- ?A
- is a shortcut for urlvar | A
- ^A
- is a shortcut for call | A
- A = B
- is a shortcut for =|A|B
- ?name = X
- is a shortcut for {.?name.} = X .
- It works also for <> != < <= > >= .