Chunks

What is a "chunk" ?

Let me repeat my explanation on what a "chunk" is -- it is the name I have given to one logical part of the body of a route or the body of an event handler or; in case of the utilities, a function that is exported and used in multiple places. So, a chunk is some code (not all) that went into constructing the body of a route, or the body of a event-handler or the body of a utility function. And a set of chunks, arranged in proper order, would form the complete body of that route/event-handler/utility function.

Before I forget ... those chunk files are searched from the current folder from where you start the build process. If you want you can create those chunk files in sub-folders of the current folder instead. In that case the relative path from the current folder should be specified in the definition file.

There are two ways by which you can write a chunk file.

First method to write a chunk file.

In the first method, you do NOT write ANY JavaScript code in your chunk file. Instead you rely on Pocket Specs to pick up the JavaScript from pre-defined pattern files and then carry out some search-and-replace, and let Pocket Specs write the code for you. Here is an example of a chunk file which defines ONE route. It has instructions for 3 chunks in there ... In such a case, the actual JS code for each chunk are assumed to be picked up from pattern files available in "patterns" sub-folder located in the same folder as that of the executable (i.e. where pocketspecs.exe resides)

chunk("Set a variable to catch result","initval",["result","dat"])
chunk("Fetch records as per GET ","fetchrecords",["!coll","!dat","records","!result"])
chunk("Return true or false, as per reading","ending",[])

If you notice; the instruction for each "chunk" is written like a JavaScript function call with 3 arguments:

chunk(<Comment>,<Source>,[<var>,<var>...])

The first argument will be used as a JavaScript comment which will help everyone know what that chunk of code does. The second argument gives a clue to Pocket Specs it will extract the source from; for it to work on. The second argument is a "keyword". It is usually unique among that set of instructions. So "initval", "fetchrecords" and "ending" are the unique keywords in the above example.

The third argument is a string list. Those are variable names that are to be used for search-and-replace on the string extracted from the source. Explained later in this topic. In the above example of a chunk file; no JavaScript was written by you. So Pocket Specs would assume that the source for the codes are in files named "initval.pat.js", "fetchrecords.pat.js" and "ending.pat.js" -- Those would be the files kept in the "patterns" subfolder of the main exe folder, as explained earlier. These pattern files, as you may have guessed, captures common software patterns used by Pocketbase (e.g. fetching record, saving record, etc.) I have given a few patterns. But as Pocket Specs grows, there will be many more pattern files written by me and others in the community. It so happens that actually only the pattern file: "fetchrecords.pat.js" exists in the installation.

So what happens to the other two? Where will Pocket Specs get the contents; if the sources themselves are missing? In such a case; Pocket Specs will assume that the source is an empty string and happily continue to proceed. Those chunks will turn into an empty block, like this ... and the comment you gave for that chunk will appear before it ... For example the keyword "initval" does not refer to any pattern file, so Pocket Specs will generate this code for that chunk :

  /*Set a variable to catch result*/

  	let result;
  	let dat;
     	  {

 	  }

If you notice, it defined the variables "result" and "dat" -- You would have guessed, that it was done from the last argument (the third argument) of the instruction given for that chunk. More on this later. What if the chunk file itself is missing? BTW, you must be knowing by now that this particular chunk file was actually referred in the main definition file (*.do.txt). What if the chunk file itself was missing? In such a case, Pocket Specs will give a warning and still proceed; assuming that the entire code that it should have written was completely an empty string.

Pocket Specs allows incremental improvement (like Kaizen) on your coding iteratively. You can even just specify the definition file (*.do.txt) and don't give any chunk file at all. In such a case, a completely empty outline of your project will be generated. All routes, all functions utilities and all event handlers will be written with empty function bodies. And if you do give a chunk file, as explained here; inside each chunk file, you may not have fully developed the source for some of the chunks. No problem. Pocket Specs will make empty code blocks (bracketed by braces) for those chunks, as explained earlier. In short, you can keep incrementally improving in an agile, cyclic manner.

There is a second method to write a chunk file

In this method, the chunk file is written actually as a JavaScript file. This is a lot more common than the first method -- the first method is usually used ONLY when you are able to describe a piece of code by pointing each keyword in the instructions for each of the chunks to the respective pattern file. But the second method does this more realistically than the first method. As often, you may not be relying purely on the pattern files. Here, the same earlier 3 chunk definitions would be written inside a JavaScript comment as shown below:

/*
chunk("Set a variable to catch result","initval",["result","dat"])
chunk("Fetch records as per GET ","fetchrecords",["!coll","!dat","records","!result"])
chunk("Return true or false, as per reading","ending",[])
*/
//@initval
result = false;
dat = {
    filter:filt,
    sort:sort,
    limit:+limit,
    offset:+offset
}
//@ending
if(!result){
    return c.json(200,{success: false});
}else {
 return c.json(200,{success: true, recs: records, count: records.length});
}

Chunk instructions are written inside a comment at the top of the file If you notice that after the initial bracketed comment (i.e. within /* ... */ ) I have indeed written some amount of JavaScript. I'll explain that part later. Let us concentrate on the header part here for now:

