Forem: Pragma

Never Used GraphQL? Fear Not!

Muhammad Tabaza — Tue, 29 Dec 2020 11:53:54 +0000

This article is a practical introduction to GraphQL that enables you to get started building beautiful APIs with Pragmalang.

What Is GraphQL?

GraphQL is a language specification released by Facebook and standardized in 2015. The language is designed to make retrieving data from front-end applications easier for developers. Some of its advantages are:

Type-Safe Communication: You always know the type/shape of the data you're receiving, and the type of data the server expects from you.
Standard Documentation: All GraphQL APIs must follow a certain standard where it comes to documentation. Many tools know how to interpret this documentation by introspecting the API.
Tooling: Since GraphQL is a standard, many tools are designed to work with all GraphQL APIs, such as tools that generate TypeScript definitions based on the GraphQL schema to be used in your Web app.
No Underfetching/Overfetching Of Data: You select exactly the data that you need, and you can perform multiple operations within a single query.

GraphQL is actually two languages smashed into one: a schema definition language, and a query language.

Schema Definition Language

The schema definition language is what is used to describe the types of data that the API operates on, and what the API is capable of doing with said types.For example:

# This is a type definition
type Character {
  name: String! # '!' means "required" or "not nullable"
  friends: [Character] # '[]' mean "array". Types can be recursive
  homeWorld: Planet! # Types can relate to each other
}

# Another type definition
type Planet {
  name: String!
  climate: String!
}

# A special type definition that specifies
# the queries that a client can perform
type Query {
  getCharacter(name: String!): Character
  #            ^^^^^^^^^^^^^   ^^^^^^^^^
  #           Query Arguments  Query Return Type
  # Note that the return type is `Character`, not `Character!`
}

Comments in schema definitions are typically used for documentation. Comments in the example above were used for clarification purposes.

GraphQL APIs have three types of operations that a client can perform:

Queries: Simple retrieval of data
Mutations: Changes to existing data, or addition of new data.
Subscriptions: Retrieval of dta over time.

When developing a GraphQL API, you typically need to specify the queries, mutations, and subscriptions that your server can handle. In the example above, the server is only capable of performing a single query that takes a name of a character, and returns that character. But here's the catch: you need to specify **how* the query is handled*. Using traditional GraphQL frameworks, you would need to define what are known as resolvers to specify how each field of the type is fetched from the database.

Query Language

Once you're done writing a GraphQL API, you can use one of many GraphQL clients to send operations to your server. Most GraphQL APIs come with a GraphQL playground that you can use to write queries, and click a button to send them to the server, and display the JSON result. But when you're building a graphical application, you would want to use a client library from your code. An example query would be:

query {
  rick:getCharacter(name: "Rick Sanchez") { # We gave the operation a 'rick' alias
    name # Rick's name, just to make sure
    friends {
      name # We only want their names
    }
    homeWorld {
      name # We only want the name
    }
  }
}

This query - if Rick exists in the database - would return:

{
  "rick": {
    "name": "Rick Sanchez",
    "friends": [],
    "homeWorld": {
      "name": "Earth"
    }
  }
}

Rick's friends array is empty because he has no friends.

Where Does Pragma Come In?

When you're developing a GraphQL API, you need to specify the schema with all the required operations and types, and then implement resolvers for these operations. Of course, you would need to set up the database first.

What Pragma does is that it only requires that you define a Pragma schema. That's it! It generates a database, GraphQL schema, and all the operations you would need. Plus, with very simple syntax, you can extend the functionality of these operations using serverless functions that you import as if you were using a normal function from a library. Here's an example Pragma schema:

config { projectName = "character_api" }

@1 model Character {
  @1 name: String @primary
  @2 friends: [Character]
  @3 homeWorld: Planet
}

@2 model Planet {
  @1 name: String
  @2 climate: String
}

Note the small differences between the Pragma schema and the GraphQL schema. In Pragma, the equivalent of a GraphQL type is a model. Models and model fields need to have unique indices (e.g. @1, @5), which enables Pragma to perform most database migrations automatically based on changes to the schema.

You can explore the GraphQL API generated by Pragma by running the above schema (see Install Pragma), or you can check out another example at The Generated API section of the documentation.

