> For the complete documentation index, see [llms.txt](https://docs.stakingrewards.com/pipescript-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stakingrewards.com/pipescript-docs/the-language/new-language.md). # A New Language ## A new language Hi, this is Hady and I'm here to tell you a story about a pipe. No, not this pipe.
That is an impressive looking pipe though, however that's not what we're here for. We're talking about this
Pipescript has one big idea that you **must** fully understand in order to make the most out of it. > Errors do not migrate This combined with the following features: * One global scope (with one small exception) * Readable, non-cryptic error messages * Function-oriented * Extremely slim on notation Will make your experience authoring scripts a joy and the scripts you produce will be reliable. {% hint style="warning" %} While on the subject of reliability, I don't need to remind you that the language is currently pre-v1. Which means changes will happen, some changes will break things and bugs will surface. Reach out when and if you run into any issues on the [#imt](slack://channel?team=T014YF1SM70\&id=C04ML01UD8B) channel {% endhint %} I understand that I threw you in the deep end there. But I really had to, these are important characteristics to learn about and it's my hope that when in doubt, you'll come back to revisit these words. It's part of the identity of the language and will become part of the identity of your code. Let's start like all good stories start, from the end. Yes, really it's not a joke. I know you're laughing... Come on now. Game face on! ### Extremely slim on notation One design goal I had for Pipescript has been to make a language that's *discoverable*. This meant the language had to concentrate the bulk of its capabilities in a location that is easy to search, index and retrieve information from. Doing anything in the language will require you to know how to glue `functions` together and where to find them. Which as it happens, is quite easy to search. Bare with me now, if the word `function` is foreign to you that's perfectly fine. You'll be swimming in functions in no time. They'll become your best friend, your pet, and your happy place... Okay maybe not that much. The point here is, the language favors clear plain-text wording over symbolic notation. there's very little weird characters that have special meanings that are impossible to search for. ### Function Oriented You may have heard that term, functional languages. This isn't one. However, there's a category of languages commonly referred to as command-oriented language. {% hint style="info" %} Languages like Bash, Batch and Awk are some examples of command-oriented languages. {% endhint %} Except we don't use commands but we use functions to do just about anything you'd like. The distinction is subtle but important to us language designers and those of you out there keen on learning more about programming language theory. Whether we call it command-oriented or function oriented is irrelevant to our talk here; the point of this is, *the likely answer to any question you'll have on how to do something is going to be a function*. ### Non-cryptic error messages You'd think engineers love to read gibberish for breakfast given how many programming languages have an affinity towards showing you error messages that take more time to parse than it would've taken you to rewrite your program. That however, is not the case. We hate it. So when building Pipescript we've been doing our best to craft intelligible error messages. This has been a design goal from the beginning given the nature of the language and its relationship with errors. More on that later. You'd laugh though if I say good error messages are a feature, it *really is.* ### Global scope Scope is rather difficult to explain for new comers to programming. It's a complex subject in language design and theory so I will do my best here but please understand that there are books and a whole research body around what we call variable scoping in our industry. Scope can be described as how much of the world can you see from any vantage point. Say you have some eye glasses in front of you, each one is fine-tuned to only see objects of a certain color. You pick the one that lets you see red objects, the only way for you to see an object is if it's colored red or you painted it red. That's scoping. When you define some value in your code, not all the code is going to be able to see and access that value. Even if the *text* of that code sits in close proximity to one another. The structure of the code dictates the items that code has access to.
Complexity ensues when you need to combine different scopes (read: needing to wear different glasses at the same time). Pipescript only uses global scopes. That is to say, if you define a value anywhere, it's accessible from anywhere else. This simplifies your work in Pipescript, puts the burden on our shoulders to make sure we do the right thing for you but it's a net-positive for everyone involved. ## Error Migration A problem that plagues all software. Pipescript has a unique error philosophy that, I don't claim to be a solution to all software problems. But I will argue that my approach here is one of the better approaches I've seen in programming language design. Pipescript is an experiment to prove the idea that errors are as much the responsibility of the language as it is the engineer using the language. I hope I'm not wrong. So what's the issue with errors? They happen, a lot. You will make a request to an online service or to a database and it will return faulty data or flat out die on you. ### Possible strategies Now you code is being presented with an error and the choices it has are limited. It could 1. Handle the error and attempt to employ some recovery strategy - *great form*. 2. Handle the error and choose to error out, so everything gently blows up - *acceptable form*. 3. Not handle the error, so everything badly blows up - *bad form*. Depending on your case, any of of these scenarios is a viable option but involves a great deal of thought. Not to mention the code required for options 1 & 2. The complexity here is in the fact that this one faulty operation is part of a larger set of operations. You needed that value from the database, in order to compute a formula, to plug it into another request, wait for the response of that request and continue accordingly. There's also collateral damage here. That one operation that failed is now cascading its way through your code like wild fire in a dry season. Other parts of the code become unsuspecting victims of their environment. Parts of your code that are healthy and can successfully complete their tasks are now also breaking. #### Different strategy, same result Any one of these choices will consistently result in two things: 1. Loss of the original context 2. Error migration #### Loss of original context Your error happened in one place, it got tossed to another place to be "dealt with". This receiver may as well toss it to another place, and so on. By the time you reach a receiver that is willing and able to deal with that error, the original context is now mangled. There's no telling if any of the pitstops this error had to make, has resulted in more additions to the original context or if the original context was completely overridden. {% hint style="danger" %} #### Noble but dangerous thinking It's noble to think this will never happen because you'll make sure your code does the right thing. However, after 16 years -pushing on 17- of engineering experience I can tell you with confidence, your code is as fallible as people are. Mistakes happen, if not by you then by your colleagues or by other peoples' code that you'll come to rely on to do your work - *be careful* with this line of thinking as you learn how to program software systems. {% endhint %} #### Error migration The second result you'll experience from having to choose one of the three options outlined above is a direct result of the loss of context. Errors move away from their point of origin. It's a massive headache that cannot be overstated in words. Here's an *extremely* -messy- fictional analogy, based on real-world programming experience. > Mirko had asked Jannik to do something, Jannik did part and passed another part over to Hady. In order for Hady to do his part, he needs Benedikt to do something. > > Benedikt is already doing something so Hady waits. > > Jannik waits but in the meantime started asking Martin to do something, however Hady errors out waiting so now Jannik needs to handle this but he's in the middle of asking Martin to do something. > > Benedikt is now free, rings Hady back asking what he originally wanted but Hady is in an error state so Benedikt enters an error state. Mirko by the way, is still waiting on Jannik to return to him. > > Jannik now needs to make a decision, does Mirko need to know the details of what's happening or not. If Mirko were to know, will this cause an error on David's side? {% hint style="warning" %} #### Disclaimer Any resemblance to real persons living or dead is purely coincidental {% endhint %} Sorry I couldn't help myself. Always wanted to say that. Back to the analogy, every name mentioned above is a component of a system or maybe another system entirely, they all need to interact. Some are interacting directly, others indirectly. Your system design will either: * *enforce a separation* (comes at the cost of great complexity, inconsistent states and consistent eradication of context) or * *give in to tight coupling* (comes at the cost of great reliance on micro-decisions, lack of holistic visibility and incoherent expectation management). As cooks with a bad taste for humor like to say, pick your poison. There's an ever shifting balance between those two approaches that every software experiences through out its lifetime. ### Solution In Pipescript, every operation resulting in some value establishes a track. If the result of that operation was an error, *any* and *everything* on that track will be dismissed summarily from the execution. We're making a guarantee of successful partial execution despite any error occurring anywhere in your code. By isolating code streams that derive from values that resulted from an erroneous operation, we're able to continue the execution of healthy code, while unhealthy code halts execution completely, their point-of-impact (where the error originated) is retained in full context and *all* the operations that ensued relying on what is now an error, will be tagged and filed for you to revisit later. > Woah, slow down Turbo! I know! I'm sorry, I keep doing this to you - throwing words at you. It's this thing they call writing. Weird stuff, really. Perhaps I'll throw a picture at you instead. All the boxes shaded gray relied on the result of the operations outlined red which errored out. All those gray shaded boxes are being skipped because the operation they relied on failed. Everything else is marked green and has or continues to execute happily.
## TL;DR; Pipescript is a language that forces your code to stay on the happy path by making you a guarantee that if part of your code has failed, the rest of your code can continue working without any intervention from your side. > Partial execution, is good execution. The language has also been designed to be extremely small and focuses on an extensive library of functions to supplement the language simplicity with a great deal of functionality.