/*
chunk("Set a variable to catch result","initval",["result","dat"])
chunk("Fetch records as per GET ","fetchrecords",["!coll","!dat","records","!result"])
chunk("Return true or false, as per reading","ending",[])
*/

As you can readily see, I have defined 3 chunks using 3 instructions. They are written exactly the same way as it was written in the first method.

But this time, those 3 instructions are given inside a bracketed comment. For Pocket Specs to understand those 3 chunk instructions, the comment start (i.e. /* ) has to start on a new line all by itself and similarly the comment end (i.e. */) has to be on the line just after those instructions, on a new line by itself.

Now let us examine once again, how Pocket Specs will fetch the source on which it can do its magic, for those keywords that were specified; namely "initval", "fetchrecords", and "ending" ... As explained earlier; it found the source for "fetchrecords" from the pattern file "fetchrecords.pat.js" ... so that takes care of one of the three keywords. But what about "initval" and "ending" ?

Just to emphasize; pattern files are always to be store in the "patterns" sub-folder of the folder where the executable 'pocktspecs.exe' is residing. The extension of such files necessarily has to be of the format <keyword>.pat.js

At this point let me highlight again that in this second form of writing these chunk files; there were some lines containing the actual JavaScript code that I wrote after the header bracketed comment.

Let me focus on that part below the header now as shown below:

//@initval
result = false;
dat = {
    filter:filt,
    sort:sort,
    limit:+limit,
    offset:+offset
}
//@ending
if(!result){
    return c.json(200,{success: false});
}else {
 return c.json(200,{success: true, recs: records, count: records.length});
}

If you see the JavaScript code; you will find that the keyword "initval" exists in a special comment. That is also the same keyword we had used earlier.

Pocket Specs looks for the special characters "//@" at the beginning of each line. If it finds that right combination, it will say "aha, the source of a keyword is now available below... provided I found a match" If the word after that //@ is exactly the same as the one one you used earlier; then it will take in all the lines below that and use that as the source on which it has to work in its algorithm... till it encounters another chunk definition starting with //@ ...

Thus, as you can readily see above, the sources for both these chunks for the keyword "initval" and the keyword "ending" have now come to the attention of Pocket Specs! But the sources you wrote for those chunks are not directly used by Pocket Specs. It processes those sources. Explained next!

What does Pocket Specs do with the source of a particular chunk?

Pocket Specs processes the chunks that are defined exactly in the same order as you had written in their instructions at the beginning of the file. In the above example; it will first process the source available for "initival" keyword, then it will process the source for "fetchrecords" keyword and lastly it will process the source for "ending" keyword. To process the source of any chunk instruction, Pocket Specs examines the last argument in the respective chunk instruction ... which is a list of strings. These strings are considered as names of variables or constants that are to be used within the source code. If the list is empty, then the source is used as is... i.e. without any replacement, but if the list is non-empty, it will take each of those variables and attempt to replace special tokens that can be present in the source. Again each variable is processed in order. The processing of the variable happens in two ways: If the variable does NOT start with an exclamation mark, then the variable is defined for you in the code. For example; in the "initval" key word the list that is given is: "result" and "dat"

chunk("Set a variable to catch result","initval",["result","dat"])

So it will write the following into the beginning of the source:

	let result;
  	let dat;

The above is NOT written by you. It is automatically written by Pocket Specs.

What if the variables are starting with the exclamation sign? Good question. I am glad you took a close look at the 3rd argument for the 2nd chunk instruction. ["!coll","!dat","records","!result"] Indeed, three of those variable names start with an exclamation sign. In such a case, Pocket Specs skips the definition of those variables. So in this example; it will only write: let records; The above is written before processing the source for the 2nd chunk. The reason for skipping the definition of those variables starting with "!" is simple: They would have been defined earlier. In JavaScript it is an error to define a variable twice.

Once the variables are written into the evolving source code, Pocket Specs takes up the source you wrote for that chunk (or was picked up from a pattern file). In the above example; the source for the first chunk was written beneath the special comment //@initval ... It will examine what you wrote, and search for special tokens that you may have given ... Those tokens are used as explained below:

Example of special tokens in your code 

	_arg1_,
  	_arg2_ 

etc. 

_arg1_ would get replaced by the first variable that you gave in that 
3rd argument (i.e. string list), _arg2_ would be replaced by the 2nd variable 
and so on 

If you notice the code I had written for the keyword "initval" did not use any of those special tokens (i.e. I did not write _arg1_, etc. so Pocket Specs does not do any replacement and instead uses the source I had written verbatim, as it is.

Where are the tokens replaced? Let us examine the 2nd instruction from those 3 chunk instructions: That indeed referred to the pattern file named "fetchrecords.pat.js" If you load that particular file from your installation, you will indeed see tokens such as _arg1_, _arg2_, etc. written in that source. Pocket Specs will dutifully replace those arguments with the one specified in the 3rd argument (string list) of the instruction for that chunk. Such pattern files are explained next.