If you have any questions or feedback, join our Discord channel, or leave a comment!

Go start building that new idea you had last week! It would only take a few minutes :)

Pragma: A Language for Building GraphQL APIs In No Time

Muhammad Tabaza — Thu, 29 Oct 2020 16:53:22 +0000

We're very excited to announce the first release of Pragma: An open-source domain-specific language for building GraphQL APIs by defining data models, and their associated validation/transformation, and authorization logic. Pragma takes your data model definitions, and automatically generates a fully functioning GraphQL API that you can use right away.

Motivation

Building a GraphQL API isn't a simple task. Writing a small API to create, read, update, and delete data in a database can take many hours, and lots of knowledge of the GraphQL framework and the language you're using.

Pragma aims to simplify this process by being incredibly easy to lean, fast to work in, trivial to set up, and very easy to maintain.

What Does Pragma Offer?

Pragma offers a way to very quickly build incredibly powerful, and extensible APIs. It supports use of serverless functions written in many languages for data validation and transformation, and also in user authorization, which is built into the language. These languages include JavaScript, Python, Go, Swift, Rust, Ruby, PHP, Java, Scala, and Ballerina.

How Can I Use It?

You can visit the documentation and read the Getting Started section to install Pragma, and follow a tutorial where you get to build a basic Todo application.

How Can I Contribute?

You can help by opening GitHub issues for any bugs you come across, or opening a pull request to improve documentation. You can read the contributing section in the README to learn how to start hacking on Pragma itself. Any help is greatly appreciated.

How Do I Stay In Touch?

You can follow Pragma on Twitter @pragmalang, and here on DEV. You can also join our Discord server for a chat. We'd love to talk to you guys and learn from your experiences.

We truly wish you enjoy the development experience we're creating as much as we enjoy working on it! Happy hacking everyone!

Parsing The World with Rust and POM

Muhammad Tabaza — Wed, 14 Aug 2019 12:09:16 +0000

As programmers, we spend a lot of time dealing with strings of text. Very often, we receive text as input from users, or we read text files and try to understand their content.

In many cases, we use regular expressions to see if the text matches a certain pattern, or to extract some information from the string. For example, if you receive a username as form input, and you want to make sure that it doesn't contain any spaces, you can use a regex like "^\S+$" to match a string with one or more non-white space characters (^ denotes the beginning of the string, \S denotes a non-white space character, + denotes repetition for one or more times, and $ denotes the end of the string). You might even write a function like:

fn has_whitespaces(s: String) -> bool {
  s.contains(' ')
}

Can you spot the bug in the code?

But what if you're trying to parse the contents of more complex strings. Say, a JSON string, a CSV (Coma-Separated Values) file, or even a program? If you don't use existing library functions, you're going to have a hard time using regular expressions and string methods.

In this article, we'll be exploring the POM library, which offers a really cool interface for intuitively defining and combining parsers. Using this library, you can conveniently define the entire grammar of a formal language (perhaps your own new programming language?)

POM is an implementation of a PEG (Parsing Expression Grammar,) which is a definition of a formal language in terms of symbols, string expressions, and rules.

For example, if we were to define a rule for parsing a variable definition such as: let x = 1;, we would say that let is a sequence of symbols, =, ;, and spaces are symbols, and x and 1 are string expressions. A variable definition consists of the let sequence, followed by a space, followed by a valid identifier (x, for example,) followed by zero or more spaces, followed by the = symbol, followed by zero or more spaces, followed by a valid expression (1 in this example,) followed by zero or more spaces and the ; symbol. A bit verbose, isn't it? Such are the definitions of formal languages.

Thankfully, POM provides a very declarative way of defining these rules. It allows us to define different rules for parsing each small piece of text, and then combine them using arithmetic and logical operators to form more complex rules. These operators are called parser combinators.

POM defines a type called: Parser, which is used to encode parsing rules. A parser can be constructed using many of the pre-defined parsers that the library provides, such as the sym and seq functions. The above example of a variable definition can be expressed in POM as:

use pom::char_class::*;
use pom::parser::*;

