DEV Community: Oguzhan Yagci

How to read a documentation?

Oguzhan Yagci — Fri, 12 Jan 2018 23:20:07 +0000

My biggest issue so far as a software developer is reading a doc. How many times did I open the docs of a new tool I am learning only to end up on Google asking how to do this and that.

Man pages are a bit easier to understand because usually I use them on specific functions. But for a frameworks like ExpressJS or bigger ones like Qt I am completely lost.

What are your tips to read a documentation efficiently?

Shell redirections explained

Oguzhan Yagci — Sat, 04 Nov 2017 21:38:15 +0000

As a student I have to use my shell everyday to get my work done. A shell can be an extremely powerful tool in everyday life if you know how to use it.

Shell redirections are something you have to use in order to accomplish many tasks without pain.

How a program outputs its content on the terminal.

To output text on the terminal a program must write it's output into a file. The classical way to manipulate files on a UNIX-like operating system is by requesting to the OS a file descriptor (fd). An fd is an unsigned integer given by the OS that identifies a given file on the system.

File descriptors are numbers that represent a way to access files.

By default your program gets 3 file descriptors that are called stdin, stdout and stderr.

The first fd stdin is the file used by your program to read input. It's default value is 0. If you start a program like cat without arguments it reads its input from stdin.

The second fd stdout is used to output content for the user (like "Hello World!"). It's default value is 1.

The third fd open by default is stderr. This one works exactly like stdout except we mostly use it to output error messages. It's default value is 2.

Shell redirections operators

In a shell, there are a few operators to perform redirections. Those are >, >>, <, <<, >&, <&.

`>`, `>>`, and `<`

Those 3 operators have one main thing in common: They interact with input/output files.

> and >> are used to redirect output from a program into a file.

$> cat my_file.txt > my_new_file.txt # The output from cat is redirect to a file caled my_new_file.txt

(If the file does not exist, it is created)

The difference between > and >> is that > truncates the file it is outputing to and >> appends to the output file.

$> echo Hello World! > greeting.txt # Creates a file with 'Hello World!' as the content

$> echo How are you? >> greeting.txt # Append 'How are you?' to greeting.txt

< allows you to use a file as input. So stdin becomes the file.

$> base64 < greeting.txt # base64 will use stdin as input which is redirected to greeting.txt by the shell

You can also combine multiple redirection operators:

$> cat < a.txt > b.txt # Reads from a.txt and outputs to b.txt

And `<<`

That one is a bit like the three above, except that it does not interact with files. Instead it is used to get input from the user's keyboard line by line.

So when you do something like:

$> cat <<EOF

... and press enter, the shell will expect input.
So you can continue:

$> cat <<EOF
> Hello World!
> How are you?
> Do you know the answer to the ultimate question?

And when you want to stop the input you either press Ctrl+D or type the word which is on the right side of the << operator (In this case EOF) and press enter (it must be on an empty line):

$> cat << EOF
> Hello World!
> How are you?
> Do you know the answer to the ultimate question?
> EOF
Hello World!
How are you?
Do you know the answer to the ultimate question?

Immediatly after the input has been stoppedt the shell runs the program with what you have typed as the content in stdin.

`>&` and `<&`

Those two do not act on files but file descriptors.

Their left side can be either ignored or be a number (the target fd).
The left side MUST be attached to the operator.

If I want to redirect stdout to stderr I can do:

$> cat ft_strdup.c 1>&2

Or...

$> cat ft_strdup.c >&2

You can also use >& and <& to close a file descriptor (If you want to ignore error messages, for example)

$> find / -name 'lost_file' 2>&- # If you don't want to see messages like 'Permision denied'

The only difference between >& and <& is the default file descriptor used in case of a not given left fd.
>& is for stdout and <& is for stdin.

Also, if you put a space between the left side of the operator and the operator itself the shell will think that the left side is actually an argument to pass to the program and will use the default left side fd number.

One last thing

Those operators can be used anywhere on the command line

$> < input_file cat

$> >output_file echo hello world

$> ls 2>&- -R /

But you should put the them either on the beginning of the command or the ending to avoid confusion.

I hope this article has been helpful to you. :)

Generating a parse tree from a shell grammar

Oguzhan Yagci — Sat, 04 Nov 2017 16:19:02 +0000

As a student at 42 one of the first projects you have to accomplish by yourself is the reimplementation of a shell. There are many things to do to have a working shell so today I will only focus on the parse tree.

A parse tree is what represents the syntactic structure of our commands and will allow us to easily perform those commands typed by the user.

So we want to be able to translate something like this:
ls | cat -e
Into a shell job that we will be able to execute as a whole command.

The first step is to transform the text input into tokens. That way we will have 4 tokens that represents our text input in a more easier way to process.

Each token has a value (the text input) and a type (if it is an operator or a command argument):

ls -> WORD
| -> PIPE
cat -> WORD
-e -> WORD

Once parsed, we expect to have something that could be rendered like this:

              pipe_sequence
              /          \
simple_command      simple_command    
      |              /          \
   cmd_name       cmd_name     cmd_suffix
      |              |             |
     'ls'          'cat'        cmd_word
                                   |
                                 '-e'

So the second step is to come up with a grammar. A grammar is a set of rules to be followed by the parser to generate the parse tree.

This is a simple version of the grammar of sh:

pipe_sequence    : simple_command
                 | pipe_sequence '|' simple_command
                 ;
cmd_suffix       : cmd_word
                 | cmd_word cmd_word
                 ;
simple_command   : cmd_name
                 | cmd_name cmd_suffix
                 ;
cmd_name         : WORD                   
                 ;
cmd_word         : WORD
                 ;

What this grammar tells us is that:

A pipe_sequence is a simple_command followed by 0 or more simple_command
A cmd_suffix is one or more cmd_word
A simple_command is a cmd_name followed or not by a cmd_suffix
A cmd_name or cmd_word is a WORD token

Each rule will be implemented as a function.

Let's start with cmd_word

/*
** struct s_parser is a data type containing informations about the current parser
** (like the tokens list)
*/
struct s_cmd_word    *cmd_word(struct s_parser *p)
{
    struct s_cmd_word    *w = NULL;

    /*
    ** p->tokens is a linked list containing all the tokens
    ** p->tokens->type is an enum corresponding to the token's type
    */
    if (p->tokens->type == T_WORD)
    {
        w = malloc(sizeof(struct s_cmd_word));
        w->data = strdup(t->data);
        p->tokens = p->tokens->next
        return (w);        
    }
    else
        return (NULL);
}

Really simple so far. If the current token is a WORD then we return a struct s_cmd_word * containing the actual data. But if the current token is not a word (it could be an operator) we return NULL. And we should not forget to advance to the next token once we used it.

What about pipe_sequence?

struct s_pipe_sequence    *pipe_sequence(struct s_parser *p)
{
    struct s_pipe_sequence    *ps;
    struct s_simple_command   *sc;

    ps = malloc(sizeof(struct s_pipe_sequence));
    while (sc = simple_command(p))
    {
        /* This function pushes a new element into a linked list */
        ft_lstpush(sc, &ps->simple_commands);
        if (p->tokens->type == T_PIPE)
            p->tokens = p->tokens->next;
    }
    if (ps->sc)
        return (ps);
    free(ps);
    return (NULL);
}

The other functions should be as easy to write as the above one.

At the end you should have a parse tree based on the grammar above.

Of course this is a very simplified version of the actual shell grammar but really this is all it takes to be able to generate by hand a parse tree.

If you want to implement a shell you should first visit this website. It's THE place to read first to understand how a shell like sh behaves.

Thanks for reading :)