F.E.L.T.

Functionally Equivalent Language Translation →

% FELT(1) User Manuals % Sean Charles % September 26, 2012

FELT Command Line Tool

felt - The FELT command line interface

SYNOPSIS

felt [options] input-file(s)...

DESCRIPTION

The felt command line tool is capable of producing rendered output in any supported back-end language provided that the relevant coder has been correctly installed. The list of input files can have any name and extension but they MUST contain FELT source code!

OPTIONS

-cw, --code_wrap
Request that the back-end coder wraps the rendered coded in whatever character sequence makes most sense. For example, specifying this option with the PHPCoder would cause the <?php ?> tags to be inserted at the start and end of the rendered output.
-sc, --syntax_check
Request that the back-end coder performs, if possible, a syntax check on the rendered code and if any errors are detected, the code is discarded and replaced with the output from the checking process.
-as, --as-coder
This indicates to FELT what back-end coder to use, the currently shipped options are any one of PHPCoder, JSCoder, NodejsCoder and CSSCoder. This option is not case sensitive so "phpcoder" does the same as "PHPCoder".
-o, --output
This specifies the relative or absolute name that all output will be rendered to. If nothing is given then stdout is the default. If multiple input files are given on the command line then they will be appended to this file.
-p, --packed
This option when given ensures that absolutely no spurious characters are emitted into the output between files. This ensures that if you are packing files together, there will be no line-feeds or spaces etc between them as this may cause problems for your final output file.
-err, --errormode
This determines the format in which error output is reported back to stdout. The default is "human readable" output as the assumption is that you are running from the command line. The possible values for this option are as follows: json, console and simple. The JSON. The Emacs felt-utils.el script uses simple mode.

The internals of the error reporting class determine from the presence of certain environment variables whether or not the current render request was caused by a web-server request or from a scripted request. Sometimes you may not get the output that you require, for example pulling a request via curl means you'd get a response formatted in HTML when in fact you wanted plain text or console mode output. That is the purpose of the other two options so you can force the output to be whatever format you require.

ERROR OUTPUT FORMATS

As stated above there are a few different output formats that can be used according to what kind of context you are calling the utility from. You can choose from the default which is "human readable", a simple JSON encoded format or "console" mode which explicitly tells the internal mechanism that we are to produce human readable output rather than attempt to best-guess based upon CLI/web-server detection methods.

DEFAULT / HUMAN READABLE / CONSOLE

Specifying "console" means that no HTML will be present in the output. The system will determine the environment and choose
or "\n" as the line separator. By specifying console mode you force it to be "\n".

Here is a sample of output in the default hum readable format:

*** FELT-ERROR ***A syntax error has been detected in your source:
add1.felt
There are too many closing brackets (-1 remaining), location is approximate!

JSON FORMAT

Specifying "json" as the output format produces a simple string that defines an object that contains four properties, here's a typical JSON message:

{"message":"There are too [..snip..] location is approximate!",
 "row":1,
 "col":12,
 "where":"add1.felt",
 "reason":"There are too [..snip..] location is approximate!"}

The fields "message" and "reason" are the same string. I need to clean that sometime!

SIMPLE FORMAT

This format, "simple", is the one used by the Emacs support code that provides render-on-save behaviour. It allows the shell output from the command to be easily parsed and used to position the cursor in the buffer. This output simply contains the file-name, row and column and message on separate lines, for example:

filename.felt
1
12
There are too many closing brackets (-1 remaining), location is approximate!

ENVIRONMENT VARIABLES

$FELT_HOME
In order for the command line tool to be able to know where things are located on your machine it is necessary to configure this variable to point to the root installation folder, that is, wherever you unpacked and installed the latest release. If you unpacked the downloaded installation package into a folder called, for example, /home/username/feltproject1 then you would set the variable to that, presumably you have a system in place for your deployment / development platform so for Ubuntu that will be /etc/profile or a local .bashrc and on Windows you will need to add it to the PATH variable.

EXAMPLES

Here are some examples of using the command line utility to render code. First we use all of the defaults to convert a file into PHP code,

felt myfeltsource.felt

This will produce PHP output without code tags. If you want the output wrapped such that it could be saved to a file and included as part of a script or web source then you need to specify the code-wrap option, here we have used the short-form,

felt -cw myfeltsource.felt

That will produce the same output but with above and below the rendered code. Now let's say we want to save that to a file instead of going to stdout,

felt -cw myfeltsource.felt -o index.php

That will create a file in the same location as the script is executed from, if you want to write it somewhere else then do this,

felt -cw myfeltsource.felt -o /var/www/mywebsite/index.php

If you want to render a different output using the above example then use the -as-coder (long form) or the -as option, like so, first we do a CSS output file and then a Node.js file,

felt -cw -as csscoder mycss.felt /var/www/mywebsite/css/main.css
felt -cw --as-coder nodejscoder /var/www/mywebsite/node/main.js

TODO

Finalise the packing option around multiple input files... the first and last one should be the only ones that are affected. Anything else to say about this utility ?

AUTHOR

Written by Sean Charles.

REPORTING BUGS

Report any bugs to felt@objitsu.com FELT home page: http://feltweb.info

COPYRIGHT

I have not yet decided on the full terms yet, BDFL is my current favourite but how to release is with those strings attached.