fn variable_def<'a>() -> Parser<'a, u8, (String, u32)> {
  let valid_id = (is_a(alpha) + is_a(alphanum).repeat(0..))
    .map(|(first, rest)| format!("{}{}", first as char, String::from_utf8(rest).unwrap()));
  let valid_expr = one_of(b"0123456789")
    .repeat(1..10)
    .convert(String::from_utf8)
    .convert(|s| s.parse::<u32>());
  seq(b"let") * sym(b' ') * valid_id - sym(b' ') - sym(b'=') 
    - sym(b' ').repeat(0..) + valid_expr - sym(b';')
}

Let's break down the code:
1 - We import all the contents of pom::char_class, which exports
predicates such as alpha, and alphanum. We use these predicates to
test the type of input characters.
pom::parser exports seq, and sym among other functions that return
Parsers.

use pom::char_class::*;
use pom::parser::*;

2 - The variable_def function takes no arguments, and return a Parser
with the lifetime 'a that accepts u8s (character bytes) as input, and
outputs a tuple of (String, u32). The tuple encodes the variable's
identifier, and its value (we limit valid values to 9-digit positive
integers for simplicity's sake.)

fn variable_def<'a>() -> Parser<'a, u8, (String, u32)>

3 - A valid variable identifier consists of at least one alphabetic character, followed by zero or more alphanumeric characters. We use the is_a parser to test that the first character of the variable id is_a(alpha), and that the rest of the id is_a(alphanum).
Notice how the + operator is used to combine the two parts of the variable identifier. It returns a tuple containing the results of both operands, which we then destructure in the map method call. map is used to transform the result of a parser, and return a new parser. In this case: (is_a(alpha) + is_a(alphanum).repeat(0..)) returns a Parser<'a, u8, (u8, Vec<u8>)> (the first character and the rest of the characters,) which we then transform into a Parser<'a, u8, String> (the whole identifier) by concatenating the first character and the rest of the characters using format!.

let valid_id = (is_a(alpha) + is_a(alphanum).repeat(0..))
    .map(|(first, rest)| format!("{}{}", first as char, String::from_utf8(rest).unwrap()));

4 - A valid expression is defined as 1 to 9 numbers converted to a String which is then parsed as a u32. convert is used here instead of map because String::from_utf8 returns a Result, so the parser wouldn't match the expression if the result of String::from_utf8 is Err.

let valid_expr = one_of(b"0123456789")
    .repeat(1..10)
    .convert(String::from_utf8)
    .convert(|s| s.parse::<u32>());

5 - The returned parser is a combination of the symbols mentioned above mixed with some spaces, and a valid identifier and expression. The * operator combines two parsers and returns the result of the right-hand parser. So Parser<'a, u8, T> * Parser<'a, u8, U> = Parser<'a, u8, U>. We also see the - operator in use, which combines two parsers and returns a parser with the value of the left-hand parser. These operators follow the same precedence rules as normal arithmetic operators in Rust.

seq(b"let") * sym(b' ') * valid_id - sym(b' ') - sym(b'=') 
    - sym(b' ').repeat(0..) + valid_expr - sym(b';')

Take a look at this handy table of parser combinators.

Now to test our parser:

#[test]
fn test_variable_parser() {
  let valid_variable_byte_string = b"let v1 = 42;";
  let parsed_variable = variable_def().parse(valid_variable_byte_string);
  assert_eq!(parsed_variable, Ok(("v1".to_string(), 42)));

  let invalid_variable_byte_string = b"let nosemicolon = 42";
  let parsed_variable = variable_def().parse(invalid_variable_byte_string);
  assert_eq!(parsed_variable, Err(pom::Error::Incomplete));

  let invalid_variable_byte_string = b"let morethan9digits = 1234567890;";
  let parsed_variable = variable_def().parse(invalid_variable_byte_string);
  assert_eq!(
    parsed_variable,
    Err(pom::Error::Mismatch {
      message: "expect: 59, found: 48".to_string(),
      position: 31
    })
  );
}

Using POM to parse a variable definition of a positive integer value might seem overkill, but try to imagine using it to parse an entire programming language.

I hope you found this article helpful. Now enjoy parsing every string in your way.

Special thanks to Junfeng Liu and all contributors for creating an amazing library. You deserve a cookie 🍪